Am 07.07.2015 um 18:14 schrieb David Kastrup:
> Urs Liska <u...@openlilylib.org> writes:
>
>> We have thought for some time to develop a specification for API
>> documentation in LilyPond files. Mainly for library stuff, but it may
>> also be useful for "documents".
>>
>> (There's some discussion you may read at
>> https://github.com/openlilylib/openlilylib/issues/109).
>>
>> There seems to be an agreement to mainly use special block comments
>> preceding the documented function. The suggestion is
>>
>> %{!
>> Enter some documentation, maybe in *Markdown*,
>> together with some fields in a to-be-discussed syntax.
>> %}
>
> Well, the general convention of entering documentation is along the
> lines of
>
> \header {
> texidoc = "... in Texinfo syntax ..."
> }
If I'm not mistaken these fields are then unique (or will probably
redefine the variable when used multiply).
If that's correct I can use that style for documenting on file level
(which is what we actually do in openLilyLib) but not on function
level. So I can't e.g. do
\header {
name = "transposeMe"
type = "music-function"
args = "in: ly:music?, shift: integer?"
...
}
transposeMe =
#(define-music-function
...
)
\header {
name = "splitMe"
type = "music-function"
args = "in: ly:music?, num-slices: integer?"
...
}
splitMe =
#(define-music-function
...
)
>
> LilyPond has a command line option for extracting those kinds of
> headers:
>
> ‘-H, --header=FIELD’
> Dump a header field to file ‘BASENAME.FIELD’.
>
> Of course they don't need to be in Texinfo syntax for that. At any
> rate, in this form they are available also for processing by GUILE.
Sounds interesting. But what could be a use case for accessing
documentation from GUILE?
Urs
>
--
Urs Liska
www.openlilylib.org
_______________________________________________
lilypond-user mailing list
lilypond-user@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-user
