[Lilypond-auto] [LilyIssues-auto] [testlilyissues:issues] #5245 markupli

[issues:#5245] markuplist not documented well

Status: New
Created: Fri Dec 15, 2017 12:56 PM UTC by Palmer Ralph
Last Updated: Fri Dec 15, 2017 12:56 PM UTC
Owner: nobody

Robin Bannister address@hidden wrote :

http://lists.gnu.org/archive/html/lilypond-user/2017-12/msg00298.html
This user thread prompted me to look up \markuplist because
- I didn't recognise it
- from the example I couldn't guess what it was doing.

It turns out that it was once \markuplines (cf issue 1988)
which I may have met previously but never used myself.

I consulted the 2.19.80 manuals, but they didn't help me very much.
I present my tribulations as user cases,
each of which might be ameliorated by a patch.

Case A
I go to 2.19 Notation.D (lilypond command index) and select the jump 'M'.
There is no entry there for 'markuplist'.
This is a regression wrt 2.18 (and 2.16).
The same applies to Notation.E (lilypond index).

Case B (after jump 'M')
Inexperienced users won't scroll back up into the backslash section.
It has 3 entries for '\markuplist', two of which are useless.
The third, 'Multi-page markup' shows \markuplist in an example,
talks vaguely about 'a specific syntax' and doesn't mention \markuplist.
Both \markuplist and the 'specific syntax' are left unexplained.
If it meant \markuplist it would say \markuplist, wouldn't it?

Case C
Sometimes I know there is something I can do with markup but I can't
remember exactly what it is called. Then I go to Notation.A11
(text markup commands) and scroll through the successive sections where
there is a description for each command. This list should be complete.
Doing this for \markuplist turns up a mention at the top of Notation.A12
(text markup list commands) but no description (resp. a link to one).
This would be a good place to insert its description (usual format),
because this is where the reader can best compare the terms
'markuplist command' and 'markup list command'.

Case D
I search in the docs for '\markuplist'. The hit list is swamped
by all the examples containing but not directly concerning \markuplist.
One revealing hit is at
http://lilypond.org/doc/v2.19/Documentation/snippets/text#text-markup-lines
It seems Issue 1988 adapted the code of such snippets but not the texts
in which they are embedded. See also 'Table of Contents' in
http://lilypond.org/doc/v2.19/Documentation/snippets/paper-and-layout

The only usefully explicit text that I found was in the regression tests
- markup-lines-identifier.ly
- markup-lines.ly

Sent from sourceforge.net because address@hidden is subscribed to https://sourceforge.net/p/testlilyissues/issues/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/testlilyissues/admin/issues/options. Or, if this is a mailing list, you can unsubscribe from the mailing list.

From:	Auto mailings of changes to Lily Issues via Testlilyissues-auto
Subject:	[Lilypond-auto] [LilyIssues-auto] [testlilyissues:issues] #5245 markuplist not documented well
Date:	Fri, 15 Dec 2017 12:56:51 -0000