Create footnotes from within annotations

[jefferyshivers]

A broader issue at the moment, this may be split into multiple as the needs of the feature become clearer.

---

This might include all or some of this wishlist:

• creating in-score footnotes
  • this may be a heftier challenge; if pursued will be a separate issue
• creating footnotes for annotation messages
  • Could be implemented as:

\musicalIssue \with {
  message = "My message about [one] some different [two] typos in the source."
  footnote-one = "First footnote text"
  footnote-two = "Second footnote text"
  annotation-footnote = "This will be placed at the end of the message"
}

• (optional) automated numbering
• setting the starting number for footnotes (manually / automatically)

[jefferyshivers]

This needs to be formatted in scholarLY's scheme code, so that ...

\criticalRemark \with {
    message = "This is a message\fnOne about the pitch."
    fnOneText = "The text of the first nested footnote."
    annotation-footnote = "This is a footnote for the entire annotation."
} NoteHead

... will be output such as ...

\criticalRemark
    {M. 1}{beat 3}
    {Right Hand}
    {Pitch}
    {This is a message\footnote{The text of the first nested footnote.} about the pitch.}
    {This is a footnote for the entire annotation.}

... and compiled by LaTeX, using the scholarLY package, as:

(1) (Critical Remark), M. 1, beat 3, Right Hand, Pitch, "This is a message^1 about the pitch."^2
---
[1] The text of the first nested footnote.
[2] This is a footnote for the entire annotation.

LaTeX is not supporting footnote superscript (as a command parameter) along with the text as an additional parameter (yet).

[uliska]

I think \fnOne is a good solution. Just to avoid misconceptions: One is an arbitrary string here and doesn't necessarily imply an ordered list (so \fnMissingSource would be fine as well). So you'll have to "peel" the key out from the property name through regular expressions.

One comment to that: Isn't it somewhat inconsistent that fnOneText is in camel case while the other properties are usually written as hyphenated words? I suggest that \fnOne maps to fn-one-text instead, and \fnMissingSource to fn-missing-source-text. What do you think?

LaTeX is not supporting footnote superscript (as a command parameter) along with the text as an additional parameter (yet).

I'm not sure what you mean by this. Would you like to be able to specify explicitly the text that is used as the footnote mark? And "complain" that currently you can only use automatic numbering?

[uliska]

Can you specify a little bit more explicitly how you think the automatic numbering should be handled (and configured)?

I think that (for now) the numbering is handled transparently by LaTeX through the inclusion of \footnote commands. If the user wants, say, to restart the numbering for the appendix with the report he can do so through LaTeX commands. Maybe one could add a convenience command like \restartFootnoteNumbering, but I'm not sure it's worth the effort (and extra documentation).

Things will get more complex when we will add the feature of in-score footnotes. Then LaTeX should get the power to determine automatically how many footnotes are in the score and continue automatically after that. But if we/you decide not to tackle in-score footnotes right away I think we can just leave that question for now. Except you have a reason I missed so far.

[jefferyshivers]

I suggest that \fnOne maps to fn-one-text instead, and \fnMissingSource to fn-missing-source-text. What do you think?

Yes, I agree - so it'll be written that way.

LaTeX is not supporting footnote superscript (as a command parameter) along with the text as an additional parameter (yet).

I'm not sure what you mean by this. Would you like to be able to specify explicitly the text that is used as the footnote mark? And "complain" that currently you can only use automatic numbering?

Footnotes aren't always handled well when used inside arguments. Resolved it with \RequirePackage[stable]{footmisc}.

Can you specify a little bit more explicitly how you think the automatic numbering should be handled (and configured)?

Well, ideally this could mean that, if automatic renumbering at page breaks is turned off, scholarLY would determine the count and prepend something like \setfootnotecount{#} to the latex inp export. Meanwhile, if automatic renumbering for pages is on, it would make sense for LaTeX to start at 1 as it does anyway, so nothing would be prepended. But it's also easy enough for now to just manually control the number (if desired) in the LaTeX document for now.

[uliska]

Can you specify a little bit more explicitly how you think the automatic numbering should be handled (and configured)?

Well, ideally this could mean that, if automatic renumbering at page breaks is turned off, scholarLY would determine the count and prepend something like \setfootnotecount{#} to the latex inp export. Meanwhile, if automatic renumbering for pages is on, it would make sense for LaTeX to start at 1 as it does anyway, so nothing would be prepended. But it's also easy enough for now to just manually control the number (if desired) in the LaTeX document for now.

It seems this is definitely a complex issue, and I'm not sure if we should really tackle it in the current context. Depending on the situation in a given book we can want several different behaviours.

For example I'm not sure it's clear where such an offset should apply. Considering the situation that we have a score which creates footnotes (in the score), then the offset in footnote numbering should affect the place in the book where the score is actually inserted. But if we export something to the start of the .inp file this may end up anywhere else.

I'm not sure if I have written this thought before, but this leads me to think that the control and responsibility over this should not be in the LilyPond side of ScholarLY, but also not on your LaTeX package. Instead it should be in the LaTeX package that controls the placement and numbering of the scores in the .tex file: which presumably should be musicexamples. The (LilyPond) ScholarLY should somehow determine the number of footnotes and write this to an intermediate file, and musicexamples should get commands to look for such intermediate files and update the footnote counter accordingly.

However, as this

• would affect yet another package (with unknown needs for updating/fixing/enhancing)
• isn't really supported by LilyPond yet (counting footnotes, having continuous footnote numbers)

I suggest we create a separate issue for this and move it down the backlog.

But maybe it would be a good idea if you ask on the LilyPond lists why footnotes always restart on each new page and if that shouldn't be changed (because it's pretty inconsistent behaviour). Of course I can ask that question as well, but it seems like a good opportunity to interact with the community.

[jefferyshivers]

For user-specified footnotes (as in, new footnote names, such as "missing source"), would ...

message = "This is a message withFNmissingsource a footnote"
fn-missingsource-text = "The missing source footnote."

... be too inelegant to use? It's not the prettiest design, but there are a couple things about this to note.

I propose uppercasing the FN prefix. It will make the search for new footnotes a much smoother process, since fn could eventually be used in a normal word - with FN, that is not so likely.

This example doesn't use backlash at the placement of the footnote. Detokenizing a backslash, which would need to happen prior to testing for new footnotes, adds a messy layer to the process, which I think should be avoided for the time being. It could be a wish list item for later, after at least satisfactory functionality is proven without a backslash. Agreed, tentatively?

[jefferyshivers]

Actually, the upcoming commit implements custom fn-my-name-text / \fnmyname usability. As it stands, the case must be consistent between the macro and the key name, but hyphens are allowed in the key name. Almost there...

[uliska]

It could be a wish list item for later, after at least satisfactory functionality is proven without a backslash. Agreed, tentatively?

I'm sorry not to have really noticed this comment earlier, as I would have accepted your reasoning. Indeed withFNmissingsource doesn't seem acceptable as a final solution, but we could have lived with it.. But fortunately you have in the meantime found a better solution already.

I think what you suggest in the last comment is acceptable: requiring case matching and ignoring hyphens. But actually I would prefer (if it's reasonably doable) to have a mappint where the footnote mark in the LilyPond annotation starts with \fn and each subsequent capital letter corresponds to a hyphenated (lowercase) word in the footnote text entry: \fnMyName => fn-my-name-text.

Either way, I think we should make the syntax mandatory (i.e. give the user some less freedom of choice). This makes parsing simpler, and I think it even makes the usage more consistent.

[jefferyshivers]

Okay - I think this is easy enough to implement (\fnMyName to fn-my-name-text). The whole procedure for doing this is still annoyingly entirely hardcoded, but ideally soon enough this whole process will be trimmed down a bunch.

[jefferyshivers]

Just to make the connection, 21d694d0afeb496bc574400ad3418942149502d4 is how this is currently being handled. The process is: search arg 1 for instances of fn-, peel the name and string from that, and finally generate a macro with the name and which applies the string as a footnote.

This should be able to happen as many times as there are new footnotes without a limit. However, looping is a complicated issue since temporary macros can't really be used within the loop (because each pass of the loop resets them). Expanding the unique names for every instance in the loop is almost possible, except for the case of the keyval definition, at (define@key{family}{fn-(here)-text}....

Originally, the idea was for the whole process of searching for \fn.. to happen in the message string specifically. This doesn't really relate to the issue of looping, but is just a thought about where/how these not-yet-defined macros should be detected.