Re: [oll-user] Call for initial feedback

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

Am 28.03.2013 17:07, schrieb Joseph Rushton Wakeling:
> 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.
OK, I'll do that and make it a test case of my branching strategy ;-)
>
>> 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.
Hm, that's what I originally intended (and what is actually still there: 
each toolbox folder that actually has content has a ...toolbox.ily file 
that can be included separately).
But Jan-Peter (and to some extent Janek) seemed to prefer an approach 
where the user simply includes the library as a whole.

As we're not fixed yet about the primary entry point strategy we can 
still discuss this (but in a separate thread please. And maybe later - 
maybe we should invite a few more people explicitely to participate in 
the current set of discussion items?
>
>> 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.
That's a good idea (the general one), but it also needs some more 
thoughts (see my previous comment)
>
> 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.
_If_ that's the case that's in fact inacceptable.
Looks like the perspective to another long running thread on 
lilypond-user ...
>
>> 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.
Definitely.
>
>> 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
Good to think about that.
It was the explicit intention to have more than a reference manual for 
OLLib. The manual should also be a learning resource goint into some 
detail about the underlying concepts.
But of course it is a valid point that this raises the step for someone 
to contribute, say, a single engraver. And of course your considerations 
about the accuracy of the docs is a valid point.

One more item to discuss ...
>
>> 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.
Right :(
>
>> 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 ;-)
Of course, I know.
But as I have to push often and at times that are imposed on me by the 
clock and not by the state of my work (each time I leave a computer), I 
have lots of Work-in-progress commits in my feature branches that I can 
safely rebase. It's just that one has to be careful about them.
And of course I wouldn't rebase a master branch  ;-)
>
> 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?
Maybe a good idea.
But perhaps I'd rather collect a set of topics to be discussed, invite a 
few more people to join the list (well, actually I can subscribe anybody 
;-)) and try to sort out things this way with some more input of more 
people.
>
>> 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).
Yes, definitely.
>   As things stand I have some
> severe doubts that raw GPL/CC-BY-SA would satisfy this requirement.
The CC-BY-SA part shouldn't be the problem, isn't it?
>
> 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.
>
> ------------------------------------------------------------------------------
> Own the Future-Intel® Level Up Game Demo Contest 2013
> Rise to greatness in Intel's independent game demo contest.
> Compete for recognition, cash, and the chance to get your game
> on Steam. $5K grand prize plus 10 genre and skill prizes.
> Submit your demo by 6/6/13. http://p.sf.net/sfu/intel_levelupd2d
> _______________________________________________
> openlilylib-user mailing list
> ope...@li...
> https://lists.sourceforge.net/lists/listinfo/openlilylib-user