Re: [oll-user] Learning manuals vs. reference documentation | lilydoc

[Urs L. <ul...@op...>]

Am Freitag, den 12.04.2013, 18:45 +0200 schrieb Janek Warchoł:
> 2013/4/5 Urs Liska <ul...@op...>

> 
> 
>         2)
>         In what form should the reference documentation be supplied?
>         I think it would really be best to have that in the source
>         files
>         themselves, this being the most straightforward approach to
>         keep it up
>         to date.
>         But we definitely need that reference in pdf form too. Which
>         leads me to
>         an idea that I've had for some time already but didn't have
>         the
>         opportunity to tackle yet: I would really love to have yet one
>         more
>         independent subproject: lilyDoc.
>         This would be similar to Javadoc, pyDoc or any other source
>         code
>         documentation system.[....]
>         What I would suggest is to discuss the possible syntax of
>         do-commenting
>         LilyPond source files and use that for the reference
>         documentation, but
>         leave the development of a full-fledged lilyDoc for the
>         future. OTOH it
>         should be quite simple to write a preliminary script that
>         prepares LaTeX
>         source code from such commented source files (to have them
>         available for
>         PDF documents).
> 
> 
> This looks like a good idea.  However, i have limited experience with
> such systems, so i don't have more thoughts on this topic.
> 
We should probably look at two or three languages (e.g. Java and Python)
and collect ideas about their syntay (i.e. how to document the source
files).
Then we should discuss our special cases - because this is another field
where we are facing the hybrid nature of LilyPond files as source code
and documents.
For our immediate need we could stick to documenting the source code,
but for a real lilyDoc library we should also strive for documenting the
content.
For example it would be a real improvement if we could enter critical
remarks directly in the source code and let a script harvest and output
them. This would an extremely cool feature when talking with
musicologists.
If I could for example enter the latex code for critical remarks
directly in the source, then I'd have 2way point-and-click at hand, i.e.
I could enter the remarks in the environment where I inspect and correct
the score. Afterwards a script would parse the files, sort the remarks
and spit out the (nearly finished) critical report. Cool!
But that's just one idea. This would have to be thoroughly discussed in
a brain-storming, maybe not on a mailing list.

For now we can concentrate on a syntax to document a library, with
extending only in the back of our minds.

Urs
> 
> Janek
>