Re: Possible documentation error in 2.7.2

[Ben Eichler]

Hi Carl,


Thanks for your thoughtful response, and apologies for my ignorance, I'm a
newbie and this is my first reported "bug". At the time, I was trying to
figure out a way to hide unnecessary printed chords for irregular or long
intervals. Since then, someone on the user list pointed out that the
duration can be multiplied to achieve this effect, and I'm up and running.

In terms of your suggestion, I actually found your usage of the jargon term
"context" helpful rather than suspect. Using jargon might help the user to
understand where that component sits in the wider architecture. It seems we
have different views on what constitutes useful documentation.

Since my suggestion is not in line with policy, and I'm a newbie and my
view is probably naive, maybe it's best to close the issue and leave the
text alone. No hard feelings over here.

Thanks again for your help.


-Ben

On Sun, 1 Mar 2020 at 08:39, Carl Sorensen <address@hidden> wrote:

>
>
> On 2/29/20, 1:46 AM, "Ben Eichler" <address@hidden> wrote:
>
>     HI there,
>
>
>     I read at "2.7.2 Displaying Chords" in the docs: "*Chord names can be
>     displayed only at the start of lines and when the chord changes.*"
>
>     This is a little bit misleading. By default, each chord in the content
> is
>     printed by Lilypond. The documentation is trying to point out that this
>     behaviour can be overridden, but this is not apparent to new readers
> of the
>     documentation.
>
>     Could this sentence in the documentation be clarified to something like
>     this: *"By default, each chord in the content is printed. This
> behaviour
>     can be overridden using the chordChanges setting, as shown below."*
>
> The original sentence is in a selected snippet.  ALL of the selected
> snippets are used to show overrides, because we try to avoid overrides in
> the main body of the text.
>
> The second sentence of your proposal goes against the documentation
> policy.  We don't talk through the code.  We consciously and deliberately
> make these descriptions as short as possible.
>
> Something like "The ChordNames context can be set to display chord names
> only at the start of lines and when the chord changes." would be more
> consistent with our policy, although listing the context name is suspect.
> How would you feel about that sentence?
>
> Thanks,
>
> Carl
>
>
>