Re: [oll-user] Call for initial feedback

[Joseph R. W. <jos...@we...>]

On 03/28/2013 02:56 PM, Urs Liska wrote:
> To be clear (maybe I suspect some misunderstanding here): OLLib is a 
> 'pure' LilyPond library. The user will write \include "OLLib.ily" (after 
> making the path accessible) and then can access all the function and 
> commands we provide in there. 

Just as a small note, I'd recommend only allowing lowercase directory and file
names.  This reflects typical practice for development and libraries across just
about every programming and/or markup language I've ever dealt with and also
helps to avoid potential issues with different case sensitivity rules across OS's.

> In addition he may include units from the 
> OLLincludes subdirectory (e.g. engravers) or he may inspect and use 
> material from the OLLexamples and OLLtemplates directories.

I recommend trying to modularize as much as possible so that users can \include
the minimally necessary parts of OLLib.  Boost is a good example here.

> Functions we implement here _may_ be added in the future to LilyPond, if 
> we and the LilyPond developers consider them general and important (and 
> stable) enough. In the past we developed the \shape function in our 
> library, before David N managed to get it in the main code base.

I think it would be good to have a focus on review, revision and standardization
with the aim of being a more flexible test-ground for LP proper.  Of course
there need be no promises, some stuff may always remain outside.  FWIW I think
your chosen pianoStaff example could probably be revised and generalized
sufficiently to be useful in LP proper, it's only a matter of time and thought.
 One possible way would be to replace SUp and SDown meaning, use the staff named
"up" or "down" with, say, \staffUp and \staffDown meaning, switch to the staff
that is above/below the current one.  Then you need make no assumptions about
staff naming.

Looking into that code, I realized there is another issue.  Your stated licence
is GPL.  How is that meant to interact with the case where e.g. I write an
original piece of music and use OLLib's toolbox in my Lilypond source file?  I
am reasonably sure that if I release only the resulting PDF, there would not be
an issue, but if I want to distribute the .ly source file(s) then almost
certainly GPL requirements would kick in and would therefore force me to give a
GPL licence to my piece of music.

This seems to me to be unacceptable overreach on the part of the licensing.  It
may be worth raising this on the LP lists as it probably also applies to LP
\include's.

> I'm not really sure if I understand you correctly. Maybe it's more to 
> the point to ask about the relation between OLLib documentation and 
> tutorials?

Well, I think it's worth mapping out very clearly what kinds of documentation
are envisioned and how they interrelate -- and modularizing appropriately.  For
example, tutorials should probably not be bundled with library documentation.

> There will be one 'book' documenting OLLib. This is traditional 
> documentation.
> And there will be tutorials that are made accessible on the web site. 
> They aren't conceptually related to OLLib, although they may of course 
> use it and may dwell on certain aspects of it.
> 
> Is that clearer?

It's clearer but I also think you have alternatives that are worth considering.
 Consider e.g. how D documents its standard library:
http://dlang.org/phobos/

Each function/data structure in the library has a brief piece of documentation,
including examples, that is closely coupled to the source code (in fact it is
written in the source code next to the code it documents, and the documentation
is automatically collated from these doc entries in a manner similar to Doxygen).

This is nice and easy to maintain because it is trivial to make sure the small
amount of documentation associated with a given function is up to date with the
function implementation itself.

It's imperfect in another way, because it gives you a only case-by-case
documentation that is not so well integrated as (say) a book.  But it also means
you have a fundamental resource to point people towards which is fairly well
guaranteed to be accurate.

That in turn gives you a certain amount of freedom with respect to other more
"user-friendly" documentation such as an in-depth manual or tutorials, because
there's slightly less urgency behind their being 100% up to date and accurate --
they can be _a_ reference, not THE reference

> Hm, I don't like having that stuff in separate branches. Of course 
> commits will probably never interfere because we have independent 
> directories. But that necessarily means that whenever I check out a 
> branch to work on one book, the others are removed from the working tree 
> and I can't have a look at them.

Treat them as separate Git projects which can be submodules of a "master"
project, not as different branches within the same repo.

That way, you can keep as many or as few of them checked out as you want (in
different subdirs), but their version history will be sufficiently independent
that if I want to contribute to just one of them, I can pull that alone and not
have to branch the whole collection.

> That may be a valid point, but I think we shouldn't have any 
> compromising material in it from the start.

Agree, but I think that we have to consider that this is an accident that is
waiting to happen, however careful we are.

> I can't really judge that due to lack of experience. I'm constantly 
> struggling with keeping all my repos up to date (as I work on different 
> computers I usually have to go through that procedure at lease four 
> times a day ...), which is even more tedious if I rebase my 'private' 
> branches and have to take great care to incorporate them correctly in 
> the other local repo(s).

Use rebase with great, great care ;-)

I have to say I have never had that great a problem keeping my repos clean and
up to date, although I have the bonus of using only a single machine most of the
time.  It helps to be very strict with yourself about using feature branches and
maintaining "master" as a clone of upstream.  (Or alternatively, maintaining an
"upstream" branch to same effect.)

Perhaps one of these days we could have a phone/Skype/other VoIP call to discuss
good git practices, and see if we can resolve some of these issues and concerns
together?

> There is _no_ status yet for both because I have no idea about the 
> proceedings. I planned to look into this as soon as there are regular 
> file releases for both packages.
> The 0.2 release of 'musicexamples' isn't available ATM, and I will have 
> to change that release once more before making it available again, 
> because I have changed the copyright notice (in the hope there won't be 
> somebody who downloaded it in the few days and will make a problem out 
> of it.)
> Probably that would be a candidate for a separate thread (if it still 
> has to be discussed), but I think we should license all source code 
> (i.e. LilyPond sources and LaTeX packages) with the GPL and the 
> 'creative' parts (documentation and tutorials) with CC BY-SA.

Licensing needs extremely careful thought, because the bottom line of it is
this: you want to be absolutely, absolutely certain of what derivative work you
are staking a copyleft claim for.  I imagine we both agree that it's important
that software and documentation deriving from your work should continue to be
free-as-in-freedom, and equally that music written using your tools should be
licensable as the composer/publisher/engraver wishes (and that would include .ly
files as well as the graphical score produced).  As things stand I have some
severe doubts that raw GPL/CC-BY-SA would satisfy this requirement.

One way to bypass that issue might be to use a permissive licence for code
and/or documentation, such as the Boost or Apache licenses (for code) and CC-BY
for docs.  It carries a certain risk, but you have to ask how seriously likely
it is that someone would produce a proprietary derivative work in the first
place, and how much damage it would actually do if they did.

This MUST have been discussed with respect to Lilypond \include calls, so let's
examine the past mailing list discussions and also raise the issue on -devel.