You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by GOMEZ Henri <hg...@slib.fr> on 2001/07/03 10:05:47 UTC
RE: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatD
ocumentation Redactors To Hire]
Ok, ok.
Many debate here about using anakia, stylebook, docbook or xxxbook.
There is a tool today, that's let you documentation in a standard
format we could use, abiword (http://www.abisource.com/).
It's free, have a decent GUI, is available for Windows,
Unix, GNOME, BeOS and QNX, and even MacOS X (for Pier purpose).
It let you export document in DocBook format WHICH is a
standard.
Apache used to follow standard, docbook is a standard,
an Open Standard, so why not use this one ?
If we have remark or comments, or detect lack, we still
could be involved....
-
Henri Gomez ___[_]____
EMAIL : hgomez@slib.fr (. .)
PGP KEY : 697ECEDD ...oOOo..(_)..oOOo...
PGP Fingerprint : 9DF8 1EA8 ED53 2F39 DC9B 904A 364F 80E6
Re: AW: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatD
ocumentation Redactors To Hire]
Posted by cm...@yahoo.com.
On Tue, 3 Jul 2001, Jon Stevens wrote:
> > It's just sad when an organization like Apache chooses to ignore existing
> > standards and invent it's own DTD and transformation language to do the
> > site.
>
> Once again Costin, you fail to impress me with your statements. You confuse
> "Apache" with some organization of people who are paid to work on stuff.
Well, it's not my goal to "impress" you - and it doesn't matter if people
are paid or not.
It's a choice that every group should make - Apache made once the choice
to strictly implement the HTTP spec, and it used to be a place where
standards meant something.
And the fact that apache site is built on top of an arbitrary xml DTD and
transformation language when a stadard one exists is quite impressive for
me.
Is apache now a standard body, competing with W3C and oasis ?
> Having said that, you didn't come up with a solution and I personally think
> that the XSLT "standards" suck. I'm sure that plenty of other people who
> have spent enough time with XSLT will agree with me (for me, it took all of
> 5 minutes to figure out that XSLT's implementation sucks).
>
> So, I came up with a solution (Anakia) that beat the pants off of Stylebook
> in terms of speed and ease of use and now at least 10 different Jakarta
> projects have adopted it. Something must be acceptable about it.
Sure - what's next ? HTTP sucks, and we implement our better version ?
After all apache has many users, I'm sure people will find some extensions
usefull.
So whoever writes a DTD and a transformation language will have apache
site converted to it, and all people will have to forget about anakia DTD
and use the new DTD ( until another apache DTD is invented ) ?
> So, when you come up with something better and port everything over, I'm
> sure that we will all just love using it. Until then, I suggest that you
> keep your opinions to yourself as they are not helpful at all.
I'm sure they're not helpful to you. But since the discussion is about
switching tomcat documentation from HTML to an apache-specific tag set, I
think people might find my opinion useful.
And of course, I do hope the use of anakia tagset will happen _after_ a
vote on tomcat_dev, as it should be.
Costin
Re: TC4 docs - can we end this?
Posted by "Craig R. McClanahan" <cr...@apache.org>.
On Wed, 4 Jul 2001, Andy Armstrong wrote:
> "Rob S." wrote:
> >
> > > Anyway +1 million on getting some decent docs written. Personally I'd
> > > find it useful if someone who is reasonably clueful on the state of TC
> > > documentation at the moment could summarise what's out there. The TC
> > > book project for example; where's that at?
> >
> > I think that falls under my personal category of "too involved to garner
> > much continual support". That's just my thought tho' =) If we had a solid
> > bank of docs and had proven to ourselves that we could even do that 'simple'
> > task, then I'd be all for a book. Lets get some docs out there first ;)
>
> Completely agree -- I'm just trying to get a feel for what's been done
> so far on the assumption that there may be useful documentation lying
> around out there.
>
Everything that is included in the Tomcat distribution is sitting there
already in CVS :-). Of course, there's quite a bit of user-written
"unofficial" documentation on Tomcat that could be drawn from as well --
I'll bet a little research on the TOMCAT-USER archives would give us lots
of pointers (plus lots of ideas on topics to be covered).
> --
> Andy Armstrong, Tagish
>
Craig
Re: TC4 docs - can we end this?
Posted by Andy Armstrong <an...@tagish.com>.
"Rob S." wrote:
>
> > Anyway +1 million on getting some decent docs written. Personally I'd
> > find it useful if someone who is reasonably clueful on the state of TC
> > documentation at the moment could summarise what's out there. The TC
> > book project for example; where's that at?
>
> I think that falls under my personal category of "too involved to garner
> much continual support". That's just my thought tho' =) If we had a solid
> bank of docs and had proven to ourselves that we could even do that 'simple'
> task, then I'd be all for a book. Lets get some docs out there first ;)
Completely agree -- I'm just trying to get a feel for what's been done
so far on the assumption that there may be useful documentation lying
around out there.
--
Andy Armstrong, Tagish
RE: TC4 docs - can we end this?
Posted by "Rob S." <rs...@home.com>.
> Anyway +1 million on getting some decent docs written. Personally I'd
> find it useful if someone who is reasonably clueful on the state of TC
> documentation at the moment could summarise what's out there. The TC
> book project for example; where's that at?
I think that falls under my personal category of "too involved to garner
much continual support". That's just my thought tho' =) If we had a solid
bank of docs and had proven to ourselves that we could even do that 'simple'
task, then I'd be all for a book. Lets get some docs out there first ;)
- r
Re: TC4 docs - can we end this?
Posted by Andy Armstrong <an...@tagish.com>.
"Rob S." wrote:
>
> (apologies in advance for the tone, I'm a happy person =)
>
> As far as Anakia is concerned, it's proven (within Jakarta), it looks a lot
> like XHTML, there's resident expertise, and TC 4 is already using it. Of
> course I am *all for* debate, discussion, etc. but in lieu of all of the
> above, why continue dicussing it? What's *wrong*?
>
> I dunno who said it, but a long time ago there's a nice quote I heard in
> English class, "The purity of a revolution lasts for about two weeks." It
> explains what happens each time we talk about docs, a nice(r) admin UI, etc.
> It seems like people are more interested in talking about what projects to
> create, what tools to use, etc. when I *still* haven't read any comments
> about *THE ACTUAL DOCUMENTATION* aside from "TOMCAT SUCKS!" and everyone's
> agreement that the docs are in need of repair... Not a lot of
> groundbreaking realizations left to make on those two points.
You have, of course, put your finger on the reason why so many free
software projects have sucky docs -- we'd all far rather fantasize about
high falutin tools than put finger to keyboard. Talking about the tools
is just another reason to delay writing the docs.
Anyway +1 million on getting some decent docs written. Personally I'd
find it useful if someone who is reasonably clueful on the state of TC
documentation at the moment could summarise what's out there. The TC
book project for example; where's that at?
--
Andy Armstrong, Tagish
RE: TC4 docs - can we end this?
Posted by "Rob S." <rs...@home.com>.
> Just start with it. When you have something, post it as a patch and they
> (Tomcat committers) will have to decide.
It takes a lllong time to write documentation. I prefer to not shotgun the
docs and hope what I come up with is useful. It's why I started this whole
thread in the first place! ;)
> IMHO, it would be better to create a tomcat-doc list and let people
> debate all these matters to death, and then perhaps do something. No
> need to have everything pinned up beforehand -- besides, it seems
> impossible to find a consensus.
Well, IMHO =) I think the decision should be up to the TC4 committers (i.e.
people who will deal with the build, edit the docs, etc.). They seem to
have already decided.
> Use your imagination. What docs would you like to have?
(See my first paragraph above)
> If you don't know where to start, then perhaps this particular task is
> not for you. No offense meant, just that someone must set off with a
> clear mind.
(See my first paragraph above)
- r
Re: TC4 docs - can we end this?
Posted by Alex Fernández <af...@tid.es>.
Hi Rob!
[quotes in no particular order]
> I would've thought a thread about docs would be concerned with what docs to
> create, what docs will glue them together, maybe an image on the doc
> homepage with a map showing what order you can read them, etc.
Just start with it. When you have something, post it as a patch and they
(Tomcat committers) will have to decide.
IMHO, it would be better to create a tomcat-doc list and let people
debate all these matters to death, and then perhaps do something. No
need to have everything pinned up beforehand -- besides, it seems
impossible to find a consensus.
> As far as Anakia is concerned, it's proven (within Jakarta), it looks a lot
> like XHTML, there's resident expertise, and TC 4 is already using it. Of
> course I am *all for* debate, discussion, etc. but in lieu of all of the
> above, why continue dicussing it? What's *wrong*?
You are right, there's nothing wrong with the dozen or so proposals to
format documentation -- except there are so many.
> All of this other bunk is essentially worthless to me. Tell me what docs to
> create, what's wrong with the ones I'm rewriting or replacing (if that's the
> case), and I'll do it in text or HTML. Everyone who wants to talk about how
> to render it can deal with it when I'm done - although I have a feeling they
> won't be the ones taking the time to port my output over to whatever format
> they deem reasonable.
Use your imagination. What docs would you like to have?
> So please, can we at least START some discussion about the contents of the
> docs other than "we need to write them" ? There's a lot of work to be done,
> and I would imagine that someone knows where a good place is to start.
If you don't know where to start, then perhaps this particular task is
not for you. No offense meant, just that someone must set off with a
clear mind.
Un saludo,
Alex.
RE: TC4 docs - can we end this?
Posted by "Craig R. McClanahan" <cr...@apache.org>.
On Wed, 4 Jul 2001, Rob S. wrote:
> It'll already take a tremendous amount of time to get the user's side up and
> going, which is what I think the grand majority of people will benefit the
> most from. I'm not saying the dev design docs aren't extremely important,
> I'm just saying that I want to spend my time where it will have the greated
> effect =)
>
I think it makes *lots* of sense to focus on the user docs first. After
all, there's a lot more of them trying to understand this stuff than there
are developers :-).
Also, developers should be "strongly" :-) encouraged to write their own
docs about architecture and so on -- and yes, I'm definitely pointing my
finger at myself as well.
> - r
>
Craig
RE: TC4 docs - can we end this?
Posted by "Rob S." <rs...@home.com>.
It'll already take a tremendous amount of time to get the user's side up and
going, which is what I think the grand majority of people will benefit the
most from. I'm not saying the dev design docs aren't extremely important,
I'm just saying that I want to spend my time where it will have the greated
effect =)
- r
> -----Original Message-----
> From: Antony Bowesman [mailto:adb@teamware.com]
> Sent: Wednesday, July 04, 2001 2:19 AM
> To: tomcat-dev@jakarta.apache.org
> Subject: Re: TC4 docs - can we end this?
>
>
> "Rob S." wrote:
> >
> > So please, can we at least START some discussion about the
> > contents of the docs other than "we need to write them" ?
> > There's a lot of work to be done, and I would imagine that
> > someone knows where a good place is to start.
>
> Let's start from the bottom up. We already have the servlet API spec,
> so how about architectural design specs. Filip Hanik, in his Tomcat
> Interceptors project, has some useful documentation and I have earlier
> provided feedback to him.
>
> However, I recently implemented a realm for TC 3.x and had some
> difficulties. I had to understand TC source code to get a feel for the
> request processing architecture. Some areas of Interceptors and
> Contexts are still unclear. For example, what are notes? These are
> referred to in ContextManager quite a lot and the SimpleRealm
> implementation but the purpose of them in a mystery. Questions on the
> list didn't get replies.
>
> What issues need to be considered when extending things like
> BaseInterceptor with regard to the contexts, JVMs, class loaders and
> synchronisation requirements.
>
> I know it's a moving target all the time but architectural specs would
> help in getting more people involved in writing better code for the
> overall project.
>
> Antony
>
Re: TC4 docs - can we end this?
Posted by Antony Bowesman <ad...@teamware.com>.
"Rob S." wrote:
>
> So please, can we at least START some discussion about the
> contents of the docs other than "we need to write them" ?
> There's a lot of work to be done, and I would imagine that
> someone knows where a good place is to start.
Let's start from the bottom up. We already have the servlet API spec,
so how about architectural design specs. Filip Hanik, in his Tomcat
Interceptors project, has some useful documentation and I have earlier
provided feedback to him.
However, I recently implemented a realm for TC 3.x and had some
difficulties. I had to understand TC source code to get a feel for the
request processing architecture. Some areas of Interceptors and
Contexts are still unclear. For example, what are notes? These are
referred to in ContextManager quite a lot and the SimpleRealm
implementation but the purpose of them in a mystery. Questions on the
list didn't get replies.
What issues need to be considered when extending things like
BaseInterceptor with regard to the contexts, JVMs, class loaders and
synchronisation requirements.
I know it's a moving target all the time but architectural specs would
help in getting more people involved in writing better code for the
overall project.
Antony
Re: TC4 docs - can we end this?
Posted by Alex Chaffee <al...@jguru.com>.
Rob S. wrote:
>I would've thought a thread about docs would be concerned with what docs to
>create, what docs will glue them together, maybe an image on the doc
>homepage with a map showing what order you can read them, etc.
>
OK, I'll write up a proposal soon with my ideas on doc organization. You
and I seem to have similar ideas about what needs to be done.
Some things that wil probably be in that proposal:
A trail map, a table of contents, a to-do list, a clear distinction
between Manuals and Howtos...
Clearly labelled sidebars for variations in OS, Tomcat version,
front-end Web server...
Tags for authorship for sections (perhaps with one section per file so
CVS can help)...
Pointers to existing docs and other sites (e.g. to specific FAQ entries)...
>p.s. I thought of another one, "Too many chefs, not enough doc writers" ;)
>
:-)
--
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/
PROPOSAL: Tomcat docs - was TC4 docs - can we end this?
Posted by Martin van den Bemt <mv...@mvdb.com>.
A very big +1, See feedback below..
> So please, can we at least START some discussion about the contents of the
> docs other than "we need to write them" ? There's a lot of work
> to be done,
> and I would imagine that someone knows where a good place is to start.
There are x main parts for the documentation :
- Why use tomcat, what does it do and what doesn't it do?
- Plain Installation and upgrades of the various tomcat versions (and maby
jserv upgrade to tomcat)
- Connectors and beyond ;-)) Why choose which connector and why don't use a
certain connector?
- Advanced configuration (what are all the entries for). In this case also
some references to technical docs which explain how to start writing eg
custom handlers, etc).
- Feature list as from tomcat 3 and as from tomcat 4 (group together
features and in which versions they appear/dissapear).
- a tomcat programmers manual
- a tips reference
- a faq reference (would be nice if there is a reference to the version it's
about or from what version the Question is valid.
- An administrator guide for tomcat.
Mvgr,
Martin van den Bemt
TC4 docs - can we end this?
Posted by "Rob S." <rs...@home.com>.
(apologies in advance for the tone, I'm a happy person =)
As far as Anakia is concerned, it's proven (within Jakarta), it looks a lot
like XHTML, there's resident expertise, and TC 4 is already using it. Of
course I am *all for* debate, discussion, etc. but in lieu of all of the
above, why continue dicussing it? What's *wrong*?
I dunno who said it, but a long time ago there's a nice quote I heard in
English class, "The purity of a revolution lasts for about two weeks." It
explains what happens each time we talk about docs, a nice(r) admin UI, etc.
It seems like people are more interested in talking about what projects to
create, what tools to use, etc. when I *still* haven't read any comments
about *THE ACTUAL DOCUMENTATION* aside from "TOMCAT SUCKS!" and everyone's
agreement that the docs are in need of repair... Not a lot of
groundbreaking realizations left to make on those two points.
I would've thought a thread about docs would be concerned with what docs to
create, what docs will glue them together, maybe an image on the doc
homepage with a map showing what order you can read them, etc.
All of this other bunk is essentially worthless to me. Tell me what docs to
create, what's wrong with the ones I'm rewriting or replacing (if that's the
case), and I'll do it in text or HTML. Everyone who wants to talk about how
to render it can deal with it when I'm done - although I have a feeling they
won't be the ones taking the time to port my output over to whatever format
they deem reasonable.
So please, can we at least START some discussion about the contents of the
docs other than "we need to write them" ? There's a lot of work to be done,
and I would imagine that someone knows where a good place is to start.
- r
p.s. I thought of another one, "Too many chefs, not enough doc writers" ;)
Re: AW: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS:
[TomcatD ocumentation Redactors To Hire]
Posted by "Pier P. Fumagalli" <pi...@betaversion.org>.
Jon Stevens at jon@latchkey.com wrote:
>
> Once again Costin, you fail to impress me with your statements. You confuse
> "Apache" with some organization of people who are paid to work on stuff.
> Again, I must remind you that this is a volunteer organization and anything
> that gets done is done because someone bothered to step up and do it. You of
> all people should have that figured out by now and not need constant
> reminding. :-(
>
> Having said that, you didn't come up with a solution and I personally think
> that the XSLT "standards" suck. I'm sure that plenty of other people who
> have spent enough time with XSLT will agree with me (for me, it took all of
> 5 minutes to figure out that XSLT's implementation sucks).
>
> So, I came up with a solution (Anakia) that beat the pants off of Stylebook
> in terms of speed and ease of use and now at least 10 different Jakarta
> projects have adopted it. Something must be acceptable about it.
>
> So, when you come up with something better and port everything over, I'm
> sure that we will all just love using it. Until then, I suggest that you
> keep your opinions to yourself as they are not helpful at all.
Once again I strongly agree with Jon. I'm not a fan of Velocity, as a
language, and more oriented towards the XSLT approach, but again, right now
I see no other viable and working alternative to Anakia, and so, until
someone doesn't give me a working and viable alternative, that's what I'm
going to vote for.
A big +1 on Anakia, on using its DTDs and Velocity based stylesheet... (And
big thanks to Jon for making that tool available).
Pier
Re: AW: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS:
[TomcatD ocumentation Redactors To Hire]
Posted by Jon Stevens <jo...@latchkey.com>.
on 7/3/01 11:20 AM, "cmanolache@yahoo.com" <cm...@yahoo.com> wrote:
> It's just sad when an organization like Apache chooses to ignore existing
> standards and invent it's own DTD and transformation language to do the
> site.
Once again Costin, you fail to impress me with your statements. You confuse
"Apache" with some organization of people who are paid to work on stuff.
Again, I must remind you that this is a volunteer organization and anything
that gets done is done because someone bothered to step up and do it. You of
all people should have that figured out by now and not need constant
reminding. :-(
Having said that, you didn't come up with a solution and I personally think
that the XSLT "standards" suck. I'm sure that plenty of other people who
have spent enough time with XSLT will agree with me (for me, it took all of
5 minutes to figure out that XSLT's implementation sucks).
So, I came up with a solution (Anakia) that beat the pants off of Stylebook
in terms of speed and ease of use and now at least 10 different Jakarta
projects have adopted it. Something must be acceptable about it.
So, when you come up with something better and port everything over, I'm
sure that we will all just love using it. Until then, I suggest that you
keep your opinions to yourself as they are not helpful at all.
:-)
I await your patches.
-jon
Re: AW: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatD
ocumentation Redactors To Hire]
Posted by cm...@yahoo.com.
Docbook is a standard for writing books, articles, technical
documentations. It is the format used by LDP ( linux doc project ) and
many ( or most ) open source projects, companies, etc. ( it's not a new
thing, has been around since SGML days ).
XSLT is the W3C standard for XML transformation.
You can use any other format for writing documents - including Word ( I
understand the latest version generates XML ), and you can use anything to
transform the XML into HTML - including VB macros.
It's just sad when an organization like Apache chooses to ignore existing
standards and invent it's own DTD and transformation language to do the
site.
Well, that's my opinion - if I'm going to write documents I'll use docbook
or HTML, and I'm -1 on asking people to learn an ad-hoc DTD when there is
a standard.
Of course, it's apache decision for what format it wants to use for it's
site - and tomcat-dev commiters can vote on using any arbitrary DTD for
its documentation ( including word or staroffice ) - it's a majority
decision.
As long as there is no vote - I think the right thing is to stick with
what is in use at this moment. That is html for tomcat3.x documentations.
If tomcat4 commiters decide to use a special xml format - that's fine with
me. ( well, I think that should be voted by all
tomcat-dev commiters, and if the vote is to use some xml format it should
apply to all tomcat versions and sub-projects ).
I'm waiting for the proposal to switch - my vote will be -1 for any xml
format except docbook, but it's just one vote. Or the PMC/ASF can decide
to use a certain format for all projects - that's fine with me too.
As Geir mentioned, that has been discussed in the past - and I don't think
it's worth continuing. There are standards, and we can ignore
them - arguments about the value of a standard are available in many
places, no need to repeat here.
Costin
AW: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatD ocumentation Redactors To Hire]
Posted by Thomas Bezdicek <th...@engnetworld.com>.
Hi
Ok Henri I am switching your discussion to tomcat-dev.
I did a short look at docbook, but it seems for me, that
the main-intension of docbook is to do something like
javadoc, with a little bit more around, but mainly get
the in-line documentation out of the source-code and
have some files for structuring around it. if this
is what the tomcat docu should be it seems to me a
very good choice.
if the documentation should be more of the style of a
book, with examples, more descriptive information, it
seems to be not really a good choice, it would be
easier to make java 3-liner which does the same without
the need of the docbook to be installed (xalan and
xerces in my opinion should be default packaged with
tomcat, even to encourage developers to use XML/XSL for
rendering and data-exchange).
If building a small servlet it should be even possible
to let the documentation be generated online (maybe with
regular check if updates of the documentation are available
with download option) and even with remarks made by the
user (it then could be used be used developers for their
application documentation).
But due to the ongoing discussion I think Anakia /Velocity
is more prefered, but I haven't looked at it yet.
Another point which might be something which would be
discussed a lot :) is, what about build a complete framework
of jakarta documentation all in one format using one tool
to get the documentation generated?
regards, tom
P.S.: I attached a small sample-XML skelton for a possible
documentation (sorry henry hadn't the time yet to convert
an existing document)
> -----Ursprüngliche Nachricht-----
> Von: GOMEZ Henri [mailto:hgomez@slib.fr]
> Gesendet: Dienstag, 3. Juli 2001 10:06
> An: tomcat-dev@jakarta.apache.org
> Betreff: RE: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS:
> [TomcatD ocumentation Redactors To Hire]
>
>
> Ok, ok.
>
> Many debate here about using anakia, stylebook, docbook or xxxbook.
> There is a tool today, that's let you documentation in a standard
> format we could use, abiword (http://www.abisource.com/).
>
> It's free, have a decent GUI, is available for Windows,
> Unix, GNOME, BeOS and QNX, and even MacOS X (for Pier purpose).
>
> It let you export document in DocBook format WHICH is a
> standard.
>
> Apache used to follow standard, docbook is a standard,
> an Open Standard, so why not use this one ?
>
> If we have remark or comments, or detect lack, we still
> could be involved....
>
>
> -
> Henri Gomez ___[_]____
> EMAIL : hgomez@slib.fr (. .)
> PGP KEY : 697ECEDD ...oOOo..(_)..oOOo...
> PGP Fingerprint : 9DF8 1EA8 ED53 2F39 DC9B 904A 364F 80E6