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

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

Am Samstag, den 13.04.2013, 00:14 +0200 schrieb Janek Warchoł:
> Hi,
> 
> 2013/4/12 Urs Liska <ul...@op...>
>         Am Freitag, den 12.04.2013, 18:45 +0200 schrieb Janek Warchoł:
>         > 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.
> 
> 
> ok.  however, i'm afraid i won't have enough time for this anywhere
> soon :(

Probably it's basically enough to think about our needs first.
And here _only_ about the needs for the LilyPond library.

When I'll have managed to set up working Git repos I'll make an
announcement on lilypond-user and invite people to join oll-user to
discuss this on a broader base.

>  
> 
>         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!
> 
> 
> Awesome :)
> 
Not only for musicologist's use.
I now realized that this way one could enter comments when entering the
music, like open questions and critical remarks.
The output of such a script could serve as a special kind of issue
tracker: There is one document (e.g. pdf or html) that collects all
remarks and links them to the soruce code.
Could also made into a collaborative tool for 'crowd editing'.
During work they are either removed or turned into entries for the
critical report, and when the work is finished one can export them to
the format for the report.
The more I think about it the more I'm looking forward to it ...

Best
Urs
> 
> 
>