Re: GDP: new display for warnings

[Hans Aberg]

On 5 Oct 2007, at 23:20, Graham Percival wrote:

> > On 4 Oct 2007, at 02:07, Graham Percival wrote:
> > [Please note that non-members are not allowed to post on LilyPond- 
> > Devel, so cc-ing it will not result in replies.]

> Thanks for the warning, I had no idea!

I may have changed over time - it did not bounce now. Check with  
David R. Linn <address@hidden>.

> (don't reply to this email, then)

It is sort of automatic, when doing reply-to-all. Easier to not worry  
about the bounces. But the one that put up the cc may not get the  
intended effect.

> > > I find them quite useful in another project I maintain; should we  
> > > use
> > > them throughout the LilyPond docs?
> > I think you might more words, depending on the contents.
>
> For clarity of documentation writers, I've defined a single @warning 
> {} macro,
> so we can only pick one word.  Everybody likes "note", so I've gone  
> with that.

That is probably more normal in documents. The Bourbaki used a  
"dangerous bend" symbol, and Knuth in the "TeX book" used something  
like that to. So I think that the important thing is to get a clear  
classification whatever it is. Knuth uses a dangerous bend symbol in  
a road sign symbol. Perhaps an exclamation mark "!" could be used for  
information that is required for the code to compile.

> > Now, the first part is really a requirement:
> >   Every part of LilyPond input must have curly braces placed  
> > around the input
> > - or else the compile fails. So it is not merely a warning - it is  
> > a requirement. Also, I changed "piece" to "part", following  
> > Church's book on lambda calculus, which has a technical definition  
> > of a "part" of a lambda expression. It seems me, you have a  
> > similar syntactically closed part in mind here.
>
> Speaking non-technically (I've never read any of Church's writings,  
> and I've forgotten his famous law/thesis/something on formal  
> automata), I think that "piece" is better than "part".  "Every  
> piece of..." sounds more natural than "Every part of..."
>
> If this was in the user manual, I'd be tempted to go with the more  
> technically correct word (ie "part"), but the tutorial is designed  
> to be easy to read, so I prefer keeping "piece".

Right. "Piece" is better informally; "part" would you ever decide to  
give a technical definition.

> > And if they are omitted in the manual, is it because there is an  
> > error in the manual or what?
>
> This is explained in 2.1.4 How to read the tutorial.

Then perhaps give some hint of that :-). If there should be a comment  
at all, it might be reworded as say: "as mentioned [before|elsewhere| 
in section 2.1.4], required [spaces|braces|stuff] may be omitted in  
the examples". This style makes the text somewhat heavier, but it  
helps local reading.

  Hans Åberg