> -----Original Message----- > From: Ross Gardler [mailto:[EMAIL PROTECTED] > Sent: Sunday, 9 April 2006 7:42 AM > To: [email protected] > Subject: Re: Glossary > > Gav.... wrote: > > I notice I can not add code examples to the Glossary, should I limit the > > Glossary to descriptions only with links to code examples then? > > In my opinion, a glossary is not intended to be any kind of tutorial or > example. It should only give a concise definition and a link to more > complete documentation.
I agree, I am still trying to create that line between description and example though. > > The problem with allowing too much detail in a glossary is that it then > becomes "just another place" for documentation to go. The more places we > have for documentation, the more fragmented that documentation becomes. > > > It would have been nice to have even an inline or one line code snippet. > > I am -0 on allowing code snippets in glossary entries. I would rather > the effort went into ensuring the main docs were complete and linking to > them from the glossary. > > Others may disagree. I do agree. I am looking through http://marc.theaimsgroup.com/?l=forrest-dev&m=112596689428172&w=2#1 which is the most upto date complete summary of what is the Dispatcher (still called Views then). Trying to describe hooks, the post says :- forrest:hooks. forrest:hooks is a concept of defining format independent hooks to structure the output. In xhtml this hooks a transformed into <span/>s and <div/>s. For example: "<forrest:hook name="testIdDiv"/> *or* <forrest:hook name="testIdDiv" type="div"/> will be transformed into <div name="testIdDiv" /> The same is true for @class attribute for forrest:hooks. <forrest:hook class="testClassDiv"/> *or* <forrest:hook class="testClassDiv" type="div"/> will be transformed into <div class="testClassDiv" /> Another feature is that you can as well output span elements for forrest:hooks instead of div elements. <forrest:hook name="testId" type="span"/> will be transformed into <span id="testId" />" If we take out the example code, we are left with :- "forrest:hooks. forrest:hooks is a concept of defining format independent hooks to structure the output. In xhtml this hooks a transformed into <span/>s and <div/>s. The same is true for @class attribute for forrest:hooks. Another feature is that you can as well output span elements for forrest:hooks instead of div elements." My summary would something like :- "forrest:hooks - A hook is structural markup, it can be a <div> block or an inline <span>." Without example code, I can not really say too much more about it. Are short Glossary Entries like this going to be good enough, with links to further references and code examples? Gav... PS - CDATA does allow for code examples in the Glossary Document, so ignore my original assumption. > > Ross > > > -- > No virus found in this incoming message. > Checked by AVG Free Edition. > Version: 7.1.385 / Virus Database: 268.4.0/304 - Release Date: 7/04/2006
