forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject Re: Glossary
Date Sun, 09 Apr 2006 00:32:04 GMT
Gav.... wrote:
> 
>>-----Original Message-----
>>From: Ross Gardler [mailto:rgardler@apache.org]
>>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

Mime
View raw message