Hallo again!
At the end of LM 3.3.2. there is the caution:
Note the distinction between the name of the context type, Staff, Voice,
etc,
and the identifying name of a particular instance of that type ...
Well, I can manage that, I think.
Because when I'm looking at the snippets,
these names look quite different: one lot are in quotes.
But when I start reading in the manuals about using these names I get
confused.
LM says, for example,
> context name (like Staff or Voice)
But when NR says
> when setting lyrics the melody is in a named context
it is talking about an identifying name.
And quite often they mention
> context type
which could make someone think that that was something different again,
i.e. something else to learn about,
but maybe
it is because it would be inappropriate to say "name" at that point
or maybe
"name" is being used nearby for something else.
OK. I know this doesn't fit in with the docs schedule.
And I shouldn't really be reading NR 5 yet.
This feedback goes orthogonal to the section view,
and so will be untimely in many different ways.
Feel free to ignore it (for the time being).
________________________________________________
Two weak rules:
WR1 Avoid "name" as a verb.
WR2. Keep "context" and "name" words well apart.
WR1 is because the this verb is ambiguous:
A: to refer to by name (like the <type> of \context)
B: to give a name to (like the = <id> of \context)
i.e. this is important when used near "\context"
where the author might mean A and the reader understands B.
(This may only apply to English, but English is the language being
translated.)
WR2 is like taking big strides when your shoelaces are undone.
It doesn't apply if there is a qualifier which reduces the ambiguity
sufficiently:
e.g. named voice context (already has a type name, so must mean id)
The lilypond word "context" itself is ambiguous if alone,
applying to either type or instance.
(I'm not talking about normal discourse, which copes with ambiguity).
Unambiguity is most important in the command syntax sections.
It is less important elsewhere but only if there are watertight
definitions
the puzzled reader can refer to when needing clarification.
To apply these rules you have to find suitable words/phrases to replace
the
forbidden ones.
________________________________________________
I thought I would try this out to see if it produced something clearer for
me.
On starting I ran into a different problem:
the placeholders used in the new/context/set/override syntax sections
vary
a lot, making it difficult for the reader to see the similarities.
I unified the placeholders for <type> and <id> (but left the others
unchanged)
and thought up some new verbs.
The result is attached as TAB-separated csv with 3 columns:
- section numbering
- phrases/sentences I considered relevant to to "context" and "name"
- my rewording of those phrases/sentences which violated WR1/2.
Cheers,
Robin
r2b