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

[henryso]

How do we name functions for user access to minimize conflict with other packages?

[rpspringuel]

Short answer: we don't, just like every other LaTeX package.

Long answer: since the internal and gtex functions are prefixed, we shouldn't have to worry about them. For the user functions, we define them conditionally, raising an error if there is a name clash. If we start getting lots of bug reports about name clashes with a specific function, then we consider renaming that function.

[eroux]

I'm not against not prefixing user commands, but it should be explicit that they are intended for gregorio scores in their names... the reason why, for instance, luatexbase or fontspec doesn't prefix its commands is because it can't be compatible with another system of the same type, but I don't think gregorio should be incompatible with another gregorian chant style.

Besides, LaTeX is heavily criticized for its lack of coherence and is considered a huge mess by many (who prefer ConTeXt), so I'm not sure it's a very good model...

[rpspringuel]

I don't disagree with the sentiment, I was just defaulting to the current standards for LaTeX because I'm familiar with them.

Perhaps the following system would be better:

1. User commands are all lowercase and are prefixed with \gre. E.g. \greincludescore (this is similar to the LaTeX standards for user commands, except with the prefix added)
2. gtex commands use CamelCase for their names with a \GRE or \Gre prefix. E.g. \GreBarSyllable or \GREBarSyllable (this is similar to the LaTeX standards for class and package commands, except with the prefix added)
3. internal GregorioTeX commands are prefixed \gre@ E.g. \gre@warning (this is the LaTeX standard for internal private commands)

In this fashion all of our commands are prefixed to identify them as ours, and the different prefix identifies which of the three groupings the command falls under.

This would require some changes to gregoriotex-write.c, but alternatively we could switch the convention for 1 and 2 to avoid that (yielding \GreIncludeScore or \GREIncludeScore and \grebarsyllable, which is what that last macro is currently called).

[eroux]

Another proposal:

• \grexxx (I admit I like \gregorioxxx better but I don't have a very strong opinion) for user commands
• \gre@ for gtex commands
• \gre@@ or \@gre@ for internal commands?

[rpspringuel]

gtex commands cannot have an @ in them because they are part of the document, not the package. Within LaTeX @ is only supposed to appear in class and package files.

Or, more specifically, if we are going to have @ in them then we need to wrap their inclusion in \makeatletter and \makeatother

[eroux]

Indeed, but I don't think it's a big problem, this can even be made in includescore and and gregorioscore, so that it doesn't appear in the .gtex file directly. What do you think? If you really don't like it, maybe it could be gregorio for user commands, gre for gtex commands and gre@ for internal commands? (if you want to do things as usually done in LaTeX, it might be better to avoid camel case, which is quite uncommon I believe)

[henryso]

Just out of curiosity, how does ConTeXt prevent/encourage packages from stepping on each other?

[eroux]

ConTeXt is a totally different model, it's really monolithic, you can only access a high level api, and you compile with special tools; if you want some low-level feature, you have to ask the developers... So it doesn't have many packages (if any), but things just work, you don't have dozens of slightly different packages for tables, etc.

[rpspringuel]

(if you want to do things as usually done in LaTeX, it might be better to avoid camel case, which is quite uncommon I believe)

I just looked it up in Guide to LaTeX by Kopka and Daly and camel case is in the standards for "class and package commands" (p. 428, if you have the book). It mentions that these are "intended for programmers" and "most are preamble-only". I would say that our gtex commands definitely meet the first criteria, and would be a reasonable exception to the second (where the use of "most" implies that exceptions are allowed).

It should be noted, that these standards are referring explicitly to commands native to LaTeX. There is no suggestion that package writers should follow this convention (though I think it's probably a good idea). I missed that little detail in my previous read through.

Of course, the only LaTeX standard we really have to worry about is the one on @ because that has some actual restrictions placed on it (though, as I indicated above, they can be circumvented).

[eroux]

I'm not strong-minded about that, so I let you choose...

[rpspringuel]

Okay, then here's a final check on the proposal:

1. User commands: \gregroioxxx
2. gtex commands: \GreXxxXxx
3. GregorioTeX internals: \gre@xxx

If there are no objections, I'll get started on implementing this later today or tomorrow.

[eroux]

ok

[henryso]

Something about the gregorio prefix for user commands rubs me the wrong way... I think it's too long... how about gtex?

[rpspringuel]

I'd prefer gre to gtex just to be consistent.

[eschwab]

I am in favor of gre over gregorio or gtex. Also users should already be familiar with the gre prefix for user commands. (greblockcustos, gresetfirstannotation etc.)

[rpspringuel]

Okay, absent other comments I'm proceeding with:

1. User commands: \grexxx
2. gtex commands: \GreXxxXxx
3. GregorioTeX internals: \gre@xxx

Having looked at some of the conflicts between the current development branch and my original texrenaming branch, I'm going to create a new branch and cherry pick changes in rather than trying to resolve the conflicts. I think in the long run this will be easier. Especially as I plan on doing this in such a way that I'll pick-up the renamings one function at a time. This should enable me to keep the whole thing working and test along the way.

[henryso]

So \includescore becomes \greincludescore? This one, more than anything else, will cause people to need to update all their code. I guess it's better to bite the bullet now.

[rpspringuel]

It would. With all the user commands, I'll be sure to define the old name alias as well and have GregorioTeX emit a warning about the name change. This should ease the transition as projects won't break right away.

And actually, for \includescore at least, this would be reverting back to an older name, IIRC.

[eroux]

as includescore is the real main command of Gregorio, I think it can have a special treatment... I was thinking about \includegregorioscore or something like that... what do you think?

[henryso]

My personal opinion is that the main commands should be named something more-or-less English but employing distinguishing words to make collision unlikely. My examples in this case are \includegregorioscore (though I'd prefer something shorter, like \gregorioscore) and \gabcsnippet. Because these commands refer specifically to Gregorio, they are not likely to collide with something from some other package. Other user commands should be prefixed, \gre... is fine for this. Commands emitted by gregorio (the program) should also be prefixed. I'm fine with \Gre..., but I'd also be fine with leaving it as \gre.... Internals are good with \gre@....

This is just my personal opinion. I'll go with the consensus.

[rpspringuel]

Started work at 7daa5b4c104d32bcddc204f8a4e3337dba1ab53f.

I'm starting with the Gregorio controls (\GreXxxxXxx). We seem to have more consensus on the convention for this group, the changes are a simple sed replacement, and I can generate a complete list of them from the contents of gregoriotex-write.c.

This also gives us an opportunity to continue the discussion about User commands.

I must say that I agree with @henryso about the User commands. Commands with good names probably don't need prefixes and we should make an effort to pick good names for as many User level commands as possible.

[rpspringuel]

@henryso, What's involved in changing \grecp... to \GreCP... and \greoCase... to \GreOCase...? My first attempt at changing grecp with a simple sed script broke something and I'm not sure what (changes were made in all files in src/gregoriotex and tex). As I recall, these commands are defined by lua scripts so I'm not sure what I should be looking at changing to get these right.

[henryso]

In addition to replacing grecp and greoCase, you also need to change the map_fonts function in gregoriotex.lua to \xdef\Gre%s%s{\char%d}. Besides that, I need to know a little bit more about what you see breaking.

[henryso]

Should we somehow differentiate between macros the user can use (as in call) as opposed to macros the user can redefine to change some behavior? Or maybe the only way to redefine these behavior macros is to call a \gre macro? (This is just a question; I have no idea what the "best" way is)

[rpspringuel]

Actually, most of the commands that a user would redefine are styling ones (for the initial, translation text, etc.) so I was thinking of reworking those as environments. If you look at the old texrenaming branch you can see an early go at this. I actually have an idea to make the LaTeX and PlainTex code a bit more interchangeable, but haven't tested it yet to make sure it works.

I'm fairly certain that if done this way there should be a clear distinction between what is redefinable and what is not.

[rpspringuel]

Okay, I'm back to trying to tackle \grecp and \greoCase. I did the sed replacement and made the modification that @henryso mentioned above. I also changed the prefix from cp to CP in gregoriotex-main.tex where map_font is called. However, I'm getting the following error:

./test-3_0_1.gtex:54: Undefined control sequence.
\gre@char@divisiomaior }-\GreCPDivisioMaior

I think this means that I missed something in the renaming process. I don't have time to work on this further today, but ideas for where I should start tomorrow are welcome.

[henryso]

Did you change

  \directlua{gregoriotex.map_font('greciliae', 'cp')}%

to

  \directlua{gregoriotex.map_font('greciliae', 'CP')}%

in gregoriotex-main.tex?

[rpspringuel]

Yes, I got that one.

[henryso]

I should have read your comment more carefully. Maybe you can use log in gregoriotex.lua to emit the macros it's generating. Beyond that, I'm a bit stumped.

[rpspringuel]

I added the following line to gregoriotex.lua to show what the macros being generated were:

      log("Setting \\Gre%s%s to \\char%d", prefix, glyph, unicode)

With this line in place, I find a whole bunch of stuff like this in the log file:

gregoriotex: Setting \GrenilTorculusResupinusQuilismaFiveFiveFiveNothing to \char59979

Note the nil in the prefix position. This led me to look back at the call of map_font in gregoriotex-main.tex where I discovered that my editor had replaced the single quotes around the prefix with smart quotes. This, naturally, screwed up Lua, as it no longer saw a quoted string, but an oddly named variable. Fixed that and things worked. Stupid "smart" editor.

[rpspringuel]

Okay, I'm getting ready to move on to the User commands, so we need to settle that issue relatively soon. To help things along, here's a list of the user commands currently defined:

• \includescore
• \gabcsnippet
• \forcecompilegabc
• \autocompilegabc
• \nevercompilegabc
• \grechangeglyph
• \greresetglyph
• \gredefsymbol
• \gredefsizedsymbol
• \gresimpledefbarglyph
• \greexpldefbarglyph
• \englishcentering
• \defaultcentering
• \grenobreakineuouae
• \greallowbreakineuouae
• \gresetdim
• \grechangedim
• \grenoscaledim
• \grescaledim
• \greloadspaceconf
• \setaboveinitialseparation
• \setspaceafterinitial
• \setspacebeforeinitial
• \setinitialspacing
• \setstafflinethickness
• \grecoloredlines
• \greredlines
• \redlines
• \grenormallines
• \normallines
• \writemode (this one should probably be deprecated)
• \gresetfirstlineaboveinitial
• \gresetfirstannotation
• \setfirstannotation
• \gresetsecondannotation
• \setsecondannotation
• \greremovelines
• \gredonotremovelines
• \grejustifiedlastline
• \greraggedlastline
• \gredisableeolshifts
• \greenableeolshifts
• \greblockcustos
• \greusenormalhyphen
• \greusezerohyphen
• \setgrefactor <-- forgot some
• \grehidealtlines
• \grenohidealtlines
• \grehidepclines
• \gredonthidepclines
• \grecommentary
• \grescorereference
• \setgretrantlationcenteringscheme
• \setnlbintranslation
• \grechangestyle <-- recent additions
• \greforcehyphen
• \greauothyphen

There are also several aliases for the above functions which are already marked as deprecated.

[henryso]

Since we're going all-out here, maybe we should get rid of deprecated macros and deprecation aliases as part of this?

Of that list above, I think \includescore could become \gregorioscore. \gabcsnippet can be left alone. \forcecompilegabc, \autocompilegabc, and \nevercompilegabc can also be left alone, but they are not major entry points so they should probably get a gre argument. Everything else without a gre prefix should take a gre prefix unless it's a deprecation alias (if we're keeping them).

Since we're going to make these incompatible changes anyway, should we also consider consolidating the mode macros into a single macro with an argument? (i.e., \forcecompilegabc, \autocompilegabc, \nevercompilegabc to \gresetcompilegabc; \englishcentering and \defaultcentering to '\gresetcentering`; etc.)

Also, an opinion: I don't like calling whole-word centering "English". For example, when I compose English chants, I still like centering on the vowel or vowel sound. If we are renaming, I'd like to discourage that naming (but then again, this is also in gabc, so it's not a cut-and-dry issue). Note: default centering is actually Latin centering, so I wouldn't call the default centering "vowel centering".

[eroux]

I agree on everything... the name "English" was proposed by the person who asked for this feature, I didn't really consider before accepting it, but it's never too late!

[rpspringuel]

When it comes to name changes for the User functions, I favor a 3 stage process:

1. Deprecated function names raise a warning which points to the new name, but otherwise work as follows.
2. Obsoleted function names no longer work, but raise an error which points to the new name.
3. The function name no longer exists in the code base. Anyone still using it gets the generic "Undefined control sequence" error.

Each of these steps should be in a major or minor release, with step 1 or 2 being a mandatory major (i.e., if step 1 is a minor release, then step 2 must be major, if step 1 is a major release, then step 2 is allowed to be a minor release).

In this fashion the user should be alerted to the change at run time at some point during the name change process.

Under this process, any functions above which we rename would be marked as deprecated in 4.0, but there are a bunch of functions that were marked as deprecated in 3.0.0 which would now move to obsolete status. 4.1 (or 5.0, if we make significant changes) would be the first release where old function names no longer appear in the code (those that were marked as deprecated in 3.0).

Exceptions to this system would exist where old names would conflict with new functionality or where there is no way to raise the appropriate warnings/error (such as in the styling changes, where the old method was to redefine commands).

As for consolidating the mode macros, I'm not opposed to this. For me having one command with an argument or multiple commands isn't that big of a difference.

For centering, how about "syllable" and "vowel" as the alternatives?

[henryso]

I'm fine with this process. As for centering, I'd actually favor "syllable" and "Latin" as the alternatives. The rules for Latin centering are based on Ecclesiastical Latin rules for interpreting semivowels, so I'd definitely go with "Latin" rather than "vowel".

[rpspringuel]

Okay, here's a proposal for the user function names. Complete arguments are not given, just those that result from the consolidation of several functions in the above list. Looking over my previous work, I also noticed some additional functions that I missed above:

Score inclusion

• \gregorioscore
• \gabcsnippet

Part of me wants there to be some consistency here (i.e. \gabcscore or \gregoriosnippet) but I'm not married to that idea.

Compilation behavior

• \gresetcompile{force|auto|never}

Glyph alteration

• \grechangeglyph
• \greresetglyph
• \gredefsymbol
• \gredefsizedsymbol
• \gresimpledefbarglyph
• \greexpldefbarglyph

I haven't looked closely at these functions yet to determine if there are opportunities for consolidation here. @henryso, you created these, you're in the best position to know what's necessary here and what's not.

Dimensional control

• \gresetdim
• \grechangedim
• \grescaledim{yes|no}
• \greloadspaceconf

Size control

• \gresetstaffsize
• \gresetstafflinethickness

Colored lines

• \grecoloredlines{gregoriocolor|black|...}

This is a short cut command for changing a style (normallines) and thus could be eliminated in a strict sense of consolidation.

Styling changes

-\grechangestyle

Text elements

• \gresetfirstlineaboveinitial
• \gresetfirstannotation
• \gresetsecondannotation
• \grecommentary
• \grescorereference

Ideally I'd like to see the first three consolidated into a single master function \greannotation, but that would require some under the hood work first.

Custos control

• \gresetcustos{block|auto}

Should there be a manual option here (i.e. custos are not placed automatically, but manual custos will appear)? If so, I think this would require some additional under the hood work.

Text alignment

• \gresetlyriccentering{latin|syllable}
• \gresettranslationcentering{left|center}

Line breaks

• \gresetbreakineuouae{allow|prohibit}
• \gresetbreakintranslation{allow|prohibit}

Line visibility

• \gresetlines{visible|invisible}
• \gresetlinesbehindalt{visible|invisible}
• \gresetlinesbehindpc{visible|invisible}

End of score alignment

• \gresetlastline{justified|ragged}

End of line adjustments

• \greseteolshifts{enabled|disabled}

Hyphen usage

• \gresethyphen{force|auto}
• \greseteolhyphen{noraml|zero}

Clef visibility

• \gresetclef{visible|invisible}

Any name on the above list would be considered deprecated and marked as such.

[henryso]

For glyph alteration, although the barglyph macros were actually added by @eroux, I think I can say that there is no real consolidation opportunity here. \grechangeglyph substitutes a score glyph. \greresetglyph resets a score glyph back. \gredefsymbol defines a non-score glyph. \gredefsizedsymbol defines a non-score glyph which takes a size argument. \greexpldefbarglyph defines a barred letter. \gresimpledefbarglyph is a simpler version of same, with some default arguments.

Note here that \gresimpledefbarglyph makes some assumptions about glyph naming, so it's not entirely something that can be handled via default arguments, so I'm inclined to leave it as it is.

However, if we are going to rename these anyway, I'd recommend not calling the "barglyph" macros by that name. Firstly, "bar" here can be confused with the "musical" bar (i.e., divisio); secondly, I've been using "glyph" to mean score glyphs and "symbol" to mean non-score glyphs; and thirdly, I cannot attribute a reasonable English meaning to \greexpldefbarglyph (explicit? exploded?). So my recommendation is to rename \gresimpledefbarglyph to \gresimpledefbarredsymbol and \greexpldefbarglyph to \gredefbarredsymbol.

On to other things. First, in general:

• Should we use the word "set"? From the list above, we are currently inconsistent about it.
• When you say \gresethyphen{force|auto} do you mean two macros, \gresethyphenforce and \gresethyphenauto or one macro that takes either force or auto as an argument?

Now, specifically (from top to bottom):

• We specifically wanted to have a naming difference between "score" and "snippet" to indicate that snippet is for short gabc bits and not for including full score, so I think the naming suggested here is fine.
• I would rename \gresetcompile to \gresetgabccompile or \gregabccompile, but I don't really feel all that strongly about it.
• If it's s significant enough short-cut, I'd leave \grecoloredlines in, perhaps renaming to \gresetlinecolor or \grelinecolor to better match what it's doing.
• What does \gresetlinesbehindpc do?
• Besides my comment about "set" above, the rest are fine with me.

[henryso]

Incidentally, how do you compare words in Plain TeX? If the arguments will be things like auto and disable, what's the right way to do the comparison in Plain TeX?

[henryso]

One more thing... You wrote "Any name on the above list would be considered deprecated and marked as such." I'm assuming you mean "Any name not on the above list would be considered deprecated and marked as such."

[henryso]

Thinking about this a bit more... Lyric centering is done directly by the C code. How do we control that from TeX?

[rpspringuel]

Should we use the word "set"? From the list above, we are currently inconsistent about it.

I added it because most of these macros are, in a manner of speaking, changing a setting. We could, of course, use something else or nothing at all.

When you say \gresethyphen{force|auto} do you mean two macros, \gresethyphenforce and \gresethyphenauto or one macro that takes either force or auto as an argument?

I mean one macro \gresethyphen which takes one of two arguments: force and auto.

We specifically wanted to have a naming difference between "score" and "snippet" to indicate that snippet is for short gabc bits and not for including full score, so I think the naming suggested here is fine.

Okay.

I would rename \gresetcompile to \gresetgabccompile or \gregabccompile, but I don't really feel all that strongly about it.

Makes sense. I'll hold off making the change until we decide on "set".

If it's s significant enough short-cut, I'd leave \grecoloredlines in, perhaps renaming to \gresetlinecolor or \grelinecolor to better match what it's doing.

The short cut is significant in that color is pretty much the most common thing you'd want to change about the lines (and indeed, one of the few things that actually would change something, since the lines are rules).

What does \gresetlinesbehindpc do?

Controls the visibility of lines behind a punctum cavum (the alt variety does the same for alterations, i.e. accidentals). Because these characters are hollow, we have to specifically fill the "hole" in the center if we don't want to see the line passing through it.

Incidentally, how do you compare words in Plain TeX? If the arguments will be things like auto and disable, what's the right way to do the comparison in Plain TeX?

The xstring package (which is what we already use for string comparisons elsewhere) is PlainTeX compatible.

One more thing... You wrote "Any name on the above list would be considered deprecated and marked as such." I'm assuming you mean "Any name not on the above list would be considered deprecated and marked as such."

Sort of. By above list I was referring to the list in my earlier post, which has many names not appearing on the list in my proposal. Admittedly the wording is very confusing. Basically anything which currently exists in GregorioTeX (the first list) and does not appear in the proposal (the second list) would be marked as deprecated.

Thinking about this a bit more... Lyric centering is done directly by the C code. How do we control that from TeX?

If the gabc header doesn't specify a centering scheme, or specifies Latin, then the C code breaks the syllable up into three parts (according to the rules for ecclesiastical Latin). The TeX code sticks those three parts back together and calls the whole thing the middle part, effectively turning on "english" centering. It cannot, unfortunately, go the other way. See #27 and #28.

[henryso]

About "setlinesbehind": in that case, I suggest spelling out \gresetlinesbehindalteration and \gresetlinesbehindpunctumcavum, though it does make the macro names a bit long. Still, how many times are you going to need to type that in a given given document?

About lyric centering, though this is incompatible, maybe the toggle should be strictly in TeX. In this case, vowel and syllable make sense as the options. We would change the C code to always apply vowel centering, and let TeX put it together for syllable centering. If we add the ability for different language-driven vowel-centering rules (which I'm thinking about right now), that would need to be switched around in gabc. Setting it to syllable mode would be TeX-based. The current value in the gabc header would either go away or be used to pass the appropriate TeX to turn on syllable mode, though in this case, it should be renamed for consistency.

[rpspringuel]

I think keeping the lyric centering in the gabc header was a backwards compatibility issue for @eroux. I wouldn't be adverse, however, to having the switch be entirely in TeX. If we were going to eliminate the centering-scheme header element from the gabc, a major version change (like from 3.0 to 4.0) would be the time to do it anyway. If you do manage to introduce language dependent centering schemes, then it would probably make more sense for the header field to be language anyway. Then the C code could use the vowel rules for that language (if it knows it) and pass the three parts of the syllable (pre-vowel, vowel, post-vowel) to TeX where the user would decide whether to use vowel or syllable centering.

About "setlinesbehind": in that case, I suggest spelling out \gresetlinesbehindalteration and \gresetlinesbehindpunctumcavum, though it does make the macro names a bit long. Still, how many times are you going to need to type that in a given given document?

Probably not many. If you think the longer name is clearer, I'm not opposed to it.

[henryso]

As far as the TeX bits are concerned, I suggest going with syllable and vowel for \gresetlyriccentering (contrary to what I originally suggested) because it doesn't control centering language. I will wait on @eroux's comments before touching the C.

As for "setlinesbehind", I vote for longer names. I wouldn't have had the question above if it had the longer name. And actually the "alt" version fooled me into misunderstanding what that macro did.

[eroux]

I think there should be a deprecation before removing it from gabc, but otherwise it's perfectly fine for me! I like syllable vs vowel, and I let you decide for the rest, as you obviously have more experience in English than I have...

[henryso]

@eroux, I'm taking this to mean that we will leave text-centering in, taking latine/english but issue a deprecation warning about this feature and that vowel/syllable will be the values used in TeX. Let me know if I misunderstand.

What do you think of having this gabc header generate the appropriate \grelyriccentering command rather than changing the centering in \gresyllable?

[eroux]

I agree with everything, setting it in TeX is really a good idea!

[rpspringuel]

Okay, based on the feed back (and assuming that #476 gets merged) here's the revised list:

Score inclusion

• \gregorioscore
• \gabcsnippet

Compilation behavior

• \gresetcompile{force|auto|never}

Glyph alteration

• \grechangeglyph
• \greresetglyph
• \gredefsymbol
• \gredefsizedsymbol
• \gresimpledefbarredsymbol
• \gredefbarredsymbol

Dimensional control

• \gresetdim
• \grechangedim
• \grescaledim{yes|no}
• \greloadspaceconf

Size control

• \gresetstaffsize
• \gresetstafflinethickness

Colored lines

• \grelinescolor{gregoriocolor|black|...}

Styling changes

-\grechangestyle

Text elements

• \greannotation
• \grecommentary
• \grescorereference

Custos control

• \gresetcustos{block|auto}

Text alignment

• \gresetlyriccentering{vowel|syllable}
• \gresettranslationcentering{left|center}

Line breaks

• \gresetbreakineuouae{allow|prohibit}
• \gresetbreakintranslation{allow|prohibit}

Line visibility

• \gresetlines{visible|invisible}
• \gresetlinesbehindalteration{visible|invisible}
• \gresetlinesbehindpunctumcavum{visible|invisible}

End of score alignment

• \gresetlastline{justified|ragged}

End of line adjustments

• \greseteolshifts{enabled|disabled}

Hyphen usage

• \gresethyphen{force|auto}
• \greseteolhyphen{noraml|zero}

Clef visibility

• \gresetclef{visible|invisible}

Any name not on this list would be considered deprecated (or obsolete) and marked as such. I'll get started on these names later today or tomorrow.

[henryso]

Obvious typos aside, this looks ok to me.