scheme modules in snippets

[jpvoigt]

I closed the issue to move the edition-engraver ... it is moved now.

But I placed some essential functions inside the lalily folder in scheme modules. This way I can create module-local singletons and IMO it allows cleaner example code.
And the code is a little bit better prepared for inclusion in standard lilypond ...

Is this acceptable?
And how can we add the standard oll snippet headers?

[uliska]

What does this use of scheme modules mean/imply/require?
Sorry, I don't understand that, so i have to ask: Does this in any way affect the use of your material?

Or are you asking whether it is acceptable to add these modules too into our repo? Then I'd say of course that's OK.

And the standard headers should be easily transferable to Scheme comments, isn't it?

[jpvoigt]

Am 20.03.2014 15:00, schrieb Urs Liska:

What does this use of scheme modules mean/imply/require?
Sorry, I don't understand that, so i have to ask: Does this in any way
affect the use of your material?
It just implies, that the folder structure stays intact/is not changed.
I use some functions in more than one place and I want to shorten the
actual module code. And I store a lot of things in singletons, which
are "safer" stored as "private" variable inside a scheme-module, which
is loaded only once.

So the "edition-engraver.ily" is dependant on "lalily-modules.ly",
"utilities.scm" and "edition-engraver.scm" in the upper folder.

Or are you asking whether it is acceptable to add these modules too into
our repo? Then I'd say of course that's OK.
:)

And the standard headers should be easily transferable to Scheme
comments, isn't it?
of course, but they will not appear in a lilypond score- or book-header.
This might impact the way, how to parse those headers for an openlilylib
web-interface.

If you say that dependency is not acceptable, I will revert it. But I
wish to stress, that it leads to long ly-files with a lot of redundant
scheme-code ;)

[uliska]

OK, I have looked (somehow) at that folder, and I have one problem with that approach (but I think we'll find a solution that is working for everybody).

the snippets repository is intended to be used this way: the root directory should be added to LilyPond's include path and then snippets should be included with their relative path. This will make it quite explicit in the main .ly file:

% included from openLilyLib-snippets
\include "specific-solutions/ismn/definitions.ily"

However, in your case it would be:
\include "templates/lalily/edition-engraver/edition-engraver.ily"

Actually it would be very good if you could break that dependency, presumably by adopting this root-directory approach. when I replace your relative include with "templates/lalily/lalily-modules.ly" it works becaus the root is in my include path.

I don't know how that (use-modules) thing is working so I can't judge further implications, but actually I think edition-engraver.ily should be renamed to definitions.ily and be moved to some TLD/edition-engraver/definitions.ily, although I'm not sure which top level directory would be appropriate. It has something of many aspects: editorial-tools, general-tools, input-shorthands (yes, even that), specific-solutions.

the lalily folder may well stay where it is, although I'd even say it is some kind of "library", and maybe we should create a library folder, where lalily and other included stuff can be placed.

But I'd need some feedback from others...

[jpvoigt]

On 20.03.2014 15:44, Urs Liska wrote:

However, in your case it would be:
|\include "templates/lalily/edition-engraver/edition-engraver.ily"|

Actually it would be very good if you could break that dependency,
presumably by adopting this root-directory approach. when I replace
your relative include with |"templates/lalily/lalily-modules.ly"| it
works becaus the root is in my include path.

OK, perhaps I will include some "relativeInclude" function I use in
lalily - there are two ways to do it:

1. set (temporarily) the relative option for lilypond - I will do that
   temporarily now, to fix it
2. extract path of file and calc resulting absolute path to include - I
   actually do that to add the lalily path to the scheme %load-path
   I don't know how that |(use-modules)| thing is working so I can't
   judge further implications, but actually /I/ think
   |edition-engraver.ily| should be renamed to |definitions.ily| and be
   moved to some |TLD/edition-engraver/definitions.ily|, although I'm not
   sure which top level directory would be appropriate. It has something
   of many aspects: editorial-tools, general-tools, input-shorthands
   (yes, even that), specific-solutions.
   The use-modules part shouldn't be any problem as long as the
   lalily-modules.ily can be found. Of course I can rename it.
   I was asking myself exactly that question, where to store it, when I
   placed it in general-tools ...
   the lalily folder may well stay where it is, although I'd even say it
   is some kind of "library", and maybe we should create a library
   folder, where lalily and other included stuff can be placed.
   I would propose a library folder and place lalily there.

[uliska]

there are two ways to do it:

1. set (temporarily) the relative option for lilypond - I will do that
   temporarily now, to fix it
2. extract path of file and calc resulting absolute path to include - I
   actually do that to add the lalily path to the scheme %load-path

Are you not content with requiring the user to have the root directory in the include path anyway? I really favor having this snippets repo used this way. That is, different from LSR where you take stuff out and insert it wherever you like.

I would propose a library folder and place lalily there.

If you don't mind create a folder libraries/lalily. I think at the moment we have to experiment a little bit with it until we have found the ideal and future-proof solution.

[jpvoigt]

On 20.03.2014 17:43, Urs Liska wrote:

Are you not content with requiring the user to have the root directory
in the include path anyway? /I/ really favor having this snippets repo
used this way. That is, different from LSR where you take stuff out
and insert it wherever you like.
I have a lalily point of view ... you can include lalily.ly from any
path. All related paths are unfolded, even if you have to include it
from a totally other path: \include "../some-stuff/lalily/lalily.ly" or
the like. But that is not necessary here. I created a new branch
"lalily-module", where I rearranged all this.

I would propose a library folder and place lalily there.

If you don't mind create a folder |libraries/lalily|. I think at the
moment we have to experiment a little bit with it until we have found
the ideal and future-proof solution.

I created it in the former mentioned branch.

[uliska]

I still don't see through all this, but I think this is appropriate now.
Maybe Janek should have a say here too.

[jan-warchol]

2014-03-20 17:43 GMT+01:00 Urs Liska notifications@github.com:

If you don't mind create a folder libraries/lalily.

Um, isn't the snippets repo a library itself? I mean, does it make sense to
have a folder named library inside?

Unfortunately i don't really have any definite opinion on how this should
be handled :(

[jan-warchol]

Anyway, don't worry about it too much. What's important is to have a
working solution that is comfortable for the people writing code, i.e.
Jan-Peter in this case-

[uliska]

Am 21.03.2014 00:02, schrieb Janek Warchoł:

2014-03-20 17:43 GMT+01:00 Urs Liska notifications@github.com:

If you don't mind create a folder libraries/lalily.

Um, isn't the snippets repo a library itself? I mean, does it make sense to
have a folder named library inside?

Unfortunately i don't really have any definite opinion on how this should
be handled :(

I had thought about this too and came to the conclusion that it is OK
to do it that way. Jan-Peter's description in the readme file is quite
appropriate "contain code that other snippets depend on".

[jan-warchol]

ok. As i said, do whatever is most convenient for the developer(s).

[jpvoigt]

good morning,

Am 21.03.2014 00:02, schrieb Janek Warchoł:

Um, isn't the snippets repo a library itself? I mean, does it make sense to
have a folder named library inside?

hm, you're absolutely right ... perhaps we should call it "frameworks"?
No, its the same misleading wording.
The thing is, how much dependancy between different oll-code is acceptable?
It is not the LSR, where on can fetch a single snippet and place it
where he likes. It is meant to be included with an include path to oll
and then the oll-path to the definitions.ily.
(I have to recall it once ;) )

One initial idea was to collect snippets in OLL-snippets, which does not
fit in LSR, because they are (for example) mostly scheme code. What
about a section to include scheme-modules? In the "lalily-module"-branch
almost all code for the edition-engraver went to the lalily folder in
libraries (edition-engraver.scm) ... I think, this is not the initial
intention. What about a module-inclusion file in oll-root, that allows
scheme-modules in any subfolder?
Now (in branch lalily-module) the edition-engraver is defined in
/editorial-tools/edition-engraver/definitions.ily .
If edition-engraver.scm shall be placed beside the ily file, the
%load-path should be appended by the OLL-snippets-root-path and then the
desired code could be used by #(use-modules (editorial-tools
edition-engraver module)) , if the code is placed in file module.scm in
the edition-engraver folder.
Or we have edition-engraver.scm placed in the folder editorial-tools
beside the edition-engraver folder. Then would be #(use-modules
(editorial-tools edition-engraver))
The second version is shorter, but the first one has a definitions.ily
and a module.scm in a named folder.

I propose a folder "scheme" with a file modules.ily to append %load-path
with the oll-snippets-path (if not already done).
In that folder may "common" utilities take place, that are needed by
other snippets or modules.

One word on modules: A scheme-module is initialized once if (use-modules
(scheme-module)) is called. Any subsequent call just makes all exported
functions visible/available/useable, but doesn't "reinitialize" the
module. Only exported functions and variables are visible, so you can
define any private variable or procedure you like, without disturbing
the code oudside (of course you can break the code inside, if you
override important globals).
If you define and export functions, which act on variables inside a
"private" closure, you have a global singleton-object, which will not
be overridden by a second call to an include.

One more word ;) I use this with the edition-engraver, to store the
editionMods globally and in lalily, I use it for storing music,
templates, paper- and layout-definitions and so on. This might be a good
way to keep the "house-styles" in place.

[jan-warchol]

I'm sorry, i really don't have an opinion on this :(
I trust your judgement.

[uliska]

Somehow it's like David K's patches which aren't properly reviewed because everybody feels overwhelmed...

Trying to "make" something like an opinion:

You are right that this repository has changed its intention from a stashing area for non-LSR-compatible snippets to that of a general-purpose library. Actually this is much more what we originally had in mind with "openLilyLib". [Maybe we should consider changing name, also to avoid confusion with the official LSR?]

In general the idea of using Scheme modules (as you describe them) seems to make sense to me, although I don't have a clue about it yet. If inclusion in our repo could lead to a better understanding of this aspect it would be a good thing too.

What would your "module-inclusion file in oll-root" actually do or provide? Would this be a requirement to be able to load modules that are located anywhere in the repo? Could you please give a usage example?

Regarding the location of an .ily and a .scm file for the edition engraver (and future modules as well) I'd prefer having them in one folder, accepting the need for a longer include statement.

I'm not completely sure what your suggested "scheme" folder and its modules.ily would actually contain. You think of a storage location for modules (and other Scheme code) that any other snippets may depend on?
Then please tell me how that would actually be used in .ly files. Or would these files only be called from snippets like the edition-engraver?
Somehow I think the directory name should reflect the fact that it's a library and not a general-purpose folder with snippets in it. Maybe scheme-lib?

But in general I can only second Janek's comment: In the end we will follow your judgment.

[jpvoigt]

I merged the state of the edition-engraver to master.
If you have problems with it, please drop a message.

In branch lalily-module I introduced a few more scheme-modules and ---tadatata--- the template-engine. This is of course a work in progress, but the example should compile!
This will need a lot more explanation, but perhaps you can see the magic, when consisting the edition-engraver inside the used templates. The path of music is synchronized with the path of the edition-engraver. So you will for example use "strings.violin.I" to store music of an orchestral piece and "strings.violin.I.Staff.A" to address the corresponding Staff-edition-engraver.

To provide those functions, I introduced some more scheme-code in folder scheme-lib. There is one file "modules.ily" to append the snippets-root-folder to %load-path, so after including that file, you can use load-from-path and use-modules to load scheme-code from oll-snippets.
Now I am struggling with: where to place meta-data and documentation ...
What do you think?

[jan-warchol]

Hi,

sorry for the delayed answer - i was ill :(

2014-03-25 13:29 GMT+01:00 jpvoigt notifications@github.com:

I merged the state of the edition-engraver to master.

Good.

If you have problems with it, please drop a message.

In branch lalily-module I introduced a few more scheme-modules and
---tadatata--- the template-engine. This is of course a work in progress,
but the example should compile!

It does - and looks very nice!

Now I am struggling with: where to place meta-data and documentation ...

What do you think?

Hmm. I suggest to have separate folders for:

• lalily core
• templates, instrument definitions etc.
• usage examples.

Each of these folders would contain a README.md with appropriate
documentation:

• information for developers that would like to understand how lalily works
  and improve it,
• information for people that would like to extend lalily (e.g. add a new
  instrument)
• information for users.

Hope this helps,
Janek