Re: GDP: new Text documentation

[Valentin Villenave]

2008/4/18 Mats Bengtsson <address@hidden>:

>  Please note that the current "Global" list is not the full list, it's just
> the ones
>  that so far haven't been sorted into the different categories, as far as I
> can see.
>  If all the different categories (subsections!?) end up on the same HTML
> page,
>  then I don't see the point of duplicating the information and also
> supplying a
>  list with all commands in sorted order.

Yes. As I specified in my former mail (and as a comment in the source
code), the "global" category was meant to be eventually removed once
the command would be fully sorted.

"Common markup commands" is indeed meant to be referenced in "common
formatting commands":
http://valentin.villenave.info/lilypond/Documentation/user/lilypond/Common-formatting-commands.html

I'm not fully satisfied with it but I can't think of anything better.

Keeping a "all markup commands" page? Hmm, I don't know what to say.
This was (kind of) my point when I told Graham these pages didn't
exactly belong in the Appendix anymore, where the "Overview of all
markup commands" unarguably belonged.
- My first idea was to regroup all related commands together, in NR
subsubsections: e.g. demonstrate in a single example \bold \italic
etc.
- Then Graham told me: "we want people to look at the Appendix,
because new markup commands are added or modified all the time and
otherwise the NR would get depreciated".
- Then I told him: "the huge Appendix page is really hard to use right
now. Neil can add examples but this wont make browsing it easier". So,
I tried to figure out a way to sort these commands and make them
easier to find -- and Mats, you may find it less usable; just like
you, I actually liked having a huge web-page with all commands -- but
if you have a look at John and Tevor's mails in this thread, you'll
probably find some other opinions :)


In other words, we want the actual command lists to be auto-generated,
*but* we also want these list to be easy to use.
So, my idea is basically to interface the NR section and subsections
with an Appendix section and subsections:

NR 1.8.2.a: "It is possible to obtain basic formatting using simple
commands: see Appendix B.6.a"

NR 1.8.2.b: "it is possible to control how the text will be
horizontally and vertically aligned: see Appendix B.6.b"

NR 1.8.2.c: "it is possible to include graphics in markup: see Appendix B.6.c"

etc.

However,
1- I am *not* fully happy with this idea. We'd still have to remove
the alphabetic sorting in the Appendix short lists, and even if we do
so, we'd still lack some separations inside these lists. If you have a
look at the link above, you'll see what I ideally would like to get in
the end.

2- It is not well coded, I agree with that. It's just a first idea,
that we need to improve. Adding an optional argument to
define-builtin-markup-command is a good idea, but it's just a first
step; then what?

3- Strangely, I'm more pessimistic than Graham here: I don't think
there's much we can do to prevent the docs from easily getting
outdated in such cases. I'd love to, but... I'm running out of ideas.

Cheers,
Valentin