Return-Path: 
 <dev-return-67756-apmail-tomcat-dev-archive=tomcat.apache.org@tomcat.apache.org>
Delivered-To: apmail-tomcat-dev-archive@www.apache.org
Received: (qmail 81640 invoked from network); 5 Apr 2006 08:41:41 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199)
  by minotaur.apache.org with SMTP; 5 Apr 2006 08:41:41 -0000
Received: (qmail 49853 invoked by uid 500); 5 Apr 2006 08:41:10 -0000
Delivered-To: apmail-tomcat-dev-archive@tomcat.apache.org
Received: (qmail 49793 invoked by uid 500); 5 Apr 2006 08:41:10 -0000
Mailing-List: contact dev-help@tomcat.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:dev-help@tomcat.apache.org>
List-Unsubscribe: <mailto:dev-unsubscribe@tomcat.apache.org>
List-Post: <mailto:dev@tomcat.apache.org>
List-Id: <dev.tomcat.apache.org>
Reply-To: "Tomcat Developers List" <dev@tomcat.apache.org>
Delivered-To: mailing list dev@tomcat.apache.org
Received: (qmail 49729 invoked by uid 99); 5 Apr 2006 08:41:10 -0000
Received: from asf.osuosl.org (HELO asf.osuosl.org) (140.211.166.49)
    by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 05 Apr 2006 01:41:10 -0700
X-ASF-Spam-Status: No, hits=2.6 required=10.0
	tests=DNS_FROM_RFC_ABUSE,SPF_HELO_SOFTFAIL
X-Spam-Check-By: apache.org
Received-SPF: error (asf.osuosl.org: local policy)
Received: from [195.172.82.236] (HELO MAIL2.qas.com) (195.172.82.236)
    by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 05 Apr 2006 01:41:04 -0700
Received: from orion.qas.com (orion.qas.com) by MAIL2.qas.com
    (Content Technologies SMTPRS 4.3.17) with ESMTP id
    <T7775d54c1f969664ee568@MAIL2.qas.com> for <dev@tomcat.apache.org>; Wed,
    5 Apr 2006 09:40:21 +0100
X-MimeOLE: Produced By Microsoft Exchange V6.0.6603.0
content-class: urn:content-classes:message
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: quoted-printable
Subject: RE: TC6 documentation
Date: Wed, 5 Apr 2006 09:40:20 +0100
Message-ID: <5684A7E6FB10504393A2806C1F4C021007B55323@orion.qas.com>
X-MS-Has-Attach: 
X-MS-TNEF-Correlator: 
Thread-Topic: TC6 documentation
Thread-Index: AcZYHnrDtsIAazhxSgG+1SqNLRTm1AAbAN9w
From: "Allistair Crossley" <Allistair.Crossley@QAS.com>
To: "Tomcat Developers List" <dev@tomcat.apache.org>
X-Virus-Checked: Checked by ClamAV on apache.org
X-Spam-Rating: minotaur.apache.org 1.6.2 0/1000/N

Hi,

I strongly disagree that the current documentation format is helpful
both in terms of readability and accessibility to update.=20

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=3D"general">
  <dt class=3D"update">&nbsp;</dt>
  <dd>
    Required tcnative library version upgraded to 1.1.2=20
    <abbr class=3D"username">(remm)</abbr>
  </dd>
</dl>

<dl id=3D"catalina">
  <dt class=3D"bug">23950</dt>
  <dd>
    Context.listBindings() should return objects not references.
    <abbr class=3D"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.=20

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=3D>XHTML or pure XHTML with CSS.

Allistair

-----Original Message-----
From: Ian Darwin [mailto:ian@darwinsys.com]=20
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=20
> to have some common elements that would get automagically resolved=20
> into the bug tracking URLs, etc.  For example, when I edit the=20
> changelog it's great to just put in <bug>n</bug> and have it be=20
> resolved to the proper Bugzilla link URL.  I think it cuts down on=20
> typos, broken links, etc.  And this is just one example of a useful=20
> custom element out of several.
>  =20
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 :-)=20

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org For additional
commands, e-mail: dev-help@tomcat.apache.org





<FONT SIZE=3D1 FACE=3D"VERDANA,ARIAL" COLOR=3DBLUE>=20
-------------------------------------------------------
QAS Ltd.
Registered in England: No 2582055
Registered in Australia: No 082 851 474
-------------------------------------------------------
</FONT> <FONT SIZE=3D1 FACE=3D"VERDANA,ARIAL" COLOR=3DBLACK>=20
Disclaimer:  The information contained within this e-mail is confidential a=
nd may be privileged. This email is intended solely for the named recipient=
 only; if you are not authorised you must not disclose, copy, distribute, o=
r 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 appropri=
ate action and avoid troubling you further.  Any views expressed in this me=
ssage are those of the individual sender.  QAS Limited has the right lawful=
ly to record, monitor and inspect messages between its employees and any th=
ird party.  Your messages shall be subject to such lawful supervision as QA=
S Limited deems to be necessary in order to protect its information, its in=
terests and its reputation. =20

Whilst all efforts are made to safeguard Inbound and Outbound emails, QAS L=
imited cannot guarantee that attachments are virus free or compatible with =
your systems and does not accept any liability in respect of viruses or com=
puter problems experienced.
</FONT>


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org