Re: [DOC] Vote on oustanding doc issues?

[Adam Fowler]

Ah-ha! the culprit!!! 8o)

Adam.

On Friday 13 July 2001 03:36, you wrote:
> Adam Fowler at [EMAIL PROTECTED] wrote:
> > *being random* The RPM of tc4 worked great on Mandrake 8.0 beta 3.
> >
> > Incidentally, the tc4 docs suck. I had to read deeply into the config
> > files to find out how to get it working with apache. This is fine for a
> > seasoned admin, but the general web community wouldn't have a clue (By
> > that I refer to the quantity of mails in tomcat-user!) 8o)
> >
> > We could do with better tc4 docs.
>
> If you're talking about how to set up tomcat with apache, that's my fault
> :)
>
> Pier

Re: [DOC] Vote on oustanding doc issues?

[Pier P. Fumagalli]

Adam Fowler at [EMAIL PROTECTED] wrote:

> *being random* The RPM of tc4 worked great on Mandrake 8.0 beta 3.
> 
> Incidentally, the tc4 docs suck. I had to read deeply into the config files
> to find out how to get it working with apache. This is fine for a seasoned
> admin, but the general web community wouldn't have a clue (By that I refer to
> the quantity of mails in tomcat-user!) 8o)
> 
> We could do with better tc4 docs.

If you're talking about how to set up tomcat with apache, that's my fault :)

Pier

Re: [DOC] Vote on oustanding doc issues?

[Adam Fowler]

*being random* The RPM of tc4 worked great on Mandrake 8.0 beta 3.

Incidentally, the tc4 docs suck. I had to read deeply into the config files 
to find out how to get it working with apache. This is fine for a seasoned 
admin, but the general web community wouldn't have a clue (By that I refer to 
the quantity of mails in tomcat-user!) 8o)

We could do with better tc4 docs. 

Just sticking my neb in - I think a separate tree for 3.2+3.3 would be a bit 
unnecessary.

Adam.

 
Adam Fowler 
Help Desk Live Project 
Information Services 
University of Wales, Aberystwyth 
Web guy+author on the TomcatBook Project 
http://tomcatbook.sourceforge.net 
e-mail: [EMAIL PROTECTED] 
 

On Wednesday 11 July 2001 15:26, you wrote:
> Craig R. McClanahan wrote:
> > On Mon, 9 Jul 2001, Alex Chaffee wrote:
> >>>Bundle the 3.2.x docs with 3.2.x and only have the 3.3 docs online
> >>> ("latest Tomcat release").  If you want the 3.2.x docs, get them with
> >>> the binary or whatever.  I certainly don't think we should keep old
> >>> versions of documentation updated.  I mean, why would updated 3.0 or
> >>> 3.1 docs be useful?
> >
> > Unless and until there's a 3.3 or 4.0 final release, *3.2* is the "latest
> > Tomcat release", and deserves to be documented on the web site.
>
> OK, but my point is that as we improve the 3.x docs -- regardless of the
> value of x -- the 3.2 docs will become less relevant.
>
> Right now there are many differences between the 3.2 and 3.3 docs, but
> they're mostly in the connector docs, which AFAIK haven't changed much if
> at all in operation. This leads me to conclude that the docs in the 3.3
> tree are just as valid when applied to 3.2, except that they're better
> docs, since more people have had a chance to revise them.  That's why I'd
> like to remove the "Tomcat 3 docs that happened to be in the depot at the
> time 3.2 shipped" in favor of "the latest version of the Tomcat 3 docs
> (which happen to be in the 3.3 dev tree)".
>
> Perhaps the easiest way to do this would be with a separate depot. I'm
> shying away from that for the reasons you (Craig) brought up.  It's nice
> for docs to be in the same depot as the code...
>
> > There's no reason to banish the current Tomcat released version, or any
> > other version that is being actively developed.  And it's quite easy to
> > arrange the user interface so that it's obvious which version you are
> > looking at (for example, including "Tomcat X.Y" in the header or footer
> > of the pages about that version).
>
> Again, apart from 3 vs 4, the difference between versions 3.2 and 3.3 is
> small, as far as docs are concerned, so announcing "Tomcat 3.2" in the
> header wouldn't be very salient, and would just promote forking of docs. We
> seem to be in this quandary because the docs have not really been part of
> the release process -- they get released slapdash relative to the code
> milestones.
>
>
> By the way, it seems like the majority of the existing documentation is
> about installation. If there were a clean, robust install script, it would
> remove 90% of the text on the site. Maybe before we write (rewrite) install
> docs we should write an install script.  I know that was on your todo list
> for 4 -- how's that coming?

RE: [DOC] Vote on oustanding doc issues?

[Robert Slifka]

> I was off the list for a while. I tried to read through the 
> archives but all 
> the vitriol gave me a headache. Did they just agree to 
> disagree?  Do you 
> think there'll be a problem with proposing to remove the 3.2 
> docs from the site?

>From what I remember, 3.3 is a major refactoring of 3.2, and 3.x (at least
under Jakarta) will remain Servlet 2.2 & Jsp1.1.  I don't remember any
massive functional changes between 3.2-3.3?

I dunno anyone who would vote for maintaining more documentation than less,
but by all means ;)

- r

RE: [DOC] Vote on oustanding doc issues?

[GOMEZ Henri]

>OK, but my point is that as we improve the 3.x docs -- 
>regardless of the 
>value of x -- the 3.2 docs will become less relevant.
>
>Right now there are many differences between the 3.2 and 3.3 docs, but 
>they're mostly in the connector docs, which AFAIK haven't 
>changed much if at 
>all in operation. This leads me to conclude that the docs in 
>the 3.3 tree 
>are just as valid when applied to 3.2, except that they're 
>better docs, 
>since more people have had a chance to revise them.  That's 
>why I'd like to 
>remove the "Tomcat 3 docs that happened to be in the depot at 
>the time 3.2 
>shipped" in favor of "the latest version of the Tomcat 3 docs 
>(which happen 
>to be in the 3.3 dev tree)".

Working on J-T-C, I'll be more than happy to adapt :

tomcat-ssl-how-to, mod_jk-howto, workers-howto. IIS-howto, domino-howto
netscape-howto could be handled by others JTC members. We're working on
having a uniq worker file which will help having an uniq workers-howto.

And in that case, the old 3.3 doc will be outdated.

>Perhaps the easiest way to do this would be with a separate depot. I'm 
>shying away from that for the reasons you (Craig) brought up.  
>It's nice for 
>docs to be in the same depot as the code...

Having a separate cvs will help having redactors as commiters.
And we could still export from the doc CVS, necessary stuff at
release time (millenium, beta, release).


>By the way, it seems like the majority of the existing 
>documentation is 
>about installation. If there were a clean, robust install 
>script, it would 
>remove 90% of the text on the site. Maybe before we write 
>(rewrite) install 
>docs we should write an install script.  I know that was on 
>your todo list 
>for 4 -- how's that coming?

I would recommand you to mention Redhat RPM which make any
users in tomcat, mod_jk in less than 30 seconds :)

That's an easy install and why not using something like
NullSoft installer to do the same under Windows ?

RE: [DOC] Vote on oustanding doc issues?

[GOMEZ Henri]

>> I like this compromise.  I will propose that we get rid of 
>the 3.2 docs
>> on the site -- once I'm convinced they're similar enough.  
>There's still
>> that old "3.3 is a rogue release" sentiment floating around, 
>and people
>> might not appreciate giving 3.3 implied legitimacy by making it the
>> "official" documentation...

Yes, many won't like it at all. The official TC 3.x release is 
TC 3.2.2. 3.3 is a rewrite but many documentations in TC 3.2/3.3
could (SHOULD) be merged and differences commented

>Woah, I thought the committers worked that out a long time 
>ago.  Well, I
>don't want to open any cans of worms so AFAIC, the TC3 doc 
>people can do
>what they want (of course), although I don't think maintaining 
>2 sets of
>docs is expected, a good idea, or will even happen =)

By sure that 3.3 team will do it's part of the job.
If there is difference (architecture, modularity, config)
we'll comment it.

Just show us how to do that (need some docs to figure how
to meet the concensus)

Please never forget that's the documentation call and
PRE-PROPOSAL came from someone working on 3.3 and who
asked to have a separate CVS for doc :)

Re: [DOC] Vote on oustanding doc issues?

[Alex Chaffee]

Craig R. McClanahan wrote:

> 
> On Mon, 9 Jul 2001, Alex Chaffee wrote:
> 
> 
>>>Bundle the 3.2.x docs with 3.2.x and only have the 3.3 docs online ("latest
>>>Tomcat release").  If you want the 3.2.x docs, get them with the binary or
>>>whatever.  I certainly don't think we should keep old versions of
>>>documentation updated.  I mean, why would updated 3.0 or 3.1 docs be useful?
>>>
>>>
> 
> Unless and until there's a 3.3 or 4.0 final release, *3.2* is the "latest
> Tomcat release", and deserves to be documented on the web site.


OK, but my point is that as we improve the 3.x docs -- regardless of the 
value of x -- the 3.2 docs will become less relevant.

Right now there are many differences between the 3.2 and 3.3 docs, but 
they're mostly in the connector docs, which AFAIK haven't changed much if at 
all in operation. This leads me to conclude that the docs in the 3.3 tree 
are just as valid when applied to 3.2, except that they're better docs, 
since more people have had a chance to revise them.  That's why I'd like to 
remove the "Tomcat 3 docs that happened to be in the depot at the time 3.2 
shipped" in favor of "the latest version of the Tomcat 3 docs (which happen 
to be in the 3.3 dev tree)".

Perhaps the easiest way to do this would be with a separate depot. I'm 
shying away from that for the reasons you (Craig) brought up.  It's nice for 
docs to be in the same depot as the code...

> There's no reason to banish the current Tomcat released version, or any
> other version that is being actively developed.  And it's quite easy to
> arrange the user interface so that it's obvious which version you are
> looking at (for example, including "Tomcat X.Y" in the header or footer of
> the pages about that version).


Again, apart from 3 vs 4, the difference between versions 3.2 and 3.3 is 
small, as far as docs are concerned, so announcing "Tomcat 3.2" in the 
header wouldn't be very salient, and would just promote forking of docs. We 
seem to be in this quandary because the docs have not really been part of 
the release process -- they get released slapdash relative to the code 
milestones.


By the way, it seems like the majority of the existing documentation is 
about installation. If there were a clean, robust install script, it would 
remove 90% of the text on the site. Maybe before we write (rewrite) install 
docs we should write an install script.  I know that was on your todo list 
for 4 -- how's that coming?


-- 
Alex Chaffee   mailto:[EMAIL PROTECTED]
jGuru - Java News and FAQs http://www.jguru.com/alex/
Creator of Gamelan http://www.gamelan.com/
Founder of Purple Technology   http://www.purpletech.com/
Curator of Stinky Art Collective   http://www.stinky.com/

RE: [DOC] Vote on oustanding doc issues?

[Rob S.]

> Unless and until there's a 3.3 or 4.0 final release, *3.2* is the "latest
> Tomcat release", and deserves to be documented on the web site.

Ah, but that's exactly my point.  I see two versions of Tomcat docs up there
now and I'm like, "wtf?"  Why have the 3.3 docs online then?  Now that I've
RTFM, I'm enlightened.  So what I'm saying is this: once 3.3 is final then
we aren't expected to update the 3.2.x docs.  The 3.2.x docs become the 3.3
docs after modification - we don't have to maintain a version 3.2.x docs.

This is my take on Alex's question of "should we maintain separate versions
of the doc for older versions?"  So when 4.1 comes out, do we maintain 4.0
documentation, or does it become 4.1 documentation?  My opinion is the
latter...

- r

Re: [DOC]: Vote on oustanding doc issues?

[Craig R. McClanahan]

On Tue, 10 Jul 2001, Alex Chaffee wrote:

> Rob S. wrote:
> 
> 
> > The tough thing about separating the docs is that the server.xml config
> > stuff is spread out among multiple files.  I wonder how difficult it would
> > be to maintain an index, or even if it's necessary.
> 
> 
> I don't think it's a big deal. I forgot to list the appendices, but one of 
> them will be a technical doc describing server.xml tag by tag. Whoever 
> writes this should put links in to the relevant parts of the TOC (which will 
> in turn contain links to the relevant documents).
> 

For Tomcat 4 at least, you'll find that the tag-by-tag docs on server.xml
is about 90% done -- the remaining work is to document the few remaining
undocumented elements, then convert the stuff from HTML to XML.  Having a
file per major element seemed to be a convenient way to organize it, but
I'm certainly open to any reasonable layout.

See directory "catalina/docs/config/" in the source repository -- or just
follow the online links if you're running Tomcat.

These docs were designed to be reference material, so they fit the concept
of an Appendix (as described above) quite well.  What's also important, of
course, is the *why* I would use a particular element, and the *how* to
solve some standard problems like "I want to use a single JDBCRealm for
all the webapps on this virtual host" or "how do I set up user home
directory based web apps?".


Craig

Re: [DOC] Vote on oustanding doc issues?

[Craig R. McClanahan]

On Mon, 9 Jul 2001, Alex Chaffee wrote:

> > 
> > Bundle the 3.2.x docs with 3.2.x and only have the 3.3 docs online ("latest
> > Tomcat release").  If you want the 3.2.x docs, get them with the binary or
> > whatever.  I certainly don't think we should keep old versions of
> > documentation updated.  I mean, why would updated 3.0 or 3.1 docs be useful?
> > 

Unless and until there's a 3.3 or 4.0 final release, *3.2* is the "latest
Tomcat release", and deserves to be documented on the web site.

Fortunately, there's a real easy way to handle this -- it's called
subdirectories :-).

There's no reason to banish the current Tomcat released version, or any
other version that is being actively developed.  And it's quite easy to
arrange the user interface so that it's obvious which version you are
looking at (for example, including "Tomcat X.Y" in the header or footer of
the pages about that version).

Craig

Re: [DOC]: Vote on oustanding doc issues?

[Jon Stevens]

on 7/10/01 4:06 AM, "Rob S." <[EMAIL PROTECTED]> wrote:

> PDF conversion would be pretty cool...  Anyone feel like coming up with a
> sheet to generate XSL:FO? =)

We have started that here:



Not perfect yet because Anakia will need some tweaking to generate all of
the pages as a single FO object, but it is a start.

The real hard part is figuring out how to write FO's. :-)

-jon

Re: [DOC] Vote on oustanding doc issues?

[Alex Chaffee]

Rob S. wrote:


>>I like this compromise.  I will propose that we get rid of the 3.2 docs
>>on the site -- once I'm convinced they're similar enough.  There's still
>>that old "3.3 is a rogue release" sentiment floating around, and people
>>might not appreciate giving 3.3 implied legitimacy by making it the
>>"official" documentation...
>>
> 
> Woah, I thought the committers worked that out a long time ago. 


I was off the list for a while. I tried to read through the archives but all 
the vitriol gave me a headache. Did they just agree to disagree?  Do you 
think there'll be a problem with proposing to remove the 3.2 docs from the site?




-- 
Alex Chaffee   mailto:[EMAIL PROTECTED]
jGuru - Java News and FAQs http://www.jguru.com/alex/
Creator of Gamelan http://www.gamelan.com/
Founder of Purple Technology   http://www.purpletech.com/
Curator of Stinky Art Collective   http://www.stinky.com/

Re: [DOC]: Vote on oustanding doc issues?

[Alex Chaffee]

Rob S. wrote:


> The tough thing about separating the docs is that the server.xml config
> stuff is spread out among multiple files.  I wonder how difficult it would
> be to maintain an index, or even if it's necessary.


I don't think it's a big deal. I forgot to list the appendices, but one of 
them will be a technical doc describing server.xml tag by tag. Whoever 
writes this should put links in to the relevant parts of the TOC (which will 
in turn contain links to the relevant documents).

> As well, is the intro not part of this breakdown or just not necessary or
> what?  Is the list even getting my emails? =)  I still think we should have
> an intro for people that may/not use Tomcat... err I'll just write it tonite
> and send it to the list and you guys can let me know if you like the
> direction it's headed in! =p


I'm not too worried about the intro, since the Web site already has a 
paragraph describing it, but a "why should I use Tomcat" chapter would go in 
the "Overview" section (see TOC).  Also, that's more a FAQ than a chapter. 
But hey, write it! We'll check it in, and you can also post it to the jGuru 
FAQ if you like.




-- 
Alex Chaffee   mailto:[EMAIL PROTECTED]
jGuru - Java News and FAQs http://www.jguru.com/alex/
Creator of Gamelan http://www.gamelan.com/
Founder of Purple Technology   http://www.purpletech.com/
Curator of Stinky Art Collective   http://www.stinky.com/

RE: [DOC]: Vote on oustanding doc issues?

[GOMEZ Henri]

>PDF conversion would be pretty cool...  Anyone feel like 
>coming up with a
>sheet to generate XSL:FO? =)

Good idea, we should find help on xml.apache.org.

>> If someone is scared of XML, they can submit it to us in 
>text format and
>> we can go add tags (as time permits), but we're all 
>developers here, so
>> I don't think that's an issue.
>
>With the (hopeful ;) abundance of docs we'll put in there ourselves,
>there'll be plenty of sample 'code' to work with.  As well, 
>the closer we
>stick to HTML, the easier it'll be...
>
>> I. Standalone Installation Guide
>> II. Installation Behind a Web Server Guide
>> III. Deploying and Configuring, or Tomcat Administrator's Guide
>> IV. Performance Tuning Guide
>> V. Tomcat Developer's Guide (writing code for Tomcat itself)
>>
>> I and II may merge, as may III and IV, but I think we're 
>looking at at
>> least three major parts. Seems natural that they'd be in separate
>> subdirectories.  But...

I feel that I and II shouldn't merge. It will confuse users 
with Apache .conf, and server.xml. Also many time, it will be
only the Admin/WebMaster of a site which will read the part II.
May be more fluent in Apache config that Tomcat server.xml...

>> My vote is -1 for a separate mailing list at this point, at 
>least until
>> we prove that we're not going to peter out like every other
>> documentation effort so far. :-)

I agree with you. Just prefix your mail with [J-T-D] and it 
will help developpers follow your works and questions :)

RE: [DOC] Vote on oustanding doc issues?

[Rob S.]

> Things To Do before we decide on format or CVS:
>
> * Look at the latest TOC and make comments
>
> * Pick a section or subsection and start writing :-)
>
> * Look at http://tomcatbook.sourceforge.net/ and
> http://groups.yahoo.com/group/tcbook and see if there's anyone there to
> recruit, or if effort is being duplicated

Sounds good to me.  That latest TOC is even more mind-blowing than the first
one.  I think you're *really* scaring people off =)

> I like this compromise.  I will propose that we get rid of the 3.2 docs
> on the site -- once I'm convinced they're similar enough.  There's still
> that old "3.3 is a rogue release" sentiment floating around, and people
> might not appreciate giving 3.3 implied legitimacy by making it the
> "official" documentation...

Woah, I thought the committers worked that out a long time ago.  Well, I
don't want to open any cans of worms so AFAIC, the TC3 doc people can do
what they want (of course), although I don't think maintaining 2 sets of
docs is expected, a good idea, or will even happen =)

> Good point.  I'm for Anakia plus a stylebook saying which HTML tags and
> tricks are approved (like, stay away from JavaScript :-)

OMG! +1 (re: JavaScript)

> No, I think we're making progress.

As far as the TOC is concerned, agreed.

- r

RE: [DOC]: Vote on oustanding doc issues?

[Rob S.]

> Yeah, I guess anarchy will be a little too... anarchic :-)  (Rob S. made
> the point more strongly in his latest message.)

PDF conversion would be pretty cool...  Anyone feel like coming up with a
sheet to generate XSL:FO? =)

> If someone is scared of XML, they can submit it to us in text format and
> we can go add tags (as time permits), but we're all developers here, so
> I don't think that's an issue.

With the (hopeful ;) abundance of docs we'll put in there ourselves,
there'll be plenty of sample 'code' to work with.  As well, the closer we
stick to HTML, the easier it'll be...

> I. Standalone Installation Guide
> II. Installation Behind a Web Server Guide
> III. Deploying and Configuring, or Tomcat Administrator's Guide
> IV. Performance Tuning Guide
> V. Tomcat Developer's Guide (writing code for Tomcat itself)
>
> I and II may merge, as may III and IV, but I think we're looking at at
> least three major parts. Seems natural that they'd be in separate
> subdirectories.  But...

I like the above breakdown as a high-level view of things.  I won't have a
chance to look at the new detailed TOC until tonite, but anything I can't
think of that would go in the docs easily fits under I - V.

The tough thing about separating the docs is that the server.xml config
stuff is spread out among multiple files.  I wonder how difficult it would
be to maintain an index, or even if it's necessary.

As well, is the intro not part of this breakdown or just not necessary or
what?  Is the list even getting my emails? =)  I still think we should have
an intro for people that may/not use Tomcat... err I'll just write it tonite
and send it to the list and you guys can let me know if you like the
direction it's headed in! =p

> My vote is -1 for a separate mailing list at this point, at least until
> we prove that we're not going to peter out like every other
> documentation effort so far. :-)

Agreed!

- r

Re: [DOC] Vote on oustanding doc issues?

[Alex Chaffee]

Rob S. wrote:

> Preamble:   =)
> 
> 
>>I don't want to rush it.
>>
> 
> Agreed, but at the same time, I'd like to decide sooner than later.  I'm on
> co-op until August 24th, then I start full-time school again.  4 courses
> doesn't leave a lot of room for TC docs.  Judging by the amount of progress
> we've made recently (pretty much *zero* in over 10 days), I'll be graduated
> by the time we figure out if Tomcat documentation needs a separate
> repository.


Things To Do before we decide on format or CVS:

* Look at the latest TOC and make comments

* Pick a section or subsection and start writing :-)

* Look at http://tomcatbook.sourceforge.net/ and 
http://groups.yahoo.com/group/tcbook and see if there's anyone there to 
recruit, or if effort is being duplicated


>>1a) Should Tomcat 3.2 documentation be rolled in together with Tomcat
>>3.3 documentation for a single, up-to-date, source base, whose release
>>cycle will be independent of the release cycle of Tomcat?
>>
> 
> Bundle the 3.2.x docs with 3.2.x and only have the 3.3 docs online ("latest
> Tomcat release").  If you want the 3.2.x docs, get them with the binary or
> whatever.  I certainly don't think we should keep old versions of
> documentation updated.  I mean, why would updated 3.0 or 3.1 docs be useful?
> 
> Too much work, too little people wanting to do it.  I don't think anyone
> would expect even a product company to update their documentation on old
> versions.  The version of docs I, as a user, would expect to see 'shipping'
> with 3.2.2 (if i want to download an older version of the container) is how
> the docs looked at 3.2.2 ship time.


I like this compromise.  I will propose that we get rid of the 3.2 docs 
on the site -- once I'm convinced they're similar enough.  There's still 
that old "3.3 is a rogue release" sentiment floating around, and people 
might not appreciate giving 3.3 implied legitimacy by making it the 
"official" documentation...

> I don't imagine anyone will want to take the task on of converting the
> anarchical doc repository into the format is decided upon, or how we'll
> generate anything useful for people to evaluate during that time.  So
> someone writes in HTML, someone writes in DocBook, etc.  If I want to help
> on different docs I have to figure out the viewing/editing mechanism for
> each one?  Ugh...


Good point.  I'm for Anakia plus a stylebook saying which HTML tags and 
tricks are approved (like, stay away from JavaScript :-)

>>We can work on the TOC independently of resolving those other issues.
>>
> 
> They're not being resolved, different questions are just asked over and over
> again.
> 
>  =)


No, I think we're making progress.




-- 
Alex Chaffee   mailto:[EMAIL PROTECTED]
jGuru - Java News and FAQs http://www.jguru.com/alex/
Creator of Gamelan http://www.gamelan.com/
Founder of Purple Technology   http://www.purpletech.com/
Curator of Stinky Art Collective   http://www.stinky.com/

Re: [DOC]: Vote on oustanding doc issues?

[Alex Chaffee]

Martin van den Bemt wrote:

>>On the topic of a new mailing list:
>>I think we can do the next steps inside the tomcat-dev list or on our
>>own. (BTW, let's use "DOC:" as a prefix so it's easier to scan for new
>>messages.) I want to do this in full view of the rest of the community,
>>mostly so they can see what's going on and volunteer to contribute.
>>
> 
> I prefer [DOC] btw.. replying to a doc issue with DOC: removes the DOC:
> entry. (at least in outlook).


OK.  (See subject of this message.)


>>>2) What is the format (XML, *Book, HTML, etc.) of the
>>>
>>documentation source?
>>
>>>If XML, what DTD?
>>>
>>
>>I propose that we do *NOT* try to answer this yet, or maybe ever.
>>Instead, I propose anarchy: that the Table Of Contents be maintained in
>>a convenient text-editable format. It will contain links to doc files
>>(sections or guides or chapters) that are files in whatever format
>>they're in. I imagine that it will eventually be most convenient to use
>>Anakia, but for now, it means that we don't have to worry about
>>rewriting useful docs that are already in HTML.
>>
> 
> Generating a default output at a certain point is not too bad though. But we
> have to be open enough for people who want to convert this to eg man pages
> or a nice pdf.


Yeah, I guess anarchy will be a little too... anarchic :-)  (Rob S. made 
the point more strongly in his latest message.)

Even if a few documents are unavoidably in wacky PDF or Word, having the 
majority in a single base format would be desirable.

I'm leaning towards Anakia, since it's basically HTML with a few wrapper 
tags, for the chapters (content). We can define a subset of HTML to be 
the "approved" tags, and encourage people to use minimal formatting 
(e.g. use  instead of ) but I'm pretty sure it's 
got the right characteristics. See 
http://jakarta.apache.org/site/jakarta-site-tags.html

If someone is scared of XML, they can submit it to us in text format and 
we can go add tags (as time permits), but we're all developers here, so 
I don't think that's an issue.

 > The main parts and main chapters in seperate subdirs at first?

Let's see. The current TOC (still no comments on it, btw -- I must have 
scared everyone off ;-) has six parts.  I think these translate nicely 
into separate documents or Guides:

I. Standalone Installation Guide
II. Installation Behind a Web Server Guide
III. Deploying and Configuring, or Tomcat Administrator's Guide
IV. Performance Tuning Guide
V. Tomcat Developer's Guide (writing code for Tomcat itself)

I and II may merge, as may III and IV, but I think we're looking at at 
least three major parts. Seems natural that they'd be in separate 
subdirectories.  But...

I'm a big fan of the "throw everything into one package until it gets so 
big you need to refactor" school of organization -- I *hate* wading 
through an infinite number of empty subdirectories that someone thought 
would be filled up some day -- so I'd be happy keeping the file tree one 
level deep for now. That frees us up to reorganize at the drop of a hat 
without painful CVS grooming.


> A vote on a seperate mailinglist for discussing doc issues would be
> appreciated though. It's getting a lot of discussion already and this will
> grow in the near future I think (and hope..). This way we don't miss any of
> the important non-docs specific stuff.


My vote is -1 for a separate mailing list at this point, at least until 
we prove that we're not going to peter out like every other 
documentation effort so far. :-)




-- 
Alex Chaffee   mailto:[EMAIL PROTECTED]
jGuru - Java News and FAQs http://www.jguru.com/alex/
Creator of Gamelan http://www.gamelan.com/
Founder of Purple Technology   http://www.purpletech.com/
Curator of Stinky Art Collective   http://www.stinky.com/