Re: run lilypond-book on internals

[Han-Wen Nienhuys]

2008/4/7, Graham Percival <address@hidden>:
> 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.

The problem is not only the backslashes, but also when you embed lisp
and quoted (") strings inside the .tely docs inside the scm file, it
quickly gets out of hand.  Emacs for example, will get very confused
about what is inside and outside of quoted string. In addition, some
internal docs are in C++, where you have to use \n to denote line
endings too.

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

We can mark properties as being externally documented. Then, if a
rename happens, the system could detect that NEW-NAME.tely does not
exist and bomb.

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

-- 
Han-Wen Nienhuys - address@hidden - http://www.xs4all.nl/~hanwen