Re: GDP: introducing examples

[Hans Aberg]

On 19 Oct 2007, at 08:40, Graham Percival wrote:

> Currently we have a few different ways of introducing examples in  
> the docs.  Should we standardize on a particular way, or just let  
> doc writers do whatever they want?

I have the idea that there should be created a separate PDF doc with  
examples, including the snippets (whose pics happen to be broken in  
my web browser, Safari 3). Then the user manual should reference  
that, with a list of what the examples manual contains.

The idea is based on what I find the easiest way to find programming  
usage, namely, in the PDF viewer (I use Preview, but I thing it works  
in Adobe Reader), type a keyword, and looking through all matches.  
The keyword can be both musical terms as well programming names. So  
therefore it helps with a manual mentioning these terms, and with  
directions for further reading

Also, the user manual is already somewhat heavy. So having a second  
manual with examples would be great.

In the context of your question, this gives the opportunity to put  
examples which are too spacious into the examples manual. The user  
manual should be restricted to examples that illustrate concept of  
the text.

Perhaps there should be a third manual: "advanced usage", as well.

  Hans Åberg