Hi,
I strongly disagree that the current documentation format is helpful
both in terms of readability and accessibility to update.
For about 2 years now I have wanted to do something with them, but never
get around to it, but my start so far is a set using DocBook. Even this
I am not keen on in terms of writing the documentation since it will
discourage some users contributing to the documentation since they have
to learn DocBook. On the other hand, it can output as XHTML and PDF
which is a real plus, and it's not all that hard. I definitely think
overall the Tomcat site could do with a general overhaul and content
restructure, but I do not know if that is possible being within the
Apache box.
There is a definate shift now to XHTML/CSS and "web standards". All
browsers in use today can support the amount of XHTML/CSS required,
developers cannot and should not deny CSS as a valid method for
structuring design and layout completely. In fact, devs should love it
because it leaves devs to write semantically pure XHTML.
Something like <bug>xxx</bug> that Yoav mentioned is easily handled by a
XHTML/CSS markup rather than using a custom tag that is rendered into a
TABLE.
For example here is how the changelog *could* be represented with
"semantically accurate" XHTML (a table is arguably also accurate, but in
this case is more of a presentational choice)
<h1>Tomcat 5.5.16</h1>
<dl id="general">
<dt class="update"> </dt>
<dd>
Required tcnative library version upgraded to 1.1.2
<abbr class="username">(remm)</abbr>
</dd>
</dl>
<dl id="catalina">
<dt class="bug">23950</dt>
<dd>
Context.listBindings() should return objects not references.
<abbr class="username">(markt)</abbr>
</dd>
</dl>
The DTs by virtue of their class can add the appropriate image for
denoting an update or a bug. It could shade the row if it really wanted,
we can do anything with it.
The DD speaks for itself, and I chose the ABBR since the dev inits are
an abbreviation of sorts, but classified it as a username. In CSS2 we
would be able to add the parantheses at start and end, but that's not
quite ready in all browsers yet.
I definitely believe the documentation should be rewritten either in
DocBook=>XHTML or pure XHTML with CSS.
Allistair
-----Original Message-----
From: Ian Darwin [mailto:[EMAIL PROTECTED]
Sent: 04 April 2006 20:32
To: Tomcat Developers List
Subject: Re: TC6 documentation
Yoav Shapira wrote:
> There were other reasons for using XML, like the ability for Jakarta
> to have some common elements that would get automagically resolved
> into the bug tracking URLs, etc. For example, when I edit the
> changelog it's great to just put in <bug>n</bug> and have it be
> resolved to the proper Bugzilla link URL. I think it cuts down on
> typos, broken links, etc. And this is just one example of a useful
> custom element out of several.
>
Right you are, thanks. And am I right that eating our own dog food -
using JSP tags for that - is out because we want to maintain
statically-usable copies? OTOH it might be a better demo of Tomcat :-)
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED] For additional
commands, e-mail: [EMAIL PROTECTED]
<FONT SIZE=1 FACE="VERDANA,ARIAL" COLOR=BLUE>
-------------------------------------------------------
QAS Ltd.
Registered in England: No 2582055
Registered in Australia: No 082 851 474
-------------------------------------------------------
</FONT> <FONT SIZE=1 FACE="VERDANA,ARIAL" COLOR=BLACK>
Disclaimer: The information contained within this e-mail is confidential and
may be privileged. This email is intended solely for the named recipient only;
if you are not authorised you must not disclose, copy, distribute, or retain
this message or any part of it. If you have received this message in error
please contact the sender at once so that we may take the appropriate action
and avoid troubling you further. Any views expressed in this message are those
of the individual sender. QAS Limited has the right lawfully to record,
monitor and inspect messages between its employees and any third party. Your
messages shall be subject to such lawful supervision as QAS Limited deems to be
necessary in order to protect its information, its interests and its
reputation.
Whilst all efforts are made to safeguard Inbound and Outbound emails, QAS
Limited cannot guarantee that attachments are virus free or compatible with
your systems and does not accept any liability in respect of viruses or
computer problems experienced.
</FONT>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
