Questions about GridLY readme/use

[uliska]

Some questions I get from reading the README in the GridLY library. @Cecca please decide for yourself if you simply want to answer the questions or if you take them as feedback to improve the README.

Am I right that the grid defined with gridly initially doesn't have anything to do with the score structure LilyPond has? I mean, the grid is "simply" a data store from which one can/has to retrieve the parts that are put into the score?
If that's true it should be possible to use a GridLY grid in parallel to other music, right? (I'm asking this because I'd like to try to use GridLY to complete "Das trunkne Lied" where all the vocal parts have to be done yet, and GridLY seems nicely to support the lyrics, which would be something to tackle first within our existing approach.)

I'm not 100% clear about \gridSetStructure. From the comments in the example file this command rather sets defaults than defining the structure of a segment. The only thing matching the name would be the music argument - but this doesn't actually define the structure but only the length.
I don't see this as a problem, but maybe you should consider renaming the command.

Am I right that you have to pass a single segment to \gridSetStructure and ' \gridPutMusic(and not a range or'all)?If yes (which makes perfect sense) you should make this clear in the README.

I'm not clear when you should use or when you can drop \checkGrid.

\gridTest is cool. But I suggest renaming it because its essence is not testing anything but compiling a segment standalone. Maybe \gridCompileSegment?
Why does it have to be in the same file as the putMusic command, is that true?
You should also make clear that it expects a single integer (and not one of the other seg-sel entities).

I don't see if that's reasonably expectable, but it would be cool to think about a way to let the grid optionally build the \score block automatically, using information from an (extended) \gridInit.

[Cecca]

Thank you for the feedback, Urs. Let me breifly answer here, before updating the README.

1) Is the grid a "datastore"?

Yes you are right, the grid has nothing to do with the score structure. It simply provides some infrastructure to organize musical fragments. Hence it is well possible to use it alongside existing music: if the vocal parts are still to be done, then you can define them in terms of the grid, and the pull them in with the rest of the music using \gridGetMusic and \gridGetLyrics.

2) Alternative name for \gridSetStructure

You are right: \gridSetStructure is not such a great name. I had many doubts in this regard, since its purpose is actually twofold. On the one hand, provides defaults for opening, closing and lyrics, and the music length as well. On the other hand it can be used to provide some "structure" for the entire score, like setting rehearsal marks and tempo changes. I'm not entirely happy with this name, however I can't find anything more appropriate. So I'm open to suggestions.

3) Arguments of gridSetStructure and gridPutMusic

Yes, \gridSetStructure and \gridPutMusic both expect a single segment, since they can deal with only one segment at a time.

4) \checkGrid

The usage of \checkGrid is entirely optional: you can use it anywhere and anytime you like. For instance you could use it in each file describing a single cell to check that the duration of the cell is correct, and you can use it at the same time right before assembling the final score, to check all the cells in one go.

5) \gridTest naming

Again, you are right about naming: \gridTest is not such a great name. But I'd prefer to rename it \gridCompileCell rather than \gridCompileSegment, because a segment spans all the parts.

It is not mandatory to have it in the same file as the \gridPutMusic command, you can put wherever you want. I personally find it more convenient to have it alongside the relevant putMusic command.

6) Automatic score block generation

Automatically generating a score block would be a cool feature, and it would supersede and generalize the template defined in grid-templates.ily. I'm open to discussion on the interface of this feature.

[uliska]

      2) Alternative name for |\gridSetStructure|

You are right: |\gridSetStructure| is not such a great name. I had
many doubts in this regard, since its purpose is actually twofold. On
the one hand, provides defaults for |opening|, |closing| and |lyrics|,
and the music length as well. On the other hand it can be used to
provide some "structure" for the entire score, like setting rehearsal
marks and tempo changes. I'm not entirely happy with this name,
however I can't find anything more appropriate. So I'm open to
suggestions.

Not a ready suggestion, but a general remark: When one can't find an
appropriate name for a function (e.g. because it serves two different
purposes) it may be appropriate to reconsider the function's design.
Maybe there should be two functions?

Let's consider this: What you mean by "structure" (marks etc.) is
actually what can be conceived as a more or less normal part. So it
might make sense to keep that part of the functionality out and suggest
to simply add a "normal" structure part if one wants to use something
like this. An indicator that this might be correct is that
\gridGetStructure is nothing more than a wrapper to retrieve music
from a special part.
(Actually this wouldn't require any change in the code, just in the
documentation)

What would remain is setting the three defaults and the length of the
segment. I think this is not the "structure" but a "template" for the
segment, and it also behaves like this with regard to being overwritten
by concrete cells' contents. And as we actually deal with a segment (and
not with the grid as a whole) I suggest

\gridSetSegmentTemplate

as the most unambiguous name.

      4) |\checkGrid|

The usage of |\checkGrid| is entirely optional: you can use it
anywhere and anytime you like. For instance you could use it in each
file describing a single cell to check that the duration of the cell
is correct, and you can use it at the same time right before
assembling the final score, to check all the cells in one go.

So a use-case could be to have the command in each cell's file and have
better error messages?
But I still don't completely get what it's intended for. Wouldn't any
errors become apparent when trying to retrieve the music anyway?

      5) |\gridTest| naming

Again, you are right about naming: |\gridTest| is not such a great
name. But I'd prefer to rename it |\gridCompileCell| rather than
|\gridCompileSegment|, because a segment spans all the parts.

Of course that's better, so it should be \gridCompileCell.

It is not mandatory to have it in the same file as the |\gridPutMusic|
command, you can put wherever you want. I personally find it more
convenient to have it alongside the relevant putMusic command.

OK, then you should remove that comment from the README because it
suggests an obligation.

      6) Automatic score block generation

Automatically generating a |score| block would be a cool feature, and
it would supersede and generalize the template defined in
|grid-templates.ily|. I'm open to discussion on the interface of this
feature.

Good, but let's come back to this when we're ready with the basics.

---

One additional comment/question: What about also renaming
\gridPutMusic? I see where it comes from, but from the perspective of
the "user" it is somewhat strange and technical in an unproductive way.
While "getting" music from the grid is completely natural, "putting"
music to the grid is less so.
So what does this actually do? It defines the content of a cell, so
Cell should be part of the name.
Maybe \gridDefineCell would be good? This would also go quite
naturally with the \with clause: "define cell with ... and the music ..."

put???

[flaminghakama]

On Thu, Feb 19, 2015 at 2:16 PM, Urs Liska notifications@github.com wrote:

One additional comment/question: What about also renaming
\gridPutMusic? I see where it comes from, but from the perspective of
the "user" it is somewhat strange and technical in an unproductive way.
While "getting" music from the grid is completely natural, "putting"
music to the grid is less so.

If this is intended to follow typical object-oriented syntax, the partner
command to getFoo would be called setFoo.

Since I haven't followed this conversation from the beginning, I am not
sure what the normal user would be doing in either case. Having said that,
if the user is using \gridGetMusic, I can't imagine that either
\gridSetMusic or \gridPutMusic would be super off-putting.

David Elaine Alt
415 . 341 .4954 "Confusion is
highly underrated"
elaine@flaminghakama.com
self-immolation.info
skype: flaming_hakama
Producer ~ Composer ~ Instrumentalist
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

[uliska]

OK, I think the setFoo argument is good. However, there are differences between the get and the set functions, they aren't related the way getter and setter functions in OOP are:

• set affects only a single cell while get can retrieve a range of segments or a full part too.
• get retrieves only the music (or lyrics) property of the cell(s) while set can also set the metadata of the (single) cell.

So I think we should use \gridGetMusic / \gridGetLyrics and \gridSetCellContent to be explicit.

[Cecca]

Ok, I'm working on the refactoring of the public interface. I just renamed gridTest to gridCompileCell and gridSetStructure to gridSetSegmentTemplate. Moreover, I deprecated gridGetStructure.

---

I'm still not very convinced about using gridSetCellContent in place of gridPutMusic. I found that the symmetry in the names (gridPutMusic and gridGetMusic) makes them easier to remember.

As for the difference in parameters and semantics, I think that it's implicit in the goal they have: gridPutMusic can deal with only one segment at a time because when inserting things it's the only thing that makes sense, whereas it is quite natural to think about gridGetMusic and gridGetLyrics as interacting with multiple segments at a time.

Moreover, I like how gridPutMusic sounds when I read it (in italics the words added by my brain):

\gridPutMusic into "soprano" 1 \with { lyrics } actual music

Finally, the main object of gridPutMusic and the grid in general is music, so I like to keep it in the name of the function.

Anyway, @uliska's concerns are all valid, and I want to think more about it.

[uliska]

Am 22.02.2015 um 18:12 schrieb Matteo Ceccarello:

Ok, I'm working on the refactoring of the public interface. I just
renamed |gridTest| to |gridCompileCell| and |gridSetStructure| to
|gridSetSegmentTemplate|. Moreover, I deprecated |gridGetStructure|.

Good.

---

I'm still not very convinced about using |gridSetCellContent| in place
of |gridPutMusic|. I found that the symmetry in the names
(|gridPutMusic| and |gridGetMusic|) makes them easier to remember.

As for the difference in parameters and semantics, I think that it's
implicit in the goal they have: |gridPutMusic| can deal with only one
segment at a time because when inserting things it's the only thing
that makes sense, whereas it is quite natural to think about
|gridGetMusic| and |gridGetLyrics| as interacting with multiple
segments at a time.

Moreover, I like how |gridPutMusic| sounds when I read it (in italics
the words added by my brain):

|\gridPutMusic| /into/ |"soprano" 1 \with { lyrics }| /actual music/

Finally, the main object of |gridPutMusic| and the grid in general
/is/ music, so I like to keep it in the name of the function.

Anyway, @uliska https://github.com/uliska's concerns are all valid,
and I want to think more about it.

Please proceed as you decide what you consider best.
We should try to get to a reasonably stable interface as soon as
possible because I need to base code on it and try to integrate GridLY
in our project.

[Cecca]

Ok, I did some other updates to the cod. In particular commit 7af4652 removed some code, simplifying a lot the library structure, and was enabled by your suggestion of separating template definition from marks and tempo changes. Thanks for that.

I'm pretty happy with the new interface, I updated the documentation to reflect it. If for you it's ok, this evening I'll go over the other issues you pointed out in the README and then merge the branch back into master, thus releasing gridly-0.4.0.

As for bug #63, since it is not a severe issue, I can deal with it in version 0.4.1, so that you can start to use GridLY as soon as possible.

[uliska]

OK, good.
Do you think you'll also reach a state where you can merge gridly back to master?

[Cecca]

Yes, this evening or tomorrow I will merge gridly into master

[Cecca]

If you have no further comments, PR #77 is ready to be merged into master, featuring GridLY 0.4.0

[uliska]

I'll have to look into it with a fresh mind, hopefully later tonight. One thing I'd like to do - but this can well be after the merge - is add a proper interface for library versions. This should be integrated in the global option handling, so that all libraries can (or have to?) define a version number somehow. This can be very useful for managing dependencies. Also we should someday think of a convert-ly like mechanism to update user code when libraries introduce breaking changes (maybe somehow hook into convert-ly itself?)

[Cecca]

Since GridLY 0.4.0 has been included into master I'm closing this issue.