Possible documentation error in 2.7.2

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

Possible documentation error in 2.7.2

Ben Eichler
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."*

Kind regards,


-Ben
_______________________________________________
bug-lilypond mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/bug-lilypond
Reply | Threaded
Open this post in threaded view
|

Re: Possible documentation error in 2.7.2

pkx166h-4
Hello Ben,

On 29/02/2020 08:46, Ben Eichler 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."*
>
> Kind regards,
>
>
> -Ben

I've created an issue to track this

https://sourceforge.net/p/testlilyissues/issues/5807/

Thanks for the input.

James



_______________________________________________
bug-lilypond mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/bug-lilypond
Reply | Threaded
Open this post in threaded view
|

Re: Possible documentation error in 2.7.2

Carl Sorensen-3
In reply to this post by Ben Eichler


On 2/29/20, 1:46 AM, "Ben Eichler" <[hidden email]> 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
   

_______________________________________________
bug-lilypond mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/bug-lilypond
Reply | Threaded
Open this post in threaded view
|

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 <[hidden email]> wrote:

>
>
> On 2/29/20, 1:46 AM, "Ben Eichler" <[hidden email]> 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
>
>
>
_______________________________________________
bug-lilypond mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/bug-lilypond