openlilylib-user — General openLilyLib discussion

Re: [oll-user] First paragraph of tutorial reads slightly oddly

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

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

> Am Donnerstag, den 11.04.2013, 19:41 +0200 schrieb Urs Liska:
> > Thanks, Ian,
> >
> > sounds good, and I'll incorporate it as soon as I have the opportunity.
>
> Done :-)
> Urs
>

:)
-------------- next part --------------
An HTML attachment was scrubbed...

Re: [oll-user] Licensing questions

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

Hi,

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

> One thing I forgot in the above post:
> If we should settle upon a more permissive license in some parts we'd
> have to take care that we still comply with GNU's ideas.
> Not because I'm a purist or because I'm afraid of David K's comments,
> but because there was a discussion on lilypond-user about GNU programs
> (i.e. LilyPond) not being allowed to endorse or link to non-free
> software and/or documentation.
>

Indeed.
Frankly, i got lost in the discussion on -user and all the legal problems
that arise :(

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

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

Re: [oll-user] Repository organization

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

Am 12.04.2013 14:13, schrieb Janek Warchoł:
> Time to catch up with some things..
>
> 2013/4/5 Joseph Rushton Wakeling <jos...@we...>
>
>> But if you are concerned,
>> the simplest way is just to give up the idea of one-repo-to-rule-them-all
>> and
>> have a few different repositories to cover different parts of the project.
>>
>> It's zero added complexity for users of the project, as one can always
>> bundle
>> everything together in one big .tar.gz file for user download; it adds some
>> complexity for developers/contributors but also reduces complexity in
>> other ways.
>>
>> So, I would start by modularizing the project appropriately into different
>> repos
>> without worrying about submodules, and think about introducing them later
>> if
>> that seems to be necessary.
>>
> This sounds reasonable.  As long as we don't have more than a few repos in
> a flat directory structure, that shouldn't be very complicated to execute.
> If we encounter problems, we can fix them in the future.
> Janek
I also thought this is reasonable. We should probably have separate 
repos for
- the LilyPond library
- common LaTeX stuff (that is necessary to compile documents)
- tutorials
- web site
- lilyglyphs
- musicexamples
- (lilydoc [if it should come into existence ...])

But it seems not so easy to separate the repositories regarding their 
history.

I tried to rip off a musicexamples repository but failed so far.
First I made a copy of the existing repo and restored the old history 
that had been stuffed away in the archive tag. This worked quite well, 
and I'm very happy I did that.

Then I tried to extract the history for the musicexamples directory with 
git filter-branch --directory-filter, and this didn't work:
- filter-branch --directory-filter works only for files that are in that 
dir _currently_
commits with files that have been moved into at some time are not included
-> the oldest transfered commit was consequently titled 'move to 
musicexamples dir' ,-)
- reason for that is:
- filter-branch pulls the directory to the root level
- if a file had been moved from a directory _above_ the target of 
--directory-filter
it would end up being considered as outside the git repository

My research regarding the other filters didn't turn up a solution, at 
least none that I'd realized/understood.

I could log the history of the files with --follow which would include 
the history across renames. But this works only for singe files, not a 
directory.

An approach I could imagine is to recursive loop over all files in the 
directory and store all commits for each one, then merge these lists to 
one to remove duplicates, finally apply them all, maybe with cherry-pick 
on a new branch.
Of course this would be rather simple for example with Python, but I 
have to admit I'm not quite ready for such a thing.
And I don't quite see the implications of different branches for this 
approach yet.

So it remains open:
Any ideas how to deal with the situation?

The simplest solution would be:
- Just remove all files except the ones needed for the new repo with a 
regular commit
- Move all remaining files to the desired new location in the directory 
structure, also with a regular commit.
Absolutely painless process, but of course each repo would carry the 
whole history.

Second simplest solution:
- Add only the desired files to the new repos
- Keep the existing repo as the only instance of the history.

I don't like both.

Urs
> -------------- next part --------------
> An HTML attachment was scrubbed...
> ------------------------------------------------------------------------------
> Precog is a next-generation analytics platform capable of advanced
> analytics on semi-structured data. The platform includes APIs for building
> apps and a phenomenal toolset for data science. Developers can use
> our toolset for easy data analysis & visualization. Get a free account!
> http://www2.precog.com/precogplatform/slashdotnewsletter
> _______________________________________________
> openlilylib-user mailing list
> ope...@li...
> https://lists.sourceforge.net/lists/listinfo/openlilylib-user

Re: [oll-user] Repository organization

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

Time to catch up with some things..

2013/4/5 Joseph Rushton Wakeling <jos...@we...>

> But if you are concerned,
> the simplest way is just to give up the idea of one-repo-to-rule-them-all
> and
> have a few different repositories to cover different parts of the project.
>
> It's zero added complexity for users of the project, as one can always
> bundle
> everything together in one big .tar.gz file for user download; it adds some
> complexity for developers/contributors but also reduces complexity in
> other ways.
>
> So, I would start by modularizing the project appropriately into different
> repos
> without worrying about submodules, and think about introducing them later
> if
> that seems to be necessary.
>

This sounds reasonable.  As long as we don't have more than a few repos in
a flat directory structure, that shouldn't be very complicated to execute.
If we encounter problems, we can fix them in the future.
Janek
-------------- next part --------------
An HTML attachment was scrubbed...

Re: [oll-user] First paragraph of tutorial reads slightly oddly

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

Am Donnerstag, den 11.04.2013, 19:41 +0200 schrieb Urs Liska:
> Thanks, Ian,
> 
> sounds good, and I'll incorporate it as soon as I have the opportunity.

Done :-)
Urs

Re: [oll-user] First paragraph of tutorial reads slightly oddly

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

Thanks, Ian,

sounds good, and I'll incorporate it as soon as I have the opportunity.

Urs

Am 11.04.2013 18:15, schrieb Ian Hulin:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> Hi Urs, Janek,
>
> The first paragraph of the tutorial reads slightly clunkily to a
> native-speaker. Could I suggest the following as a re-draft?
>
> LilyPond has extensive documentation, which is an excellent state of
> affairs when compared to most other Open Source software packages.
> However there are still some occasions when new or even more advanced
> user could do with some more detailed explanations.
>
> The documentation is mostly reference material and so does not take
> very much time in leading the user the key concepts in the appropriate
> order.
>
> This is where our tutorials aim to help out. They each concentrate on
> a single topic, and can afford to dwell on that however long as its
> author considers appropriate.
>
>
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.11 (GNU/Linux)
> Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/
>
> iQEcBAEBAgAGBQJRZuGtAAoJEBqidDirZqAS7D4IAIYDWyFztY6TKCpPJvlj8Aep
> 0MKFGOkH+rfuaDKwLqpE3sRXJwAoGljS6b0n712ZEv340LIuxVUD/MaR2EHku1zV
> JsAJccy6c6L/Ge6hEYOo+ZxsOUY4wHTE7fF+wyMKRKop8uxYjvXf/KwREDmPc7QW
> 0qYPl1XZkJwR7G2YW1CKesUeTPmYQiUjPSfymYNn5UzsaNpl8U4B9skd0J+c7wyW
> zhFZwEIMpZiH0LCIMbiu1UGD9fjc1hcf2r+21bVIYuoH+73TODxWUGCityUdsMdQ
> a8yAu6jm0IDM2CrrfG1DrChPO1EEMdxr9YGizSjiHiAm5nsd0kD2IlTLIwdTwnw=
> =6nzm
> -----END PGP SIGNATURE-----
>
> ------------------------------------------------------------------------------
> Precog is a next-generation analytics platform capable of advanced
> analytics on semi-structured data. The platform includes APIs for building
> apps and a phenomenal toolset for data science. Developers can use
> our toolset for easy data analysis & visualization. Get a free account!
> http://www2.precog.com/precogplatform/slashdotnewsletter
> _______________________________________________
> openlilylib-user mailing list
> ope...@li...
> https://lists.sourceforge.net/lists/listinfo/openlilylib-user

[oll-user] First paragraph of tutorial reads slightly oddly

[Ian H. <ia...@hu...>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi Urs, Janek,

The first paragraph of the tutorial reads slightly clunkily to a
native-speaker. Could I suggest the following as a re-draft?

LilyPond has extensive documentation, which is an excellent state of
affairs when compared to most other Open Source software packages.
However there are still some occasions when new or even more advanced
user could do with some more detailed explanations.

The documentation is mostly reference material and so does not take
very much time in leading the user the key concepts in the appropriate
order.

This is where our tutorials aim to help out. They each concentrate on
a single topic, and can afford to dwell on that however long as its
author considers appropriate.


-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQEcBAEBAgAGBQJRZuGtAAoJEBqidDirZqAS7D4IAIYDWyFztY6TKCpPJvlj8Aep
0MKFGOkH+rfuaDKwLqpE3sRXJwAoGljS6b0n712ZEv340LIuxVUD/MaR2EHku1zV
JsAJccy6c6L/Ge6hEYOo+ZxsOUY4wHTE7fF+wyMKRKop8uxYjvXf/KwREDmPc7QW
0qYPl1XZkJwR7G2YW1CKesUeTPmYQiUjPSfymYNn5UzsaNpl8U4B9skd0J+c7wyW
zhFZwEIMpZiH0LCIMbiu1UGD9fjc1hcf2r+21bVIYuoH+73TODxWUGCityUdsMdQ
a8yAu6jm0IDM2CrrfG1DrChPO1EEMdxr9YGizSjiHiAm5nsd0kD2IlTLIwdTwnw=
=6nzm
-----END PGP SIGNATURE-----

[oll-user] Riemann symbols

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

It is nothing current, but I want to make a note here in order not to forget it later (or to attract some interest):
In addition to the 'lilydoc' subproject I wrote about recently there is one more subproject I will need myself and would therefore like to have added to openLilylib:
Functional analysis symbols for LilyPond and LaTeX.

Urs

[oll-user] Issue splitting Git repository

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

See
http://stackoverflow.com/questions/15868808/split-subdirectory-from-a-git-repository-and-keep-history-of-all-files-that-are

Re: [oll-user] OLLib<->LilyPond | Contribution/review

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

On 04/06/2013 01:32 PM, Urs Liska wrote:
> Good point. But I don't think we should over-emphasize OLLib's potential 
> as a 'staging area' for LilyPond.

Yes.  It should be one purpose that OLLib can serve, rather than _the_ purpose.

> I'd rather say that we should have a rather strict policy of including 
> only material in OLLib that has got a certain degree of approval. This 
> means that we should discuss the point of including any functionality at 
> all, and  have a somewhat strict review process before pushing 
> contributions to the master branch.

Exactly.  You're not LSR -- this is stuff that is guaranteed to have had review
and thought and where the design has been considered with some care, not
someone's personal private solution that has been chucked over the wall and will
no longer be maintained.

(Obviously lots of stuff in LSR was carefully thought out by its contributors
and I'm sure that individual people did try and maintain their contributions,
but the design of LSR didn't ensure that stuff _would_ be maintained or well
designed.  OLLib is different in that respect.)

> So first we should consider whether a proposed addition makes sense as 
> an enhancement of OLLib and already get an idea if we consider it 
> appropriate to propagate it for inclusion into LilyPond.
> Then we should review patches and discuss them with regards also to 
> syntactical consistence with LilyPond's conventions.

Sure, you can decide on a case-by-case basis whether a feature is obviously
Lilypond-bound (in which case OLLib can literally be a staging/testing area),
whether it's something more experimental which may or may not turn out to be
worth sending to LP in the future, or whether it's something that is useful but
guaranteed to never be something worth putting in the core LP project.

> That's a good idea, and you may have noticed that I started my research 
> on this topic.

Yes, I saw.  Good for you for moving so quickly! :-)

> But (for the sake of having an example) I'd nevertheless keep the SUp 
> versions as shorthands in a library, because they would then be 
> shorthands for \staffUp \voiceOne etc. (which I wouldn't consider as 
> really natural for being included in LilyPond proper).

The nice thing about OLLib is that you can actually maintain stuff like this
without damaging anyone.

Re: [oll-user] Call for initial feedback

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

On 04/06/2013 01:39 PM, Urs Liska wrote:
> This is a very good idea. It is completely practical to have an 
> individual style sheet for use in an individual tutorial.
> Or a tutorial author could write his additions directly in the preamble 
> of his 'subfile'.

That said, you want to avoid this as much as possible, because it means that
changes to the global stylesheet may break individual tutorials if there are
clashes with their customizations.

I know that probably sounds like a contradiction with what I said before, but
not really.  Priority should be something like: if you need a new stylesheet
feature, try and design something general-purpose and useful to everyone that
can go in the global stylesheet.  If your need is really, really specific, then
put it in a local stylesheet, but try and design it so that it's very unlikely
to suffer from global stylesheet tweaks.

What shouldn't be acceptable is someone making a custom stylesheet just as a
lazy way of having to avoid thinking about how to tweak the global stylesheet.
Of course, if you really like someone's tutorial, you could accept it as a short
term measure to get the tutorial included and then the core OLLib people take
responsibility for correcting the design ... :-)

> I see your point, but that's not really the case here.
> I have to change the style sheets often because they are developed along 
> the way. So I'll add an environment for a specific kind of table when I 
> first need it. So the number of this kind of updates will fastly 
> decrease. And it can be made simpler with your previous suggestion.

As you say it's a short-term pain.  So, in the long term it's irrelevant from
the point of view of modularizing the documentation.

Re: [oll-user] Licensing questions

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

Am 05.04.2013 20:00, schrieb Urs Liska:
> Maybe we'll manage to keep this quieter within this still small number
> of readers than on the lilypond-user list
> (see
> http://lists.gnu.org/archive/html/lilypond-user/2013-03/msg01144.html
> and _many_ follow-ups).
>
> We agree that the licencing as is present in the current source files
> needs reconsideration before the first serious file release.
>
One thing I forgot in the above post:

If we should settle upon a more permissive license in some parts we'd 
have to take care that we still comply with GNU's ideas.
Not because I'm a purist or because I'm afraid of David K's comments, 
but because there was a discussion on lilypond-user about GNU programs 
(i.e. LilyPond) not being allowed to endorse or link to non-free 
software and/or documentation. (This was in the context of discussing my 
tutorial containing copyrighted music).

Urs

Re: [oll-user] Call for initial feedback

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

Am 28.03.2013 18:50, schrieb Joseph Rushton Wakeling:
> On 03/28/2013 05:59 PM, Urs Liska wrote:
> ...
>> Not really problems, its rather the complexity of the amount of repos.
>> An example: If I work on, say, the manual for 'musicexamples' I may run
>> into updating the stylesheet package. If everything is in one repository
>> I will surely notice the need for committing this change, at least if I
>> want to power down the computer and see that git status isn't clean.
> Wouldn't that kind of issue suggest that your repos are improperly modularized?
>
> For example, if an individual tutorial needs a stylesheet change, it might make
> sense to allow tutorials to have custom local stylesheets that are used
> alongside the global one.  And if, reviewing the merge of a tutorial patch,
> there is a stylesheet change, it could be consciously decided to make that
> change to the global stylesheet instead.
This is a very good idea. It is completely practical to have an 
individual style sheet for use in an individual tutorial.
Or a tutorial author could write his additions directly in the preamble 
of his 'subfile'.
>
> Put it another way -- if you have to make changes to the global stylesheet
> often, then your global stylesheet needs rethinking anyway.  Preventing you from
> habitually making stylesheet changes along with tutorial changes is probably a
> good way to enforce good discipline of design.
I see your point, but that's not really the case here.
I have to change the style sheets often because they are developed along 
the way. So I'll add an environment for a specific kind of table when I 
first need it. So the number of this kind of updates will fastly 
decrease. And it can be made simpler with your previous suggestion.

Urs

[oll-user] OLLib<->LilyPond | Contribution/review

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

Hi,

probably the last of my 'initial' emails.

Another one of Joe's questions/suggestions:
>   -- I would like to see a better clarification of the relationship between
>       OLLib and Lilypond proper.  In particular where usability/technical
>       tools are provided, why aren't they being pushed directly into LP proper?
>       Will they be in future?  How is the development relationship seen for the
>       future, e.g. will OLLib be for LP something like what Boost is for C++, a
>       testing and review ground where concepts and tools can be refined before
>       being standardized?
Good point. But I don't think we should over-emphasize OLLib's potential 
as a 'staging area' for LilyPond.
I'd rather say that we should have a rather strict policy of including 
only material in OLLib that has got a certain degree of approval. This 
means that we should discuss the point of including any functionality at 
all, and  have a somewhat strict review process before pushing 
contributions to the master branch.
So first we should consider whether a proposed addition makes sense as 
an enhancement of OLLib and already get an idea if we consider it 
appropriate to propagate it for inclusion into LilyPond.
Then we should review patches and discuss them with regards also to 
syntactical consistence with LilyPond's conventions.

AFAIK GitHub supports pull requests from within a repository, and I have 
read about organizations that created their review process around that.

> 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, and you may have noticed that I started my research 
on this topic.
But (for the sake of having an example) I'd nevertheless keep the SUp 
versions as shorthands in a library, because they would then be 
shorthands for \staffUp \voiceOne etc. (which I wouldn't consider as 
really natural for being included in LilyPond proper).

Best
Urs

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

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

Am 05.04.2013 17:33, schrieb Urs Liska:
> As Joe pointed out my conception of openLilyLib's documentation could
> make our lives unnecessarily complicated.
I should have included the following:
> Urs:
> > 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?
> Joe:
> 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
>

[oll-user] Licensing questions

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

Maybe we'll manage to keep this quieter within this still small number 
of readers than on the lilypond-user list
(see 
http://lists.gnu.org/archive/html/lilypond-user/2013-03/msg01144.html 
and _many_ follow-ups).

We agree that the licencing as is present in the current source files 
needs reconsideration before the first serious file release.

While our situation is similar to that of LilyPond proper we still are 
independent and can (and have to) find our own solution.

Generally we seem to agree on our intentions it seems difficult to 
understand how the license models apply to our files. For final 
decisions we will have to wait for the outcome of the general 
discussion, but I'd like to summarize what I assume to be our 
intentions, to be able to discuss them and have them ready when necessary.

There are a few points where we have to distinguish, and we can't apply 
one solution for all aspects:
- We have to put copyright notices into each source file,
   but also as printed copyright notices in the pdf manuals.
   Do they have to be different, and if yes, in which way?
- We have LilyPond and LaTeX files. Can they be treated identically?
- We have different types of (LilyPond) files with different types of 
content:
   - library files with functions that are typically _used_
   - example and template files that are sometimes used but probably 
more often copied and modified

Now to our assumed intentions as I understand them:

- In general we want to provide our material as 'free' as possible.
- But this freedom should also include the right to distribute works 
with restricted licenses.

To be more concrete:

a) OLLib:
- Someone includes ollib and uses its functions, engravers or other 
material in his .ly documents:
   -> He can do what he wants with them,
      i.e. distribute the output files with or without sources and under 
any license
      He does _not_ have to distribute OLLib together with the sources
      (except he wants the recipient to be able to compile the files ...)
- Someone (uses OLLib and) copies and modifies items from it:
   -> He may distribute the resulting PDF files without sources under 
any license
   -> If he wants to share the sources,
      he has to do so under the same (?) license that we found (i.e. 
with the same level of enforced freedom ;-) )
      But: Does this then apply to the complete file or only to the used 
material?
   -> He has to correctly attribute the used material
This applies to OLLib core functions as well as the examples and template.

I think the best outcome would be if we just _can_ use the GPL for this.

b) LaTeX packages
- We should check whether the LPPL (Latex Public Project License) is a 
useable choice for us too.
- Specific question: Does it matter that we have LilyPond sources and 
Python scripts as part of the packages?

c) Tutorials and Documentation
- We want that people can use, modify and redistribute any materials.
- For this the appropriate license seems to by the CC-BY-SA license.
- Question: Can one just release the complete pdf under that license? Or 
does one have to distinguish between, say, texts, source code examples, 
music (which may be under copyright or a non-compatible license)?

I think we should have a "if not stated otherwise" disclaimer in any case.


A final question:
How should the main copyright clause be set?
Currently I have "Copyright 2013 by Urs Liska and others", but I'm not 
sure if that's the right way.
In a clause we should also say something like: Copyright the attributed 
authors of each content item - but of course we'd need some fallback clause.

Best
Urs

[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

Re: [oll-user] Repository organization

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

On 04/05/2013 05:01 PM, Urs Liska wrote:
> Basically I fully agree with that POV, as the sub-projects really are quite independent conceptually, and I agree that the interdependence of the current design is based on my perception of the 'whole' which is far from being carved in stone.

The other key reason to separate is about maintenance and commit right
bottlenecks.  By having everything in one big repo, you wind up either having to
give lots of people commit rights (not very safe), or you have to channel all
contributions through a few people.

By splitting things into separately-versioned projects, you can have different
people maintaining different parts, so a small number of committers on a
per-project basis but a large number of people involved overall.

> However, I'm still somewhat insecure about how the submodule approach is actually manageable.
>  From trying to understand the docs and reading blog posts I have two questions:
> 
> 1)
> A submodule isn't just a Git repository living in a subdirectory. Instead, a submodule points to another remote repository, so this seems to mean that we have (e.g.) lilyglyphs as a subdirectory/submodule within openlilylib _and_ as  standalone repository.
> I understand this set-up for the usual examples of a third-party library, but I don't really see how this is natural for our case.
> 
> 2)
> I have read that it is comparably 'simple' to get the repo/submodule constellation out of sync and even corrupted (if one part points to a commit that the other part hasn't pushed etc.).
> How complicated does a working policy have to prevent this? And how complicated is it to recover from such situations?
> Instead of an explanation I would also accept statements like "I know this works smoothly, and you'll see it when it is running".

Can't speak to (2) as I have never encountered it.  But if you are concerned,
the simplest way is just to give up the idea of one-repo-to-rule-them-all and
have a few different repositories to cover different parts of the project.

It's zero added complexity for users of the project, as one can always bundle
everything together in one big .tar.gz file for user download; it adds some
complexity for developers/contributors but also reduces complexity in other ways.

So, I would start by modularizing the project appropriately into different repos
without worrying about submodules, and think about introducing them later if
that seems to be necessary.

[oll-user] Repository organization

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

Hi,

this is the first email separating issues from a recent thread
(http://sourceforge.net/mailarchive/forum.php?thread_name=5147033D.9030301%40openlilylib.org&forum_name=openlilylib-user)
into separate topics.
I'd be glad if we could keep them separate as much as possible ;-)

Joe is highly in favor of separating our stuff into separate Git submodules.
The most important statements are possibly the following (you can find 
more in the thread):

> but I don't see the point in having
> one-repo-to-rule-them-all_unless_  done via submodules -- the separation into 3
> different projects is quite correct IMO, as each part is clearly independently
> useful (or at least, such dependencies as exist are one-way only).

> I think you need to think of it like this: users who only want to_use_  one or
> more of the parts may operate off archived releases, but what about users who
> only want to_work_  on one of the parts?  It's really not clear to me why
> someone who wants to work solely on lilyglyphs (say) should have to pull in
> OLLib or the manuals.
Basically I fully agree with that POV, as the sub-projects really are quite independent conceptually, and I agree that the interdependence of the current design is based on my perception of the 'whole' which is far from being carved in stone.

However, I'm still somewhat insecure about how the submodule approach is actually manageable.
 From trying to understand the docs and reading blog posts I have two questions:

1)
A submodule isn't just a Git repository living in a subdirectory. Instead, a submodule points to another remote repository, so this seems to mean that we have (e.g.) lilyglyphs as a subdirectory/submodule within openlilylib _and_ as  standalone repository.
I understand this set-up for the usual examples of a third-party library, but I don't really see how this is natural for our case.

2)
I have read that it is comparably 'simple' to get the repo/submodule constellation out of sync and even corrupted (if one part points to a commit that the other part hasn't pushed etc.).
How complicated does a working policy have to prevent this? And how complicated is it to recover from such situations?
Instead of an explanation I would also accept statements like "I know this works smoothly, and you'll see it when it is running".

If that's actually manageable, I'd happily accept to split the main repository in as many submodules as seem appropriate. But I'd be glad if someone could guide me through the process of doing so without me having to learn everything from scratch.

Best
Urs

Re: [oll-user] Next iteration on the way to paradise ...

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

Am 30.03.2013 07:42, schrieb Jan-Peter Voigt:
> Hi Urs,
>
> thank you for taking this so far!
> And sorry for bringing up sourceforge
If it wouldn't be for this email I wouldn't have recalled it was you ...
> ... I didn't know ... ;)
Now you know.
But of course you couldn't. "From the specs" it looked perfect.
> If you want to recreate the google list some time, it wouldn't hurt -
> just send a message.
OK. But I think it's quite good as it is right now.

Best
Urs
>
> Best
> Jan-Peter
>
>

Re: [oll-user] Call for initial feedback

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

On 03/28/2013 06:16 PM, Urs Liska wrote:
>> 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 ...

... whoops .... :-\

Anyway, I'll draft that email to SFLC in the next days.

Re: [oll-user] Next iteration on the way to paradise ...

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

On Sat, 30 Mar 2013 17:48:09 +0100
Janek Warchoł <lem...@gm...> wrote:

> Hi,
> 
> 2013/3/29 Urs Liska <ul...@op...>
> 
> > > as for file downloads i think zipped
> > > branches would be enough.
> > No.
> > They may be used by a developer who isn't yet evangelized by Git ;-)
> > But they aren't ready for end-users because they aren't organized,
> > presumably contain unnecessary files and _don't_ contain any binary files,
> > particularly the manuals.
> > So I think we have to make regular download packages available through the
> > web site. This means that there will be binary files in the web site
> > repository, but only those that are ready for release (they will be added
> > right before release) - this doesn't mean we have to track binary files 'in
> > development'.
> >
> 
> ok, you're right.

... but it's a comparably small issue.
As soon as my family gives me the opportunity I'll rip off several new threads from the recent discussion. Joe in particular has raised a few quite important questions ...

Best - and happy holidays
Urs

> 
> cheers,
> Janek

Re: [oll-user] Next iteration on the way to paradise ...

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

Hi,

2013/3/29 Urs Liska <ul...@op...>

> > as for file downloads i think zipped
> > branches would be enough.
> No.
> They may be used by a developer who isn't yet evangelized by Git ;-)
> But they aren't ready for end-users because they aren't organized,
> presumably contain unnecessary files and _don't_ contain any binary files,
> particularly the manuals.
> So I think we have to make regular download packages available through the
> web site. This means that there will be binary files in the web site
> repository, but only those that are ready for release (they will be added
> right before release) - this doesn't mean we have to track binary files 'in
> development'.
>

ok, you're right.

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

Re: [oll-user] Next iteration on the way to paradise ...

[Jan-Peter V. <jp....@gm...>]

Hi Urs,

thank you for taking this so far! And sorry for bringing up sourceforge 
... I didn't know ... ;)
If you want to recreate the google list some time, it wouldn't hurt - 
just send a message.

Best
Jan-Peter


Am 29.03.2013 23:20, schrieb Urs Liska:
> Hi Jan,
>
> thanks for the feedback.
>
> On Fri, 29 Mar 2013 18:29:04 +0100
> Janek Warchoł <lem...@gm...> wrote:
>
>> Hi,
>>
>> I'm not sure about the mailing list;
> Currently I tend to keep the mailing list and the project front page on SourceForge. The plain old mailman list seems appropriate. And having that project page as one landing page shouldn't be bad either.
>
>> as for file downloads i think zipped
>> branches would be enough.
> No.
> They may be used by a developer who isn't yet evangelized by Git ;-)
> But they aren't ready for end-users because they aren't organized, presumably contain unnecessary files and _don't_ contain any binary files, particularly the manuals.
> So I think we have to make regular download packages available through the web site. This means that there will be binary files in the web site repository, but only those that are ready for release (they will be added right before release) - this doesn't mean we have to track binary files 'in development'.
>
>> I agree with your other conclusions.
> Thanks. But I'll reconsider the website issue.
> GitHub's Jekyll is very blog-centric (as mentioned), and 'talking it into' creating hierarchical websites would probably include writing (simple) plugins - that can't be used, as Jekyll is run on the server (which seemed like an advantage initially).
> As I have come to like the idea of 'static site generators' (that I hadn't known before) I will consider using one of them that works locally, isn't blog-centric and written in Python.
>
> Best
> Urs
>
> ------------------------------------------------------------------------------
> Own the Future-Intel(R) 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://altfarm.mediaplex.com/ad/ck/12124-176961-30367-2
> _______________________________________________
> openlilylib-user mailing list
> ope...@li...
> https://lists.sourceforge.net/lists/listinfo/openlilylib-user