lilypond-user
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: openLilyLib


From: Urs Liska
Subject: Re: openLilyLib
Date: Thu, 17 Nov 2016 00:55:47 +0100
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.4.0

Hi Joram,

Am 17.11.2016 um 00:02 schrieb Noeck:
Dear Urs,

it was not my intention to blame you. I know you put a lot of effort in
it. I just wanted to mention what makes me keeping some distance to oll
at the moment in order to solve some of it. While I am not the right
person to boost this, I would like to take this reminder and look at
openlilylib now again.

First of all, I don't feel offended at all. The questions you raise are exactly the kind of discussion I wanted to trigger with this thread. (And the fact that I didn't reply to your private email doesn't "mean" anything. It's just that I didn't manage to do that yet (and after this public reply I'll probably drop it anyway).


Therefore, I'd like to ask for some direction - publicly because others
might profit from the explanation:


1. What are the repos on github I should look at?
   https://github.com/openlilylib
   I mean which ones are deprecated and what is it you want to develop
   and bring in a good shape? On github all repos are equally listed.

Yes, that's a problem I have with Github's set-up as well. It's not possible to have something like a tree of repositories.
I think I should create a second "organization", for example named "openlilylib-meta" or something like this, so that in "openlilylib" remain only the actual libraries.

   Only openlilylib says 'deprecated' in the description.
   Could there be a prefix in the description telling the newbie which
   of the repos are packages for the oll-core system?

As said, I'd prefer to answer that question by moving these repos to another "organization" because the repo name propagates to the users' harddisk and to the "\include" statement.

The "openlilylib" repository is deprecated because it has been renamed to "snippets" one day. I didn't want to simply break existing code so I decided to make a copy and add a deprecation comment.
As this seems to have taken place more or less a year ago it may be time to do the next step: deleting all the content from the working tree in "openlilylib" and keep the README.md exclusively. After a shorter period the repo should then be dropped completely.

   lily-fonts and oll-latex probably not.
   What do I need to checkout? oll-core, snippets?
   scholarly, edition-engraver are packages?

OK, let's list them:

  • "snippets" aka "openlilylib"

This is a standalone repository that can be used on its own

  • oll-core
  • breaks
  • edition-engraver
  • editorial (stub)
  • ji
  • page-layout
  • partial-compilation
  • scholarly

These are the repositories that belong to the new "oll-core" structure

  • enc2cmd
  • gitbook-plugin-lilypond-highlight
  • lily-fonts
  • oll-latex

These are the repositories that do *not* belong there and should be moved somewhere else.




2. As mentioned already: Why so many places for the same content?

   - snippets and openlilylib (ok there is a deprecation warning on the
     latter, won't count that)
   - edition-engraver snippets/editorial-tools
   - lily-fonts / snippets/fonts / snippets/py and different branches
   - a lot of duplication inside snippets (ok, you said everything there
     is kind of deprecated)

   There should be one place for every part only, all others should
   have deprecation warnings. Rather than copying everything and have
   multiple places while working on the new system, I would recommend
   to have a separate branch, where things are in the new location only
   and a stable branch where things are where they used to be, but never
   twice on either branch.

This is correct and should be a major item on the todo/bug list. Actually there *is* a deprecation mechanism in place, but also only half-heartedly. Actually someone (which of course could also be me) should go through the whole stuff, identify such duplicates and discuss with the authors/maintainers what should be done about them in each case.



3. Specificly for snippets: Which branch should I checkout and how is
   it supposed to be used now? Only the ly folder or together with the
   oll-core repo?

You see I am a bit lost. OpenLilyLib (now snippets) used to be easier to
understand, I just include it and use what is in there. I will try the
advice from your previous mail.

If you want to *use* the "snippets" repository you'll generally want the master branch checked out. For usage see next item:


It's not the intention to replace the snippets with that, though.
What is snippets intended for if all the other packages exist?

The other packages are intended to provide coherent sets of functionality each. For example the "ji" package that I have just started will provide support for displaying and encoding Just Intonation. So if you want to use such a thing you load/include that package.

"snippets" OTOH is still basically just a sort-of organized heap of functions that can be used through \include-ing.


The first step was to create these packages *inside* the "snippets"
repository, within a subdirectory /ly. 
So do I want to use snippets still?

Yes, you want to.
What is bound to be abandoned is the stuff inside /ly.
Most of it has been moved to separate packages by now (and yes, this stuff should clearly be deprecated), but the "gridly", "stylesheets" and "tablature" packages are still in that place.


Other packages (like scholarLY or the edition-engraver) can be either
loaded thorugh oll-core's module handling or \include-d directly (upon
which they'll implicitly load oll-core). You now only need to add one
directory to the include path.
And which path? oll-core?

No, the parent directory where all repos are in.
oll-core will then be loaded through "oll-core/package.ily"

I'll test that. I have to say that I liked the one repo, because now I
have to update several repos.

This is true, and this is one of the reasons why there should be a package manager available doing all the dirty work for you.

Where are these repos to be installed, all in one directory?

Yes.


And as there still isn't
that cool mechanism to generate package documentation from doc comments
in the files I'm kind of reluctant to add more packages.
I was very fond of docstrings etc. some years ago, but I actually like
readme.md files (or similar) much better now than cluttering code with
insane amounts of comments like the doc creation in latex does. User
documentation and making code understandable for developers is something
different IMHO.

This is something that has to be discussed (thoroughly).
What I'm worrying about is that maintaining the documentation separately from the code might make it too easy not to write documentation.

I just heard about a programming language (I think it was D) where unit tests are written immediately above the functions they test, and these unit tests are directly incorporated into the user documentation - as examples for the use of the functions. This led to the situation that they don't have to worry about their contributors writing tests ...



Something totally different in the end: I wish these packages are not
needed for too long, because I would like to see the good parts of it go
into lilypond proper at some point. One of the biggest drawbacks of
LaTeX is IMHO the many inconsistent packages. And when sharing .ly files
I don't like if others are required to install a whole bunch of extra
packages via git which they might not know. For Mutopia scores it is
also a no-go. So I see the packages as a test-bed and temporary stage.

Yes and no.
It has been a motivation from the start to provide an infrastructure where things could be developed to a mature state *before* asking for inclusion in the LilyPond code base.
However, there are use cases where I don't see functionality included in LilyPond, simply because it is to specific. openLilyLib provides a way to conveniently make such code available without bloating the code base.
of course this rules out some uses (like Mutopia) and makes some things (sharing) more complicated, as long as there ins't a LilyPond package manager.


Thanks for your advice! I hope my mail is not too long.
Joram


PS: Some kind of answer to this mail would be an overview-documentation
about oll-core and the corresponding packages. I would be happy to
review such a (even small) documentation. I feel not able to write it :)

Probably this would actually be a good idea.
I feel stuck in the situation that I want to do it immediately right and this being too big a step. So maybe it would really be useful/appropriate to simply write some Wiki pages ...

Best
Urs


_______________________________________________
lilypond-user mailing list
address@hidden
https://lists.gnu.org/mailman/listinfo/lilypond-user


reply via email to

[Prev in Thread] Current Thread [Next in Thread]