Gav.... wrote:
-----Original Message-----
From: Ross Gardler [mailto:[EMAIL PROTECTED]
Sent: Sunday, 9 April 2006 7:42 AM
To: dev@forrest.apache.org
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).
...
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.
Well the problem with adding code (in this specific example) is that one
has to choose an output format, such as HTML, but a concept such as the
dispatcher is relevant to much more than just HTML. So even your mention
of "<div>" and "<span>" could end up causing confusion for some readers.
How about something like:
"A markup element that defines a logical "chunk" of data within the
structural make-up of a page. For example, the navigation menu is one
such "chunk" of data, whilst the main body is another. Each chunk can be
given individual styling information at the final output stage. Each
forrest:hook may contain zero or more forrest:hook children."
(this is still clumsy but at least it removes implementation specific
details)
Are short Glossary Entries like this going to be good enough, with links to
further references and code examples?
I think this particular example illustrates pretty well why I think we
need to avoid code in glossary entries - there really is not enough
space to deal with all the possible examples.
Ross
