You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by Christopher Cain <cc...@mhsoftware.com> on 2001/07/03 03:04:33 UTC
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocu
mentation Redactors To Hire]
Jon Stevens wrote:
>
> The Tomcat website is already generated with Anakia. It is trivial to add
> more .xml files to the site and there is absolutely no excuse to not just go
> that route.
>
> I just don't see the merits of this discussion. Go write documentation
> instead.
>
> -jon
LOL.
Oh, well then, as long as _Jon_ doesn't see any merits, I guess this is
all just so much fodder. Never mind that the question has not yet been
adequately answered, and is still being constructively debated. Never
mind that some program I never heard of generates the Tomcat site. Never
mind that what happens on the Apache servers has about as much to do
with Tomcat documentation, which is being discussed as a new context
installed with the server, as what I plan on feeding my cat Mittens
tonight. Never mind all that ... Jon has descended from the Ivory tower
with his rather cryptic edict. Once we make sense of this devine wisdom,
we are to proceed immediately and without question.
For someone who loves to speak at great lengths about community
discussions and honoring majority decisions, this is a rather bizzare
tact to say the least. Some of us, including myself, would like for this
discussion to come to a well-considered conclusion so that we can help
out with documentation. Your nonsensical suggestions and irritation at
being bothered with this thread are both completely irrelevant, Ace. I
have no interest in Anakia, and quite frankly, as has been pointed out
very astutely by Costin, I have no interest in bothering with XML for
the purposes of documentation. I will produce HTML docs with my favorite
editor and call it a task adequately completed. Asking anything beyond
that will more than likely be more time and effort than I am prepared to
invest in simple documentation.
In short, let us please continue and decide upon how to proceed.
Regardless of Jon's off-topic confusion, I would really like to know how
the community would like to see any documentation which I may
contribute.
- Christopher
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS:
[TomcatDocumentation Redactors To Hire]
Posted by Jon Stevens <jo...@latchkey.com>.
on 7/3/01 8:04 AM, "Justin Erenkrantz" <je...@ebuilt.com> wrote:
> On Mon, Jul 02, 2001 at 07:38:55PM -0700, Si Ly wrote:
>> I submitted a very simple patch last week, and I haven't heard from
>> anyone about it. It seems to me that "outsiders" (non-committers)
>> can't get anything into CVS because the committers are not looking at
>> the patches, for whatever reasons.
>>
>> Or maybe it's because there are problems with the patches? Even if
>> that's the case, a response would still be appreciated. Otherwise,
>> what encouragement is there for future submissions?
The best place to put patches is into the bug tracking system...
<http://Nagoya.apache.org/bugzilla/>
-jon
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocumentation Redactors To Hire]
Posted by Justin Erenkrantz <je...@ebuilt.com>.
On Mon, Jul 02, 2001 at 07:38:55PM -0700, Si Ly wrote:
> I submitted a very simple patch last week, and I haven't heard from
> anyone about it. It seems to me that "outsiders" (non-committers)
> can't get anything into CVS because the committers are not looking at
> the patches, for whatever reasons.
>
> Or maybe it's because there are problems with the patches? Even if
> that's the case, a response would still be appreciated. Otherwise,
> what encouragement is there for future submissions?
FWIW, if at first you don't succeed in getting a reply, repost your
patch.
I typically wait about a week in between submissions.
After about the third week, I usually drop the patch if no one has
responded. =)
And, please don't take non-responsiveness personally. It is probably
more the case that the people with commit access don't believe that your
problem is worth fixing. You'll need to make a convincing argument to
stop them from hitting the "delete" key when reading the message.
-- justin
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS:
[TomcatDocumentation Redactors To Hire]
Posted by cm...@yahoo.com.
On Mon, 2 Jul 2001, Si Ly wrote:
> I submitted a very simple patch last week, and I haven't heard from
> anyone about it. It seems to me that "outsiders" (non-committers)
> can't get anything into CVS because the committers are not looking at
> the patches, for whatever reasons.
Sorry about that, Larry is in vacation, I'm preparing to go in vacation,
almost everyone is quite busy.
The patch is good, if nobody else get to submit it I'll do that when I
return ( and start again on jasper - I just want to make sure the
connector is in good state so we can finally have the beta ).
Thanks for the patch, sorry for the delay :-(
Costin
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocumentation Redactors To Hire]
Posted by Si Ly <sl...@pobox.com>.
On Tue, Jul 03, 2001 at 03:02:43AM +0100, Pier P. Fumagalli wrote:
> > Documentation is just as valuable as the software...
>
> Probably even more... It allows more dummies to install our software, more
> dummies = more bugs found, more bugs found = more fixes, more fixes = better
> software... Or that's right only in f**ked up mind? :)
It's hard to argue against "more fixes = better software".
I submitted a very simple patch last week, and I haven't heard from
anyone about it. It seems to me that "outsiders" (non-committers)
can't get anything into CVS because the committers are not looking at
the patches, for whatever reasons.
Or maybe it's because there are problems with the patches? Even if
that's the case, a response would still be appreciated. Otherwise,
what encouragement is there for future submissions?
-- Si
Re: [PRE-PROPOSAL] jakarta-tomcat-doc
sub-project:WAS:[TomcatDocumentation Redactors To Hire]
Posted by Christopher Cain <cc...@mhsoftware.com>.
"Geir Magnusson Jr." wrote:
>
[snip]
Most of this was under the assumption that there would be no one
volunteer to dedicate additional time and energy in a little cabal of
people to take the lead on organizing and standardizing Tomcat
documention. Since I have now gone from, "Bah! Don't pester me about
learning Anakia or any other damn thing for simple docs," to, "Cool,
let's organize and standardize this bad boy," and since you are offering
to devote time as well, all my previous grumblings are officially
withdrawn. Under an organized approach, which I will damn well help out
with, I can live with almost any solution.
> > If I am Joe
> > User, and I put together some notes on how I managed to get a connector
> > configured under Windoze 2000, am I likely to try and learn a complex
> > DTD in order to submit it to the project, especially if I have a rather
> > demanding day job? Probably not. Am I likely to download a program,
> > learn it, and generate the right format? Probably not.
>
> Again, I am not sure this parses for me. If you let people submit docs
> in whatever randomly broken variant of HTML their HTML editor generates,
> the submissions will be far less useful than just plain text.
>
> So have a policy :
>
> 0) All documentation is appreciated.
> 1) If you can, submit docs using our XML DTD. It makes it easy to
> integrate into the rest of the documentation. Here is a sample
> template. Fill in the content section.
> 2) If you can't we still appreciate your effort. Please send us notes
> and docs in ASCII text format.
>
> In the beginning of the Velocity project, we had someone dedicated to
> doing documentation. He wasn't technical, but was able to grok what
> needed do be done, and styled and formatted whatever was offered. He
> even watched the mail lists to get examples.
>
> I would be someone might volunteer to be Minister of Documentation...
You and I are in complete agreement here. I had considered that people
would hand-code the HTML, but maybe you're right in that that might be
too much to hope for. God help us all if people start submitting Front
Page-generated docs!
I think your policy suggestion makes perfect sense. Again, as long as
there are people willing to help out with accepting/converting any user
docs instead of simply telling people of varying skill levels to go
learn Anakia or whatever, my reservations about the complexity of the
approach vanish. My statements about keeping it as simple as possible,
possibly HTML, were under the assumption that no one would continue to
be "in charge" of documentation. I just don't want to see it get any
harder for docs to get included in Tomcat ... it's already pretty
hit-and-miss as it is.
> XML isn't that hard. Give it a whirl sometime..
I have a pretty reasonable amount of experience in XML. It wasn't really
a question of knowledge, it was more a question of how much overhead it
would add. I had visions of trying to install and configure some
screwball display parser for half a day just to preview my documentation
in order to get it accepted. Since it appears that I have unwittingly
placed myself into the newly-forming "Ministry of Documentation",
however, I guess that's not much of an issue anymore. =)
Seriously, though, I think your proposal makes sense. I will certainly
assist in this new, more organized approach to TC documentation. As I
said, I have no real opinion about which solution to go with. XML, HTML
(no FrontPage!), DHTML, XHTML ... whatever, I'll let you guys sort it
out. I kinda liked the idea of having it set up as a new context and
installed along with Tomcat, though. That would be pretty hip, and the
idea has merit.
- Christopher "His-love-is-real,-but-his-documentation-is-not" Cain
RE: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project:WAS:[TomcatDocumentation Redactors To Hire]
Posted by "Rob S." <rs...@home.com>.
> Writing XML docs is easy. For doing docs compatible with the 'implied'
> anakia DTD, it's hardly different than HTML.
Agreed... I'm not sure that some of the detractors have checked out the
existing XML docs in Struts. It may as well be XHTML for all its
similarities to HTML.
- r
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project
:WAS:[TomcatDocumentation Redactors To Hire]
Posted by "Geir Magnusson Jr." <ge...@optonline.net>.
Christopher Cain wrote:
>
> "Geir Magnusson Jr." wrote:
> >
> > Documentation is just as valuable as the software...
>
> I could not agree more. What I meant by "simple" documentation is that
> I, personally, do not have to requisite expertise to write in-depth docs
> on the various inner workings of Tomcat. Since there are a fair amount
> of short docs on specific aspects, such as the NT service, running the
> connectors in-process, etc., we should keep in mind that the frequency
> of submissions of such "simple" documentation by users is inversely
> proportionate to the complexity of the solution we choose.
I actually don't follow the logic here.
You said
"I have no interest in bothering with XML for the purposes of
documentation."
Writing XML docs is easy. For doing docs compatible with the 'implied'
anakia DTD, it's hardly different than HTML.
The nice part is that they can be managed and restyled.
> If I am Joe
> User, and I put together some notes on how I managed to get a connector
> configured under Windoze 2000, am I likely to try and learn a complex
> DTD in order to submit it to the project, especially if I have a rather
> demanding day job? Probably not. Am I likely to download a program,
> learn it, and generate the right format? Probably not.
Again, I am not sure this parses for me. If you let people submit docs
in whatever randomly broken variant of HTML their HTML editor generates,
the submissions will be far less useful than just plain text.
So have a policy :
0) All documentation is appreciated.
1) If you can, submit docs using our XML DTD. It makes it easy to
integrate into the rest of the documentation. Here is a sample
template. Fill in the content section.
2) If you can't we still appreciate your effort. Please send us notes
and docs in ASCII text format.
In the beginning of the Velocity project, we had someone dedicated to
doing documentation. He wasn't technical, but was able to grok what
needed do be done, and styled and formatted whatever was offered. He
even watched the mail lists to get examples.
I would be someone might volunteer to be Minister of Documentation...
> Now if a few people on the list are willing to take text and/or HTML
> submissions and generate the "approved" format, then so much the better.
> Since I have now opened my mouth and made a suggestion on what *others*
> should do with their OSS time, I suppose I am more or less volunteering
> to help up in that regard.
Great!
> But my point was simple to caution against an
> over-engineered approach to documentation without a few people stepping
> forward to help "own" Tomcat documentation. Otherwise it will only lead
> to less documentation.
That's not how I read your post. However, I will assume now it was my
misunderstanding and leave it at that.
> > > In short, let us please continue and decide upon how to proceed.
> > > Regardless of Jon's off-topic confusion, I would really like to know how
> > > the community would like to see any documentation which I may
> > > contribute.
> >
> > Didn't you just say that you are going to do it in HTML and declare
> > victory no matter what?
>
> Actually, what I said was that I would declare it a "task adequately
> completed." =)
>
> What I meant to imply was that let's not make generating documentation a
> class project.
What you get if you don't is a mess.
> Like most non-critical software, at the end of the day it
> doesn't really matter how many bells and whistles the solution provides
> if no one has the inclination or the time to learn how to use a complex
> package. We are all programmers, and the easier the solution the more
> likely it is we will deign to actually bother with documentation.
XML isn't that hard. Give it a whirl sometime..
> My delivery was admitedly a little pointed and unclear because I was
> having a little fun with Jon. But that's okay, he loves the abuse. =)
I am sure that's why he dedicates so much time to this.
geir
--
Geir Magnusson Jr. geirm@optonline.net
System and Software Consulting
Developing for the web? See http://jakarta.apache.org/velocity/
You have a genius for suggesting things I've come a cropper with!
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project :
WAS:[TomcatDocumentation Redactors To Hire]
Posted by Christopher Cain <cc...@mhsoftware.com>.
"Geir Magnusson Jr." wrote:
>
> This is deja vu all over again. We should take one copy if this
> discussion (we had the same thing in Commons, and I am sure it happened
> everywhere else...), post it somewhere, and people can just submit
> article numbers or something rather than typing the same arguments over
> and over.
>
> "Yes, I know you feel [21], but [17-19,28]."
>
> It would be so much quicker...
>
> Christopher Cain wrote:
> >
> > being bothered with this thread are both completely irrelevant, Ace. I
> > have no interest in Anakia, and quite frankly, as has been pointed out
> > very astutely by Costin, I have no interest in bothering with XML for
> > the purposes of documentation. I will produce HTML docs with my favorite
> > editor and call it a task adequately completed. Asking anything beyond
> > that will more than likely be more time and effort than I am prepared to
> > invest in simple documentation.
>
> Documentation is just as valuable as the software...
I could not agree more. What I meant by "simple" documentation is that
I, personally, do not have to requisite expertise to write in-depth docs
on the various inner workings of Tomcat. Since there are a fair amount
of short docs on specific aspects, such as the NT service, running the
connectors in-process, etc., we should keep in mind that the frequency
of submissions of such "simple" documentation by users is inversely
proportionate to the complexity of the solution we choose. If I am Joe
User, and I put together some notes on how I managed to get a connector
configured under Windoze 2000, am I likely to try and learn a complex
DTD in order to submit it to the project, especially if I have a rather
demanding day job? Probably not. Am I likely to download a program,
learn it, and generate the right format? Probably not.
Now if a few people on the list are willing to take text and/or HTML
submissions and generate the "approved" format, then so much the better.
Since I have now opened my mouth and made a suggestion on what *others*
should do with their OSS time, I suppose I am more or less volunteering
to help up in that regard. But my point was simple to caution against an
over-engineered approach to documentation without a few people stepping
forward to help "own" Tomcat documentation. Otherwise it will only lead
to less documentation.
> > In short, let us please continue and decide upon how to proceed.
> > Regardless of Jon's off-topic confusion, I would really like to know how
> > the community would like to see any documentation which I may
> > contribute.
>
> Didn't you just say that you are going to do it in HTML and declare
> victory no matter what?
Actually, what I said was that I would declare it a "task adequately
completed." =)
What I meant to imply was that let's not make generating documentation a
class project. Like most non-critical software, at the end of the day it
doesn't really matter how many bells and whistles the solution provides
if no one has the inclination or the time to learn how to use a complex
package. We are all programmers, and the easier the solution the more
likely it is we will deign to actually bother with documentation.
My delivery was admitedly a little pointed and unclear because I was
having a little fun with Jon. But that's okay, he loves the abuse. =)
- Christopher
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS:
[TomcatDocumentation Redactors To Hire]
Posted by "Pier P. Fumagalli" <pi...@betaversion.org>.
Geir Magnusson Jr. at geirm@optonline.net wrote:
>
> Documentation is just as valuable as the software...
Probably even more... It allows more dummies to install our software, more
dummies = more bugs found, more bugs found = more fixes, more fixes = better
software... Or that's right only in f**ked up mind? :)
Pier
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS:
[TomcatDocumentation Redactors To Hire]
Posted by "Geir Magnusson Jr." <ge...@optonline.net>.
This is deja vu all over again. We should take one copy if this
discussion (we had the same thing in Commons, and I am sure it happened
everywhere else...), post it somewhere, and people can just submit
article numbers or something rather than typing the same arguments over
and over.
"Yes, I know you feel [21], but [17-19,28]."
It would be so much quicker...
Christopher Cain wrote:
>
> being bothered with this thread are both completely irrelevant, Ace. I
> have no interest in Anakia, and quite frankly, as has been pointed out
> very astutely by Costin, I have no interest in bothering with XML for
> the purposes of documentation. I will produce HTML docs with my favorite
> editor and call it a task adequately completed. Asking anything beyond
> that will more than likely be more time and effort than I am prepared to
> invest in simple documentation.
Documentation is just as valuable as the software...
> In short, let us please continue and decide upon how to proceed.
> Regardless of Jon's off-topic confusion, I would really like to know how
> the community would like to see any documentation which I may
> contribute.
Didn't you just say that you are going to do it in HTML and declare
victory no matter what?
geir
--
Geir Magnusson Jr. geirm@optonline.net
System and Software Consulting
Developing for the web? See http://jakarta.apache.org/velocity/
You have a genius for suggesting things I've come a cropper with!
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project
:WAS:[TomcatDocumentation Redactors To Hire]
Posted by "Geir Magnusson Jr." <ge...@optonline.net>.
Christopher Cain wrote:
>
> Anyway, since it sounds like Geir has graciously volunteered to help me
> form the "Ministry of Documentation" as he so cleverly coined it, the
> point is more or less moot now. Users can submit plain text if they
> like, and I certainly have no problems learning whatever the community
> decides upon. Everybody wins.
Let me clarify - that was a typo. What I typed read :
"I would be someone might volunteer to be Minister of Documentation..."
and what I was missing was a 't', for it to read
"I would bet someone might volunteer to be Minister of Documentation..."
meaning that Tomcat has a *huge* community of users and developers, and
someone who is a user of Tomcat and talented at writing might offer to
help out like that. As long as the community recognizes that its an
important role, all will be well, especially if you can find someone to
take the lead and assert direction and guidance to the project.
I am willing to help of course as a satisfied Tomcat user, but I cannot
be the Minister. I am too swamped by OSS and professional commitments.
geir
--
Geir Magnusson Jr. geirm@optonline.net
System and Software Consulting
Developing for the web? See http://jakarta.apache.org/velocity/
You have a genius for suggesting things I've come a cropper with!
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project
:WAS:[TomcatDocu mentation Redactors To Hire]
Posted by Jon Stevens <jo...@latchkey.com>.
on 7/3/01 4:00 PM, "Christopher Cain" <cc...@mhsoftware.com> wrote:
> Anyway, I had no idea that Anakia was your product. I will most
> certainly have a look and provide my official critique. Since your
> stance on JSP is dead-on accurate, and I hear that your replacement tool
> is actually something of an improvement, Anakia certainly deserves a
> look.
>
> - Christopher
I want Anakia to stand on its own instead of being "my product" so I don't
hold that out as a carrot for people to munch on.
In reality, what you need to use is the jakarta-site2 module which is an
application built around Anakia. Ie: it is a pre-fabricated .vsl file,
examples and build scripts that allow you to quickly get started creating
documentation. You can also look at the jakarta-tomcat-site module which is
already setup to have the dependency on jakarta-site2.
Like I said before, everything you need to write documentation is already
there...discussing this over and over again is futile.
-jon
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project :WAS:[TomcatDocu
mentation Redactors To Hire]
Posted by Christopher Cain <cc...@mhsoftware.com>.
Jon Stevens wrote:
>
> on 7/3/01 11:50 AM, "Christopher Cain" <cc...@mhsoftware.com> wrote:
>
> > The more (most) people have to
> > try and learn an extensive DTD or templating system, the less likely
> > they are to bother.
>
> I agree. That is why I came up with Anakia. It is brain dead simple to use
> and runs extremely quickly. The "DTD" is a few simple XML tags and XHTML.
>
> I suggest that before you make any more comments, you spend some time
> looking at it.
The statement you quoted me on above was a caution in the abstract about
standardizing on a complicated approach without having a few people
willing to process user contributions, primarily so that we don't
discourage such contributions. It was not directed at Anakia in
particular, hence the "or templating system." As I said, there are at
least three different suggestions floating around out there, so this was
simply my two cents on things to consider when deciding. I have
absolutely no experience with any of the proposed products, nor have I
ever pretended to.
Anyway, since it sounds like Geir has graciously volunteered to help me
form the "Ministry of Documentation" as he so cleverly coined it, the
point is more or less moot now. Users can submit plain text if they
like, and I certainly have no problems learning whatever the community
decides upon. Everybody wins.
Really, my man ... if you're going to take me to task on something,
you're going to have to learn not to quote me out of context. It's so
passe. For future reference, I never criticize an approach or product,
especially on a dev list, without thoroughly edifying myself on the
subject. (Yes, you can quote me on that. ) If you ever think that I
have, then you have misunderstood me.
Anyway, I had no idea that Anakia was your product. I will most
certainly have a look and provide my official critique. Since your
stance on JSP is dead-on accurate, and I hear that your replacement tool
is actually something of an improvement, Anakia certainly deserves a
look.
- Christopher
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project :
WAS:[TomcatDocu mentation Redactors To Hire]
Posted by Jon Stevens <jo...@latchkey.com>.
on 7/3/01 11:50 AM, "Christopher Cain" <cc...@mhsoftware.com> wrote:
> The more (most) people have to
> try and learn an extensive DTD or templating system, the less likely
> they are to bother.
I agree. That is why I came up with Anakia. It is brain dead simple to use
and runs extremely quickly. The "DTD" is a few simple XML tags and XHTML.
I suggest that before you make any more comments, you spend some time
looking at it.
:-)
-jon
--
If you come from a Perl or PHP background, JSP is a way to take
your pain to new levels. --Anonymous
<http://jakarta.apache.org/velocity/ymtd/ymtd.html>
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS:[TomcatDocu
mentation Redactors To Hire]
Posted by Christopher Cain <cc...@mhsoftware.com>.
Jon Stevens wrote:
>
> on 7/2/01 6:04 PM, "Christopher Cain" <cc...@mhsoftware.com> wrote:
>
> > I
> > have no interest in Anakia, and quite frankly, as has been pointed out
> > very astutely by Costin, I have no interest in bothering with XML for
> > the purposes of documentation. I will produce HTML docs with my favorite
> > editor and call it a task adequately completed. Asking anything beyond
> > that will more than likely be more time and effort than I am prepared to
> > invest in simple documentation.
>
> I bet you will only use a certain brand of toilet paper as well.
Dunno. I let me girlfriend handle the tough decisions like that =)
> > In short, let us please continue and decide upon how to proceed.
> > Regardless of Jon's off-topic confusion, I would really like to know how
> > the community would like to see any documentation which I may
> > contribute.
> >
> > - Christopher
>
> That's good, cause I haven't seen you contribute anything so far, Ace.
>
> The answer is simple...
>
> <?xml version="1.0"?>
> <document>
> <properties>
> <author email="ccain@mhsoftware.com">Christopher Cain</author>
> <title>Cain's Documentation</title>
> </properties>
> <body>
>
> <section name="Recent News">
> <p>
> Mr. Cain actually writes a bit of documentation instead of threatening us
> with the idea that he might do it someday if we are lucky.
> </p>
> </section>
>
> </body>
> </document>
>
> :-)
>
> -jon
Touche' ... that's fair. I have a small cache of docs that I never got
around to submitting, partly because they are install/config docs (and
the Tomcat install procedure has always been a moving target) and partly
out of sheer laziness. I will bring them up to date and cast them to the
dogs (tomcats?) before the next milestone.
There now at least three different approaches being tossed around. As
long as we come to one standardized solution, which I think is
important, I'm personally pretty doc-program agnostic. If the XML
solution being considered is as comparatively non-labor-intensive as the
rather insightful example above, then you might indeed be lucky enough
to have the gift of my documentation bestowed upon you =).
My point, badly made to be sure, was simply that it would be a good idea
to avoid over-engineering a doc solution. The more (most) people have to
try and learn an extensive DTD or templating system, the less likely
they are to bother. I have a feeling that there is an untapped wealth of
docs and notes sitting around out there, written by admins and users for
their own benefit in installation/configuration. The easier we make it,
the more contributions we will undoubtedly receive.
If a cohesive documentation system is decided upon, I would love to
start contributing. I personally agree with Pier that documentation is
easily as important than the product itself. I was very pleasantly
surprised to see a thread seriously discussing the issue of the current
"catch-as-catch-can" docs, and I got a little tweaked when it appeared
that it would flame out without resolution. For all my criticism of you
Jon, I do have to give you props on one thing. Of all the dev-list
bullies I know, you are the only one who can take as much heat as you
give, and do it with a smile. Plus most of the other bullies are so
hopelessly overmatched in verbal exchanges that it almost isn't any fun.
But you got flair, baby! =)
- Christopher
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS:
[TomcatDocu mentation Redactors To Hire]
Posted by Jon Stevens <jo...@latchkey.com>.
on 7/2/01 6:04 PM, "Christopher Cain" <cc...@mhsoftware.com> wrote:
> I
> have no interest in Anakia, and quite frankly, as has been pointed out
> very astutely by Costin, I have no interest in bothering with XML for
> the purposes of documentation. I will produce HTML docs with my favorite
> editor and call it a task adequately completed. Asking anything beyond
> that will more than likely be more time and effort than I am prepared to
> invest in simple documentation.
I bet you will only use a certain brand of toilet paper as well.
> In short, let us please continue and decide upon how to proceed.
> Regardless of Jon's off-topic confusion, I would really like to know how
> the community would like to see any documentation which I may
> contribute.
>
> - Christopher
That's good, cause I haven't seen you contribute anything so far, Ace.
The answer is simple...
<?xml version="1.0"?>
<document>
<properties>
<author email="ccain@mhsoftware.com">Christopher Cain</author>
<title>Cain's Documentation</title>
</properties>
<body>
<section name="Recent News">
<p>
Mr. Cain actually writes a bit of documentation instead of threatening us
with the idea that he might do it someday if we are lucky.
</p>
</section>
</body>
</document>
:-)
-jon
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocu
mentation Redactors To Hire]
Posted by "Craig R. McClanahan" <cr...@apache.org>.
On Sat, 7 Jul 2001 guru@stinky.com wrote:
> On Fri, Jul 06, 2001 at 10:06:21PM -0700, Craig R. McClanahan wrote:
> >
> > * Docs should live in the source tree of the project that they
> > are about. Although Henri's suggestion for jakarta-tomcat-docs
> > is noble, what you'll find in practice is that there is very little
> > documentation that is relevant across multiple versions of Tomcat.
>
> That remains to be seen. My gut tells me the opposite. I'm thinking
> connectors, classpath issues (though some details are different with
> Catalina, a lot are the same),
Although the concepts of the issues above are similar, the details are
very different.
> web.xml docs, authentication,
These are the same because they are application-related (i.e. portable
because of the servlet spec) not Tomcat-related. In principle, anything
we write about this should apply to any servlet container.
> performance-tuning a web app...
That's a huge area, and may be somewhat ambitious. But, again, most of
this would be portable to any servlet container, not just Tomcat.
> I'd love to get your input on the
> outline I just posted if you get around to it -- tell me which
> sections are definitely different between 3 and 4.
>
Could you repost the most recent version of the proposed outline? My
delete key got a little sticky, and I accidentally deleted the most recent
version last night.
Just for interest's sake, here's the list of "user" things in Tomcat 4.0
that are new (relative to 3.2), cribbed from my JavaOne talk:
* Access logs (web-server style)
* CGI support
* Configurable realms at Engine, Host, and Context levels, including
JNDIRealm.
* Container-managed security (DIGEST and CLIENT-CERT modes,
plus single sign on support)
* "Default Context" configuration
* HTTP/1.1 support in stand-alone mode
* JNDI naming context support (including support for configuring
<env-entry> and <resource-ref> mappings, JDBC connection pooling,
and extensible object factories).
* "Manager" web app
* MOD_WEBAPP
* Request filtering valves (accept/deny based on client hostname
or IP address)
* Run directly from war file
* Server side includes (*.shtml)
* User web apps (http://www.mycompany.com/~craigmcc)
Now, picture yourself installing Tomcat 3.2 (because it's the current
production version). Do you *really* want to wade through the docs on all
of the above, which is totally irrelevant to your needs, just because we
put the docs for all versions in one file? To say nothing about all the
things that were present in 3.2 but are configured differently in 4.0 ...
> The current situation with the docs on the site for 3.2 and 3.3
> illustrate the problem with fragmenting two doc trees that are
> actually very similar.
Nearly everything important about configuring Tomcat is different
anyway. The only "common" stuff is the App Dev Guide. As has been
discussed, that probably makes sense in a common docs directory (until you
have do decide whether or not to cover both versions of the specs --
servlet 2.2/2.3 and JSP 1.1/1.2 -- in the same docs :-). But, if it's
separate, you've also got to figure out how you're going to "release" it.
> Any reorganization or new docs or error fixing
> will need to be propagated back to the 3.2 branch,
Why?
The code is in maintenance mode -- I don't see a problem with the docs
being in maintenance mode as well.
Of course, anyone who *wants* to do this is welcome to do so, but I don't
see it as a prerequisite.
> which will be a
> terror to maintain. I feel the same thing could easily happen with
> 4.0 vs 4.1 in the near future.
>
Not if we get started with a nice disciplined source directory
structure. That's why this discussion is so timely.
Not when you remember that the 4.0->4.1 changes won't be a complete
rearchitecting (at least to the extent that people listen to me :-), the
way that 3.2->3.3 turned out to be.
Not when you remember that 4.0 will go into maintenance mode when 4.1 is
released, so we can focus energies (both code and docs) on the current
version.
But 4.1 *will* be different than 4.0. So there will need to be a way
to produce the docs for 4.1 *only* -- by that time, users won't care how
4.0 worked, either.
IMHO, trying to mix docs for multiple versions in the same document set
is a receipie for disaster -- for reasons that I articulated last
night, plus the fact that people only care about the version they are
installing.
It's fine to have "comparative features" sorts of docs in some separate
(common) docs repository, along with the App Dev Guide type stuff that is
also common. But that's maybe three-to-five pages worth of stuff -- good,
comprehensive docs on something like Tomcat is going to be more in the low
hundreds of pages (depending, of course, on how fine-grained we decide to
make it), for any given version.
> > * The files that are checked in should only be the XML sources, *not* the
> > generated files. This varies from what Jon set up in jakarta-site2,
> > based on long and drawn out earlier discussions (same issues as those
> > surrounding checking JAR files into CVS :-).
>
> +1
>
> .xml = .java, .html = .class
> ./build.sh docs would generate the html directory
>
>
> --
> Alex Chaffee mailto:alex@jguru.com
Craig
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocu mentation Redactors To Hire]
Posted by gu...@stinky.com.
On Fri, Jul 06, 2001 at 10:06:21PM -0700, Craig R. McClanahan wrote:
>
> * Docs should live in the source tree of the project that they
> are about. Although Henri's suggestion for jakarta-tomcat-docs
> is noble, what you'll find in practice is that there is very little
> documentation that is relevant across multiple versions of Tomcat.
That remains to be seen. My gut tells me the opposite. I'm thinking
connectors, classpath issues (though some details are different with
Catalina, a lot are the same), web.xml docs, authentication,
performance-tuning a web app... I'd love to get your input on the
outline I just posted if you get around to it -- tell me which
sections are definitely different between 3 and 4.
The current situation with the docs on the site for 3.2 and 3.3
illustrate the problem with fragmenting two doc trees that are
actually very similar. Any reorganization or new docs or error fixing
will need to be propagated back to the 3.2 branch, which will be a
terror to maintain. I feel the same thing could easily happen with
4.0 vs 4.1 in the near future.
> * The files that are checked in should only be the XML sources, *not* the
> generated files. This varies from what Jon set up in jakarta-site2,
> based on long and drawn out earlier discussions (same issues as those
> surrounding checking JAR files into CVS :-).
+1
.xml = .java, .html = .class
./build.sh docs would generate the html directory
--
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: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocu mentation Redactors To Hire]
Posted by Aaron Bannert <aa...@ebuilt.com>.
On Sat, Jul 07, 2001 at 05:11:04PM -0700, Pier Fumagalli wrote:
> Quoting Aaron Bannert <aa...@ebuilt.com>:
> >
> > d) jakarta-tomcat-connectors (* Pier is working on this, I've
> > submitted
>
> Hold it... Pier is working on the new build for the WebApp Module, and the
> documentation related to it... I never said I'm going to take care of the
> documentation of all jakarta-tomcat-connectors :) :) :)
Whoops, sorry. I knew that, but it slipped out. :)
-aaron
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocu mentation Redactors To Hire]
Posted by Pier Fumagalli <pi...@betaversion.org>.
Quoting Aaron Bannert <aa...@ebuilt.com>:
>
> d) jakarta-tomcat-connectors (* Pier is working on this, I've
> submitted
Hold it... Pier is working on the new build for the WebApp Module, and the
documentation related to it... I never said I'm going to take care of the
documentation of all jakarta-tomcat-connectors :) :) :)
Pier
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocu
mentation Redactors To Hire]
Posted by "Craig R. McClanahan" <cr...@apache.org>.
On Sat, 7 Jul 2001, Aaron Bannert wrote:
> On Sat, Jul 07, 2001 at 09:25:46AM -0700, Craig R. McClanahan wrote:
> > Yes, we obviously need pointers in a top-level README on "where the docs
> > went".
>
> I'm willing to collaborate on these types of docs. On a slight tangent,
> I'd like to point out that we could use more STATUS and README documents,
> if only to serve the purpose of a signpost for current and new developers.
>
> *Every* CVS module that is a work-in-progress should have some sort of
> STATUS document, as well as a README describing what the repository
> contains. The first serves as a road map for any new developers who
> want to get into the source. The second serves as a roadmap for new
> builders/testers who want to know what the heck they're looking at.
>
>
> > Also, on my list of "high level" desires, I forgot to include one:
> >
> > * All of the Tomcat documentation should be visible online at the Tomcat
> > web site.
> >
> > which can (at least partially) deal with Alex's "how do you set up the
> > VCR" issue :-).
>
> ( s/Alex/Aaron/ :)
>
Sorry about that ... too many "A-list" people today :-)
> That will partially satisfy me, but not everyone has fully-connected
> high-speed internet access and graphical browsers (at least not while
> they're trying to get Tomcat working). I'd still like to push for plain
> text documentation for each of the following:
>
> 0) README and STATUS in each of
> a) jakarta-tomcat-4.0
> b) jakarta-regexp
> c) jakarta-servletapi-4
> d) jakarta-tomcat-connectors (* Pier is working on this, I've submitted
> the beginnings of a README)
> e) "the various TC3.x repositories that I'm less familiar with"
>
> 1) build instructions for each. Not extensive, just simple bootstrapping
> instructions, maybe even just in the README.
>
> 2) [basic] configuration instructions. Again, not extensive, but enough
> to get it up. Maybe a recipe that would answer questions like:
> a) What goes in server.xml?
> b) How do I start/stop TC?
> c) What must be already installed in order to run TC? (JDK version, etc...)
>
It definitely makes sense to have enough "how to get started" stuff in
plain text README form to get a newbie going.
Hmm, if we can transform XML->HTML, maybe we can just use a different
stylesheet (or set of Anakia macros) and transform XML->TXT as well .....
>
> Who's with me on this? I can submit an outline for each and let the people
> with more experience fill in the blanks.
>
>
> > > 2) Why have the docs as a web app? I'm not sure I see the benefits yet,
> > > aside from being able to have a pointer to the docs from the ROOT/index
> > > page.
> > >
> >
> > A couple of reasons:
> >
> > * Because we already do -- and it's quite convenient to be able to
> > look at the docs once you get Tomcat started the first time. The
> > problem today is that we are really overloading the ROOT web app,
> > and it's not particularly well organized.
>
> I totally agree that it is convenient, but it may be harder for us to
> realize the difficulty in getting this beast rolling the first time
> from our altitude. We want every college student who has ever had any
> interest in Servlets/JSP running this thing on their home Linux/*BSD/WinXX
> (*gag*) machine, and they're only going to do that if the barrier to
> entry is well defined.
>
As a side comment on this topic, Tomcat 4 installation and administration
is going to directly benefit from Sun's JavaOne announcement about the Web
Services Pack (which will include Tomcat). In particular, my team at Sun
is going to put some serious developer hours into these areas, and the
vast majority of the resulting code will work just fine for a stand-alone
download of Tomcat from Apache as well.
By the way, one of the current XML docs
(catalina/docs/dev/xdocs/fs-admin-apps.xml) is a proposed set of high
level functional requirements for administrative apps for Tomcat 4.
Developers interested in this topic are encouraged to read it and
suggest improvements.
Sun is also increasing the number of folks writing and executing tests of
Tomcat 4 features (beyond the issues of spec compliance). In order to do
this, the test writers need a description of what correct behavior is --
so one of the things I will personally be working on is "functional
specs" type docs for the various existing features (such as the fs-*.xml
files in the same directory as the admin apps doc). That's why I'm quite
happy to see a discussion about documentation formats and tools happen
now. The net result will be a substantial increase in the amount of
useful "internals" documentation about how Tomcat 4 is put together.
> -aaron
>
>
Craig
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocu mentation Redactors To Hire]
Posted by Aaron Bannert <aa...@ebuilt.com>.
On Sat, Jul 07, 2001 at 09:25:46AM -0700, Craig R. McClanahan wrote:
> Yes, we obviously need pointers in a top-level README on "where the docs
> went".
I'm willing to collaborate on these types of docs. On a slight tangent,
I'd like to point out that we could use more STATUS and README documents,
if only to serve the purpose of a signpost for current and new developers.
*Every* CVS module that is a work-in-progress should have some sort of
STATUS document, as well as a README describing what the repository
contains. The first serves as a road map for any new developers who
want to get into the source. The second serves as a roadmap for new
builders/testers who want to know what the heck they're looking at.
> Also, on my list of "high level" desires, I forgot to include one:
>
> * All of the Tomcat documentation should be visible online at the Tomcat
> web site.
>
> which can (at least partially) deal with Alex's "how do you set up the
> VCR" issue :-).
( s/Alex/Aaron/ :)
That will partially satisfy me, but not everyone has fully-connected
high-speed internet access and graphical browsers (at least not while
they're trying to get Tomcat working). I'd still like to push for plain
text documentation for each of the following:
0) README and STATUS in each of
a) jakarta-tomcat-4.0
b) jakarta-regexp
c) jakarta-servletapi-4
d) jakarta-tomcat-connectors (* Pier is working on this, I've submitted
the beginnings of a README)
e) "the various TC3.x repositories that I'm less familiar with"
1) build instructions for each. Not extensive, just simple bootstrapping
instructions, maybe even just in the README.
2) [basic] configuration instructions. Again, not extensive, but enough
to get it up. Maybe a recipe that would answer questions like:
a) What goes in server.xml?
b) How do I start/stop TC?
c) What must be already installed in order to run TC? (JDK version, etc...)
Who's with me on this? I can submit an outline for each and let the people
with more experience fill in the blanks.
> > 2) Why have the docs as a web app? I'm not sure I see the benefits yet,
> > aside from being able to have a pointer to the docs from the ROOT/index
> > page.
> >
>
> A couple of reasons:
>
> * Because we already do -- and it's quite convenient to be able to
> look at the docs once you get Tomcat started the first time. The
> problem today is that we are really overloading the ROOT web app,
> and it's not particularly well organized.
I totally agree that it is convenient, but it may be harder for us to
realize the difficulty in getting this beast rolling the first time
from our altitude. We want every college student who has ever had any
interest in Servlets/JSP running this thing on their home Linux/*BSD/WinXX
(*gag*) machine, and they're only going to do that if the barrier to
entry is well defined.
-aaron
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
Re: [DOC]: Vote on oustanding doc issues?
Posted by Alex Chaffee <gu...@stinky.com>.
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/
DOC: Re: Vote on oustanding doc issues?
Posted by Martin van den Bemt <mv...@mvdb.com>.
> 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).
> (Martin's notes-gathering list is a good idea, but I think a bit
> premature, given issues like what the topics are and what format they
> need to be in. I definitely don't want substantive discussion to happen
> on his lists (see prior para.))
The lists are not for discussion and especially not these discussions.. They
should contain notes! Good idea, a hey, mail to one of the lists (you don't
have to be a member).
The format needs to be discussed indeed. My "proposal" on that wasn't really
usefull and too complicated.
> > on these two things? Are we ready to do that yet?
>
> I don't want to rush it.
Better do it correct the first time.
>
> > 1) Tomcat documentation per-project or in a single repository?
> >
>
> (Personally, I'm leaning towards yes on all 3, but I'm not quite sure.)
I agree completely. Don't think we must start this in a current cvs root.
> > 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.
The main parts and main chapters in seperate subdirs at first?
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.
> Organizing the TOC and and assigning volunteer authors to write parts is
> much more important than file format right now.
I already volunteerd for the gathering notes ;)
> > Once we know these two things, we can get to work. Of course
> there will be
> > discussion on these points, but I'd like to bring them to a close sooner
> > than later, so we can keep moving on with things like the TOC.
>
> We can work on the TOC independently of resolving those other issues.
As long everything is stays flexible enough, we don't want to spend 80% of
our time in generating docs in whatever format. In the beginning we probably
will only be complementry to current documentation until we are grown up
enough to be the source for documentation on tomcat releases. This leaves
room for experimenting with what works best.
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.
Mvgr,
Martin
Re: [DOC] Vote on oustanding doc issues?
Posted by Adam Fowler <af...@aber.ac.uk>.
Ah-ha! the culprit!!! 8o)
Adam.
On Friday 13 July 2001 03:36, you wrote:
> Adam Fowler at aff9@aber.ac.uk 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?
Posted by "Pier P. Fumagalli" <pi...@betaversion.org>.
Adam Fowler at aff9@aber.ac.uk 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?
Posted by Adam Fowler <af...@aber.ac.uk>.
*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: adamfowler@chillin.co.uk
----
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?
Posted by Alex Chaffee <gu...@stinky.com>.
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: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 "Rob S." <rs...@home.com>.
> 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?
Posted by "Craig R. McClanahan" <cr...@apache.org>.
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?
Posted by Alex Chaffee <gu...@stinky.com>.
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: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 "Rob S." <rs...@home.com>.
> 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! +111111111 (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?
Posted by Alex Chaffee <gu...@stinky.com>.
Rob S. wrote:
> Preamble: <grumble> <grumble> =)
>
>
>>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.
>
> <grumble grumble> =)
No, I think we're making progress.
--
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: Re: Vote on oustanding doc issues?
Posted by "Rob S." <rs...@home.com>.
Preamble: <grumble> <grumble> =)
> 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.
> 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.
> 1b) Should Tomcat 3.x documentation be rolled together with Tomcat 4.x
> documentation?
>
> 1c) Should there be a separate CVS repository for Tomcat Documentation
> that is separate from jakarta-tomcat and jakarta-tomcat-4.0?
Depends on if there is something that should be factored out from the
documentation. From what we've seen so far, aside from Craig's dev guide,
the answer is "not much".
> 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.
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...
> Organizing the TOC and and assigning volunteer authors to write parts is
> much more important than file format right now.
Agreed, but the decision needs to be made. I don't want to start discussing
something the moment we need it.
> 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.
<grumble grumble> =)
- r
DOC: Re: Vote on oustanding doc issues?
Posted by Alex Chaffee <gu...@stinky.com>.
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.
(Martin's notes-gathering list is a good idea, but I think a bit
premature, given issues like what the topics are and what format they
need to be in. I definitely don't want substantive discussion to happen
on his lists (see prior para.))
Rob S. wrote:
> Not to be pushy or anything, but I'd like to get these settled quickly so we
> can get down to writing some docs =) Does a committer want to call a vote
> on these two things? Are we ready to do that yet?
I don't want to rush it.
> 1) Tomcat documentation per-project or in a single repository?
>
This is actually three separate questions, and I don't think any are
quite ready for a vote yet:
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?
1b) Should Tomcat 3.x documentation be rolled together with Tomcat 4.x
documentation?
1c) Should there be a separate CVS repository for Tomcat Documentation
that is separate from jakarta-tomcat and jakarta-tomcat-4.0?
(Currently, there's a src/doc subdirectory in the jakarta-tomcat
repository that would work just fine (especially if the answer to 1b is
"no.") OTOH, it might be nice to get a fresh slate, our own build.xml, etc.)
(Personally, I'm leaning towards yes on all 3, but I'm not quite sure.)
> 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.
Organizing the TOC and and assigning volunteer authors to write parts is
much more important than file format right now.
> Once we know these two things, we can get to work. Of course there will be
> discussion on these points, but I'd like to bring them to a close sooner
> than later, so we can keep moving on with things like the TOC.
We can work on the TOC independently of resolving those other issues.
--
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: Vote on oustanding doc issues?
Posted by Christopher Cain <cc...@mhsoftware.com>.
I was out of town for the holiday, so I have just read almost all of
this ex post facto. It looks like there are quite a few people, myself
included, willing to devote an appreciable amount of time to an informal
new group of "doc wrangers." When I originally jumped into this thread
early on, I had no idea that there were so many people ready to help
out. That the Tomcat list has so many people truly interested in
providing users with extensive and well-organized documentation only
speaks to the quality of the Tomcat developer community. Hell, most OSS
projects would be arguing over whether there would be enough internal
effort to even warrant a separate docs sub-project. The fact that this
is a foregone conclusion with Tomcat, and that we are actually debating
whether or not it makes logical sense, is really quite impressive when
you stop and think about it.
Anyway, I agree with Rob. I would like to see a committer bring at least
#1 to a vote at this point. That way we can at least get the directories
in place, where we can then start shuffling all existing docs into an
organized location (or locations) and go from there. Alex has graciously
agreed to be the current Czar, and based on his work at jGuru, I think
we should *definitely* take him up on that. He and Rob seem to have a
sensible Master Plan(tm) with the TOC. With #1 out of the way, at least
people can start sending in whatever is out there. Once our fearless
Czar consolidates that, we'll can get a good idea of where we stand. The
rest (doc format, to webapp or not to webapp, fine tuning the TOC, etc.)
can follow later. I think that once we have something tangible (the
repositories), everything else will start to take shape quite nicely. A
vote on #1 will also, through the resulting +1's vs. +0's, give us an
idea of exactly how many contributors this new cabal will have. The more
people who answer the roll call, the fancier and more extensive we can
get when dicussing the TOC.
Regards,
Christopher
"Rob S." wrote:
>
> Not to be pushy or anything, but I'd like to get these settled quickly so we
> can get down to writing some docs =) Does a committer want to call a vote
> on these two things? Are we ready to do that yet?
>
> 1) Tomcat documentation per-project or in a single repository?
>
> 2) What is the format (XML, *Book, HTML, etc.) of the documentation source?
> If XML, what DTD?
>
> Okay, you can't really vote on the second I one I guess =) Hmm... what to
> do? Personally I'd like to use something XML-like, but close to HTML. It
> would require less documentation (re: tags) and less work than HTML to
> author docs, meaning hopefully more people would do it, more often. If
> that's Anakia, whatever. If it's XML with some other DTD, whatever.
>
> Once we know these two things, we can get to work. Of course there will be
> discussion on these points, but I'd like to bring them to a close sooner
> than later, so we can keep moving on with things like the TOC.
>
> - r
Vote on oustanding doc issues?
Posted by "Rob S." <rs...@home.com>.
Not to be pushy or anything, but I'd like to get these settled quickly so we
can get down to writing some docs =) Does a committer want to call a vote
on these two things? Are we ready to do that yet?
1) Tomcat documentation per-project or in a single repository?
2) What is the format (XML, *Book, HTML, etc.) of the documentation source?
If XML, what DTD?
Okay, you can't really vote on the second I one I guess =) Hmm... what to
do? Personally I'd like to use something XML-like, but close to HTML. It
would require less documentation (re: tags) and less work than HTML to
author docs, meaning hopefully more people would do it, more often. If
that's Anakia, whatever. If it's XML with some other DTD, whatever.
Once we know these two things, we can get to work. Of course there will be
discussion on these points, but I'd like to bring them to a close sooner
than later, so we can keep moving on with things like the TOC.
- r
RE: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocu
mentation Redactors To Hire]
Posted by "Craig R. McClanahan" <cr...@apache.org>.
On Sat, 7 Jul 2001, Rob S. wrote:
> > Providing Tomcat documentation in a WAR file is a little like providing
> > a VHS tape on how to setup your VCR. It may seem really elegant to have
> > on-the-fly style-generating documentation, and I may be alone on this,
> > but I think that the majority of the user-oriented documentation should
> > just be plain text. (By 'user-oriented documentation' I specifically
> > mean build instructions and deployment configuration docs).
>
> It would be in a WAR file as HTML. The build would do the transformation
> and create the WAR file.
>
> Two things:
>
> 1) Users may be confused as to "where the docs went" if they don't see a
> /docs directory. Solution (one of many): have /docs/readme.txt with a
> pointer back to /INSTALL.txt. A quick-install guide would be pretty
> short...
>
Yes, we obviously need pointers in a top-level README on "where the docs
went".
Also, on my list of "high level" desires, I forgot to include one:
* All of the Tomcat documentation should be visible online at the Tomcat
web site.
which can (at least partially) deal with Alex's "how do you set up the
VCR" issue :-).
> 2) Why have the docs as a web app? I'm not sure I see the benefits yet,
> aside from being able to have a pointer to the docs from the ROOT/index
> page.
>
A couple of reasons:
* Because we already do -- and it's quite convenient to be able to
look at the docs once you get Tomcat started the first time. The
problem today is that we are really overloading the ROOT web app,
and it's not particularly well organized.
* Implicitly, I think we've been agreeing that the *output* format is
HTML. Using plain text just doesn't cut it when you want to create
links to other portions of the docs, or include images beyond what
you can do in ASCII art. In essence, a web app is just a documentation
directory with a little extra stuff (WEB-INF/*) that is not really much
different than any other project that chooses HTML format for its docs.
It's just in "webapps/docs" instead of "docs" in the binary distro.
> - r
>
>
Craig
RE: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocu mentation Redactors To Hire]
Posted by "Rob S." <rs...@home.com>.
> Providing Tomcat documentation in a WAR file is a little like providing
> a VHS tape on how to setup your VCR. It may seem really elegant to have
> on-the-fly style-generating documentation, and I may be alone on this,
> but I think that the majority of the user-oriented documentation should
> just be plain text. (By 'user-oriented documentation' I specifically
> mean build instructions and deployment configuration docs).
It would be in a WAR file as HTML. The build would do the transformation
and create the WAR file.
Two things:
1) Users may be confused as to "where the docs went" if they don't see a
/docs directory. Solution (one of many): have /docs/readme.txt with a
pointer back to /INSTALL.txt. A quick-install guide would be pretty
short...
2) Why have the docs as a web app? I'm not sure I see the benefits yet,
aside from being able to have a pointer to the docs from the ROOT/index
page.
- r
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocu mentation Redactors To Hire]
Posted by Aaron Bannert <aa...@ebuilt.com>.
On Fri, Jul 06, 2001 at 10:06:21PM -0700, Craig R. McClanahan wrote:
> * Tomcat docs for a particular version should be delivered as one or more
> web apps (not necessarily the root webapp as is current practice). That
> way, the corresponding WAR files could be dropped into *any* container,
> or opened up and read directly from the filesystem.
>
> * At least two documentation webapps (developer-oriented and
> user-oriented) would seem to be appropriate. Having more than two
> will make it difficult to create reliable hyperlinks (since you don't
> have any control over the context path that someone uses to deploy).
Although I find the rest of your comments on this topic both clear and
refreshing, I'd like to point out a possible fallacy here:
Providing Tomcat documentation in a WAR file is a little like providing
a VHS tape on how to setup your VCR. It may seem really elegant to have
on-the-fly style-generating documentation, and I may be alone on this,
but I think that the majority of the user-oriented documentation should
just be plain text. (By 'user-oriented documentation' I specifically
mean build instructions and deployment configuration docs).
Just my 2c,
-aaron
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS:
[TomcatDocu mentation Redactors To Hire]
Posted by "Pier P. Fumagalli" <pi...@betaversion.org>.
Jon Stevens at jon@latchkey.com wrote:
>
> +1 on both points. Anakia isn't gods solution yet, but it does the job just
> fine for about 10 different Jakarta projects and like Pier says...if someone
> comes up with a better solution tomorrow, it is easy to switch to it.
That's why I _love_ XML so much... Almost like Java... You find a better
OS/VM combination, just throw away all your old stuff and move onto the new
platform...
As Duncan used to say: "Java, portable code. XML, portable data."
> p.s. The main apache.org site will soon be generated with Anakia as well.
That's so cool... Ok, Jon... Before you actually do it, we _need_ to find a
solution for mirrors (relative links for static stuff, absolute links for
CGIs and Servlets)
Pier
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS:
[TomcatDocu mentation Redactors To Hire]
Posted by Jon Stevens <jo...@latchkey.com>.
on 7/2/01 6:45 PM, "Pier P. Fumagalli" <pi...@betaversion.org> wrote:
> Anakia has been proven to be a good option when it came down to the problem
> of building our website, and thank god that Jon made it... And so, by big +1
> on using Anakia for our docs...
>
> (And if something gets out in the future which is better - I'm not implying
> anything here - we can decide whether to switch or not... That's the f**king
> good part of XML :)
>
> Pier
+1 on both points. Anakia isn't gods solution yet, but it does the job just
fine for about 10 different Jakarta projects and like Pier says...if someone
comes up with a better solution tomorrow, it is easy to switch to it.
p.s. The main apache.org site will soon be generated with Anakia as well.
-jon
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS:
[TomcatDocu mentation Redactors To Hire]
Posted by "Pier P. Fumagalli" <pi...@betaversion.org>.
Rob S. at rslifka@home.com wrote:
> This seems to be one of the questions that comes up and never gets answered
> (re: docs, not Jon's behavior ;) I'm not sure what magical solution will
> get people to read docs. Frankly, I'd just like to get started. Anakia
> works for Jakarta, it works for Struts ==> it'll probably work for Catalina.
>
> Committers, [VOTE] on this?
Personally, I don't think that Anakia is the _best_ solution ever invented,
and Jon knows that I prefer XSLT to Velocity syntaxes, but so far there is
no alternative option (don't even consider using StyleBook, OK? I wrote it
and I deprecated it long time ago).
Anakia has been proven to be a good option when it came down to the problem
of building our website, and thank god that Jon made it... And so, by big +1
on using Anakia for our docs...
(And if something gets out in the future which is better - I'm not implying
anything here - we can decide whether to switch or not... That's the f**king
good part of XML :)
Pier
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocumentation Redactors To Hire]
Posted by Punky Tse <pu...@yahoo.com>.
>
> "Developer" in the sense of this sentence is a Tomcat
> developer. "User" is the people that just want to download, install,
> configure, and utilize Tomcat as a servlet container.
>
Agree. That's why I suggested that we need to separate Developer Guide from
User/Administrator Guide. I believed that the "User" community is much
larger than "Developer" comunity. Hence, the 1st priority must go into
writing the User/Administrator Guide first.
I also agreed that we don't really need web application guide. As someone
say (Criag ?), all the web application development is almost the same across
different containers. What we really need is the documentation about the
deployment, which should be placed under User/Administrator Guide.
And I also suspect that the "Developer" Guide would be useful. I don't
think we need to document every technical details (like API, function calls,
class diagrams), because these will change from time to time. What we
really need is some technical notes on the design idea. Of course, if the
APIs are stable enough, like RequestIntercepter(3.x) and Filter(4.x)
patterns, they need to be properly documented as well. Hence, the
"Developer" Guide serves as "effective communication tools" among
developers. For real hackers who want to know the internals or extend
Tomcat, I still believe that source code is the best documentation.
I don't have any preference on where the doc should be place, just like what
Craig says, it don't bother me much, and just hoping that I don't screw up
the code.
Punky
P.S. Sorry to respond late as I'm 100% off the list since last Friday.
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS:
[TomcatDocumentation Redactors To Hire]
Posted by "Craig R. McClanahan" <cr...@apache.org>.
On Mon, 9 Jul 2001, Jon Stevens wrote:
> on 7/7/01 9:33 AM, "Craig R. McClanahan" <cr...@apache.org> wrote:
>
> > FWIW, I'm fine with Anakia, XSLT, Cocoon, Stylebook, Docbook, or whatever
> > ... but IF AND ONLY IF the tags for use by the document authors are well
> > documented, and the page generation procedure is amenable to Ant scripting
> > (not a difficult problem in most cases).
>
> Jakarta-Site tags are now documented.
>
> http://jakarta.apache.org/site/jakarta-site-tags.html
>
Cool. That's exactly what I was looking for.
> Also, please quit grouping Anakia into "Anakia tags need to be documented".
> It is the Jakarta-Site2 project's tags which need to be documented (and have
> been). Anakia itself doesn't give a shit what tags you use. :-)
>
That's correct. It's also correct of XSLT :-).
> -jon
>
>
Craig
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS:
[TomcatDocumentation Redactors To Hire]
Posted by Jon Stevens <jo...@latchkey.com>.
on 7/7/01 9:33 AM, "Craig R. McClanahan" <cr...@apache.org> wrote:
> FWIW, I'm fine with Anakia, XSLT, Cocoon, Stylebook, Docbook, or whatever
> ... but IF AND ONLY IF the tags for use by the document authors are well
> documented, and the page generation procedure is amenable to Ant scripting
> (not a difficult problem in most cases).
Jakarta-Site tags are now documented.
http://jakarta.apache.org/site/jakarta-site-tags.html
Also, please quit grouping Anakia into "Anakia tags need to be documented".
It is the Jakarta-Site2 project's tags which need to be documented (and have
been). Anakia itself doesn't give a shit what tags you use. :-)
-jon
RE: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS:
[TomcatDocumentation Redactors To Hire]
Posted by "Craig R. McClanahan" <cr...@apache.org>.
On Sat, 7 Jul 2001, Rob S. wrote:
> Unfortunatly, I won't be able to participate much in this discussion this
> weekend since i know *0* about AWT and the Java cert (Monday morning, 9am)
> apparently thinks you should =) Sorry all...
>
> > The important issue is *not* what transformation tool is used. The
>
> Oh, by "works for Catalina" I was stating that TC4 is already using the
> tool; why not continue using it?
>
TC4 is not currently using Anakia (which is the tool I thought you were
talking about). It's using Ant's <style> tag, just like Struts
does. But, as I tried to make very clear in the CVS commits, that's just
a temporary expedient until the tool choice is made.
FWIW, I'm fine with Anakia, XSLT, Cocoon, Stylebook, Docbook, or whatever
... but IF AND ONLY IF the tags for use by the document authors are well
documented, and the page generation procedure is amenable to Ant scripting
(not a difficult problem in most cases).
> > * Docs should live in the source tree of the project that they
> > are about. Although Henri's suggestion for jakarta-tomcat-docs
> > is noble, what you'll find in practice is that there is very little
> > documentation that is relevant across multiple versions of Tomcat.
>
> I have a feeling that whatever is the same will be a lot of piecemeal here
> and there, excluding of course, web-app documentation. So far yourself,
> Pier, and Henri are the only three TC developers to post their position on
> that (re: inter-version relevancy). Personally, I don't think there should
> be a separate project, but I think I've already said that a few times =)
>
I thought of another reason for my preference in the shower this morning
:-). Consider that I might make a code change that also requires a change
to the corresponding docs. If the docs are in the same repository, that
can easily be done on the same commit (and it becomes obvious to everyone
when a developer makes a change that breaks the documentation, but fails
to update it :-). Having a separate docs repository means I need to do
two independent check-ins -- it's easy to forget one, and there is no
obvious link between them to remind you (for example) to back out the docs
change if you back out the code change.
On the other hand, a separate docs repository has one potential advantage
as well: we can grant CVS commit privileges on the docs to people who do
not have those privileges on the code repositories. To me, this isn't a
big deal -- if we can trust people to get the docs right, we should be
able to trust them not to screw up the code -- but it's still there.
> > * The files that are checked in should only be the XML sources, *not* the
> > generated files. This varies from what Jon set up in jakarta-site2,
> > based on long and drawn out earlier discussions (same issues as those
> > surrounding checking JAR files into CVS :-).
>
> Someone will have to setup something that exposes the latest generated
> documentation on the Jakarta www site. It's being done already for Struts,
> so I guess that won't be a big problem.
>
It's pretty straightforward.
> > * At least two documentation webapps (developer-oriented and
> > user-oriented) would seem to be appropriate. Having more than two
>
> "developer" as in "web" or "Tomcat"? I'm not sure why separating the doc
> into two packages helps - perhaps I'm missing some obvious benefit trying to
> think at 7:15am =)
>
"Developer" in the sense of this sentence is a Tomcat
developer. "User" is the people that just want to download, install,
configure, and utilize Tomcat as a servlet container.
> - r
>
>
Craig
RE: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocumentation Redactors To Hire]
Posted by "Rob S." <rs...@home.com>.
Unfortunatly, I won't be able to participate much in this discussion this
weekend since i know *0* about AWT and the Java cert (Monday morning, 9am)
apparently thinks you should =) Sorry all...
> The important issue is *not* what transformation tool is used. The
Oh, by "works for Catalina" I was stating that TC4 is already using the
tool; why not continue using it?
> * Docs should live in the source tree of the project that they
> are about. Although Henri's suggestion for jakarta-tomcat-docs
> is noble, what you'll find in practice is that there is very little
> documentation that is relevant across multiple versions of Tomcat.
I have a feeling that whatever is the same will be a lot of piecemeal here
and there, excluding of course, web-app documentation. So far yourself,
Pier, and Henri are the only three TC developers to post their position on
that (re: inter-version relevancy). Personally, I don't think there should
be a separate project, but I think I've already said that a few times =)
> * The files that are checked in should only be the XML sources, *not* the
> generated files. This varies from what Jon set up in jakarta-site2,
> based on long and drawn out earlier discussions (same issues as those
> surrounding checking JAR files into CVS :-).
Someone will have to setup something that exposes the latest generated
documentation on the Jakarta www site. It's being done already for Struts,
so I guess that won't be a big problem.
> * At least two documentation webapps (developer-oriented and
> user-oriented) would seem to be appropriate. Having more than two
"developer" as in "web" or "Tomcat"? I'm not sure why separating the doc
into two packages helps - perhaps I'm missing some obvious benefit trying to
think at 7:15am =)
- r
RE: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocu
mentation Redactors To Hire]
Posted by "Craig R. McClanahan" <cr...@apache.org>.
On Mon, 2 Jul 2001, Rob S. wrote:
> This seems to be one of the questions that comes up and never gets answered
> (re: docs, not Jon's behavior ;) I'm not sure what magical solution will
> get people to read docs. Frankly, I'd just like to get started. Anakia
> works for Jakarta,
Yep, thanks to Jon's hard work setting up jakarta-site2, a large majority
of the Jakarta web site is generated using Anakia.
> it works for Struts
Technically, it's not actually *used* by Struts -- Struts uses the Ant
<style> tag, which does an XSLT transformation.
However, the XML tags that Anakia (as used in jakarta-site2) understands
are very similar to the ones used in the Struts stylesheets -- and that is
a very important point.
==> it'll probably work for Catalina.
>
The important issue is *not* what transformation tool is used. The
important issue is on what tags you use in your docs, so that you can use
your favorite transformation tool. That's what we should agree on first,
because that is the gating factor on actually writing documentation.
> Committers, [VOTE] on this?
>
+1 on anyone willing to propose *and act on* writing docs, using some
reasonable XML format, on all interesting versions of Tomcat.
That being said, I do have a couple of thoughts on process -- but they are
just my own feelings, not mandates or requirements.
* Docs should live in the source tree of the project that they
are about. Although Henri's suggestion for jakarta-tomcat-docs
is noble, what you'll find in practice is that there is very little
documentation that is relevant across multiple versions of Tomcat.
* The files that are checked in should only be the XML sources, *not* the
generated files. This varies from what Jon set up in jakarta-site2,
based on long and drawn out earlier discussions (same issues as those
surrounding checking JAR files into CVS :-).
* Tomcat docs for a particular version should be delivered as one or more
web apps (not necessarily the root webapp as is current practice). That
way, the corresponding WAR files could be dropped into *any* container,
or opened up and read directly from the filesystem.
* At least two documentation webapps (developer-oriented and
user-oriented) would seem to be appropriate. Having more than two
will make it difficult to create reliable hyperlinks (since you don't
have any control over the context path that someone uses to deploy).
> - r
>
Craig McClanahan
RE: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocu mentation Redactors To Hire]
Posted by "Rob S." <rs...@home.com>.
This seems to be one of the questions that comes up and never gets answered
(re: docs, not Jon's behavior ;) I'm not sure what magical solution will
get people to read docs. Frankly, I'd just like to get started. Anakia
works for Jakarta, it works for Struts ==> it'll probably work for Catalina.
Committers, [VOTE] on this?
- r
> -----Original Message-----
> From: Christopher Cain [mailto:ccain@mhsoftware.com]
> Sent: Monday, July 02, 2001 9:05 PM
> To: tomcat-dev@jakarta.apache.org
> Subject: Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS:
> [TomcatDocu mentation Redactors To Hire]
>
>
>
> Jon Stevens wrote:
> >
> > The Tomcat website is already generated with Anakia. It is
> trivial to add
> > more .xml files to the site and there is absolutely no excuse
> to not just go
> > that route.
> >
> > I just don't see the merits of this discussion. Go write documentation
> > instead.
> >
> > -jon
>
> LOL.
>
> Oh, well then, as long as _Jon_ doesn't see any merits, I guess this is
> all just so much fodder. Never mind that the question has not yet been
> adequately answered, and is still being constructively debated. Never
> mind that some program I never heard of generates the Tomcat site. Never
> mind that what happens on the Apache servers has about as much to do
> with Tomcat documentation, which is being discussed as a new context
> installed with the server, as what I plan on feeding my cat Mittens
> tonight. Never mind all that ... Jon has descended from the Ivory tower
> with his rather cryptic edict. Once we make sense of this devine wisdom,
> we are to proceed immediately and without question.
>
> For someone who loves to speak at great lengths about community
> discussions and honoring majority decisions, this is a rather bizzare
> tact to say the least. Some of us, including myself, would like for this
> discussion to come to a well-considered conclusion so that we can help
> out with documentation. Your nonsensical suggestions and irritation at
> being bothered with this thread are both completely irrelevant, Ace. I
> have no interest in Anakia, and quite frankly, as has been pointed out
> very astutely by Costin, I have no interest in bothering with XML for
> the purposes of documentation. I will produce HTML docs with my favorite
> editor and call it a task adequately completed. Asking anything beyond
> that will more than likely be more time and effort than I am prepared to
> invest in simple documentation.
>
> In short, let us please continue and decide upon how to proceed.
> Regardless of Jon's off-topic confusion, I would really like to know how
> the community would like to see any documentation which I may
> contribute.
>
> - Christopher
>