> From: Bert Van Kets [mailto:[EMAIL PROTECTED]] > > 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: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
