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

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

As Joe pointed out my conception of openLilyLib's documentation could 
make our lives unnecessarily complicated.

I (intentionally) expected any contributor of code to also contribute 
the relevant documentation. While this is basically a matter of course 
it may be more complex because the documentation is (was) intended 
completely in the form of elaborate tutorial-like learning manuals (i.e. 
being additional learning resources).
While I still think this would be good to have, I admit that this causes 
some problems:
- Any contributor is forced to get the whole archive of the whole project
   because there are dependencies, especially on the LaTeX side.
- This could be a inhibition threshold for someone ready to contribute a 
bit but not to dive too deep into LaTeX authoring.
- The probability of documentation being out of date is high.

Joe's suggestion is good to separate concerns into elaborate manuals and 
concise reference documentation.
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.

Of course there is a difference whether one contributes to a LaTeX 
package or the LilyPond library, but the main concept could be the same.

I have two questions however, that I'd like to be discussed (one smaller 
and one potentially big one):

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.

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.
First a syntax to enter special comments in source files, second a 
program interpreting one file respectively crawling over a chain of 
included files outputting documentation. This should of course not only 
document explicitely commented items but also any item (e.g. variable 
declarations etc.).
I would implement this as a Python program, a) because that's the 
language I started to learn recently and b) because this endeavor 
definitely should be designed right from the beginning to also be a 
contribution to Frescobaldi.

Such a program would be a teriffic enhancement for LilyPond use, not 
only for use with our library, but also for anyone working with complex 
scores.
But I can't start this now because that's absolutely too much to do it 
in addition to everything else. And I'm not proficient enough with 
Python to do it reasonably efficient.
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).
If we have such a syntax design halfway on the way we can still look for 
assistance, i.e. at least one person with sufficient Python skills to 
get the project started.

Best
Urs