TeX macro naming conventions

[rpspringuel]

I figured I'd open in issue for this so that it can be listed in the milestones for 4.0 and so people can comment on it if the feel the need.

1. functions internal to gregoriotex are named \gre@*
2. functions which appear in the gtex output of gregorio, but which should not be accessed by users are named \gre*
3. functions which are meant for user access and use have no prefix

[eschwab]

Also looks good for me.

[eschwab]

Looks like we are missing \setgregoriofont unless that has been changed somewhere else that I'm missing.

[henryso]

I'm pretty sure \setgregoriofont will become \GreSetGregorioFont. It is not part of this set of renames. See #453.

[rpspringuel]

Since that function normally gets written to the gtex file (taking the value of its argument from the gabc header) it's been renamed to \GreSetGregorioFont.

However, perhaps we should deprecate the font choice header in the gabc file? I think this would be more inline with the way we're handling the lyric centering now.

[eroux]

I agree

[rpspringuel]

If we're going to make that change, then I should probably make it before we merge #453. Does anyone else have any opinions on deprecating the gregoriotex-font header?

[henryso]

It makes sense to me. Moving styling concerns to TeX is (I think) a generally good idea.

[eschwab]

I concur with @henryso

[rpspringuel]

I've gotten started with the changes and have committed them to my feature/tex-renaming branch now that the first phase has been merged. Below is a task list showing my progress:

Score inclusion

• [x] \gregorioscore
• [x] \gabcsnippet
• [x] \gresetcompile{force|auto|never}

Overall Size

• [x] \grechangestaffsize
• [x] \grechangestafflinethickness

Fine Tuning Dimensions

• [x] \grecreatedim
• [x] \grechangedim
• [x] \grescaledim{yes|no}
• [x] \greloadspaceconf

Staff Lines

• [x] \gresetlinecolor{gregoriocolor|black|...}
• [x] \gresetlines{visible|invisible}
• [x] \gresetlinesbehindalteration{visible|invisible}
• [x] \gresetlinesbehindpunctumcavum{visible|invisible}

Score Font

• [x] \gresetgregoriofont

Glyph alteration

• [x] \grechangeglyph
• [x] \greresetglyph
• [x] \gredefsymbol
• [x] \gredefsizedsymbol
• [x] \gresimpledefbarredsymbol
• [x] \gredefbarredsymbol

Styling

• [x] \grechangestyle

Text elements

• [x] \greannotation
• [x] \grecommentary
• [x] \grescorereference

Text alignment

• [x] \gresetlyriccentering{vowel|syllable}
• [x] \gresettranslationcentering{left|center}

End of Line Behavior

• [x] \gresetbreakineuouae{allow|prohibit}
• [x] \gresetbreakintranslation{allow|prohibit}
• [x] \greseteolcustos{manual|auto}
• [x] \greseteolshifts{enabled|disabled}
• [x] \gresetlastline{justified|ragged}

Hyphen usage

• [x] \gresethyphen{force|auto}
• [x] \greseteolhyphen{noraml|zero}

Clef visibility

• [x] \gresetclef{visible|invisible}

Oh, and for documentation, I'd appreciate any opinions on the proper order of the sections (or even if my section divisions make sense).

[henryso]

These are just my opinions:

"Dimensional control" sounds like some kind of superpower. I would change that to simply "Dimensions". In fact, I would drop "control" from "Custos control" as well, or perhaps put \gresetcustos under "Line breaks".

I can also see \gresetlastline and \greseteolshifts under "Line breaks", which could be named something like "End of line"

I'm not sure about "Neume font" as there is more than just neumes in there. Maybe "Score font" would be better. Somewhat related, maybe \gresetgregoriofont should probably be \gresetscorefont.

I think "Styling changes" should just be "Styling".

\gresetcompile could go under "Score inclusion".

In terms of section order, it seems somewhat arbitrary, so maybe just alphabetize it.

[rpspringuel]

I've made some changes to the outline above, using some of the advice of @henryso as well as some ideas of my own.

[rpspringuel]

Phase II is up for review.

Phase III, the renaming of the internals, will have to wait for when I get back from the North American Benedictine Juniors Conference (I leave tomorrow and will be back on the 27th of June), unless someone else wants to take it on.

[henryso]

I found some bugs while removing deprecation warnings from the tests.

• \grenormalclef is called by \GreChangeClef and \greinchangeclef. \greinchangeclef appears to be unused, so I suppose it can be removed, but \GreChangeClef is produced by the gregorio executable and thus generates Package GregorioTeX Warning: \grenormalclef is deprecated.
• \gresetdim is called by \gre@changeonedimenfactor#1#2#3, so there are a lot of spurious Package GregorioTeX Warning: \gresetdim is deprecated. warnings in the logs.

[rpspringuel]

The first should be changed to \gresetclef{visible}, assuming the functionality provided by the old command is needed. (I'd need to look at the code in context to determine that and it's late.)

The second should be changed to \gerceatedim. This one I know for sure should be changed because I authored that section of the code and thus know what's going on there without looking.

[henryso]

I will create a pull request for these two bugs and you can review/merge as you see fit.

[rpspringuel]

Thanks for the fixes.

[henryso]

Is there a reason the texverb-called macros in the gabc-notes-determination.l were not renamed to camel-case?

[rpspringuel]

I didn't realize there was anything in that file which needed to be renamed.

[henryso]

I wouldn't have noticed either except that I was looking at @jakubjelinek's work on the dynamically sizable braces, which means that a change now will be a bit of a messy merge with his work.

[rpspringuel]

Perhaps, then, we should hold off on making the changes until he's done?

Also, is it a good idea to keep those macro names in that file or should there be some sort of mechanism for having gregoriotex-write.c write them like it does all the other macros?

[henryso]

Those macros are "shimmed over" to use the texverb system rather than being "first class" gregorio objects. It's not perfect, but it does work, so I'd just as soon leave them there (my opinion and only mine, of course) unless and until there's a reason to promote them into "first class" status (like we did for the manual custos).

[henryso]

@rpspringuel I noticed that the barred letter macro names in UPGRADE.md don't match after the rename. I think UPGRADE.md needs a review before 4.0 RC1 (which I realize is down the road a bit).

Edit: Note: I've updated the barred letter macro section of UPGRADE.md with the new names as part of #543, but I didn't review any other part of that file.

[rpspringuel]

I'll take a look when I get the chance.

[rpspringuel]

I'm nearly done with this and plan to look at the nabc functions next. Not being familiar with this section of the code, I'm not sure which functions should go in which category. Can someone who is familiar with the nabc code (@eroux or @jakubjelinek) look at the following list and let me know how they should align with the naming scheme:

\nabcneumes \scorenabclines \dogregorionabcchar \donabcneumes \gregorionabcchar \gregorionabcfontname \gregorionabcfontsize \gregorionabcstyle \gregoriosetnabcfont \grenabcfontloaded

[rpspringuel]

Another question:

Right now there are several \gre@char@... macros which are simply aliases for a corresponding \GreCP... function. Is there a reason for having this extra layer of aliases or would it be okay to replace the \gre@char@... macros with the corresponding \GreCP... functions?

[henryso]

I would personally prefer to get rid of the extra layer (i.e., I agree with what you suggest), but I didn't want to rile any feathers.

[rpspringuel]

Since no one has provided a reason for the extra layer, I'm going to explore eliminating it.

Oh, @eroux and @jakubjelinek, I'm still looking for some guidance on the nabc functions.

[jakubjelinek]

\nabcneumes \scorenabclines \gregorionabcchar

are macros used in .gtex generated from .gabc. BTW, it seems there is a typo in gregoriotex/, one of the uses is gregorionabccchar (3xc) which is not defined anywhere. gregorionabcchar is also used directly in the documentation.

\gregoriosetnabcfont

is a macro that users can use to change the neume font and/or size.

\gregorionabcstyle

is something users can redefine to other style.

\donabcneumes \dogregorionabcchar \gregorionabcfontname \gregorionabcfontsize \grenabcfontloaded

I think all these are internal (but for all of them one should check the documentation, it uses some internals directly).

And, of course, feel free to rename any or all of them to match the style.

[rpspringuel]

@jakubjelinek, In looking at the nabc functions, I've noticed that \nabcneumes is defined with two arguments, but only makes use of the second. Is there a planned purpose for the first argument (and thus a reason to keep it) or would it be safe to eliminate it?

[rpspringuel]

@jakubjelinek, Along similar lines, I note that the argument for \scorenabclines (which appears to be the number of nabc lines the score is supposed to accept) doesn't get used. Is this something I should keep around?

[rpspringuel]

Hmm... After reading through the nabc documentation, I think I see what those arguments are for: multiple lines of nabc above the staff. While it doesn't look like it's been implemented yet, it does look like you've got plans for allowing multiple lines of nabc above the staff and the currently unused arguments would be for specifying information about those lines. If that's the case, I'll leave them in.

[jakubjelinek]

The plan is primarily to add support for having one line of neumes above the score and one in between the score and text below it (like in Graduale Triplex). So the first argument to nabcneumes is meant to say which of the locations it goes to. It will primarily make sense when (if) support for Laon neumes is added.

[henryso]

I'm not sure if this should be closed now. Should it?

[rpspringuel]

The only thing left to deal with (if desired) are the names of the fonts. These are currently a bit of a hodge-podge: \gregoriofont, \gregoriostylefont, \gre@nabcfont, \gre@fontofbiginitial (PlainTeX only), \gre@fontofinitial (PlainTeX only), and some whose names are less immediately clear because they are defined by Lua based on the value of some string variable. I haven't done anything with these because of just how much of a mess changes here could make (especially for the ones defined or used by Lua). My thoughts are to name them in the pattern \gre@font@... but I'm also willing to leave well enough alone if that's what others would prefer.

[henryso]

Because of how they are used, the lua generated fonts had to be named without the at-symbol (but this can probably be worked around by using catcode_at_letter, which came into existence later). I don't have a strong opinion on this, either way; just saying it's doable if we wanted to do it.

[henryso]

I have a patch ready to name the fonts created in Lua to \gre@font@variant@.... Now is a good time as any to rename the rest of them, if you want to do it. Let me know if and where you want me to push change to gregoriotex.lua.

[rpspringuel]

Can you submit it as a pull request against the texrenamingiii branch on my repository? That should make it easy for me to build on what you've done to rename the rest of the fonts.

[rpspringuel]

Actually, never mind. I just did a fetch operation and I see the branch on your repository. I can merge it into my repository locally.

[henryso]

I suppose this is done.