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 [EMAIL PROTECTED] > - verba volant, scripta manent - > (discussions get forgotten, just code remains) >--------------------------------------------------------------------- > > >--------------------------------------------------------------------- >To unsubscribe, e-mail: [EMAIL PROTECTED] >For additional commands, email: [EMAIL PROTECTED] --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
