Re: GDP: new Text documentation

[Nicolas Sceaux]

Le 6 avr. 08 à 11:05, Valentin Villenave a écrit :
> - 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.

\markup "returns" a markup.
\markuplines "returns" a list of markups.
When \markup is found at top-level, the markup is added to the list of
scores and markups that compose the book.
When \markuplines is found at top-level, the markups are added to the
list of scores and markups that composes the book, with their inter
padding and spacing set to 0 (so that the text is never vertically
stretched).

Now, \markuplines can only be used at top-level (it does not make
sense in a text script for instance). However, markup-lists (what
\markuplines deals with) already existed before \markuplines was
created: this is what \line or \column use as their argument.  What
was created however together with \markuplines is markup-list
commands, ie commands that return a list of markups, whereas markup
commands return a single markup.  You can define a markup-list command,
and use it in a regular \markup expression:

#(define-markup-list-command (wordwrap-center-lines layout props args)
  (markup-list?)
  "Returns a list of "
  (map (lambda (stencil)
        (interpret-markup layout props (markup #:fill-line (#:stencil  
stencil))))
   (interpret-markup-list layout props (make-wordwrap-lines-markup- 
list args))))

#(define-markup-command (wordwrap-center layout props args) (markup- 
list?)
  (interpret-markup layout props
   (make-column-markup
    (make-wordwrap-center-lines-markup-list args))))

{
  c'^\markup \override #'(line-width . 20)
  \wordwrap-center { A long text rendered as short, centered lines. }
}

In this example, \wordwrap-center builds a markup by stacking the
centered lines built by \wordwrap-center-lines with all the words
the constitutes its arguments.

The syntax is unlikely to change.

> If I may, is it really necessary to have *two* different \markup and
> \markuplines commands?

yes (considering how markups are currently internally represented).

> Would it be possible to implement \markuplines features in \markup
> itself

no (considering how markups are currently internally represented).

Let me answer by an analogy:
The staves of a system should not be sepearated one from each other.
The result of \markup is like a system: consisting of elements that
should stay together. However, several systems may be sepearated by
a page break. The result of \markuplines is like a list of systems:
they may spread over several pages.

...

Nevertheless. Currently, markups are internally represented as a list
of a markup command and its arguments:
  \markup { Hello world! }
  (list line-markup (list "Hello" "word!"))
That is, no property can be specified for a particular markup. Maybe,
if they were objects capable of holding some properties (eg. markup- 
list,
next-padding, etc), we could get rid off \markuplines.

Nicolas