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