[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: mdash in markup?
From: |
James Harkins |
Subject: |
Re: mdash in markup? |
Date: |
Sun, 5 May 2013 02:52:50 +0000 (UTC) |
User-agent: |
Loom/3.14 (http://gmane.org/) |
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
- mdash in markup?, James Harkins, 2013/05/03
- Re: mdash in markup?, Kieren MacMillan, 2013/05/03
- Re: mdash in markup?, James Harkins, 2013/05/03
- Re: mdash in markup?, Urs Liska, 2013/05/03
- Re: mdash in markup?, James Harkins, 2013/05/04
- Re: mdash in markup?, David Kastrup, 2013/05/04
- Re: mdash in markup?,
James Harkins <=
- Re: mdash in markup?, Werner LEMBERG, 2013/05/05
- Re: mdash in markup?, David Kastrup, 2013/05/05
- Re: mdash in markup?, James Harkins, 2013/05/05
- Re: mdash in markup?, Urs Liska, 2013/05/05
Re: mdash in markup?, Noeck, 2013/05/03