RE: Barracuda docs....

Hi,
I like the stylesheet route.
 
All you need to do is have seperate stylesheets for 'style' and another for
'layout'
Pretty Simple..
 
To manage 'site wide' changes you can further split the layout into 'global'
and 'page-specic' layouts.
I've done something similar in my current web-app.
Works Great.
 
Viva la Css Positioning.. ;)
 
Regards
KD

-----Original Message-----
From: Jacob Kjome [mailto:[email protected]]
Sent: 24 February 2003 04:44
To: [email protected]
Subject: RE: [Barracuda] Barracuda docs....



Hi Christian,

See comments inline below...

At 08:19 AM 2/24/2003 -0500, you wrote:


Hi Jake,

> At some point we need to figure out what we want to do with Barracuda's
> docs.  The way things are is not overly manageable.

Can you clarity exactly what you mean by "not overly manageable"? I _think_
you're referring to the complex HTML introduced by the nested tables, but
perhaps you have something else in mind too? I want to make sure I
understand exactly what you perceive the issues to be...

My general thought is that the complexity of the current markup could be
greatly simplified simply by using stylesheets.



This would definitely be an improvement.



The advantage of keeping the docs in standard HTML is that it allows us to
use HTML editing tools to edit/modify the docs (FrontPage, Mozilla's HTML
editor, etc.) So, a basic requirement for me is that whatever docs solution
we come up is GUI editable in something other than just textpad. Obviously,
not everyone wants (or should have) to use a gui markup editor, but those of
us that do want to take this approach should be able to...because it is a
very fast way to generate docs.



It may be fast, but FrontPage produces some of the messiest possible HTML.
It is very difficult to read in a text editor.  Tools are fine if they work.
I know you feel that FrontPage works for you, but it makes it so things
don't work for anyone else.  When this was brought up before, Diez agreed
with me that it should be simple to write the docs in a plain text editor.
The way FrontPage mangles the markup makes that very difficult and deters
outside contributions to documentation.



So what I'd propose reworking the current format using style sheets to
greatly simplify the markup format - that way those of us who have editors
can continue to use them, and those who don't can edit by hand.



Yes, this would be good, but HTML will always impose a particular structure.
I have provided examples what is possible with stylesheets (
http://www.visi.com/~hoju/barracuda/barracuda.html
<http://www.visi.com/~hoju/barracuda/barracuda.html>  ).  However, there is
always still some structure imposed when you use static HTML.  Using XML,
the entire markup structure can be modified for the whole site in an instant
without using a GUI tool.



Are there other benefits or advantages of a system like Forrest? (I just do
not see much point in storing them as xml...but maybe you see something that
I don't).



Like I said above, you can modify the structure of the markup dramatically
without using a GUI tool.  Instead, it can be done using our Ant build.

That said, if Forest (or the like) isn't agreeable, I guess we won't use it.
It was just a suggestion about using an existing site management tool that
is being used by a number of projects.  But if we do just use static HTML +
stylesheets, we need to make sure that we aren't also using spacer images,
<font> tags, tables for layout,  and the like.  It needs to be valid (XHTML)
and *clean* markup.  If the GUI tools can't provide for that requirement,
then out with the GUI tools.  If they can meet the requirements, more power
to them.




Final comment...as much as the docs need to get updated, there are other
things that really need to get done first.



I agree, but if there are some who would volunteer to do this in parallel,
then I don't see why this can't be done at the same time.  Obviously, for
those of use who have access to make changes to the server, what you have
below is priority.



a) we need to revamp the contrib structure (I think we talked about this,
but I don't think we every actually implemented it yet)



I'm really going to miss the way the contrib apps currently work.  Try this,
for example...

ant contrib -Dsubproject=all -Dsubtarget=catalina-install

That will build Barracuda, build the main contrib stuff, and then build and
install both Diez' and Stefan's projects into Tomcat.  All that with one
little command.

I'm not saying we should keep this.  I know it has already been discussed at
length.  I'm just proud of how slick it works and am going to miss the
functionality :-(



b) we really need to get our daily builds and downloads system up and
running



definitely!



c) we need to get the barracuda.enhydra.org site redirecting to
barracudamvc.org.



most definitely!



d) we need to get another major release out (with the newest version of
xmlc?)



I wouldn't hold your breath on this one....at least not for too long.  As I
understand it, the current approach for the 2.2 release is to wrap Xerces
into XMLC.  As far as I could tell, 2.2 was nearly ready to be released
until this decision was made.  I'm not sure how much, if any, progress has
been made in this effort?  When it is released, it should make it that much
simpler to build apps with XMLC because there *shouldn't* be any more
collision with existing Xerces packages which means that we *should* be able
to just put XMLC into WEB-INF/lib and not worry about putting an
XMLC-specific version of Xerces in a shared classloader.  W'd just use
whatever is there already.  This will simplify things greatly but, again, it
may be a bit before it is out.  I would ping Richard or David to  see if we
can get an approximate estimate for time-of-release.



e) we need to make a concerted effort to get the word about Barracuda out,
by doing press releases, announcing on various lists, etc.



I have been doing it on the Tomcat-user list when people are looking for
frameworks or solutions to certain problems but I know that doesn't
advertise Barracuda as far and wide as we'd like.  BTW, I did submit the
Barracuda list for archiving on http://marc.theaimsgroup.com/
<http://marc.theaimsgroup.com/>  , however, I never got a response.  I'll
have to try again.



I think the docs need to be updated somewhere around d or e, but I'm really
more interested in getting the other items listed above resolved first.



yep.

Jake



Just my .02...

Christian
----------------------------------------------
Christian Cryder [[email protected]]
Internet Architect, ATMReports.com
Barracuda - http://barracudamvc.org <http://barracudamvc.org/> 
----------------------------------------------
"Coffee? I could quit anytime, just not today"

> -----Original Message-----
> From: [email protected]
> [ mailto:[email protected]
<mailto:[email protected]> ]On Behalf Of Jacob Kjome
> Sent: Sunday, February 23, 2003 2:03 PM
> To: [email protected]
> Subject: [Barracuda] Barracuda docs....
>
>
>
> At some point we need to figure out what we want to do with Barracuda's
> docs.  The way things are is not overly manageable.
>
> I think we should use something like Forest from the XML Apache project:
> http://xml.apache.org/forrest/index.html
<http://xml.apache.org/forrest/index.html> 
>
> This will make the doc source human readable and allow for lots of
> flexibility in the presentation.  Human readability is important
> for those
> who might want to contribute to the docs.  They should be able to do so
> using a simple text editor and not have to know much of anything
> about the
> resulting format of the docs.  This ease of use will, I believe, increase
> contributions to our documentation   which, everyone will agree, requires
> some enhancement.
>
> While it might seem like Forest forces a particular presentation format
> based on most of the sites that use Forest looking almost exactly
> the same
> ( such as http://ant.apache.org/ <http://ant.apache.org/>  looking like
Forest's layout above ), I
> believe this was a conscious choice of those sites to use what is
> probably
> the default layout.  Looking at some of the sites who claim to use Forest
> bears this fact out....
> http://xml.apache.org/forrest/live-sites.html
<http://xml.apache.org/forrest/live-sites.html> 
>
> There are a few in that list that don't look like standard Forest layout.
>
> I'm not saying we need to do this immediately.  However, we need to get
> some people thinking about it and working on it at some point.  Any
> thoughts?  Any volunteers?
>
> Jake
>
> _______________________________________________
> Barracuda mailing list
> [email protected]
> http://barracudamvc.org/lists/listinfo/barracuda
<http://barracudamvc.org/lists/listinfo/barracuda> 

_______________________________________________
Barracuda mailing list
[email protected]
http://barracudamvc.org/lists/listinfo/barracuda
<http://barracudamvc.org/lists/listinfo/barracuda>