Re: run lilypond-book on internals

[Graham Percival]

On Mon, 7 Apr 2008 22:39:35 -0300
"Han-Wen Nienhuys" <address@hidden> wrote:

> I am not sure what the right technology would be. The quoting would
> get very hairy, because most of the internals are generated from .scm
> or .cc files.

Is the method demonstrated in
  scm/define-markup-commands.scm
not good?  It's true that we need to escape \ with \\, but it's
sufficient for the kind of very short examples that we're using in
it.

> I think we should look into a way of having a directory
> 
>   Documentation/internal/grob-properties/PROPERTY-NAME.tely
> 
> make it so that the internals documentation automatically uses that
> snippet for documenting said property.  That would also provide a way
> to do documentations.

I'm not certain this is much better than dumping property
documentation directly in Documentation/user/*.itely... the issue
at hand is making it as easy as possible for programmers to
update.  ie when (not if)  a programmer renames
  staff-symbol #line-count
to
  staff-symbol #number-of-staff-lines
the property-docs should automatically apply.  I thought that if
we included these examples in the .scm files, it would work.


>From an "ease of writing docs" perspective, putting property docs
directly in the .itely file is the easiest.  I've been fighting
tooth and nail to avoid this, because I know from painful
experience that this is terrible from an "ease of maintaining
docs" persepective.

Cheers,
- Graham