Doc: add markup objects overview

Doc: add markup objects overview

Someone on -user has made me realize that there was
room in the current NR for a (non-exhaustive) list of
the different places where \markup may be used:
https://lists.gnu.org/archive/html/lilypond-user/2019-01/msg00425.html

Aaron Hill has provided a nice example, which I elaborated
upon as http://lsr.di.unimi.it/LSR/Item?id=1084
and then Trevor D. convinced me that it could
find its way into the NR itself.  So, there.

[Valentin Villenave, 2019-01-20 23:24:12]

Typo: add space before @ref link.

[lemzwerg, 2019-01-21 06:18:36]

LGTM, with some minor issues.  Thanks!

https://codereview.appspot.com/357930043/diff/20001/Documentation/notation/te...
File Documentation/notation/text.itely (right):

https://codereview.appspot.com/357930043/diff/20001/Documentation/notation/te...
Documentation/notation/text.itely:50: @cindex Text objects
Any specific reason why you use uppercase?  Wouldn't

  @cindex text objects

be sufficient?

https://codereview.appspot.com/357930043/diff/20001/Documentation/notation/te...
Documentation/notation/text.itely:51: @cindex Markup objects
BTW, I think you should also add

  @cindex objects, markup

for completeness.

https://codereview.appspot.com/357930043/diff/20001/Documentation/notation/te...
Documentation/notation/text.itely:63: 
Grammatical nitpick: If you have a list of items, either do

  This is as follows.
  * Foo bar.
  * Ping pong.
  * Frob nicate.

or

  This is as follows:
  * foo bar;
  * ping pong;
  * frob nicate.

https://codereview.appspot.com/357930043/diff/20001/Documentation/notation/te...
Documentation/notation/text.itely:82: in any definition inside the
@code{\header} block (e.g.
Mid-sentence abbreviations that end with a full dot should have a trailing '@:'
to get correct whitespace.  In this case, however, I would write 'e.g.,'

https://codereview.appspot.com/357930043/diff/20001/Documentation/notation/te...
Documentation/notation/text.itely:83: @var{title}, @var{subtitle},
@var{composer}), or in some
s/@var/@code/

Those header block elements are not variable (i.e., they cannot be changed by
the user to an arbitrary string).

https://codereview.appspot.com/357930043/diff/20001/Documentation/notation/te...
Documentation/notation/text.itely:85: @var{evenHeaderMarkup} for page numbers. 
This is explained in
Ditto.

https://codereview.appspot.com/357930043/diff/20001/Documentation/notation/te...
Documentation/notation/text.itely:89: @noindent
I don't see a necessity for '@noindent'.  You actually start a new paragraph,
don't you?

https://codereview.appspot.com/357930043/diff/20001/Documentation/notation/te...
Documentation/notation/text.itely:119: @noindent
Ditto.

https://codereview.appspot.com/357930043/diff/20001/Documentation/notation/te...
Documentation/notation/text.itely:122: @var{text} property if it has one, or its
@var{stencil} property.  Some of
s/@var/@code/

https://codereview.appspot.com/357930043/diff/20001/Documentation/notation/te...
Documentation/notation/text.itely:148: \once \override NoteHead.text = \markup
\lower #0.5 "NoteHead"
Please check the PDF output; I guess that some lines in your example are too
wide.

https://codereview.appspot.com/357930043/diff/20001/Documentation/notation/te...
Documentation/notation/text.itely:641: Extentind LilyPond:
s/Extentind/Extending/

[Valentin Villenave, 2019-01-24 20:39:09]

Thanks a lot Werner! You caught quite a few things I should have dealt with more
rigorously.

https://codereview.appspot.com/357930043/diff/20001/Documentation/notation/te...
File Documentation/notation/text.itely (right):

https://codereview.appspot.com/357930043/diff/20001/Documentation/notation/te...
Documentation/notation/text.itely:50: @cindex Text objects
On 2019/01/21 06:18:35, lemzwerg wrote:
> Any specific reason why you use uppercase?  Wouldn't
> 
>   @cindex text objects
> 
> be sufficient?

Done.

https://codereview.appspot.com/357930043/diff/20001/Documentation/notation/te...
Documentation/notation/text.itely:51: @cindex Markup objects
On 2019/01/21 06:18:35, lemzwerg wrote:
> BTW, I think you should also add
> 
>   @cindex objects, markup
> 
> for completeness.

Done.

https://codereview.appspot.com/357930043/diff/20001/Documentation/notation/te...
Documentation/notation/text.itely:63: 
On 2019/01/21 06:18:35, lemzwerg wrote:
> Grammatical nitpick: If you have a list of items, either do

Yes. I hesitated between the two, since I’m already using semi-colons before
"see also" (I was reluctant to add another just afterwards). On the other hand,
since the introductory sentence ends with a colon, all that follows is clearly
part of the same sentence. Oh well.

>   * Frob nicate.

Didn’t know that one, thanks :-)

https://codereview.appspot.com/357930043/diff/20001/Documentation/notation/te...
Documentation/notation/text.itely:82: in any definition inside the
@code{\header} block (e.g.
On 2019/01/21 06:18:35, lemzwerg wrote:
> Mid-sentence abbreviations that end with a full dot should have a trailing
'@:'
> to get correct whitespace.  In this case, however, I would write 'e.g.,'

Done.

https://codereview.appspot.com/357930043/diff/20001/Documentation/notation/te...
Documentation/notation/text.itely:83: @var{title}, @var{subtitle},
@var{composer}), or in some
On 2019/01/21 06:18:35, lemzwerg wrote:
> s/@var/@code/
> 
> Those header block elements are not variable

Hm… You’re right. But they’re not really properties either (not in the sense of
music-props or context-props.
I’m gonna write
"specific elements defined inside the @code{\paper} block".

https://codereview.appspot.com/357930043/diff/20001/Documentation/notation/te...
Documentation/notation/text.itely:85: @var{evenHeaderMarkup} for page numbers. 
This is explained in
On 2019/01/21 06:18:35, lemzwerg wrote:
> Ditto.

Right; I ought to remember that @var is not for variables.

https://codereview.appspot.com/357930043/diff/20001/Documentation/notation/te...
Documentation/notation/text.itely:89: @noindent
On 2019/01/21 06:18:35, lemzwerg wrote:
> I don't see a necessity for '@noindent'.  You actually start a new paragraph,
> don't you?

I guess you could see it that way (and it actually makes more sense).  In my
view, I was prolonging the list (and ditto below) by mentioning _other_ places
where \markup may be used. But you’re right, splitting into new paragraphs is
cleaner.

https://codereview.appspot.com/357930043/diff/20001/Documentation/notation/te...
Documentation/notation/text.itely:119: @noindent
On 2019/01/21 06:18:35, lemzwerg wrote:
> Ditto.

Done.

https://codereview.appspot.com/357930043/diff/20001/Documentation/notation/te...
Documentation/notation/text.itely:122: @var{text} property if it has one, or its
@var{stencil} property.  Some of
On 2019/01/21 06:18:35, lemzwerg wrote:
> s/@var/@code/

Done.

https://codereview.appspot.com/357930043/diff/20001/Documentation/notation/te...
Documentation/notation/text.itely:148: \once \override NoteHead.text = \markup
\lower #0.5 "NoteHead"
On 2019/01/21 06:18:35, lemzwerg wrote:
> Please check the PDF output; I guess that some lines in your example are too
> wide.

Done.

https://codereview.appspot.com/357930043/diff/20001/Documentation/notation/te...
Documentation/notation/text.itely:641: Extentind LilyPond:
On 2019/01/21 06:18:35, lemzwerg wrote:
> s/Extentind/Extending/

Oh, dear.

[Valentin Villenave, 2019-01-24 21:11:20]

Address Werner’s suggestions.

[Valentin Villenave, 2019-01-28 20:07:19]

On 2019/01/24 21:11:20, Valentin Villenave wrote:
> Address Werner’s suggestions.

This is a rather trivial amendment, so if nobody has any further objection, I
suggesting pushing it onto the countdown list…

[Valentin Villenave, 2019-02-01 15:17:17]

On 2019/01/28 20:07:19, Valentin Villenave wrote:
> if nobody has any further objection,
> I suggest pushing it onto the countdown list…

Pushed as
https://git.savannah.gnu.org/cgit/lilypond.git/commit/?h=staging&id=e4996ee89...

Thanks!