Integration with musicexamples package

[uliska]

I will now start reviewing the musicexamples package, with three main targets:

• general coding review (I assume there's much to be improved)
• removing obsolete attempts to achieve what lyluatex now does
• ensuring compatibility with lyluatex

We should try to minimize functionality overlap as much as possible in order to make the two package perfect complements. Actually I even considered integrating musicexamples's functionality into lyluatex because that would be the most natural thing to do. However, I think musicexamples should continue to work with any LaTeX engine, so that's not an option.

The general idea should be that lyluatex generates an \includegraphics expression that can be inserted in a musicexamples environment. This will work very easily with fragments, but fullpage scores are a more complex issue (which I'll discuss in a separate issue when the time is there for that (after more review of the other package)).

My idea about the integation is the following: when lyluatex knows that musicexamples is loaded (this would mean musicexamples would have to be loaded first) it changes some parts of its operation and automatically wraps the \includegraphics commands in musicexamples environments. For the user the immediate difference would be that the scores aren't simply placed wherever they fall but are beautifully spaced by environments. And simply passing a caption in the optional argument will do all the magic of numbering, adding to a list of music examples etc.). This will lead to quite some more new options, but by now that shouldn't scare us anymore.

[rpspringuel]

If you make use of the afterpackage package then there is no need to worry about the package loading order.

[jperon]

Now that most developments about lyluatex itself are done, here are my thoughts about this point. I really like the reference to \includegraphics: IMHO, lyluatex should be for musicexamples what \includegraphics is to floating environments. \includegraphics isn't wrapping anything, it is wrappable. So we should ensure the easiest wrappable behavior from lyluatex, letting wrapping to musicexamples (or other packages, as users could have other approaches to this problem).

So I agree that musicexamples shouldn't depend on lyluatex; but on the other side, I don't think lyluatex's behavior should be impacted by musicexamples. Perhaps the idea that simply adding a caption does all the magic has something appealing, but I also think it may be confusing. IMHO, the following approach would be less confusing:

\newenvironment{lyfigure}[2][]{%
  \edef\mycaption{#2}
  \figure
    \center
      \ly[#1]%
}{%
      \endly
    \caption{\mycaption}
  \endcenter
\endfigure
}

Then the user would have to type:

\begin{lyfigure}[LYLUATEX_OPTIONS]{caption}
LY_CODE
\end{lyfigure}

And if the caption must be before the score, this would only be a question of changing the place of \caption.

I don't say this approach is exempt of rough edges: ly is a very special environment, that isn't so easily wrappable as is; but I think this would be the way to go.

[jperon]

N. B.: you have another example with \lily in wrappingcommands.tex; this file could serve to experiment that way.

[rpspringuel]

I'm with @jperon on this one. I think that while having musicexamples and lyluatex work well together is important, the two package should be maintained separately.

Convenience functions which combine the functionality of the two packages strike me something that belong in the user preamble, however, if they are especially complicated I could see writing a separate style file whose specific goal is to combine the two. In this fashion the basic code in both lyluatex and musicexamples remains distinct and relatively clear in its purpose. This new style file could be a part of either the musicexamples or lyluatex package, or even its own package.

[uliska]

I have no time to consider these points, I hope to be able to comment Sunday afternoon/evening. -- Diese Nachricht wurde von meinem Android-Gerät mit K-9 Mail gesendet.

[uliska]

I think it is somewhat inappropriate to discuss my pull request #135 in this issue out of context. Changes in that pull request are completely isolated from the question of musicexamples, and @jperon only comments on half of the story here.

Essentially my PR departs from the idea of hardcoded musicexamples integration. And what it suggests is not “simply adding a caption does all the magic” rather than adding an option environment that makes the following possible:

\usepackage[environment=figure]{lyluatex}

% or

\begin{lilypond}[%
environment=figure,
caption={My Example}]
c'
\end{lilypond}

and if environment is set to something each score will automatically be wrapped in that environment (with env-opts being there to control the optional argument of the environment, for example to control the positioning). Now if only a caption is set (and no environment given as package option) the “magic” is simply to implcitly set environment=figure for that score.

I really don't see how that could be confusing or overly un-LaTeX-y, and it really is a convenience for the user. When writing a document with scores included system-by-system at least half of the use cases include enclosing the scores in environments, and it will help if lyluatex not only takes care of wrapping the lilypond call but also automatically creates the environment around the score.

With that in place I can simply use musicexamples by using its environments here, and I agree that this should be done in “my” document's preamble or my custom style file.

On the other hand I don't agree with the \lyfigure idea. This is basically a hard-coded figure environment around the ly score that doesn't seem to help much: This would at least have to be configurable to allow different environments to be used, different env (not lyluatex) options to be applied and the caption to be placed. I think then the name \lyfigure would become misleading, and it would actually be equally practical to have the user enter their environments manually.

I am convinced that my environment option is a good idea, and it if there is something to be argued against that (within this issue) it is important to forget about the notion of musicexamples.

[jperon]

@uliska I hope you didn't find my comments aggressive: it's quite complicated to explain why I don't agree in short messages, and all I want is to be the most constructive possible. I've no reason to forget about musicexamples, as I really want to make interaction between it and lyluatex the most clever possible.

The lyfigure idea isn't something I'd like to implement within lyluatex: it's an example of what can be done either by the user in the header, or in a .cls. What I think about environment option is that:

• it's an unusual way to proceed (would you expect something like \includegraphics[environ=figure]{image} ?);
• it adds a real degree of complexity in lyluatex.lua, whithout solving a problem that wouldn't be better solved by existing LaTeX tools (especially \newenvironment);
• it's even too restrictive: the user could want to add more than \begin{environment} and \end{environment} before and after the score.

In other words, I think lyluatex should respect the keep it simple, stupid and do one thing and do it well principles to make integration with the rest better.

[uliska]

I replied by email, but I don't see the reply on this page, so I'll repost manually:

Am 18.02.2018 um 12:51 schrieb jperon:

@uliska I hope you didn't find my comments aggressive:

I didn't find them aggressive but I have to admit that I was irritated, especially as you seemed to double down on them through action, namely pushes to master.

it's quite complicated to explain why I don't agree in short messages, and all I want is to be the most constructive possible. I've no reason to forget about musicexamples, as I really want to make interaction between it and lyluatex the most clever possible.

The lyfigure idea isn't something I'd like to implement within lyluatex: it's an example of what can be done either by the user in the header, or in a .cls.

OK, I didn't get it that way since you did add it to lyluatex.sty and even on the master branch.

What I think about environment option is that:

• it's an unusual way to proceed (would you expect something like \includegraphics[environ=figure]{image} ?);

No, but I would gladly accept \usepackage[environment=figure]{graphicx} or something similar. Well, maybe not with graphicx as that is a quite general package, but if I had a package that created, say, a small flow chart in a TiKZ image I would appreciate the possibility to not always have to explicitly write an environment around it.

In the case of lyluatex we have three different ways to enter LilyPond music: a command, an environment, and a file inclusion command. With the environment option it's a unified interface how systems can be wrapped in an environment while with the \lyfgure idea one would have to create individual wrappers for each.

I predict that we'll be back at this point no later than when figuring out how to use lyluatex from Pandoc. I don't see how it is acceptable (or even possible) to enclose a code block in a LaTeX environment like

\begin[figure}
```lilypond
c'
```
\end{figure}

• it adds a real degree of complexity in lyluatex.lua, whithout solving a problem that wouldn't be better solved by existing LaTeX tools (especially \newenvironment);
• it's even too restrictive: the user could want to add more than \begin{environment} and \end{environment before and after the score.

That could be taken care of by a command that is similar to \lysetverbenv. That's what I actually started to do first but then I found the option approach simpler.

In other words, I think lyluatex should respect the keep it simple, stupid and do one thing and do it well principles to make integration with the rest better.

I admit I don't really agree, but I won't push any further with this.

I assume you don't want the horizontal alignment either, because that's also in the domain of what could be handled on the LaTeX side? But I'm not sure I can avoid working with that when handling protrusion.

[jperon]

OK, I didn't get it that way since you did add it to lyluatex.sty and even on the master branch.

As you may check, I didn't. wrappingcommands.tex is, as the folder name indicates it, an example of what can be done.

I don't see how it is acceptable (or even possible) to enclose a code block in a LaTeX environment

It isn't possible. But anyway, Pandoc is another problem, as we'll have to take care of multiple formats for export; so it won't be possible to simply pass options from Pandoc blocks to LaTeX environments.

That could be taken care of by a command that is similar to \lysetverbenv. That's what I actually started to do first but then I found the option approach simpler.

I had thought about something similar, and I think it would indeed be the way to go, if we can't make ordinary LaTeX commands work more smoothly with lyluatex. The reason is that such commands should be invocated before calculating the dimensions of the score, in case they would change some parameters; so they can't be passed as ordinary options.

As of protrusion, I'm really convinced you have a better view on this problem than I do; so if it's necessary to handle some horizontal alignment for that, do what you like. But indeed, if it's possible to avoid making something that's already handled by LaTeX, I'd prefer.

[uliska]

merged into #152