Re: mdash in markup?

[James Harkins]

David Kastrup <dak <at> gnu.org> writes:

> > I see it now. It wasn't obvious to me that the special character
> > aliases wouldn't work without enabling them in the paper block.
> 
>     A list of ASCII aliases for special characters can be included:
> 
>         \paper {
>           #(include-special-characters)
>         }
> [...]
> 
> It does not get much more obvious than that.

It can.

My real point is about the styles in which people approach documentation. My 
complaint comes up in SuperCollider-land because, more often than I'd like) a 
method's documentation consists of one sentence (or sometimes just a sentence 
fragment) that barely says more than you could guess from the method's name. 
Then there's one example, from which the reader is supposed to infer the 
relationship between the input and output, and anticipate corner cases (in the 
absence of any hints that corner cases could even exist). This bugs me because 
a/ I tend to read text and skim examples and (more importantly) b/ it's 
imprecise. Here, I was left to guess about the criticality of include-special-
characters, and I guessed wrong. My point is, why should I have had to guess 
in the first place?

Lilypond's documentation is generally better than that. But here is a case 
where a feature is entirely inactive without a statement, placed earlier in 
the document (possibly even in a different file, if the markup appears in an 
included file), and nothing in the text says that these aliases will fail 
otherwise. Sure, the manual "contains" the information, but neither does it 
call attention to the complete failure of this feature (admittedly, a marginal 
feature...). As a general rule of thumb in documentation, I tend to think, if 
something will break completely without special preparation, that warrants a 
NOTE or WARNING in the text.

I can send a doc patch, if you like. Fixing is better than complaining.

hjh