tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Alex Chaffee <g...@stinky.com>
Subject Re: [DOC]: Vote on oustanding doc issues?
Date Tue, 10 Jul 2001 01:47:39 GMT
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:alex@jguru.com
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/


Mime
View raw message