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

[Janek W. <lem...@gm...>]

2013/4/5 Urs Liska <ul...@op...>

> Contributors should be obliged to provide documentation for their
> contribution, but only in the form of very small reference
> documentation, similar to what one finds in the LSR (i.e. comments,
> explanation and usage example in the source file itself.
>

+10
i think files provided by David Nalesnik are really nice in this regard.  I
never had any trouble understanding and using his functions, usually
everything is obvious after i look at the examples.


> 1)
> How should the documentation be organized on disk (assuming we go for
> the submodule approach)?
> I think the manuals should be located inside each submodule (because the
> 'musicexamples' user needs the 'musicexamples' manual, be it in the
> binary download or in the Git clone). But this would still mean that
> anybody who wants to compile the manual would have to get either the
> main openlilylib repo or a dedicated latexstuff submodule containing the
> documentclasses and style packages.


yes.


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

Janek
-------------- next part --------------
An HTML attachment was scrubbed...