Re: GDP: new Text documentation

[Graham Percival]

On Fri, 18 Apr 2008 14:10:47 +0200
"Valentin Villenave" <address@hidden> wrote:

> 2008/4/18 Mats Bengtsson <address@hidden>:
> 
> >  Please note that the current "Global" list is not the full list,

Sorry.  I definitely wasn't paying attention.

> >  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.

Ok.  That's easily done.  Valentin:
@appendixsec Markup commands

@subsubheading Formatting

@include formatting-list.texi

@subsubheading Alignment

@include alignment-list.texi

...



> "Common markup commands" is indeed meant to be referenced in "common
> formatting commands":

Well, I've already said that those names/categories are not ideal.
"formatting commands" might be better.  Of course, it might make
sense to rename the 1.8.2 section in that case.


> 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?

What else is needed?  We want to group these commands into
categories.  Your first result was good; the programming was just
not ideal.  If your patch didn't have that problem, I'd have
pushed it to master already.

> 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.

Nothing else is needed.  When a programmer adds a new \markup
command, he edits define-markup-commands.scm.  Programmer doesn't
touch .itely, since they don't like doing that anyway; once this
system is set up, documenters don't touch .scm, since they don't
like doing *that* anyway.

Cheers,
- Graham