Re: GDP: new Text documentation

[Valentin Villenave]

2008/4/6 Graham Percival <address@hidden>:

>  Hey, scheme guys: how hard would it be to introduce our own sorting to
>  B.6 ?  scm/document-markup.scm contains this:

[...]

>  which sorts things alphabetically.  Could we instead group things by
>  function... ideally with our own headings?  ie

OK. Graham, I did implement something that could be useful -- or not.
It's not very elegant, but at least it doesn't break anything.

Here's a patch, in case you'd like to check it out:
http://valentin.villenave.info/lilypond/new_markup_docs.patch

Here's what it looks like (look at the appendix):
http://valentin.villenave.info/lilypond/Documentation/user/lilypond/index.html


On the developers side, I implemented several ways to create a markup command:

define-builtin-markup-command is the way we've used so far. These
commands are listed in "Global markup commands".
define-builtin-markup-list-command is what Nicolas implemented in
2007. These commands are listed in "Multi-pages markup commands"
(formerly known as "Markup lines commands")

Following the same idea, I implemented:

define-builtin-markup-align-command for such commands as
\center-align, etc: these commands are listed in "Markup alignment
commands"

define-builtin-markup-common-command for such commands as \italic,
\bold etc: these commands are listed in "Common markup commands"

define-builtin-markup-graphic-command for things such as \triangle,
\postscript etc: these commands are listed in "Graphical markup
commands"

define-builtin-markup-music-command for every piece of music notation
that goes inside \markup: e.g. \note, \musicglyph, \score etc. These
commands are listed in "Musical markup commands"

define-builtin-markup-other-command is for commands we can't put into
any other category (such as \with-url). This is NOT for unsorted
commands (see below). These commands are listed in "Other markup
commands"

The default "define-builtin-markup-commands" is still active and
usable. The commands that are defined this way are listed in bulk in
"Global markup commands", but this is just meant to be temporary. We
have to work on these commands to sort them, and if developers want to
add new markup commands, it would be preferable that they use one of
the commands I implemented.

So, this creates a bunch of subsections in the Appendix, and then I
can add convenient @refs to link
NR 1.8.2.1 with B.6.1,
NR 1.8.2.2 with B.6.2,
NR 1.8.2.3 with B.6.3,... you get the idea.

Right now, this implementation is not elegant at all. The best
solution would have been to modify the define-builtin-mrkup-command
itself, to make it take the categories as an argument (in some way, to
"tag" the markup commands as we do for LSR snippets). The reason why I
didn't do it is ( because I'm an ignoramus and) because this could
break compatibility at some points: if a command is defined without a
markup-category, I don't know how to handle this situation.

Cheers,
Valentin