Re: Some documentation issues

Hello Luise!


>    - In Learning Manual > 5.4.2 Within-staff objects > The direction
>      property, in the list of predefined \objectDown \objectUp
>      \objectNeutral commands, every command in the “Revert” column
>      is \*Neutral, except for the command for arpeggio arrows, which
>      is \arpeggioNormal. Please change it to \arpeggioArrowNeutral
>      to match every other command.

Well, `\arpeggioArrowNeutral` doesn't make any sense!  There are no
arrows in the 'neutral' case.

>      Additionally, it might be best to change the \arpeggioArrowDown
>      and \arpeggioArrowUp commands to simply \arpeggioDown and
>      \arpeggioUp respectively, in which case the reverting command
>      should become \arpeggioNeutral to match them

Carl Sorensen has changed this from `\arpeggioDown` to
`\arpeggioArrowDown`, in version 2.11.51 (from 2008).  Carl, do you
remember why you did that?  I would't object if this was renamed back
to `\arpeggioDown` for consistency...

> Highlighting inconsistencies:
> 
>    - Nowhere in the Notation Reference does the TextMark object get
>    highlighted, and neither does Text_mark_engraver

Hmm.  If I look at the NR from version 2.25.29, I see `TextMark`
printed in boldface.  However, you are right, `Text_mark_engraver` is
not emboldened.  This is because the 'pygments' Python package isn't
updated to a recent LilyPond version – it doesn't know that this is a
keyword.

To fix this, I've just submitted a Pull Request

  https://github.com/pygments/pygments/pull/2974

and as soon this gets accepted, I'll update the pygments code in
LilyPond.

>    - incipit-width (\layout variable) doesn't get highlighted

Ditto.

>    - It's unclear if pdftitle (\header var) should be highlighted or
>      not (quite sure you only see it the one single time in NotRef
>      3.3.3 Creating output file metadata)

Probably yes, they should be highlighted.  I've added them to the
pygments patch.

>    - I don't think annotate-spacing (\paper var) gets mentioned in
>      the lists of \paper variables [...]

In the NR of 2.25.29, it is documented in Appendix B.22, together with
all other paper variables (note that we no longer update 2.24.x
documentation).

> Finally, I'd like to ask why some functions are simply Not There in
> the internals reference??

Good question.  The most likely answer is that the automatic
generation of the IR doesn't cover them (yet).

> I not find magstep in the scheme function list?

There is a trove of functions in file `lily-library.scm`, which are
considered helpful in writing Scheme code for LilyPond, and which
don't appear in the IR (look for all functions defined with
`define-public`).  `magstep` is one of them.  Maybe we should move the
definition of `magstep` to another file so that it gets documented in
the IR, since this is one of the 'standard' function a user might
need.

> IntRef A.1 concept index is completely empty, was it supposed to go
> there?

I've removed it, thanks; see

  https://gitlab.com/lilypond/lilypond/-/merge_requests/2740

> where did make-pango-font-tree go :(

In the 2.25 series, this has been replaced with a better solution.
Please read

  https://lilypond.org/doc/v2.25/Documentation/changes/text-and-font-improvements


     Werner