v6.2.0

The Gregorio team is happy to announce the release of v6.2.0 of Gregorio. The release marks the first time we've had complete test coverage on all 3 major OS families (Windows, Linux, and macOS).

Due to delays in publishing this release, it is not part of TeX Live 2026 and will not be pushed to CTAN. To upgrade, you must install using the appropriate resource from this release page. Since this is not the first time we've had problems getting a release completed in time for TeX Live's annual release (though it is the first time we've actually missed the release in a while), we'll be revising our release timeline in order to ensure that our next release makes it into TeX Live 2027.

UPGRADE from 6.1

LuaTeX >= 1.0 required

The minimum required version of LuaTeX is now 1.0 (released in 2016). Attempts to compile documents with older versions of LuaTeX will result in an error.

grefinalpenalty

The count grefinalpenalty no longer has any effect and will be removed in a future release.

Final Z and z

Forced line breaks (Z or z) at the very end of a score are discouraged. Please use \gresetlastline{ragged} or \gresetlastline{justified} instead to set the appearance of the last line.

spaceabovelines and abovelinestextheight changed meaning

The meanings of these distances were changed to be (hopefully) easier to use and closer to their descriptions in the documentation. Please see the section "Vertical spacing" in GregorioRef.pdf for more information. Scores that use the default settings and have above-lines text (<alt>) will now have slightly more whitespace above the above-lines text. Scores that set either of these two distances explicitly may experience larger changes in whitespace between staves, and should be checked.

spaceabovelines and spacebeforesigns changed from skips to dimens

These spaces were changed from skips to dimens; that is, they can no longer have stretch or shrink (plus or minus). For example, a command \grechangedim{spacebeforesigns}{0.050 cm plus 0.004 cm minus 0.004 cm}{scalable} should be changed to \grechangedim{spacebeforesigns}{0.050 cm}{scalable}.

• In previous versions, stretch/shrink on spaceabovelines was ignored, so removing stretch/shrink will not change the output.
• In previous versions, stretch/shrink on spacebeforesigns was causing a double punctum mora to be misaligned, so removing stretch/shrink should improve the output.

What's Changed

• One-pass computation of line spacing by @davidweichiang in #1641
• Trim staff lines on last line by @davidweichiang in #1627
• Fix overfull \hbox warning in ledger lines by @davidweichiang in #1646
• Fix bug causing an error on scores with two line breaks in a row by @davidweichiang in #1653
• Change mora_vposition from a bitfield to its own field by @davidweichiang in #1654
• Clarify vertical spacing by @davidweichiang in #1659
• Some fixes to the documentation by @rpspringuel in #1651
• Windows make by @rpspringuel in #1640
• Speed up \gre@createdim by @davidweichiang in #1664
• Add missing newlines in error messages by @davidweichiang in #1666
• NABC+abovelinestext and NABC below lines by @davidweichiang in #1662
• Eliminate \gre@luasavedim by using the "new" token library by @davidweichiang in #1679
• Yearly Maintenance plus by @rpspringuel in #1687
• Print commentary even when first syllable has no text (#1678) by @davidweichiang in #1681
• Add overtie/undertie symbols, and lyric tying shorthand by @lbssousa in #1684
• Change spacebeforesigns from a skip to a dimen (#1656) by @davidweichiang in #1682
• Missing CHANGELOG entry by @rpspringuel in #1689
• Missing CHANGELOG entries by @rpspringuel in #1690
• Change spaceabovelines from a skip to a dimen by @davidweichiang in #1697
• checkSyllabation.py: Handle more tags; handle words with notes only at the end by @bhank in #1671
• Make bool.h compatible with C23 (used by default by GCC 15) by @davidweichiang in #1696
• Correct recording of files read and written in Lua by @davidweichiang in #1692
• Add/remove documentation - fixes #1704 by @eschwab in #1705
• Enhanced Visibility Controls by @lbssousa in #1683
• Add commands to documentation for macros with long arg tables by @rpspringuel in #1707
• Fix parser handling of empty GABC/NABC snippets (#1700) by @lbssousa in #1701
• feat: add configurable NABC horizontal alignment mode (#1702) by @lbssousa in #1703
• Fix conflict between develop and ctan branches after merging PRs #1701 and #1703 by @lbssousa in #1709
• Fix regressions introduced after ctan merge (#1708) by @lbssousa in #1711
• New feature: \gresetnabcskipalterations by @lbssousa in #1714
• Add shim for lfs.mkdirp for compatibility with LuaTeX < 1.18 by @davidweichiang in #1730
• Unset glyph height attributes right after glyph is emitted. Fixes #1717. by @davidweichiang in #1721
• Use signed char instead of char for a pitch or ambitus by @davidweichiang in #1731
• Fix segfault on empty GRE_ELEMENT when nabc_state wraps mid-syllable (#1726) by @lbssousa in #1727
• Handle option errors internally by @rpspringuel in #1739

New Contributors

• @lbssousa made their first contribution in #1684
• @bhank made their first contribution in #1671

Full Changelog: https://github.com/gregorio-project/gregorio/blob/v6.2.0/CHANGELOG.md

v6.2.0-rc1

We've found and fixed something that wasn't quite a bug, so we're moving on to the first release candidate. Absent any bug reports we anticipate issuing the release April 15.

What's Changed

• Handle option errors internally by @rpspringuel in #1739

Full Changelog: https://github.com/gregorio-project/gregorio/blob/v6.2.0-rc1/CHANGELOG.md

v6.2.0-beta3

This fixes the last known blocking bug for the 6.2.0 release. Please test and report back any bugs you find. As this is being released at the beginning of Holy Week (a traditionally busy time for those interested in Gregorian Chant), we will won't be moving to a release candidate until after Easter.

What's Changed

• Fix segfault on empty GRE_ELEMENT when nabc_state wraps mid-syllable (#1726) by @lbssousa in #1727

Full Changelog: https://github.com/gregorio-project/gregorio/blob/v6.2.0-beta3/CHANGELOG.md

v6.2.0-beta2

The first beta revealed some problems that have now been fixed and a couple of the new feature have been made more robust. There are still a couple of outstanding issues that we expect to resolve before moving to release candidates, but we're at the point where we'd like to solicit more testing.

What's Changed

• feat: add configurable NABC horizontal alignment mode (#1702) by @lbssousa in #1703
• Fix conflict between develop and ctan branches after merging PRs #1701 and #1703 by @lbssousa in #1709
• Fix regressions introduced after ctan merge (#1708) by @lbssousa in #1711
• New feature: \gresetnabcskipalterations by @lbssousa in #1714
• Add shim for lfs.mkdirp for compatibility with LuaTeX < 1.18 by @davidweichiang in #1730
• Unset glyph height attributes right after glyph is emitted. Fixes #1717. by @davidweichiang in #1721
• Use signed char instead of char for a pitch or ambitus by @davidweichiang in #1731

Full Changelog: https://github.com/gregorio-project/gregorio/blob/v6.2.0-beta2/CHANGELOG.md

6.2.0-beta1

We've missed the TeX Live 2026 Pretest, so this release will not end up in TeX Live 2026, but there's been a bunch of development over the course of the past year (and especially the last month, hence missing the pretest). You will need to install this locally using the either the installers (MacOS and Windows) or make (MacOS or Linux).

CHANGELOG

[6.2.0-beta1] - 2026-02-23

Fixed

• Fixed a bug that could cause a punctum mora that is supposed to be below the line (.0) to appear above the line. This bug was platform-dependent and was observed on a Windows system. See #1642.
• Error messages from executable have been cleaned up to be more uniform. See #1644.
• NABC neumes are now rendered for syllables with empty GABC/NABC snippets when NABC content is present (e.g. (|vi|ta), (|vi), (||ta), (g||ta)). See #1700.
• Commentary will now print even if the first syllable of the score has no lyric text. See #1678.
• You can now have both nabc neumes and above line text. See #1559.
• Error raised by double blank lines has been fixed. See #1652.

Added

• Added unified visibility controls (visible, invisible, phantom, and hphantom). Solves #1626.
• Decouple visibility control for NABC and above-lines text from notes. Solves #1547.
• Added proper vertical spacing and alignment of score elements in NABC+lyrics-only contexts. Solves #1694.
• Added horizontal spacing preservation for NABC neumes, preventing overlap. Solves #1699.
• Added overtie/undertie special symbols (<sp>ut</sp> for \greundertie, <sp>ot</sp> for \greovertie, and <sp>dt</sp> for \gredoubletie), and a configurable lyric tying shorthand (~ for \GreLyricTie).
• Added support for the C23 standard (the default in GCC 15). The included build scripts continue to default to GNU89 C.
• Added new option \gresetlastline{trimmed}, which sets the last line ragged and also trims the staff lines. See #1418.
• Nabc can now appear below the staff in addition (or instead of) above. See #1645.

Changed

• Variable line heights are now computed in one pass instead of two. Per-line adjustments using \grechangenextscorelinedim and \grechangenextscorelinecount are also done in one pass, but only work on dimensions/counts related to line heights. Mentioned in #1488.
• Previously, if a score ended with Z (ragged line break) or z (justified line break), the appearance of the last line would sometimes depend on Z versus z and sometimes depend on \gresetlastline{ragged} versus \gresetlastline{justified}. Now, the appearance of the last line always depends on \gresetlastline.
• Fixed a bug introduced in 6.1.0 that caused latexmk not to recognize when a GABC file has changed and needs to be recompiled (issue #1685).
• spacebeforesigns and spaceabovelines were changed from skips to dimens; that is, they can no longer have a stretch or shrink (plus or minus). Fixes #1489, #1656, and #1695.
• The meanings of the distances spaceabovelines and abovelinestextheight were changed to be (hopefully) easier to use and closer to their descriptions in the documentation. Fixes #1633 and #1634.
• All lengths related to vertical spacing are documented in greater detail in a dedicated section in GregorioRef.pdf. Fixes #1631.
• We now require LuaTeX version 1.0 (2016) or greater. This enabled some streamlining of the internal code, but user interface is unaffected.
• \gre@createdim now takes an additional argument which specifies whether the dim allows a glue (i.e., whether it would be a skip or a dimen). This eliminates the previous strategy of looking up the known glues, speeding up the process of creating all the dims.

Deprecated

• The count grefinalpenalty no longer has any effect and will be removed in a future release.

UPGRADE

6.2

LuaTeX >= 1.0 required

The minimum required version of LuaTeX is now 1.0 (released in 2016). Attempts to compile documents with older versions of LuaTeX will result in an error.

grefinalpenalty

The count grefinalpenalty no longer has any effect and will be removed in a future release.

Final Z and z

Forced line breaks (Z or z) at the very end of a score are discouraged. Please use \gresetlastline{ragged} or \gresetlastline{justified} instead to set the appearance of the last line.

spaceabovelines and abovelinestextheight changed meaning

The meanings of these distances were changed to be (hopefully) easier to use and closer to their descriptions in the documentation. Please see the section "Vertical spacing" in GregorioRef.pdf for more information. Scores that use the default settings and have above-lines text (<alt>) will now have slightly more whitespace above the above-lines text. Scores that set either of these two distances explicitly may experience larger changes in whitespace between staves, and should be checked.

spaceabovelines and spacebeforesigns changed from skips to dimens

These spaces were changed from skips to dimens; that is, they can no longer have stretch or shrink (plus or minus). For example, a command \grechangedim{spacebeforesigns}{0.050 cm plus 0.004 cm minus 0.004 cm}{scalable} should be changed to \grechangedim{spacebeforesigns}{0.050 cm}{scalable}.

• In previous versions, stretch/shrink on spaceabovelines was ignored, so removing stretch/shrink will not change the output.
• In previous versions, stretch/shrink on spacebeforesigns was causing a double punctum mora to be misaligned, so removing stretch/shrink should improve the output.

v6.1.0

This is the release intended to go into TeX Live 2025.

CHANGELOG

[6.1.0] - 2025-02-28

Fixed

• Multiple Scribus render frames were all using the same file name, which would result in the same score appearing in all render frames. This change makes the score files use an available Scribus variable to force multiple file names.
• When kpsewhich cannot write to a particular location, it generates an error which is directed to stderr but not to our glog file. This created an undocumented error when trying to write to a gtex file to a bad location. We now capture stderr output produced when compiling scores and redirect it to our glog file so that the error is properly recorded. Fixes #1541.
• Fixed the interaction between hyphens and styles. See #1538.
• Fixed the loss of ongoing styles when a syllable starts with a forced center. See #1551.
• Fixed first syllables of one letter with a style causing a segfault. See #1585.
• Fixed a bug that caused a custos to sometimes change into a clef. See #1373.
• Fixed the alignment of 2-line initials so that an initial's baseline more exactly aligns with the baseline of the lowest line it appears next to.
• When fancyhdr and GregorioTeX are used together, GregorioTeX's disabling of hyphenation and its post_linebreak modification of the post_linebreak_filter interfere with multiline headers. Using the fancyhdr/before and fancyhdr/after hooks we temporarily reenable hyphenation and disable our post_linebreak modification while headers and footers are being processed in the middle of a score. See #1603.
• Fixed a bug that could cause a hyphen to appear on the wrong line. See #1319.
• Fixed the placement of above-lines text (<alt>) relative to a note above the staff or when the number of staff lines is not 4. See #1613 and #1614.
• Fixed a bug where the above-lines text (<alt>) could collide with a note above the staff. See #1613.
• Fixed a bug that could cause the clef and staff to be printed too high. See #1503.

Changed

• Modified gregorio to write to the log file specified as an argument and to send all messages to it (except errors about opening the log file itself). See #1541 and #1628.
• Defined an output directory for gtex and glog files. Default is tmp-gre. This can be changed using \gresetoutputdir{...}. Fixes #1393, #1542, and #1571.
• GregorioTeX no longer searches for and reuses existing gtex files using kpathsea; it only looks in the output directory.
• If gtex or glog files from other versions of gregorio are found either in the same directory as the gabc file or in the output directory, they are deleted.
• gabc.vim has been expanded into a proper vim plugin.

Added

• Added a configurable setting \gresetunisonbreakbehavior to control automatic line breaks between unison notes above a syllable. Defaults to breakable for backwards compatibility, but may be set to unbreakable if that behavior is desired. See #1504.
• Added the ability to fuse upwards to a virga. See #1558
• Added the ability to use the "stroke" form of a clivis instead of the default two-notes form by specifying [shape:stroke] after the clivis to change. See #1558
• Allow \gresetinitiallines{n} where n is any number of lines (a non-negative integer). The manual linebreaks (z) that used to be required for 2-line initials are no longer required. See #1488. Added new options \gresetinitialanchor and \gresetinitialposition to control the placement of initials.
• Added new alterations: soft flat (X) and sharp (##), which appear when there is no previous flat or sharp (respectively) in effect, and soft natural (Y), which appears when there is a previous flat or sharp in effect. A new option \gresetalterationeffect determines what the "effect" of an alteration is. It defaults to line, which is useful for Dominican chant. See #157 and also #1575.
• 9 new St. Gall neume glyphs have been added to the gregall font.

UPGRADE

6.1

Multiline initials

Initial letters that are 2 lines high used to require manual linebreaks (z), but no longer do. The alignment of 2-line initial letters has changed slightly and may need to be adjusted. Further, initials can now span over an arbitrary number of lines.

Soft alterations

GABC now has some new alterations: soft flat (X) and sharp (##), which appear when there is no previous flat or sharp (respectively) in effect, and soft natural (Y), which appears when there is a previous flat or sharp in effect. A new option \gresetalterationeffect determines what the "effect" of an alteration is. It defaults to line, meaning that an alteration's effect extends to the end of the line. Thus, for Dominican chant, type a soft flat (X) in front of every note that is to be sung a half-step flat; naturals should also be soft (Y), but only naturals that cancel flats need to be typed.

v6.1.0-rc1

This should be the last pre-release before the TeX Live 2025 pretest ends. All known blocking bugs have been addressed. We'll push the final release as soon as we've verified there are no problems with the upload to the TeX Live pretest.

v6.1.0-beta2

This is the second beta release for the TeX Live 2025 Pretest.

Windows installer is not currently available but should be available by time of final release.

CHANGELOG (since beta1)

[6.1.0-beta2] - 2025-02-17

Fixed

• Fixed a bug that could cause a hyphen to appear on the wrong line. See #1319.
• Fixed the placement of above-lines text (<alt>) relative to a note above the staff or when the number of staff lines is not 4. See #1613 and #1614.
• Fixed a bug where the above-lines text (<alt>) could collid with a note above the staff. See #1613.
• Fixed a bug that could cause the clef and staff to be printed too high. See #1503.

UPGRADE (cumulative)

[Unreleased][develop]

Initial letters that are 2 lines high used to require manual linebreaks (z), but no longer do. The alignment of 2-line initial letters has changed slightly and may need to be adjusted.

GABC now has some new alterations: soft flat (X) and sharp (##), which appear when there is no previous flat or sharp (respectively) in effect, and soft natural (Y), which appears when there is a previous flat or sharp in effect. A new option \gresetalterationeffect determines what the "effect" of an alteration is. It defaults to line, meaning that an alteration's effect extends to the end of the line. Thus, for Dominican chant, type a soft flat (X) in front of every note that is to be sung a half-step flat; naturals should also be soft (Y), but only naturals that cancel flats need to be typed.

v6.1.0-beta1

This is the first beta release for the TeX Live 2025 Pretest.

Windows installer is not currently available but should be forthcoming.

[6.1.0-beta1] - 2025-02-10

Fixed

• Multiple Scribus render frames were all using the same file name, which would result in the same score appearing in all render frames. This change makes the score files use an available Scribus variable to force multiple file names.
• When kpsewhich cannot write to a particular location, it generates an error which is directed to stderr but not to our glog file. This created an undocumented error when trying to write to a gtex file to a bad location. We now capture stderr output produced when compiling scores and redirect it to our glog file so that the error is properly recorded. Fixes #1541.
• Fixed the interaction between hyphens and styles. See #1538.
• Fixed the loss of ongoing styles when a syllable starts with a forced center. See #1551.
• Fixed first syllables of one letter with a style causing a segfault. See #1585.
• Fixed a bug that caused a custos to sometimes change into a clef. See #1373.
• Fixed the alignment of 2-line initials so that an initial's baseline more exactly aligns with the baseline of the lowest line it appears next to.
• When fancyhdr and GregorioTeX are used together, GregorioTeX's disabling of hyphenation and its post_linebreak modification of the post_linebreak_filter interfere with multiline headers. Using the fancyhdr/before and fancyhdr/after hooks we temporarily reenable hyphenation and disable our post_linebreak modification while headers and footers are being processed in the middle of a score. See #1603.

Changed

• Modified gregorio to append to the log file specified as an argument and to send early messages to it. See #1541.
• Defined an output directory for gtex and glog files. Default is tmp-gre. This can be changed using \gresetoutputdir{...}. Fixes #1393, #1542, and #1571.
• gabc.vim has been expanded into a proper vim plugin.

Added

• Added a configurable setting \gresetunisonbreakbehavior to control automatic line breaks between unison notes above a syllable. Defaults to breakable for backwards compatibility, but may be set to unbreakable if that behavior is desired. See #1504.
• Added the ability to fuse upwards to a virga. See #1558
• Added the ability to use the "stroke" form of a clivis instead of the default two-notes form by specifying [shape:stroke] after the clivis to change. See #1558
• Allow \gresetinitiallines{n} where n is any number of lines (a non-negative integer). The manual linebreaks (z) that used to be required for 2-line initials are no longer required. See #1488. Added new options \gresetinitialanchor and \gresetinitialposition to control the placement of initials.
• Added new alterations: soft flat (X) and sharp (##), which appear when there is no previous flat or sharp (respectively) in effect, and soft natural (Y), which appears when there is a previous flat or sharp in effect. A new option \gresetalterationeffect determines what the "effect" of an alteration is. It defaults to line, which is useful for Dominican chant. See #157 and also #1575.
• 9 new St. Gall neume glyphs have been added to the gregall font.

v6.0.0

With the close of the TeX Live 2021 pretest just around the corner, we’re finalizing the 6.0.0 release. This release is will not be available through tlmgr for TeX Live 2020, but can be installed using the appropriate method for your platform if you want it before the release of TeX Live 2021.

Changelog

[6.0.0] - 2021-03-13

Fixed

• Fixed some problem in 900_gregorio.xml (Scribus render frame tool). First, the use of filecontents rather than filecontents* was leading to a comment header that made it impossible for Gregorio to find the gabc headers in the temporary score file. Further, some of the indenting (which makes the file more human readable) was leading to errors in the formatting of the created files because they are processed in a way which handles whitespace differently from XML. See #1457.
• spacelinestext is now based on the lyric font size instead of being a fixed distance. As a result, large lyrics should no longer overlap with low notes. See #1261.
• Added parenthesized figures for virgula (gabc: `?), divisio minima (gabc: ,?), flat (gabc: x?), natural (gabc: y?), and sharp (gabc: #?). See #1475.
• Staff line thickness is now set in gsp-default.tex. This corrects a problem with the staff lines changing thickness when the default spacing configuration is loaded while the staff size is something other than the default (17). See #1461.
• Corrected interaction issues between text styles and ligatures. The LaTeX commands like \textit insert italics correction, preventing ligatures being formed between their arguments if two occur sequentially. On the other hand the switches like \itshape do not. Since gregorio breaks up syllables around the vowel and then applies the formating commands to each part, this behavior showed up. We switch to using the switches to avoid this (except for underlining, for which a switch does not exist). We also fix this for color tags by loading luacolor which changes how the \color tag is implemented to allow ligatures to span groups. See #1444.
• A reuse of a save register led to the \hyphenpenalty not being restored correctly at the end of the score. All save registers are now clearly identified by when they are used so as to make it harder to accidentally use the wrong one. See posts on mailing list.
• Fixed an overly specific find/replace in snippets that that led to \par being able to slip into the snippet file under certain circumstances (and there by causing compilation to fail). See #1497.
• Updated to use iftex package (the sucessor to ifluatex). See #1481.

Added

• Default spacings are now designated internal and thus always loaded. gsp-sample.tex is added to the doc folder to show users how to create their own custom spacing configuration. As part of this change, spacing configuration files no longer need to be complete. Since the default configuration is always loaded at package startup, all needed penalties and spacings will be defined and the user's configuration file need only specify those whose value they wish to customize. Addresses issues raised in #1460.
• Added additional message to verbose output of command-line tool to prevent confusion when a custom Latin vowel convention is found that the internal Latin rules will be used. See #1470.
• Added $ in gabc text to prevent special interpretation of the character that follows. See #1515
• GregorioTeX will now look in additional places for scores. Users can specify paths to look in using \gresetgregpath. If scores are not found in the current working directory or the list of provided paths, we fall back on kpse to try and find them. See #1395.
• Added the ability to toggle the visibility of the translation and above lines text. See user request on mailing list.

Changed

• The space between a non-punctum inclinatum and the upright punctum inclinatum is renamed to uprightpunctuminclinatumshift. This helps to better distinguish it from punctuminclinatumunisonshift (the space between two consecutive ascending or descending puncta inclinata on the same line). See #1507.
• noteadditionalspacelinestext now calculates the actual amount of additional space needed by low notes. To enable the old behavior (when noteadditionalspacelinestext is set by the user), use \gresetnoteadditionalspacelinestext{manual}. See #1521 and #1526.

Removed

• \gresethyphenprotrusion{percentage}, supplanted by \gresetprotrusionfactor{eolhyphen}{factor}. Note that the value the new command takes is a factor rather than a percentage.

Upgrade

6.0

Upright punctum inclinatum

Gregorio will now use an "upright" punctum inclinatum shape for a series of unison punctum inclinatum notes over a given syllable. When there is a single punctum inclinatum, Gregorio will use a heuristic to choose a shape. In any of these cases, if the result is not satisfactory, especially in context with nearby syllables, you may select a different shape by using 0 (for the descending shape) or 1 (for the ascending shape) after the capitalized letter indicating the punctum inclinatum. Forced selection of the upright shape is also possible by using 2 after the capitalized letter indicating the punctum inclinatum.

GABC escape character

In GABC text, the dollar sign ($) is now an "escape character" which prevents any special interpretation of the single character which follows the $. This allows you to put things like parentheses in text (use $(), but it also prevents other special interpretation of the character that follows (e.g., $: prevents auto-protrusion for the colon and $- prevents hyphenation handling of the dash). In order to send a $ to TeX, use $$ to escape the dollar sign.

If you had used the $ for some reason in your GABC text, this change will break your score. You will need to change all $ in your text to $$ to retain the old behavior.