Re: What the docs say about \markuplist

[Robin Bannister]

Palmer Ralph wrote:
> The issue has been entered as Issue #5245 markuplist not documented well.


Thanks.
And by the way, this was all with split HTML, if that makes a difference.


I kept this purely user-oriented, leaving implementation unconsidered;
that was quite easy, seeing that I still don't understand markuplist
and have only a hazy idea about what goes on behind the scenes re docs.

But, prompted by James's reply, I started investigating a bit.



Case A
This 'regression' is due to issue 4894.
Going from 2.18 to 2.19.80
  - the backslashed section doesn't change much
  - the subsequent sections lose nearly half of their entries
This severely clobbers the jump<letter> facility.

To compensate, we would need a jump<backslash+letter> facility,
something I've always felt the need for.


Case B
I maintain that the 'Separate text' and 'See also' references are useless.
The user hopes to find mention of \markuplist, the full description
or maybe just some aspect, whatever.
'Separate text' doesn't mention \markuplist.
'See also' is inside 'Multi-page markup' so this reference is redundant.

The 'Multi-page markup' reference is getting warmer but this text 
successfully does its best to avoid mentioning \markuplist.
I traced the history of 'specific syntax':
In [1] it displaces the (old) command name, introducing the obfuscation.
In [2] Valentin accedes to Graham's criticism and removes 'specific' re 
markup, but he keeps 'specific' re 'Multi-page markup'.

Reinstating the command name in these 'specific' places restores the
justification of the 'Separate text' and 'Multi-page markup' references.

But since the relevant part of 'Separate text' is only concerned with
pointing to 'Multi-page markup', this reference is also pretty redundant.


Case C
I retract my proposal (but not the justification) for documenting 
\markuplist at the top of Notation.A12 (text markup list commands) 
because I now see that \markuplist plays a role analogous to \markup 
(this being treated not in Notation.A11 but in Notation.1.8.2).

The least disruptive approach would build on the 'Multi-page markup'
section; keep the initial example and just develop the description after it.


Case D
grep markuplines finds these two ly files and their es/fr counterparts.



[1] 
http://git.savannah.gnu.org/gitweb/?p=lilypond.git;a=commit;h=4cc11ce36f01076b3b5e6bc93b865c612ea68036 

[2] http://lists.gnu.org/archive/html/lilypond-user/2008-10/msg00135.html


Cheers,
Robin