cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Vadim Gritsenko" <>
Subject RE: Documentation and abbreviations
Date Fri, 12 Jul 2002 21:38:45 GMT
> From: Bert Van Kets []
> At 16:19 12/07/2002 +0200, you wrote:
> >Andrew C. Oliver wrote:
> >>Hi All,
> >>this is mostly a pedantic issue.  But one thing that bugs me about
> >>of the existing cocoon documentation is the style in which
> >>Cocoon-specific abbreviations are used.  A good example:
> >>
> >>The most basic question is "What does XSP stand for?"  From there,
> >>could almost guess what it is essentially.  My suggestion to
> >>documentation writers is that when using an abbreviation think "Is
> >>standard Java developer using Cocoon for the first time going to
> >>what this means".
> >>My suggestion in the case they won't, use an abbreviation
> >>for the first use in the document as follows:
> >>---
> >>Here will soon appear an overview of the user perspective of
> >>Server Pages (XSP).
> >>---
> >>from then on its safe to use the abbreviation and the reader will
> >>what you mean. I believe that doing this will prevent Cocoon
> >>documentation from reading like an eyechart ;-)
> >
> >Even better, we make a link creating Transformer that transforms all
> >instances of " xsp " to a link that links to a cocoon terms
> this is a great idea if implemented properly.  I hate being moved to a
> page just clicking on a link on an abbreviation.
> I see different implementations
> 1. a link to a footnote on the same place where the abbreviation is
> explained.  At least the user would stay on the same page.
> 2. a javascript alert that gives the full explanation
> 3. use of the title attribute
> (, but then
> is a non-functioning link on the abbreviation


<span title="eXtensible Server Pages>XSP</span>

PS Why not <acronym/>?


> 4. a link to a new window and anchor containing the explanation,
> sized using the JavaScript command
> 5. a link and anchor in the same window (beurk) definitely a -1 from
> I thing it should be possible to use XSLT for this, but it might be
> slooooooooow as every text node needs to be tested for every
> abbreviation.  Sadly enough my Java knowledge is not up to speed yet.
> Bert

To unsubscribe, e-mail:
For additional commands, email:

View raw message