You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by Alex Chaffee <gu...@stinky.com> on 2001/07/10 03:47:39 UTC
Re: [DOC]: Vote on oustanding doc issues?
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/
Re: [DOC]: Vote on oustanding doc issues?
Posted by "Craig R. McClanahan" <cr...@apache.org>.
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?
Posted by Alex Chaffee <gu...@stinky.com>.
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: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/
Re: [DOC]: Vote on oustanding doc issues?
Posted by Jon Stevens <jo...@latchkey.com>.
on 7/10/01 4:06 AM, "Rob S." <rs...@home.com> wrote:
> PDF conversion would be pretty cool... Anyone feel like coming up with a
> sheet to generate XSL:FO? =)
We have started that here:
<http://jakarta.apache.org/cvsweb/index.cgi/jakarta-velocity/whiteboard/dave
b/pdfvsl/>
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
AW: [DOC]: Vote on oustanding doc issues?
Posted by Thomas Bezdicek <th...@engnetworld.com>.
> PDF conversion would be pretty cool... Anyone feel like coming up with a
> sheet to generate XSL:FO? =)
No problem, I can help out on this issue
regards, tom
RE: [DOC]: Vote on oustanding doc issues?
Posted by "Rob S." <rs...@home.com>.
> 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