tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Allistair Crossley" <Allistair.Cross...@QAS.com>
Subject RE: TC6 documentation
Date Wed, 05 Apr 2006 08:40:20 GMT
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">&nbsp;</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:ian@darwinsys.com] 
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: dev-unsubscribe@tomcat.apache.org For additional
commands, e-mail: dev-help@tomcat.apache.org





<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: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org


Mime
View raw message