cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bert Van Kets <b...@vankets.com>
Subject Re: Documentation and abbreviations
Date Fri, 12 Jul 2002 20:26:57 GMT
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
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


>--
>Nicola Ken Barozzi                   nicolaken@apache.org
>             - verba volant, scripta manent -
>    (discussions get forgotten, just code remains)
>---------------------------------------------------------------------
>
>
>---------------------------------------------------------------------
>To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
>For additional commands, email: cocoon-dev-help@xml.apache.org


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


Mime
View raw message