cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Vadim Gritsenko" <vadim.gritse...@verizon.net>
Subject RE: Documentation and abbreviations
Date Fri, 12 Jul 2002 21:38:45 GMT
> From: Bert Van Kets [mailto:bert@vankets.com]
> 
> 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
much
> >>of the existing cocoon documentation is the style in which
> >>Cocoon-specific abbreviations are used.  A good example:
> >>http://xml.apache.org/cocoon/userdocs/xsp/index.html
> >>The most basic question is "What does XSP stand for?"  From there,
one
> >>could almost guess what it is essentially.  My suggestion to
> >>documentation writers is that when using an abbreviation think "Is
the
> >>standard Java developer using Cocoon for the first time going to
know
> >>what this means".
> >>My suggestion in the case they won't, use an abbreviation
introduction
> >>for the first use in the document as follows:
> >>---
> >>Here will soon appear an overview of the user perspective of
eXtensible
> >>Server Pages (XSP).
> >>---
> >>from then on its safe to use the abbreviation and the reader will
know
> >>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
dictionary.
> 
> this is a great idea if implemented properly.  I hate being moved to a
new
> 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
> (http://www.w3.org/TR/html4/struct/global.html#adef-title), but then
there
> is a non-functioning link on the abbreviation

???

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

http://www.w3.org/TR/html4/struct/global.html#h-7.5.4


PS Why not <acronym/>?


Vadim


> 4. a link to a new window and anchor containing the explanation,
perhaps
> sized using the JavaScript window.open command
> 5. a link and anchor in the same window (beurk) definitely a -1 from
me
> 
> 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: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org


Mime
View raw message