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 <H1> instead of <FONT SIZE=+3><B>) 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/
