Discuss the alignment of scores to the text area

[uliska]

Now that #31 has been merged lyluatex applies protrusion and correctly determines the correct line width. But this raises further questions, on a typographical, technical, and interface level. Attached is a detailed PDF* demonstrating the issues. The questions to be discussed in order to allow further development are (additions welcome):

• Should protrusion be used always or are there valid reasons to avoid it?
• What is the correct way to deal with the issue (from the typographical perspective)?
• Which interface should be provided for package users?

*(the source code used to produce this can be found as test-alignment.tex)

[uliska]

In absence of discussion I think I'll start with one part:

• Add an option protrusion that defaults to true and which causes the behaviour as currently implemented: its the staff lines that has the specified width.
• When protrusion=false a two-pass compilation is started:
  • 1st pass: compile score and retrieve width of margin stuff
  • 2nd pass: subtract margin stuff from line width and recompile
• A question is: should the default be toggled for scores that are narrower than line width (i.e. shorter "non-justified" examples)?
• Maybe it should have its own issue but I would like to have a line-width option (unit) to pass the line-width in percent (of current LaTeX line width.

[rpspringuel]

Having finally had a chance to look at this, here are my comments:

protrusion should not be a yes/no property, but rather a max amount, and probably two of them (left and right). Elements which extend beyond the ends of the staff lines are allowed to extend into the margin by up to given maximum. If they're larger than that, then the line width should be shrunk so that the score fits within the available space (left protrusion + textwidth + right protrusion). If that takes a two pass system, then so be it. There are plenty of LaTeX packages that require multiple passes.

I would try to support package option, command, and keyword argument abilities for setting the protrusion.

I'm going to have to think about the shorter stuff some more.

[uliska]

protrusion should not be a yes/no property, but rather a max amount, and probably two of them (left and right).

Good point. I've just checked that it is possible to infer also the right "natural" protusion amount from the EPS file. One - minor - issue with this is that the bounding box LilyPond is written as integers (in points), so there are rounding errors of +/- 0.5pt (= +/- 0.18mm). This is not much but still not ideal ...

It will take a two-pass system, but as you say that's OK. However, I suggest to have a way to avoid that check. It may be desirable to always have the staff lines align with the text and do arbitrary protrusion (i.e. the author has to ensure that margin text aren't too long). This may either be through yet another option or some special value. For example:

• max-protrusion=1cm (as you suggest)
• max-protrusion=-1cm (negative values are impossible and could imply unlimited protrusion).
  But I find that unintuitive
• protrusion=true, max-protrusion=1cm with one option overriding the other if both are given.
  protrusion=false would then be equivalent to max-protrusion=0cm, I think.

max-protrusion could have a default behaviour of 50% of the current margins.

---

When the line-width is set to be less than the available line width protrusion should be calculated from that given line width, and not from the available line width because multiple scores are also considered in relation to each other and not only to the text area. However, if the line is ragged because it contains less music protrusion should also only be limited if it reaches the border of the given line-width. I think the following is a good visualization:

Score protruding to 3 "units" left and 2 "units" right

Regular/unlimited protrusion

   ================
   |==============|
---xxxxxxxxxxxxxxxx--
   |==============|

Protrusion limited to 1 "unit" on both sides, shrinks score's line width

   ================
   |==============|
  ---xxxxxxxxxxxxx--
   |==============|

Protrusion limited to 1 "unit" on both sides, but line isn't filled (8 "units"),
protrusion doesn't have any effect.

   ================
    ---xxxxxxxx--
   ================

line-width set to 8 "units", line filled completely.
Unlimited and limited protrusion.
First and fourth score have protrusion that naturally fits into the limits

   ================
      -xxxxxxxx
   ====|======|====
    ---xxxxxxxx--
   ====|======|====
      ---xxxxx--
   ====|======|====
      -xxxxxxxx
   ====|======|====

[jperon]

Just a point about that, when you implement it : make sure the protrusion is taken in account in the temporary file name, either by modifying line-width before calling hash_output_filename, or by adding it to the name. Otherwise, if one changes this option, the score won't get recompiled.

[rpspringuel]

However, I suggest to have a way to avoid that check. It may be desirable to always have the staff lines align with the text and do arbitrary protrusion (i.e. the author has to ensure that margin text aren't too long). This may either be through yet another option or some special value.

The check itself won't be terribly costly in terms of time or computational resources, so I'm don't think there is any real need to avoid it. All that's needed is the ability to avoid the second pass, which the user can do by simply set the max amount to a ridiculously large amount, there is no need for the package to specially handle it.

The other thing that could be done is to work out the procedure so that a single pass of LuaLaTeX only ever invokes a single pass of LilyPond. The information needed to determine the parameters are written to the aux file so that a second pass of LuaLaTeX has access to that information and makes the adjustments to the run of LilyPond. In this case if a second pass is needed, the first pass should raise a warning indicating such (with the wording chosen so that latexmk can see it).

Further, the negative protrusion values could, effectively, be "indentation" of the score. We probably don't want to do things that way, but I thought I should point out what the likely behavior is if we don't check explicitly for negative values.

When the line-width is set to be less than the available line width protrusion should be calculated from that given line width, and not from the available line width because multiple scores are also considered in relation to each other and not only to the text area.

That's a given. Sorry if my previous comments said otherwise.

[uliska]

Also consider lilypond-book options. https://github.com/jperon/lyluatex/issues/72

[uliska]

@jperon I don't quite understand how protrusion is supposed to work as you have implemented it:

1. as @rpspringuel pointed out "protrusion" should not be an absolute value but a “max” protrusion amount
2. currently it doesn't work properly at all:
   • when no protrusion is set the scores is aligned to the image border and the right edge sticks out into the margin
   • when a protrusion value is defined it is applied in the wrong direction.

I'd actually rewrite the functionality from scratch, using max-protrusion as the option name, but I'd wanted to first ask about your original intentions.

[jperon]

I didn't think about protrusion as something definitive anyway, but only "touched" it to enhance the behaviour of fragments: feel free to change it as you like, as I think you have a better insight on it than I do.

[uliska]

OK, I'll see where I'll get to. I think this is the last major issue before we can do a release. So apart from that area we'll have to complete the manual and then go through it quite thoroughly to see if all the descriptions are correct in the first place and if they are still up-to-date with the current behaviour.

I suggest we first complete the manual and then ask a few people to test the package together with the manual.

[uliska]

OK, I've once more skimmed through the document that is attached to this issue's initial description and also through the discussion. Here's what I think I'll implement:

• No boolean option protrusion and no fixed setting for protrusion as protrusion is a dynamic “activity”:
  • If someone wants a fixed protrusion that should be achievable with a negative indent
  • noprotrusion can be achieved by setting the allowed protrusion to zero
• max-protrusion (and max-right-protrusion), which default to the actual margins (I think there's no LaTeX dimension availalbe, so we'll have to create a function (reusing existing code) to determine the current margins)
  • I think the default behaviour should be to align the beginning of the stafflines with the margins, this is also what LilyPond itself does. And the behaviour we can't influence with fullpage scores.
  • max-protrusion is only a guard against scores that protrude too much (note that Lilypond itself does not provide such a guard, and the user can easily let, say, the instrument names run into the left margin where it will be cut off.
• For centered scores I will (try to) implement it so that it's still the staff symbol that is centered, with protrusion making the actual file sit somewhat out of the page center.

I think all this is not complicated and can easily be implemented. The only thing I'm not fully clear about is the process of re-compiling if max-protrusion is exceeded by a score. I'll have to think about it when I'm at that point. I'm not sure what is more complicated: implementing an instant LilyPond-re-run or an auxiliary file approach that will hook into the next LaTeX run.