GDP: new Text documentation

[Valentin Villenave]

Hi everybody, hi Graham, hi Nicolas, hi Neil, hi Trevor,

As you may have noticed (or not), the NR1.8 Text section is going
through several major changes.

######################

1- I have added a new subsection in  Text, called "Separate text":
http://kainhofer.com/~lilypond/Documentation/user/lilypond/Separate-text.html
This subsection is meant to introduce top-level \markup and
\markuplines expressions.

==> Questions:

- how can I put @lilypond examples to document these features? Do I
need to use \book? Is there a way to prevent lilypond-book to add the
usual header around my code?

- I need some suggestions on how to document \markuplines vs \markup.
The question behind it being: Nicolas, is the \markuplines syntax
likely to change? e.g. could, at some point, \markuplines be included
in \markup blocks? Is \markuplines a superset to \markup, or is it the
other way around? etc.

###################

2- The 1.8.2 section, formerly "Text markup", has been renamed to
"Formatting text", for better consistency with 1.8.1 "Writing text".
Neil is (or will be) rewriting all the examples and stuff like that.
However, we need to think about

In this section, I'd like to introduce the top-level \markup features,
as well as Nicolas' brand new \markuplines syntax. The commands will
be precisely described in 1.8.2 "Formatting text", that's the new name
of our former "Text markup" subsection. So, the current layout is:

# 1.8 Text

    * 1.8.1 Writing text
          o 1.8.1.1 Text scripts
          o 1.8.1.2 Text spanners
          o 1.8.1.3 Text marks
          o 1.8.1.4 Separate text

    * 1.8.2 Formatting text
          o 1.8.2.1 Text markup introduction
          o 1.8.2.2 Nested scores
          o 1.8.2.3 Page wrapping text
          o 1.8.2.4 Font selection

I am absolutely not fond of the 1.8.2. layout. Having thought a bit
about it, I'd like to propose something like:

    * 1.8.2 Formatting text

          o 1.8.2.1 Introduction to markup mode
                            ( \markup basics; basic text alignment)

          o 1.8.2.2 Common markup commands
                            ( \bold, \italic etc; advanced text alignment )

          o 1.8.2.3 Graphics and glyphs inside markup
                            ( \postscript, \musicglyph etc)

          o 1.8.2.4 Music notation inside markup
                            ( nested \scores etc)

          o 1.8.2.5 Multi-pages markup
                            ( \markuplines; multi-pages text alignment etc)

Questions:

- any thoughts?

########################

3- Graham and I are considering moving Font selection to NR3, and add
Trevor-style @refs in 1.8.2.x

Graham said:
>  > >  Big consideration: is font selection used for anything other than
>  > >  text?  (vocal music, maybe?)   I really don't know the answer,
>  > >  since I know (and care) nothing about vocals, and I've never been
>  > >  concerned enough with text to bother changing the font.

I said:
>  > There are actually two issues at stake: selecting an already
>  > implemented font (sans, roman etc) is easy, selecting custom fonts is
>  > a nightmare (involves rebuilding the pango-tree etc). We should
>  > document the simple one in simple terms (i.e. not the way it's
>  > currently done, which is why this has to move), and let a NR3 @ref for
>  > daring users wanting to try the complex one.

Questions:

-comments, anyone?

###############################

If I may, is it really necessary to have *two* different \markup and
\markuplines commands?
Would it be possible to implement \markuplines features in \markup
itself, or am I being delusional here?
I mean, who might want his markups to spread out of the page?

Cheers,
Valentin