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:[EMAIL PROTECTED]]
> Gesendet: Dienstag, 3. Juli 2001 10:06
> An: [EMAIL PROTECTED]
> 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 : [EMAIL PROTECTED]        (. .)
> PGP KEY : 697ECEDD    ...oOOo..(_)..oOOo...
> PGP Fingerprint : 9DF8 1EA8 ED53 2F39 DC9B 904A 364F 80E6
<?xml version="1.0" encoding="UTF-8"?>
<jakarta:documentation version="1.0" xmlns:jakarta="urn:jakarta.apache.org" lang="EN" target-encoding="ISO-8859-1" name="index" cascading-style-sheet="ccs/style.ccs">

	<jakarta:index name="Documentation Overview" level="1" vertical-align="" horizontal-align="" vertical-postion="10px" horizontal-position="10px">
		<jakarta:index-element>
			<jakarta:link src="" anchor="installation">Installation</jakarta:link>
		</jakarta:index-element>
		<jakarta:index-element>
			<jakarta:link src="" anchor="configuration">Configuration</jakarta:link>
		</jakarta:index-element>
	</jakarta:index>
	
	<jakarta:paragraph caption="Installation" name="installation" level="1">
	For installing Tomcat refer to these documents:
		<jakarta:list type="number" intend="1">
			<jakarta:list-element>
				<jakarta:link src="install/unix" anchor="">
					unix - installation
				</jakarta:link>
			</jakarta:list-element>
			<jakarta:list-element>
				<jakarta:link src="install/win32" anchor="">
					win32 - installation
				</jakarta:link>
				<jakarta:list type="point" intend="2">
					<jakarta:list-element>
						Windows 98/ME
					</jakarta:list-element>
					<jakarta:list-element>
						Windows NT/2000
					</jakarta:list-element>
				</jakarta:list>
			</jakarta:list-element>
		</jakarta:list>
	</jakarta:paragraph>
	
	<jakarta-paragraph caption="Configuration" name="configuration" level="1">
		Here is shown some graphics which gives you a rough overview of the <jakarta:underline>information flow</jakarta:underline>
		which is done by the auto-config feature <jakarta:bold>automagically</jakarta:bold>. 
		<jakarta:image name="filename.jpg" alt="Overview of information flow" width="" height=""/>
		Now follows some preformated text in code-style
		<jakarta:code>
		$JAKARTA_HOME
		|-- bin
		|-- lib
		|-- conf
		|-- webapps
		|-- src
		</jakarta:code>
		<jakarta-paragraph caption="SSL-Configuration" name="ssl_config" level="2">
			For configuring SSL with Tomcat you need the following libraries
			<jakarta:list type="table" columns="2">
				<jakarta:list-element column="1">
					JSSE 1.0.2
				</jakarta:list-element>
				<jakarta:list-element column="2">
					Java Secure Socket Extension, provided by SUN, download from <jakarta:link src="http://java.sun.com/";>here</jakarta:link>
				</jakarta:list-element>
			</jakarta:list>
		</jakarta-paragraph>
	</jakarta-paragraph>
	<jakarta:comment>
		<jakarta:author>Henri Gomez</jakarta:author>
		<jakarta:version>3.3</jakarta:version>
		<jakarta:date>02.07.2001</jakarta:date>
	</jakarta:comment>
</jakarta:documentation>

Reply via email to