gregoriotex (12mar18)

git-svn-id: svn://tug.org/texlive/trunk@46990 c570f23f-e606-0410-a88d-b1316a301751

15 files changed, 962 insertions, 111 deletions

diff --git a/Master/texmf-dist/doc/luatex/gregoriotex/Command_Index_User.tex b/Master/texmf-dist/doc/luatex/gregoriotex/Command_Index_User.tex
index bf897bf711c..86a8f4d0129 100644
--- a/Master/texmf-dist/doc/luatex/gregoriotex/Command_Index_User.tex
+++ b/Master/texmf-dist/doc/luatex/gregoriotex/Command_Index_User.tex
@@ -80,6 +80,12 @@ Gregorio\TeX{} two-pass processing is compatible with \texttt{latexmk}.
 
 If you only need the special symbols which Gregorio\TeX\ contains, and not the ability to include scores or musical glyphs, then you can load \texttt{gregoriosyms} instead of \texttt{gregoriotex}.  It supports all of the above options except those specifically related to scores.  \textbf{You should not try to load both packages}.
 
+\subsubsection{Gregorio\TeX{} and \texttt{microtype}}
+
+If you are using the \texttt{microtype} package or a package that itself uses
+\texttt{microtype}, please load it after \texttt{gregoriotex}.  If you load
+\texttt{microtype} before \texttt{gregoriotex}, you may receive an error about
+an ``undefined control sequence'' if you use certain Gregorio\TeX{} features.
 
 \subsection{Commands}
 
@@ -428,6 +434,14 @@ Macro for setting whether the staff lines behind an alternation (\ie, an acciden
 	& \texttt{invisible} & The staff lines behind an alteration should not be printed (\LaTeX\ default)
 \end{argtable}
 
+\macroname{\textbackslash gresetlinesbehinddottedbar}{\{\#1\}}{gregoriotex-signs.tex}
+Macro for setting whether the staff lines behind a dotted bar should be shown or not.
+
+\begin{argtable}
+	\#1 & \texttt{visible} & The staff lines behind a dotted bar should be printed\\
+	& \texttt{invisible} & The staff lines behind a dotted bar should not be printed (default)
+\end{argtable}
+
 
 \subsubsection{Score Font}
 Gregorio\TeX\ currently supports 3 different fonts for the glyphs in a score (neumes, clefs, alterations, \etc): Greciliae (a customized version of Caeciliae by Fr.\ Matthew Spencer, OSJ), Gregorio, and Grana Padano (née Parmesan, developed for Lilypond by Juergen Reuter).
@@ -476,10 +490,9 @@ from the specified font.
 	& string & (any other string) The name of the glyph to use.
 \end{argtable}
 
-\medskip If \texttt{\#1} has a wildcard (a \texttt{*}) in it, then
-\texttt{\#3} must start with a dot and all glyphs matching \texttt{\#1}
-will be replaced with corresponding glyphs whose names have \texttt{\#3}
-appended.
+\medskip If \texttt{\#1} has a wildcard (a \texttt{*}) in it, then \texttt{\#3}
+must be empty or start with a dot, and all glyphs matching \texttt{\#1} will be
+replaced with corresponding glyphs whose names have \texttt{\#3} appended.
 
 \medskip If \texttt{\#2} is \texttt{*}, then the substitution is assumed
 to be available in all score fonts.
@@ -497,6 +510,18 @@ versions, use the following:\par\medskip
 	\grechangeglyph{TorculusResupinus*}{*}{.alt}
 \end{latexcode}
 
+\textbf{Nota Bene:} Because the bar glyphs vary based on number of score lines,
+substituting them is more complicated.  To cover all numbers of score lines,
+you will need to substitute all of the glyphs for the same (like
+\texttt{VirgulaTwo} through \texttt{VirgulaSix} for all available virgula
+glyphs).  For example:
+
+\medskip To replace all "dotted divisio maior" glyphs with their same-named
+variants from the \texttt{gregorio} font, use the following:\par\medskip
+\begin{latexcode}
+	\grechangeglyph{DivisioMaiorDotted*}{gregorio}{}
+\end{latexcode}
+
 \macroname{\textbackslash greresetglyph}{\{\#1\}}{gregoriotex-main.tex}
 Removes a Gregorio\TeX\ score glyph substitution, restoring it back to
 its original form.
diff --git a/Master/texmf-dist/doc/luatex/gregoriotex/Command_Index_gregorio.tex b/Master/texmf-dist/doc/luatex/gregoriotex/Command_Index_gregorio.tex
index 0bd6bcff49d..76276bd7f32 100644
--- a/Master/texmf-dist/doc/luatex/gregoriotex/Command_Index_gregorio.tex
+++ b/Master/texmf-dist/doc/luatex/gregoriotex/Command_Index_gregorio.tex
@@ -260,6 +260,15 @@ Macro to typeset a divisio maior.
 	\#2 & \TeX\ code & Macros which may happen before the skip but after the divisio maior (typically \verb=\grevepisema=).\\
 \end{argtable}
 
+\macroname{\textbackslash GreDivisioMaiorDotted}{\#1\#2}{gregoriotex-signs.tex}
+Macro to typeset a dotted divisio maior.
+
+\begin{argtable}
+	\#1 & \texttt{0} & There is no text under the bar.\\
+	& \texttt{1} & There is text under the bar.\\
+	\#2 & \TeX\ code & Macros which may happen before the skip but after the divisio maior (typically \verb=\grevepisema=).\\
+\end{argtable}
+
 \macroname{\textbackslash GreDivisioMinima}{\#1\#2\#3}{gregoriotex-signs.tex}
 Macro to typeset a divisio minima.
 
@@ -271,6 +280,17 @@ Macro to typeset a divisio minima.
 	& \texttt{1} & The notes around the bar are far, \verb=@short= versions of spaces will be used.\\
 \end{argtable}
 
+\macroname{\textbackslash GreDivisioMinimaHigh}{\#1\#2\#3}{gregoriotex-signs.tex}
+Macro to typeset a divisio minima on the ledger line above the staff.
+
+\begin{argtable}
+	\#1 & \texttt{0} & There is no text under the bar.\\
+	& \texttt{1} & There is text under the bar.\\
+	\#2 & \TeX\ code & Macros which may happen before the skip but after the divisio minima (typically \verb=\grevepisema=).\\
+	\#3 & \texttt{0} & The notes around the bar are vertically close to the bar.\\
+	& \texttt{1} & The notes around the bar are far, \verb=@short= versions of spaces will be used.\\
+\end{argtable}
+
 \macroname{\textbackslash GreDivisioMinor}{\#1\#2}{gregoriotex-signs.tex}
 Macro to typeset a divisio minor.
 
@@ -591,9 +611,15 @@ Same as \verb=\GreDivisioFinalis= except inside a syllable.
 \macroname{\textbackslash GreInDivisioMaior}{\#1\#2}{gregoriotex-signs.tex}
 Same as \verb=\GreDivisioMaior= except inside a syllable.
 
+\macroname{\textbackslash GreInDivisioMaiorDotted}{\#1\#2}{gregoriotex-signs.tex}
+Same as \verb=\GreDivisioMaiorDotted= except inside a syllable.
+
 \macroname{\textbackslash GreInDivisioMinima}{\#1\#2\#3}{gregoriotex-signs.tex}
 Same as \verb=\GreDivisioMinima= except inside a syllable.
 
+\macroname{\textbackslash GreInDivisioMinimaHigh}{\#1\#2\#3}{gregoriotex-signs.tex}
+Same as \verb=\GreDivisioMinimaHigh= except inside a syllable.
+
 \macroname{\textbackslash GreInDivisioMinor}{\#1\#2}{gregoriotex-signs.tex}
 Same as \verb=\GreDivisioMinor= except inside a syllable.
 
@@ -612,6 +638,9 @@ Saves the extrema of the initial clef.
 \macroname{\textbackslash GreInVirgula}{\#1\#2\#3}{gregoriotex-signs.tex}
 Same as \verb=\GreVirgula= except inside a syllable.
 
+\macroname{\textbackslash GreInVirgulaHigh}{\#1\#2\#3}{gregoriotex-signs.tex}
+Same as \verb=\GreVirgulaHigh= except inside a syllable.
+
 \macroname{\textbackslash GreItalic}{\#1}{gregoriotex.sty or gregoriotex.tex}
 Makes argument (a string) italic.  Accesses \LaTeX\ \verb=\textit= or
 Plain \TeX\ \verb=\it= as appropriate.  Corresponds to ``<i></i>'' tags
@@ -1100,6 +1129,17 @@ Macro to typeset a virgula.
 	& \texttt{1} & The notes around the bar are far, \verb=@short= versions of spaces will be used.\\
 \end{argtable}
 
+\macroname{\textbackslash GreVirgulaHigh}{\#1\#2\#3}{gregoriotex-signs.tex}
+Macro to typeset a virgula on the ledger line above the staff.
+
+\begin{argtable}
+	\#1 & \texttt{0} & There is no text under the bar.\\
+	& \texttt{1} & There is text under the bar.\\
+	\#2 & code & Macros which may happen before the skip but after the virgula (typically \verb=\grevepisema=).\\
+	\#3 & \texttt{0} & The notes around the bar are vertically close to the bar.\\
+	& \texttt{1} & The notes around the bar are far, \verb=@short= versions of spaces will be used.\\
+\end{argtable}
+
 \macroname{\textbackslash GreWriteTranslation}{\#1}{gregoriotex-main.tex}
 Macro to typeset argument in the translation position.
 
diff --git a/Master/texmf-dist/doc/luatex/gregoriotex/Command_Index_internal.tex b/Master/texmf-dist/doc/luatex/gregoriotex/Command_Index_internal.tex
index 0b7fc789bae..4025483495d 100644
--- a/Master/texmf-dist/doc/luatex/gregoriotex/Command_Index_internal.tex
+++ b/Master/texmf-dist/doc/luatex/gregoriotex/Command_Index_internal.tex
@@ -837,6 +837,10 @@ Macro to write a bar.
 	& \texttt{3} & major\\
 	& \texttt{4} & finalis\\
 	& \texttt{5} & the last finalis\\
+	& \texttt{6}--\texttt{13} & Dominican bars\\
+	& \texttt{14} & virgula on ledger line above the staff\\
+	& \texttt{15} & minima on ledger line above the staff\\
+	& \texttt{16} & dotted major\\
 	\#2 & \texttt{0} & in a syllable containing only this bar\\
 	& \texttt{1} & in a syllable containing other notes\\
 	\#3 & \texttt{0} & if there is no text underneath the bar\\
@@ -1439,6 +1443,10 @@ Prevents the current syllable from overlapping with the previous syllable.
 			& note & the current syllable is a note syllable.\\
 \end{argtable}
 
+\macroname{\textbackslash gre@read@temp}{}{gregoriotex-main.tex}
+File handle used to mark auto-compiled gabc files as dependencies for tools
+like latexmk.
+
 \subsection{Auxiliary File}
 Gregorio\TeX\ creates its own auxiliary file (extension \texttt{gaux}) which it uses to store information between successive typesetting runs.  This allows for such features as the dynamic interline spacing.  The following functions are used to interact with that auxiliary file.
 
@@ -1594,6 +1602,38 @@ A fused character consisting of a leading quilisma (of ambitus two) and a regula
 \macroname{\textbackslash gre@char@he@...}{\#1}{gregoriotex-chars.tex}
 A class of macros for the horizontal episema which populates the \verb=\gre@box@hep= box.
 
+\macroname{\textbackslash gre@char@bar@virgula}{}{gregoriotex-main.tex}
+Alias that will hold the character for the virgula for the current number of
+lines for the staff.
+
+\macroname{\textbackslash gre@char@bar@virgulahigh}{}{gregoriotex-main.tex}
+Alias that will hold the character for the high virgula for the current number
+of lines for the staff.
+
+\macroname{\textbackslash gre@char@bar@divisiominima}{}{gregoriotex-main.tex}
+Alias that will hold the character for the divisio minima for the current
+number of lines for the staff.
+
+\macroname{\textbackslash gre@char@bar@divisiominimahigh}{}{gregoriotex-main.tex}
+Alias that will hold the character for the high divisio minima for the current
+number of lines for the staff.
+
+\macroname{\textbackslash gre@char@bar@divisiominor}{}{gregoriotex-main.tex}
+Alias that will hold the character for the divisio minor for the current
+number of lines for the staff.
+
+\macroname{\textbackslash gre@char@bar@divisiomaior}{}{gregoriotex-main.tex}
+Alias that will hold the character for the divisio maior for the current
+number of lines for the staff.
+
+\macroname{\textbackslash gre@char@bar@divisiomaiordotted}{}{gregoriotex-main.tex}
+Alias that will hold the character for the dotted divisio maior for the current
+number of lines for the staff.
+
+\macroname{\textbackslash gre@char@bar@divisiomaiordottedbacking}{}{gregoriotex-main.tex}
+Alias that will hold the character for the dotted divisio maior backing for the
+current number of lines for the staff.
+
 \macroname{\textbackslash gre@nabccharno}{\#1\#2\#3}{gregoriotex-nabc.tex}
 Prints the nabc glyphs for the given nabc string.
 
@@ -1645,6 +1685,9 @@ Boolean used to specify whether the staff lines behind a punctum cavum should be
 \macroname{\textbackslash ifgre@hidealtlines}{}{gregoriotex-signs.tex}
 Boolean used to specify whether the staff lines behind an alteration should be hidden.
 
+\macroname{\textbackslash ifgre@hidedottedbarlines}{}{gregoriotex-signs.tex}
+Boolean used to specify whether the staff lines behind a dotted bar should be hidden.
+
 \macroname{\textbackslash ifgre@hepisemabridge}{}{gregoriotex-signs.tex}
 Boolean used to specify whether adjacent horizontal episemata should be joined together.
 
@@ -1709,6 +1752,9 @@ Count to indicate how the clivis is to be aligned with its respective syllable t
 \macroname{\textbackslash gre@insidediscretionary}{}{gregoriotex-signs.tex}
 Macro which indicates whether we are currently inside a discretionary (\texttt{1}) or not (\texttt{0}).  Cannot be converted to a \TeX\ boolean because it’s value needs to be passed to Lua.
 
+\macroname{\textbackslash ifgre@in@custos}{}{gregoriotex-signs.tex}
+Boolean which indicates whether typesetting is currently in the context of a custos.
+
 \macroname{\textbackslash ifgre@isonaline}{}{gregoriotex-syllable.tex}
 Boolean which indicates whether the current note is on a line or not (used to adjust the height of some symbols so they won’t print on a line).
 
diff --git a/Master/texmf-dist/doc/luatex/gregoriotex/Gabc.tex b/Master/texmf-dist/doc/luatex/gregoriotex/Gabc.tex
index 0054aa102b6..f2fcda232cb 100644
--- a/Master/texmf-dist/doc/luatex/gregoriotex/Gabc.tex
+++ b/Master/texmf-dist/doc/luatex/gregoriotex/Gabc.tex
@@ -38,20 +38,33 @@ Files written in gabc have the extension \texttt{.gabc} and have the
 following structure:
 
 \begin{lstlisting}[autogobble]
-name: incipit;
-gabc-copyright: copyright on this gabc file;
-score-copyright: copyright on the source score;
-author: if known;
-language: latin;
-mode: 6;
-mode-modifier: t.;
-annotation: IN.;
-annotation: 6;
-%%
-(clef) text(notes)
+	name: incipit;
+	gabc-copyright: copyright on this gabc file;
+	score-copyright: copyright on the source score;
+	author: if known; % maybe some additional comment
+	language: latin;
+	mode: 6;
+	mode-modifier: t.;
+	annotation: IN.;
+	annotation: 6;
+	
+	%%
+	
+	(clef) text(notes)
+	% another comment
+	com(notes)plex(notes) word(notes)
 \end{lstlisting}
 
-\subsection{Headers}
+The file above is separated into two sections by the \texttt{\%\%} (line 11).  The first section is the header section and contains, appropriately enough, the headers which are used to contain metadata about the score.  These are discussed in more detail in \nameref{headers}.  The second section is the notation section, where the score itself is represented.  The section consists of syllable text and notes.  Notes are contained within the parentheses, and the syllable text is outside.  The syntax for syllable text is discussed in \nameref{textsyntax}.  The syntax for notes is discussed in \nameref{notesyntax}.
+
+Spaces in the notation section are significant, and the end of lines in the
+gabc file are considered spaces.
+
+A \texttt{\%} character marks the beginning of a comment which ends at the end
+of the line.  A comment also suppresses the end-of-line space.  Comments may appear within either section of the document and can either be at the end of a line with non-comment material (as in line 4 above) or on their own line (line 14).
+
+
+\subsection{Headers}\label{headers}
 
 The headers, such as \texttt{name: incipit;}, above, each have a name
 before the colon and a value, between the colon and the semicolon.  The
@@ -79,7 +92,7 @@ Some headers have special meaning to Gregorio:
 \item[author] The author of the piece, if known; of course, the author of most traditional chant is not known.
 \item[language] The language of the lyrics.
 \item[oriscus-orientation] If \texttt{legacy}, the orientation of an unconnected oriscus must be set manually.
-\item[mode] The mode of the piece. This should normally be an arabic
+\item[mode] The mode of the piece. This should normally be an Arabic
 	number between 1 and 8, but may be any text required for unusual
 	cases. The mode number will be converted to roman numerals and
 	placed above the initial unless one of the following conditions are
@@ -113,12 +126,20 @@ Some headers have special meaning to Gregorio:
 	If the user already defined annotation(s) in the main \TeX\ file via
 	\verb=\greannotation= then the \texttt{annotation} header field will not
 	overwrite that definition.
+\item[staff-lines] The number of lines in the staff.
+\item[nabc-lines] The number of NABC lines in the staff; currently only 1 NABC
+	line is supported.
+\item[oriscus-orientation] If set to \texttt{legacy}, Gregorio will use the
+	older oriscus orientation semantics.  Leave the header out to use the
+	default oriscus orientation semantics.
+\item[def-m\textit{n}] Defines \TeX\ code to be used for the given numbered
+	macro (from 0--9).  See \nameref{defmacros}.
 \end{description}
 
-Although gregorio ascribes no special meaning to them, other suggested headers are:
+Although Gregorio ascribes no special meaning to them, other suggested headers are:
 
 \begin{description}
-\item[office-part] The office-part is the category of chant (in Latin), according to its liturgical rôle. Examples are: antiphona, hymnus, responsorium brevium, responsorium prolixum, introitus, graduale, tractus, offertorium, communio, kyrie, gloria, credo, sanctus, benedictus, agnus dei.
+\item[office-part] The office-part is the category of chant (in Latin), according to its liturgical role. Examples are: antiphona, hymnus, responsorium brevium, responsorium prolixum, introitus, graduale, tractus, offertorium, communio, kyrie, gloria, credo, sanctus, benedictus, agnus dei.
 \item[occasion] The occasion is the liturgical occasion, in Latin. For example, Dominica II Adventus, Commune doctorum, Feria secunda.
 \item[meter] For hymns and anything else with repetitive stanzas, the meter, the numbers of syllables in each line of a stanza. For example, 8.8.8.8 for typical Ambrosian-style hymns: 4 lines each of 8 syllables.
 \item[commentary] This is intended for notes about the source of the text, such as references to the Bible.
@@ -182,22 +203,366 @@ Some examples:
 	{\scriptsize\verb=t. irregularis=} & & & \writemode{t. irregularis}{}{} \\
 \end{tabularx}
 
-\subsection{General Syntax}
+\subsubsection{Defining Macros}\label{defmacros}
 
-\subsection{Note Syntax}
+When you want to do something special in the course of processing several syllables then you should define a macro which contains the instructions for what to do.  In this fashion, you do not have to insert the full set of instructions each time.  A basic macro definition looks like this:
 
-\verb=[nocustos]= will prevent a custos from appearing at the point where
-specified, if line formatting causes a line break there.  The \verb=[nocustos]=
-tag must appear \emph{before} spaces appearing at the point specified or it will
-have no effect.
+\begin{lstlisting}[autogobble]
+	def-m0: \mymacro;
+\end{lstlisting}
+
+You would then need to define \verb=\mymacro= in your \TeX\ file.  We recommend using this structure whenever possible because it makes sharing and reusing a score much easier.  If a later project doesn’t require the use of \verb=\mymacro=, then it’s relatively trivial to change the definition in the \TeX\ file for that project to an empty macro.
+
+However, it is also possible to have longer macro definitions directly in the gabc file.  In this case you probably want to make use of the multi-line header possibilities to make the macro more readable.  For instance, the following two macros would allow the toggling on or off of the automatic custos behavior in the middle of the score.
+
+\begin{lstlisting}[autogobble]
+	def-m1: \makeatletter
+	\gre@usemanualcustos
+	\makeatother;;
+	def-m2: \makeatletter
+	\gre@useautocustos
+	\makeatother;;
+\end{lstlisting}
+
+Macros are used inside the notes portion of the notation section.  See \nameref{usemacros}.
+
+\subsection{Notation --- Lyrics Notation}
+
+As a reminder, the notation section consists of lines which look like this:
+
+\begin{lstlisting}[autogobble]
+	(clef) text(notes)
+	com(notes)plex(notes) word(notes)
+\end{lstlisting}
+
+We’ll start by discussing the syllable text syntax (which appears outside the parentheses) and then discus the note syntax (see \nameref{notesyntax}).
+
+\subsubsection{Syllable Text Syntax}\label{textsyntax}
+
+Text outside parenthesis is considered syllable text.  In general, this is the
+text that appears below the staff.  Parenthesized note sections separate
+syllables.  Spaces (end end-of-lines) in syllable text mark the end of words
+and should be placed after the parenthesized notes section for the last
+syllable of a given word.
+
+There are several markup-like codes that may be inserted into syllable text.  We divide these into three categories: style tags, syllable controls, and other.
+
+\paragraph{Style Tags}
+These tags are used to apply basic styling to the syllable text and are very similar to html markup.
+
+\begin{description}
+	\item[bold] Text between \texttt{<b>} and \texttt{</b>} will be typeset in
+		boldface if supported by the font.
+	\item[colored] Text between \texttt{<c>} and \texttt{</c>} will be colored
+		using the \texttt{gregoriocolor} color.
+	\item[italics] Text between \texttt{<i>} and \texttt{</i>} will be typeset
+		in italics if supported by the font.
+	\item[small capitals] Text between \texttt{<sc>} and \texttt{</sc>} will be
+		typeset with small capitals if supported by the font.
+	\item[teletype] Text between \texttt{<tt>} and \texttt{</tt>} will be
+		typeset as teletype (typically monospaced).
+	\item[underlined] Text between \texttt{<ul>} and \texttt{</ul>} will be
+		underlined.
+\end{description}
+
+\paragraph{Syllable Controls}
+These tags are used to control the interaction between the syllable in which they appear and either the surrounding syllables or the line breaks.
+
+\begin{description}
+	\item[clear] The \texttt{<clear>} or \texttt{<clear/>} marker indicates that
+		the given syllable may not extend into the notation of the previous
+		syllable.
+	\item[elision] Text between \texttt{<e>} and \texttt{</e>} will be
+		considered an elision (by default typeset in italics), with special
+		consideration given when placing the syllable under the notes above.
+	\item[Euouae] Text between \texttt{<eu>} and \texttt{</eu>} is considered
+		``Euouae'' (\textit{s\ae{}culorem, Amen} of the lesser doxology) for
+		marking tone \textit{differentia}, with special typographic consideration
+		for line breaks.
+	\item[no line break] Text between \texttt{<nlba>} and \texttt{</nlba>} is a
+		``no line break area,'' and line breaks in the output will be
+		suppressed here.
+	\item[protrusion] Text after \texttt{<pr>} or \texttt{<pr/>} in a syllable
+		is considered a protrusion and may push into the margin.  Optionally, the
+		\texttt{pr} may be followed by a colon and a number between 0 (text may
+		not protrude) and 1 (text may protrude in its entirety) indicating how
+		much of the marked text is allowed to push into the margin.  For example:
+		\texttt{<pr:.5>}
+\end{description}
+
+\paragraph{Other}
+These tags allow for a variety of special effects.
+
+\begin{description}
+	\item[above lines text] Text between \texttt{<alt>} and \texttt{</alt>} is
+		``above lines text'' and will be typeset above the staff lines.
+	\item[special character] Text between \texttt{<sp>} and \texttt{</sp>} is a
+		``special character,'' as defined by \texttt{\textbackslash
+		gresetspecial}.  There are also several special characters defined by default
+		(see	\nameref{specialcharacters} below).
+	\item[verbatim] Text between \texttt{<v>} and \texttt{</v>} is passed
+		directly to \TeX, without preprocessing as gabc text.
+\end{description}
+
+Additionally, besides parentheses, there are a few other special characters in
+the syllable text.  Curly braces (\texttt{\{} and \texttt{\}}) are for
+\nameref{lyriccentering}.  Square brackets (\texttt{[} and \texttt{]}) are for
+\nameref{translationtext} that appears below the lyric text.  See immediately
+below for more information.
+
+\subsubsection{Lyric Centering}\label{lyriccentering}
+
+Gregorio centers the text of each syllable around the first note of each
+syllable.  There are three basic modes, selected with the command \verb=\gresetlyriccentering{<mode>}=:
+
+\begin{description}
+\item[syllable] the entire syllable is centered around the first note
+\item[firstletter] the first letter of the syllable is centered around the first note
+\item[vowel] the vowel sound of the syllable is centered around the first note
+\end{description}
+
+The default is \texttt{vowel}, being common in most Gregorian chant
+books with text in Latin.  The definition of how Gregorio\TeX{} interprets
+vowels is described in \nameref{voweldetection}, below.
+
+All modes allow you to force the centering with curly brackets,
+for example \verb=a{b}c= will center the notes around \texttt{b}.
+
+\subsubsection{Translation Text}\label{translationtext}
+
+Translation text, enclosed in square brackets (\texttt{[} and \texttt{]}),
+appears below the lyric text (by default) in italics.  It is aligned to the
+syllable where it appears in the gabc file unless the special sequence
+\texttt{[/]} appears in a later syllable indicating that the translation text
+should be centered between those two points.
+
+\subsubsection{Special Characters}\label{specialcharacters}
+
+Special characters are specified between \texttt{<sp>} and \texttt{</sp>}.
+They may be defined in the \TeX{} file using the \verb=\gresetspecial= command
+and undefined using the \verb=\greunsetspecial= command.  The following
+special characters are defined by default:
+
+\rowcolors{1}{lightgray}{lightgray}
+\begin{tabularx}{\textwidth}{c|X}
+	\textbf{Sequence} & \textbf{Description}\\
+	\hline
+	\texttt{ae} & The \ae{} ligature.\\
+	\texttt{oe} & The \oe{} ligature.\\
+	\texttt{\textquotesingle{}ae}  & An accented \ae{} (\'\ae).\\
+	\texttt{\textquotesingle{}oe}  & An accented \oe{} (\'\oe).\\
+	\texttt{\textquotesingle{}æ}   & An accented \ae{} (\'\ae).\\
+	\texttt{\textquotesingle{}œ}   & An accented \oe{} (\'\oe).\\
+	\texttt{A/} & A with a bar (\Abar), typically used to signify the
+								antiphon.\\
+	\texttt{R/} & R with a bar (\Rbar), typically used to signify the refrain
+								or response.\\
+	\texttt{V/} & V with a bar (\Vbar), typically used to signify the verse.\\
+	\texttt{*}  & The character produced by \verb=\GreStar= (\GreStar).\\
+	\texttt{+}  & The character produced by \verb=\GreDagger= (\GreDagger).\\
+	\texttt{-}  & A zero-width hyphen.\\
+	\texttt{\textbackslash} & A backslash, avoiding \TeX{} interpretation.\\
+	\texttt{\&} & An ampersand, avoiding \TeX{} interpretation.\\
+	\texttt{\#} & A hash mark, avoiding \TeX{} interpretation.\\
+	\texttt{\_} & An underscore, avoiding \TeX{} interpretation.\\
+	\texttt{\textasciitilde} & A centered tilde (a ``math'' tilde, \gretilde).\\
+\end{tabularx}
+
+Note that barred letters may be redefined by the \verb=\gredefbarredsymbol=
+and \verb=\gresimpledefbarredsymbol= commands.
+
+\subsubsection{Vowel Detection}\label{voweldetection}
+
+The default rules built into Gregorio for \texttt{vowel} mode are for
+Ecclesiastical Latin and work fairly well (though not perfectly) for
+other languages (especially Romance languages).  However, Gregorio
+provides a gabc \texttt{language} header which allows the language of
+the lyrics to be set. The default is Latin.
+
+Special characters (input with \texttt{<sp>}) or verbatim text (\texttt{<v>})
+count as consonants, so you have to force centering around them, for example
+\verb=gr{<sp>'ae</sp>}=. If an elision (input with \texttt{<e>}) is present in
+the syllable, Gregorio will consider it as consonant too.
+
+If no vowel is found, the notes are centered around the whole syllable.
+
+If you are using a language for which built-in language rules do not exist and the fallbacks are insufficient, then you may wish to provide your own set of vowel detection rules.  This can be done with a special file:\verb=gregorio-vowels.dat=.  See \nameref{customvowels} for information about how to create and use this file.
+
+
+\subsection{Notation --- Note Syntax}\label{notesyntax}
+
+In the notation section of the gabc file, notes and other figures that appear
+on the staff are specified within parentheses.
+
+\subsubsection{Pitches}
+
+Pitches are represented by a single letter from \texttt{a}--\texttt{n} and
+\texttt{p}.  Each letter represents the typographical position of the pitch
+regardless of the position of the clef (\ie, \textbf{not} the musical position
+of the pitch relative to the clef).  The letters available depend on the
+number of staff lines (set by the \texttt{staff-lines} header): three pitches
+are allowed above the top staff line.  This means that a two-line staff
+supports \texttt{a}--\texttt{i}:
+
+{
+	\gresetinitiallines{0}\gresetlyriccentering{firstletter}%
+	\gresetclef{invisible}\gresetlastline{justified}%
+	\ttfamily
+	\gregorioscore[a]{pitches2}
+}
+
+A three-line staff supports \texttt{a}--\texttt{k}:
+
+{
+	\gresetinitiallines{0}\gresetlyriccentering{firstletter}%
+	\gresetclef{invisible}\gresetlastline{justified}%
+	\ttfamily
+	\gregorioscore[a]{pitches3}
+}
+
+A four-line staff (the default) supports \texttt{a}-\texttt{m}:
+
+{
+	\gresetinitiallines{0}\gresetlyriccentering{firstletter}%
+	\gresetclef{invisible}\gresetlastline{justified}%
+	\ttfamily
+	\gregorioscore[a]{pitches4}
+}
+
+A five-line staff supports \texttt{a}-\texttt{n} and \texttt{p}.
+
+{
+	\gresetinitiallines{0}\gresetlyriccentering{firstletter}%
+	\gresetclef{invisible}\gresetlastline{justified}%
+	\ttfamily
+	\gregorioscore[a]{pitches5}
+}
+
+\subsubsection{One-Note Neumes}
+
+A lower-case pitch letter represents a \textit{punctum quadratum}, a square
+note.  A capitalized pitch letter represents a \textit{punctum inclinatum}, a
+diamond-shaped note.  Other shapes are created by appending various characters
+to the pitch letter.  These characters may be used together, and
+Gregorio\TeX{} will try to typeset them together.
+
+Things like flats, sharps, and naturals, while not technically notes, are
+treated as one-note neumes by Gregorio\TeX.  Thus, they are also added by
+appending characters to pitch letters.
+
+\begin{tabularx}{\textwidth}{l|X}
+	Gabc & Description \\
+	\hline
+	\pitchchar & punctum quadratum \\
+	\Pitchchar{} & punctum inclinatum (automatic leaning based on surrounding
+								 pitches) \\
+	\Pitchchar0 & left-leaning punctum inclinatum \\
+	\Pitchchar1 & right-leaning punctum inclinatum \\
+	\pitchchar\texttt{o} & oriscus \\
+	\pitchchar\texttt{w} & quilisma \\
+	\pitchchar\texttt{v} & virga (stem on right) \\
+	\pitchchar\texttt{V} & virga reversa (stem on left) \\
+	\pitchchar\texttt{s} & stropha \\
+	\pitchchar\texttt{\textasciitilde} & liquescent deminutus (small note) \\
+	\pitchchar\texttt{<} & augmented liquescent \\
+	\pitchchar\texttt{>} & diminished liquescent \\
+	\pitchchar\texttt{=} & linea \\
+	\pitchchar\texttt{r} & cavum (hollow note) \\
+	\pitchchar\texttt{R} & punctum quadratum surrounded by lines \\
+	\pitchchar\texttt{r0} & punctum cavum surrounded by lines \\
+	\pitchchar\texttt{x} & flat \\
+	\pitchchar\texttt{\#} & sharp \\
+	\pitchchar\texttt{y} & natural \\
+\end{tabularx}
+
+In the above table, \pitchchar{} represents a pitch character and
+\Pitchchar{} represents a capitalized pitch character.
+
+Some examples:
+
+{
+	\gresetinitiallines{0}\gresetlyriccentering{firstletter}%
+	\gresetclef{invisible}\gresetlastline{justified}\greseteolcustos{manual}%
+	\gabcsnippet{
+		( )
+		g(g) g<sp>~~</sp>(g~) g<(g<) g>(g>) go(go) go<sp>~~</sp>(go~) gw(gw)
+		gv(gv) gV(gV) gs(gs) gs<(gs<) g=(g=)
+		( ) (z) ( )
+		gr(gr) gR(gR) gr0(gr0) G(G) G0(G0) G1(G1) G~(G~) G>(G>) Gr(Gr) gx(gx)
+		g#(g#) gy(gy)
+		( )
+	}
+}
+
+\subsubsection{Oriscus Orientation}
+
+Under the default rules for oriscus orientation, the direction of an oriscus
+(pointing upwards or downwards) depends on whether the first non-unison note
+that follows is higher or lower than the oriscus.  However, if Gregorio\TeX{}
+does not produce the desired oriscus, the direction may be explicitly selected
+using \texttt{o0} or \texttt{O0} for a downwards-pointing oriscus and
+\texttt{o1} or \texttt{O1} for an upwards-pointing oriscus.
+
+The \texttt{legacy} rules for oriscus orientation are deprecated and only
+remain for backwards compatibility with older gabc files that depend on their
+quirks.  They will not be discussed here.
+
+\subsubsection{Complex Neumes}
+
+Neumes with more than one note are simply made by chaining notes together
+without worrying about the connections between them.  In addition to the
+characters for one-note neumes, some more characters are available to adjust
+the shape.
 
-\subsection{Neume Fusion}
+\begin{tabularx}{\textwidth}{l|X}
+	Gabc & Description \\
+	\hline
+	\texttt{-}\pitchchar & (prior to the pitch it modifies) initio debilis \\
+	\pitchchar\texttt{O} & oriscus scapus (an oriscus with stems that connect
+							 to the note prior to it) \\
+	\pitchchar\texttt{q} & quadratum (for making a "square" pes shape; see
+							 example below) \\
+	\pitchchar\texttt{W} & quilisma quadratum (similarly, for making a "square"
+							 quilisma shape) \\
+	\pitchchar\texttt{ss} & distropha \\
+	\pitchchar\texttt{sss} & tristropha \\
+	\pitchchar\texttt{vv} & bivirga \\
+	\pitchchar\texttt{vvv} & trivirga \\
+\end{tabularx}
+
+In the above table, \pitchchar{} represents a pitch character.
+
+Some examples:
+
+{
+	\gresetinitiallines{0}\gresetlyriccentering{firstletter}%
+	\gresetclef{invisible}\gresetlastline{justified}%
+	\ttfamily
+	\gabcsnippet{( )
+		egoi(egoi) egOi(egOi)
+		gi(gi) gqi(gqi)
+		gwi(gwi) gWi(gWi) (z)
+		( ) gss(gss) gsss>(gsss>)
+		gvv(gvv) gvvv(gvvv)
+		gfh(gfh) <v>-</v>dge(-dge)
+		grfge<(grfge<) fgeh(fgeh)
+		<v>-</v>fgehf>(-fgehf>) ( )
+	}
+}
+
+Sometimes Gregorio\TeX{} will incorrectly guess the shape.  In this case, a
+space (see \nameref{neumespacing} below) may be needed to get the
+desired shape.
 
-Neume fusion allows for the composition of new shapes based on a set of
-primitive neumes.  These primitives are:
+\subsubsection{Neume Fusion}
+
+Sometimes, especially with longer neumes, Gregorio\TeX{} will not form the
+desired shape.  In this case, there is neume fusion.  Neume fusion allows for
+the composition of new shapes based on a set of primitive neumes.  These
+primitives are:
 
 \begin{tabularx}{\textwidth}{l|l|X}
-	Gabc & Description & Rules \\
+	Primitive & Description & Rules \\
 	\hline
 	\texttt{g} & punctum & fuses from higher or lower notes, and can fuse to higher or lower notes \\
 	\texttt{go} & oriscus & may only fuse in the direction it was fused from \\
@@ -209,9 +574,12 @@ primitive neumes.  These primitives are:
 	\texttt{gfg} & porrectus & at the end only, previous note must be lower to fuse \\
 \end{tabularx}
 
+In the above table, \texttt{f}, \texttt{g}, and \texttt{h} are representative
+pitch characters, considered by pitch relation.
+
 Placing the \texttt{@} character between two notes will attempt to use the above
-rules to fuse the notes together.  If a shape that is not fusable is used,
-Gregorio will typically fall back on the non-fusable form, but in some cases
+rules to fuse the notes together.  If a shape that is not fusible is used,
+Gregorio will typically fall back on the non-fusible form, but in some cases
 will result in a syntax error.
 
 Placing the \texttt{@} character before a primitive that would get a stem will
@@ -220,30 +588,295 @@ and the porrectus.
 
 Here are some examples of fusion:
 
-\gresetinitiallines{0}\gresetlyriccentering{firstletter}%
-\gabcsnippet{
-(c3) h@iw@ji@j@ih<sp>~</sp>(h@iw@ji@j@ih~)
-(;) d@eo@fd(d@eo@fd)
-(;) IJ@kh(IJ@kh)
+{
+	\gresetinitiallines{0}\gresetlyriccentering{firstletter}%
+	\gresetclef{invisible}\gresetlastline{justified}%
+	\ttfamily
+	\gabcsnippet{
+		( )
+		h@iw@ji@j@ih<sp>~~</sp>(h@iw@ji@j@ih~)
+		d@eo@fd(d@eo@fd)
+		IJ@kh(IJ@kh)
+		( )
+	}
 }
 
 As a convenience, a sequence of notes enclosed within \texttt{@[} and
 \texttt{]} will be fused automatically based on an algorithm that breaks up
 the notes into the above primitives.  Using the same examples as before:
 
-\gabcsnippet{
-(c3) @<v>[</v>hiwjijih<sp>~</sp><v>]</v>(@[hiwjijih~])
-(;) @<v>[</v>deofd<v>]</v>(@[deofd])
-(;) @<v>[</v>IJkh<v>]</v>(@[IJkh])
+{
+	\gresetinitiallines{0}\gresetlyriccentering{firstletter}%
+	\gresetclef{invisible}\gresetlastline{justified}%
+	\ttfamily
+	\gabcsnippet{
+		( )
+		@<v>[</v>hiwjijih<sp>~~</sp><v>]</v>(@[hiwjijih~])
+		@<v>[</v>deofd<v>]</v>(@[deofd])
+		@<v>[</v>IJkh<v>]</v>(@[IJkh])
+		( )
+	}
+}
+
+\subsubsection{Neume Spacing}\label{neumespacing}
+
+For musical phrases that consist of multiple neumes, various spaces may be
+added to the notes.
+
+\begin{tabularx}{\textwidth}{l|X}
+	Gabc & Description \\
+	\hline
+	\texttt{/0} & a half space that is considered part of the same neume \\
+	\texttt{/!} & an small separation that is considered part of the same neume \\
+	\texttt{/} & a small separation between neumes \\
+	\texttt{//} & a medium separation between neumes \\
+	\textit{space} & a large separation between neumes \\
+	\texttt{/[}\textit{factor}\texttt{]} & a space with the size the large
+							 separation scaled by the given \textit{factor} (which may be
+							 negative, resulting in a backspace) \\
+	\texttt{!} & if alone, a zero-width space used when Gregorio\TeX{} does not
+							 break the chain of notes in the correct place; if followed by a
+							 space, makes the space that follows a non-breaking space \\
+\end{tabularx}
+
+\subsubsection{Additional Symbols}
+
+Puncta mora, episemata, and other symbols may also be added to a note by
+adding various other characters.  As with note shapes, these may also be
+used together.
+
+\begin{tabularx}{\textwidth}{l|X}
+	Gabc & Description \\
+	\hline
+	\pitchchar\texttt{.} & punctum mora \\
+	\pitchchar\texttt{\textunderscore} & horizontal episema (see
+														 \nameref{horizontalepisemata} below)\\
+	\pitchchar\texttt{\textquotesingle} & vertical episema / ictus (automatic placement) \\
+	\pitchchar\texttt{\textquotesingle0} & vertical episema / ictus below the note \\
+	\pitchchar\texttt{\textquotesingle1} & vertical episema / ictus above the note \\
+	\pitchchar\texttt{r1} & accent above staff \\
+	\pitchchar\texttt{r2} & accent grave above staff \\
+	\pitchchar\texttt{r3} & circle above staff \\
+	\pitchchar\texttt{r4} & lower semicircle above staff \\
+	\pitchchar\texttt{r5} & upper semicircle above staff \\
+	\pitchchar\texttt{r6} & musica ficta flat \\
+	\pitchchar\texttt{r7} & musica ficta natural \\
+	\pitchchar\texttt{r8} & musica ficta sharp \\
+\end{tabularx}
+
+In the above table, \pitchchar{} represents a pitch character.
+
+Some examples:
+
+{
+	\gresetinitiallines{0}\gresetlyriccentering{firstletter}%
+	\gresetclef{invisible}\gresetlastline{justified}%
+	\ttfamily
+	\gabcsnippet{
+		g.(g.) g_(g_) g<v>\textquotesingle</v>(g') g<v>\textquotesingle</v>1(g'1)
+		gr1(gr1) gr2(gr2) gr3(gr3) gr4(gr4) gr5(gr5) gr6(gr6) gr7(gr7) gr8(gr8)
+		G<v>\textquotesingle</v>_.r3(G'_.r3) gv_r7(gv_r7)
+	}
+}
+
+\subsubsection{Rhythmic signs}
+
+\paragraph{\textit{Punctum Mora}}
+
+The \textit{punctum mora} (dots after the note) are denoted by adding a period ( \texttt{.} ) after the note. When there are two \textit{punctum mora} after a neume, the character is simply doubled: ( \texttt{..} ).  You cannot place more than two \textit{punctum mora} after a note.
+
+{
+	\gresetinitiallines{0}\gresetlyriccentering{firstletter}%
+	\gresetclef{invisible}\gresetlastline{justified}%
+	\ttfamily
+	\gabcsnippet{( ) g.(g.) h.(h.) g..(g..) ( )}
+}
+
+\paragraph{\textit{Ictus}}
+
+The \textit{ictus} (also called the vertical \textit{episema}) is denoted by an apostrophe ( \verb='= ) after the note. Gregorio will place the episema above or below the note according to the context, however you can force its position with \verb='0= (for always below) and \verb='1= (for always above).
+
+Of course, the \textit{ictus} can be present more than once in a neume, but only once per note.
+
+{
+	\gresetinitiallines{0}\gresetlyriccentering{firstletter}%
+	\gresetclef{invisible}\gresetlastline{justified}%
+	\ttfamily
+	\gabcsnippet{( ) g<v>\textquotesingle</v>(g') dh<v>\textquotesingle</v>(dh') g<v>\textquotesingle</v>1(g'1) dh<v>\textquotesingle</v>0(dh'0) ( )}
+}
+\paragraph{Horizontal Episemata}\label{horizontalepisemata}
+
+For the horizontal \textit{episema}, type an underscore ( \verb=_= ) after every note that is under an \texttt{episema}.  A horizontal \texttt{episema} may be adjusted with the addition of numbers.  Multiple numbers may be added to combine their effects.
+
+\begin{tabularx}{\textwidth}{l|X}
+	Gabc & Description \\
+	\hline
+	\texttt{0} & place the \texttt{episema} below the note \\
+	\texttt{1} & place the \texttt{episema} above the note \\
+	\texttt{2} & disable bridging the \texttt{episema} with the following \texttt{episema} \\
+	\texttt{3} & use a small \texttt{episema}, aligned left \\
+	\texttt{4} & use a small \texttt{episema}, aligned center \\
+	\texttt{5} & use a small \texttt{episema}, aligned right \\
+\end{tabularx}
+
+To demonstrate:
+
+{
+	\gresetinitiallines{0}\gresetlyriccentering{firstletter}%
+	\gresetclef{invisible}\gresetlastline{justified}%
+	\ttfamily
+	\gabcsnippet{
+		( )
+		g_(g_) g_0(g_0) d_hd(d_hd) d_1hd(d_1hd) (:?)
+		H_g_(H_g_) H_2g_(H_2g_) g_/g_(g_/g_) g_2/g_(g_2/g_) (z)
+		( ) g_3(g_3) g_4(g_4) g_0_4(g_0_4)  g_5(g_5) H_502g_0(H_502g_0)
+		( )
+	}
+}
+
+Additional tuning is possible.  See \nameref{horizontalepisematuning} below.
+
+\subsubsection{Separation Bars}
+
+Bars separate sections of the chant.
+
+\begin{tabularx}{\textwidth}{l|X}
+	Gabc & Description \\
+	\hline
+	\texttt{`} & virgula \\
+	\texttt{`0} & virgula on the ledger line above the staff \\
+	\texttt{,} & divisio minima (quarter bar) \\
+	\texttt{,0} & divisio minima on the ledger line above the staff \\
+	\texttt{;} & divisio minor (half bar) \\
+	\texttt{:} & divisio maior (full bar) \\
+	\texttt{:?} & dotted divisio maior \\
+	\texttt{::} & divisio finalis \\
+	\texttt{;}\textit{n} & Dominican bar, where \textit{n} is the position, from
+												 1--8; depending on the number of staff lines, some
+												 Dominican bars will not be available. \\
+\end{tabularx}
+
+Bars can also take the following characters for additional symbols:
+
+\begin{tabularx}{\textwidth}{l|X}
+	Gabc & Description \\
+	\hline
+	\texttt{\textquotesingle} & vertical episema \\
+	\texttt{\_} & bar brace \\
+\end{tabularx}
+
+Some examples:
+
+{
+	\gresetinitiallines{0}\gresetlyriccentering{firstletter}%
+	\gresetclef{invisible}\gresetlastline{justified}%
+	\ttfamily
+	\gabcsnippet{
+		( )
+		`(`) `0(`0) ,(,) ,0(,0) ;(;) :(:) :?(:?) ::(::)
+		;1(;1) ;2(;2) ;3(;3) ;4(;4) ;5(;5) ;6(;6)
+		:<v>\textquotesingle</v>(:') ,_(,_)
+		(// //)
+	}
 }
 
-\subsection{Stem length for the bottom lines}
+\subsubsection{Clefs}
+
+The syntax for a clef is a letter corresponding to the clef symbol, \texttt{c}
+or \texttt{f}, followed optionally by \texttt{b} if the clef should have a
+flat, followed by a number from \texttt{1} up to the number of staff lines
+indicating the line on which the clef is typeset.
+
+Two clefs may be typeset at the same time by linking the two clefs with a
+\texttt{@}.  The two clefs will be typeset in such a way that they don't
+collide with each other.
+
+{
+	\gresetinitiallines{0}\gresetlyriccentering{firstletter}%
+	\gresetclef{invisible}\gresetlastline{justified}%
+	\ttfamily
+	\gabcsnippet{
+		( )
+		c1(c1) ( ) c2(c2) ( ) c3(c3) ( ) c4(c4) ( )
+		f3(f3) ( ) f4(f4) ( )
+		cb3(cb3) ( )
+		c1@c4(c1@c4) ( ) f3@f4(f3@f4)
+		( )
+	}
+}
+
+\subsubsection{Custos}
+
+Gregorio\TeX{} typesets the custos automatically by default.  This may be
+switched off using the \verb=\greseteolcustos= command.  Additionally, a
+custos whose pitch depends on the note that follows may be typeset anywhere by
+entering \texttt{z0} or at any pitch by entering a \texttt{+} after the
+desired pitch character (\eg, \texttt{g+} for a custos at the \texttt{g}
+pitch).
+
+\verb=[nocustos]= will prevent a custos from appearing at the point where
+specified, if line formatting causes a line break there.  The \verb=[nocustos]=
+tag must appear \emph{before} spaces appearing at the point specified or it will
+have no effect.
+
+\subsubsection{Line Breaks}
+
+Gabc has a few codes to control line breaks.
+
+\begin{tabularx}{\textwidth}{l|X}
+	Gabc & Description \\
+	\hline
+	\texttt{z} & insert a justified line break whose custos depends on the
+							 \verb=\greseteolcustos= configuration \\
+	\texttt{z+} & insert a justified line break with a forced automatic custos \\
+	\texttt{z-} & insert a justified line break without a custos \\
+	\texttt{Z} & insert a ragged line break whose custos depends on the
+							 \verb=\greseteolcustos= configuration \\
+	\texttt{Z+} & insert a ragged line break with a forced automatic custos \\
+	\texttt{Z-} & insert a ragged line break without a custos \\
+	\texttt{<nlba>} & mark the beginning of a set of neumes where no line breaks
+										are allowed \\
+	\texttt{</nlba>} & mark the end of a set of neumes where no line breaks are
+										 allowed \\
+\end{tabularx}
+
+\subsubsection{Choral Signs}
+
+Choral signs (text near the note in the staff) may be typeset by using
+\texttt{[cs:}\textit{choral sign text}\texttt{]}.
+
+An NABC choral sign may be typeset by using
+\texttt{[cn:}\textit{nabc neume code}\texttt{]}.
+
+\subsubsection{Braces}
+
+To typeset a brace, use
+\texttt{[}\textit{type}\texttt{:}\textit{n}\texttt{;}\textit{size}\texttt{]}
+after some neume.  The \textit{type} may be \texttt{ob} for a round brace
+above the staff, \texttt{ub} for a round brace below the staff, \texttt{ocb}
+for a curly brace above the staff, or \texttt{ocba} for a curly brace with
+accent above the staff.  If \textit{n} is \texttt{0}, the brace will begin at
+the end of the neume.  If \textit{n} is \texttt{1}, the brace will begin at
+the start of the neume.  The \textit{size} should be a \TeX{} size unit.
+
+Alternately, use
+\texttt{[}\textit{type}\texttt{:}\textit{n}\texttt{\{]} followed by
+\texttt{[}\textit{type}\texttt{:}\textit{n}\texttt{\}]} after some later
+neume.  The \textit{type} and \textit{n} are as above, but this form typesets
+a brace with the endpoints thus defined.
+
+\subsubsection{Stem length for the bottom lines}
 
 Gregorio will determine the length of the stem for most neumes.
 Some manual input might be needed for notes on the bottom staff
 line (\textit{d}). Most of the time they will take a short form:
 
-\gabcsnippet{(c3) dv(dv) ed(ed) ed~(ed~) dcd(dcd)}
+{
+	\gresetinitiallines{0}\gresetlyriccentering{firstletter}%
+	\gresetclef{invisible}\gresetlastline{justified}%
+	\ttfamily
+	\gabcsnippet{(  ) dv(dv) ed(ed) ed~(ed~) dcd(dcd) ( )}
+}
 
 But when a ledger line is drawn below these notes, they should take a long
 form. The problem is that many cases are ambiguous: for instance if a note
@@ -251,15 +884,25 @@ is close to a ledger line, one may want to make it long, others may not.
 To solve this problem, you can add \texttt{[ll:0]} to the note carrying the stem
 to get its short form, or \texttt{[ll:1]} to force its long form.
 
-% This snippet makes LuaTeX segfault!
-%\gabcsnippet{
-%  (c3) dv<v>[</v>ll:1<v>]</v>(dv[ll:1]) ed<v>[</v>ll:1<v>]</v>(ed[ll:1])
-%       ed<sp>~</sp><v>[</v>ll:1<v>]</v>(ed~[ll:1]) dcd<v>[</v>ll:1<v>]</v>(dcd[ll:1] Z)
-%       b!dv<v>[</v>ll:0<v>]</v>(b!dv[ll:0]) b!ed<v>[</v>ll:0<v>]</v>(b!ed[ll:0])
-%       b!ed<sp>~</sp><v>[</v>ll:0<v>]</v>(b!ed~[ll:0]) dcd<v>[</v>ll:0<v>]</v>!b(dcd[ll:0]!b)
-%  }
+{
+	\gresetinitiallines{0}\gresetlyriccentering{firstletter}%
+	\gresetclef{invisible}\gresetlastline{justified}\greseteolcustos{manual}%
+	\gabcsnippet{
+		( )
+		dv<v>[</v>ll:1<v>]</v>(dv[ll:1])
+		ed<v>[</v>ll:1<v>]</v>(ed[ll:1])
+		ed<sp>~~</sp><v>[</v>ll:1<v>]</v>(ed~[ll:1])
+		dcd<v>[</v>ll:1<v>]</v>(dcd[ll:1])
+		( ) (z) ( )
+		b!dv<v>[</v>ll:0<v>]</v>(b!dv[ll:0])
+		b!ed<v>[</v>ll:0<v>]</v>(b!ed[ll:0])
+		b!ed<sp>~~</sp><v>[</v>ll:0<v>]</v>(b!ed~[ll:0])
+		dcd<v>[</v>ll:0<v>]</v>!b(dcd[ll:0]!b)
+		( )
+	}
+}
 
-\subsection{Custom Ledger Lines}
+\subsubsection{Custom Ledger Lines}
 
 To specify a custom ledger line, use
 \texttt{[oll:}\textit{left}\texttt{;}\textit{right}\texttt{]} to create an
@@ -289,13 +932,13 @@ ledger line in the middle of two-note primitive shapes.  To work around this,
 either adjust the parameters of the ledger line or use manual fusion to break
 up those two notes.
 
-\subsection{Simple Slurs}
+\subsubsection{Simple Slurs}
 
 To specify a simple slur, use
 \texttt{[oslur:}\textit{shift}\texttt{;}\textit{width}\texttt{,}\textit{height}\texttt{]}
 to create an over-the-notes slur with the specified \textit{width} and
 \textit{height}.  If \textit{shift} is \texttt{0}, the slur will start on the
-right side of the note to which it is atteched.  If \textit{shift} is
+right side of the note to which it is attached.  If \textit{shift} is
 \texttt{1}, the slur will start one punctum's width to the left of the right
 side of the note to which it is attached.  If \textit{shift} is \texttt{2},
 the slur will start one-half punctum's width to the left of the right side of
@@ -310,17 +953,18 @@ the same meaning as before, but applies to both ends of the slur.
 Use \texttt{uslur} instead of \texttt{oslur} (with either form) to create an
 under-the-staff slur.
 
-\subsection{Horizontal episema placement for very high and low notes}
+\subsubsection{Horizontal episema placement for very high and low notes}
 
-Gregorio places horizontal episema under c and above k (or the not above upper line when
-staff does not have exactly 4 lines) closer to the notes when no ledger line is present.
-The heuristics used by Gregorio are not perfect so it may be necessary to make
-the presence or absence of ledger line explicit for horizontal episema placement.
-This is done in the exact same way as for stem length: place \texttt{[ll:0]} or
-\texttt{[ll:1]} on the note carrying the episema, to force gregorio to consider the
-absence or presence of a ledger line in episema placement.
+Gregorio places horizontal episema under \texttt{c} and above \texttt{k} (or
+the note above the topmost line when staff does not have exactly 4 lines)
+closer to the notes when no ledger line is present.  The heuristics used by
+Gregorio are not perfect so it may be necessary to make the presence or
+absence of ledger line explicit for horizontal episema placement.  This is
+done in the exact same way as for stem length: place \texttt{[ll:0]} or
+\texttt{[ll:1]} on the note carrying the episema, to force Gregorio to
+consider the absence or presence of a ledger line in episema placement.
 
-\subsection{Horizontal Episema Tuning}
+\subsubsection{Horizontal Episema Tuning}\label{horizontalepisematuning}
 
 The horizontal episema position within the space can be adjusted should the
 defaults not be satisfactory.
@@ -343,6 +987,8 @@ appending \texttt{[oh:\textit{p}]} (for the episema over the note) or
 \texttt{\textit{p}} is an optional position specifier followed by an optional
 nudge.  However at least one or the other must be specified.
 
+\pagebreak[4]
+
 The position specifier allows you to select which of the five tunable
 dimensions will be used for the base position:
 
@@ -361,7 +1007,7 @@ dimensions will be used for the base position:
 
 The nudge is a \TeX{} dimension specification (number and units) that starts
 with \texttt{+} for a nudge upwards or \texttt{-} for a nudge downwards from
-base position selected by the position speciifer.  If omitted, the episema will
+base position selected by the position specifier.  If omitted, the episema will
 be drawn at the base position.
 
 In addition, gabc also allows you to specify that a block of notes---possibly
@@ -374,39 +1020,40 @@ after the last note of the block.  When using this syntax, \texttt{\textit{p}}
 is the position specifier as before, but is entirely optional, and when
 completely omitted, allows the \texttt{:} to also be omitted.
 
-\subsection{Lyric Centering}
+\subsubsection{Above Lines Text Within Notes}
 
-Gregorio centers the text of each syllable around the first note of each
-syllable.  There are three basic modes, selected with the command \verb=\gresetlyriccentering{<mode>}=:
+``Above lines text'' may also be specified within the notes for better
+positioning.  To do this, use \texttt{[alt:}\textit{text}\texttt{]}.
 
-\begin{description}
-\item[syllable] the entire syllable is centered around the first note
-\item[firstletter] the first letter of the syllable is centered around the first note
-\item[vowel] the vowel sound of the syllable is centered around the first note
-\end{description}
+\subsubsection{Verbatim \TeX}
 
-The default is \texttt{vowel}, being common in most Gregorian chant
-books with text in Latin.
+\TeX{} may be inserted directly within the notes.  This is an advanced command
+and is not easy to use, but it can allow for some interesting tweaks and
+special effects.
 
-All modes allow you to force the centering with curly brackets,
-for example \verb=a{b}c= will center the notes around \texttt{b}.
+To do this, use \texttt{[nv:}\textit{tex code}\texttt{]} to insert \TeX\ code
+at the note level, \texttt{[gv:}\textit{tex code}\texttt{]} to insert \TeX\
+code at the glyph level, or \texttt{[ev:}\textit{tex code}\texttt{]} to insert
+\TeX\ code at the element level.
 
-\subsubsection{Vowel detection}
+Here, note, glyph, and element refer to how Gregorio understands the score.
 
-The default rules built into Gregorio for \texttt{vowel} mode are for
-Ecclesiatical Latin and work fairly well (though not perfectly) for
-other languages (especially Romance languages).  However, Gregorio
-provides a gabc \texttt{language} header which allows the language of
-the lyrics to be set. The default is Latin.
+\subsubsection{Macros}
 
-Special characters (input with \texttt{<sp>}) or verbatim text (\texttt{<v>})
-count as consonants, so you have to force centering around them, for example
-\verb=gr{<sp>'ae</sp>}=. If an elision (input with \texttt{<e>}) is present in
-the syllable, Gregorio will consider it as consonant too.
+Macros may be defined using the \texttt{def-m}\textit{n} headers, where
+\textit{n} is 0--9, as described in the \nameref{headers} section above.  Then
+they may be inserted into the score at the note level using
+\texttt{[nm}\textit{n}\texttt{]}, at the glyph level using
+\texttt{[gm}\textit{n}\texttt{]}, or at the element level using
+\texttt{[em}\textit{n}\texttt{]}.  For backwards compatibility reasons,
+Gregorio will also accept \texttt{[altm}\textit{n}\texttt{]} to invoke the
+macro at the element level.
 
-If no vowel is found, the notes are centered around the whole syllable.
+As before, note, glyph, and element refer to how Gregorio understands the
+score.
 
-\subsubsection{Vowel file}
+
+\subsection{Vowel file}\label{customvowels}
 
 When run, Gregorio will look for a file named
 \texttt{gregorio-vowels.dat} in your working directory or amongst the
@@ -509,3 +1156,6 @@ suffix we We wE WE;
 
 secondary w W;
 \end{lstlisting}
+
+
+\endinput
diff --git a/Master/texmf-dist/doc/luatex/gregoriotex/GregorioNabcRef.pdf b/Master/texmf-dist/doc/luatex/gregoriotex/GregorioNabcRef.pdf
index fed58ad7713..c971ca5e48c 100644
--- a/Master/texmf-dist/doc/luatex/gregoriotex/GregorioNabcRef.pdf
+++ b/Master/texmf-dist/doc/luatex/gregoriotex/GregorioNabcRef.pdf
diff --git a/Master/texmf-dist/doc/luatex/gregoriotex/GregorioNabcRef.tex b/Master/texmf-dist/doc/luatex/gregoriotex/GregorioNabcRef.tex
index 3c645e02d80..b8f3b239014 100644
--- a/Master/texmf-dist/doc/luatex/gregoriotex/GregorioNabcRef.tex
+++ b/Master/texmf-dist/doc/luatex/gregoriotex/GregorioNabcRef.tex
@@ -819,6 +819,7 @@ only present in the font source file to help drawing the glyphs.}
 \texttt{E193D} Domine, exaudi orationem \texttt{OT53}\\
 \texttt{E195D} Dominus Iesus \texttt{GT165}\\
 \texttt{E205R} Resurrexi \texttt{GT196}\\
+\texttt{E213C} Alleluia Christus resurgens \texttt{GT226}\\
 \texttt{E248V} Viri Galilaei \texttt{GT235}\\
 \texttt{E255S} Spiritus Domini \texttt{GT252}\\
 \texttt{E256C} Confirma hoc \texttt{OT79}\\
@@ -876,8 +877,11 @@ only present in the font source file to help drawing the glyphs.}
 \texttt{H179L} Liberavit Dominus \texttt{ARII183}\\
 \texttt{H179A} Amicus meus osculi \texttt{NR381}\\
 \texttt{H179I} Iudas mercator \texttt{NR382}\\
+\texttt{H179U} Unus ex discipulis \texttt{NR383}\\
+\texttt{H180U} Una hora non potuistis \texttt{NR388}\\
 \texttt{H219T} Tradiderunt me \texttt{NR408}\\
 \texttt{H219I} Iesum tradidit impius \texttt{NR409}\\
+\texttt{H225M} Mulieres sedentes \texttt{AM449}\\
 \texttt{H266D} Domino si in tempore\\
 \texttt{H269S} Spiritus Sanctus\\
 \texttt{H269D} Dum complerentur \texttt{NR493}\\
@@ -1049,7 +1053,8 @@ only present in the font source file to help drawing the glyphs.}
 \sneume{po~} & \texttt{po\char`\~} & \texttt{C58A} & aeternum\\
 \sneume{poG-} & \texttt{poG-} & \texttt{A167O} & meum\\
 \sneume{posu2} & \texttt{posu2} & \texttt{C46O} & gloria\\
-\sneume{po-1su2} & \texttt{po-1su2} & \texttt{H269R} & alleluia\\ \hline
+\sneume{po-1su2} & \texttt{po-1su2} & \texttt{H269R} & alleluia\\
+\sneume{posu1sut1} & \texttt{posu1sut1} & \texttt{C80Q} & saeculum.\\ \hline
 & \multicolumn{3}{l}{\textbf{torculus}} & \\
 \sneume{to} & \texttt{to} & \texttt{C78O} & Domine\\
 \sneume{tolsc3} & \texttt{tolsc3} & \texttt{C39B} & nomine\\
@@ -1153,7 +1158,8 @@ only present in the font source file to help drawing the glyphs.}
 \sneume{vi-pp4} & \texttt{vi-pp4} & \texttt{C154A} & rectos\\
 \sneume{vi-!vi-!vi} & \texttt{vi-!vi-!vi} & \texttt{H118G} & erubescat\\
 \sneume{vipp4} & \texttt{vipp4} & \texttt{A127E} & eum\\
-\sneume{vi>ppt2} & \texttt{vi>ppt2} & \texttt{H75V} & apertis\\ \hline
+\sneume{vi>ppt2} & \texttt{vi>ppt2} & \texttt{H75V} & apertis\\
+\sneume{scG-1} & \texttt{scG-1} & \texttt{H225M} & Mulieres & \fbox{1.6x}\\ \hline
 & \multicolumn{3}{l}{\textbf{porrectus flexus}} & \\
 \sneume{pf} & \texttt{pf} & \texttt{C27E} & sacrificia\\
 \sneume{pflsc2} & \texttt{pflsc2} & \texttt{C58D} & intendentes\\
@@ -1189,6 +1195,8 @@ only present in the font source file to help drawing the glyphs.}
 \sneume{vippu1su2} & \texttt{vippu1su2} & \texttt{C74B} & Altissime.\\
 \sneume{pesu1sut3} & \texttt{pesu1sut3} & \texttt{C60S} & venti.\\
 \sneume{pesu2suv1} & \texttt{pesu2suv1} & \texttt{C60C} & Sana\\
+\sneume{pesu2sut1} & \texttt{pesu2sut1} & \texttt{E213C} & Alleluia. & \fbox{2.0x}\\
+\sneume{pesu1sut2} & \texttt{pesu1sut2} & \texttt{E213C} & Alleluia. & \fbox{2.0x}\\
 \sneume{vippu1su2lsc3} & \texttt{vippu1su2lsc3} & \texttt{C32B} & caeli\\
 \sneume{pe-1su1suu1} & \texttt{pe-1su1suu1} & \texttt{C61I} & pascuae\\
 \sneume{peSsu1sux1} & \texttt{peSsu1sux1} & \texttt{G89D} & filii & \fbox{0.85x}\\
@@ -1204,6 +1212,7 @@ only present in the font source file to help drawing the glyphs.}
 \sneume{pe-1su1sut1} & \texttt{pe-1su1sut1} & \texttt{H306N} & de & \fbox{2.0x}\\
 \sneume{pe-1su1sut2} & \texttt{pe-1su1sut2} & \texttt{H305G} & Mariae & \fbox{2.0x}\\
 \sneume{pe-1su1suu2} & \texttt{pe-1su1suu2} & \texttt{H305G} & vidente & \fbox{2.0x}\\
+\sneume{pe-1suu1su2} & \texttt{pe-1suu1su2} & \texttt{H180U} & exhortabamini & \fbox{1.75x}\\
 \sneume{pe-su4} & \texttt{pe-su4} & \texttt{C139A} & Alleluia\\
 \sneume{pesuv1su1sut1} & \texttt{pesuv1su1sut1} & \texttt{C139A} & Alleluia\\ \hline
 & \multicolumn{3}{l}{\textbf{scandicus flexus}} & \\
@@ -1230,7 +1239,8 @@ only present in the font source file to help drawing the glyphs.}
 \sneume{tr-~1} & \texttt{tr-\char`\~1} & \texttt{C107A} & Alleluia.\\
 \sneume{trS-} & \texttt{trS-} & \texttt{C89T} & pedes,\\
 \sneume{trS1} & \texttt{trS1} & \texttt{E26L} & eeiieiue & \fbox{2.166x}\\
-\sneume{tr-3} & \texttt{tr-3} & \texttt{H323D} & honore & \fbox{2.0x}\\ \hline
+\sneume{tr-3} & \texttt{tr-3} & \texttt{H323D} & honore & \fbox{2.0x}\\
+\sneume{trsu3} & \texttt{trsu3} & \texttt{C95D} & eius.\\ \hline
 & \multicolumn{3}{l}{\textbf{stropha}} & \\
 \sneume{st} & \texttt{st} & \texttt{C80Q} & commovebitur\\
 \sneume{st-} & \texttt{st-} & \texttt{C52P} & Desiderium\\
@@ -1424,9 +1434,11 @@ only present in the font source file to help drawing the glyphs.}
 \sneume{qi!vssu2} & \texttt{qi!vssu2} \textit{Cf.} \sneume{qi!vsppt1su2} & \multicolumn{3}{l}{\texttt{qi!vsppt1su2} minus tractulus}\\
 \sneume{ql-su1suu1} & \texttt{ql-su1suu1} \textit{Cf.} \sneume{ql-ppt1su1suu1} & \multicolumn{3}{l}{\texttt{ql-ppt1su1suu1} minus tractulus}\\
 \sneume{ql-su1suv1su2} & \texttt{ql-su1suv1su2} \textit{Cf.} \sneume{ql-ppt2su1suv1su2} & \multicolumn{3}{l}{\texttt{ql-ppt2su1suv1su2} minus tractulis}\\
+\sneume{qisu2} & \texttt{qisu2} & \texttt{E166C} & sermones & \fbox{2.0x}\\
 \sneume{qisut2} & \texttt{qisut2} \textit{Cf.} \sneume{qippt2sut2} & \multicolumn{3}{l}{\texttt{qippt2sut2} minus tractulis}\\
 \sneume{ql-su3} & \texttt{ql-su3} \textit{Cf.} \sneume{ql-ppt1su3} & \multicolumn{3}{l}{\texttt{ql-ppt1su3} minus tractulus}\\
 \sneume{qlsut3} & \texttt{qlsut3} \textit{Cf.} \sneume{qlppt1sut3} & \multicolumn{3}{l}{\texttt{qlppt1sut3} minus tractulus}\\
+\sneume{qlsu2} & \texttt{qlsu2} \textit{Cf.} \sneume{qlppt1su2} & \multicolumn{3}{l}{\texttt{qlppt1su2} minus tractulus}\\
 \sneume{ql-su2} & \texttt{ql-su2} \textit{Cf.} \sneume{ql-ppt1su2} & \multicolumn{3}{l}{\texttt{ql-ppt1su2} minus tractulus}\\
 \sneume{ql-sut2} & \texttt{ql-sut2} & \texttt{H73S} & cedebat\\
 \sneume{ql-su1sux1} & \texttt{ql-su1sux1} \textit{Cf.} \sneume{ql-ppt1su1sux1} & \multicolumn{3}{l}{\texttt{ql-ppt1su1sux1} minus tractulus}\\
@@ -1483,6 +1495,7 @@ only present in the font source file to help drawing the glyphs.}
 \sneume{ql-ppt1su1suu1} & \texttt{ql-ppt1su1suu1} & \texttt{H305H} & David & \fbox{2.0x}\\
 \sneume{ql-ppt1su3} & \texttt{ql-ppt1su3} & \texttt{H323D} & subire & \fbox{2.0x}\\
 \sneume{qlppt1sut3} & \texttt{qlppt1sut3} & \texttt{H305G} & Redemptorem & \fbox{2.0x}\\
+\sneume{qlppt1su2} & \texttt{qlppt1su2} & \texttt{E166C} & secundum & \fbox{2.0x}\\
 \sneume{ql-ppt2su1suv1su2} & \texttt{ql-ppt2su1suv1su2} & \texttt{H306N} & illustrat & \fbox{2.0x}\\
 \sneume{ql-su1sut1} & \texttt{ql-su1sut1} & \texttt{H307F} & iustitiae & \fbox{2.0x}\\
 \sneume{qippt2sut2} & \texttt{qippt2sut2} & \texttt{H297B} & generationes & \fbox{2.0x}\\
@@ -1530,6 +1543,7 @@ only present in the font source file to help drawing the glyphs.}
 \sneume{pe!vi} & \texttt{pe!vi} & \texttt{C57B} & qui\\
 \sneume{tgsuu1} & \texttt{tgsuu1} & \texttt{C49I} & eum.\\
 \sneume{tgSsuu1} & \texttt{tgSsuu1} & \texttt{C57B} & nimis.\\
+\sneume{bv-sut2} & \texttt{bv-sut2} & \texttt{H179U} & fuisset. & \fbox{1.75x}\\
 \sneume{sa-su2sut1} & \texttt{sa-su2sut1} & \texttt{C49I} & eum\\ \hline
 \end{supertabular}
 
@@ -1625,6 +1639,7 @@ only present in the font source file to help drawing the glyphs.}
 \texttt{L14P} Prope es tu Domine \texttt{GT24}\\
 \texttt{L14O} Ostende nobis \texttt{GT31}\\
 \texttt{L17H} Hodie scietis \texttt{GT38}\\
+\texttt{L18L} Laetentur caeli \texttt{GT44}\\
 \texttt{L19B} Benedictus qui venit \texttt{GT45}\\
 \texttt{L20P} Puer natus est \texttt{GT47}\\
 \texttt{L24D} Dextera Domini \texttt{GT194}\\
@@ -1932,6 +1947,7 @@ only present in the font source file to help drawing the glyphs.}
 \lneume{tr>} & \texttt{tr>} & \texttt{L64D} & diligerent\\
 \lneume{poppn1} & \texttt{poppn1} & \texttt{L82O} & vero\\
 \lneume{po>ppn1} & \texttt{po>ppn1} & \texttt{L82O} & secundum\\
+\lneume{po>ppn1ppz1} & \texttt{po>ppn1ppz1} & \texttt{L18L} & faciem\\
 \lneume{po>pp2} & \texttt{po>pp2} & \texttt{L28G} & angeli,\\
 \lneume{trlst3lshp7} & \texttt{trlst3lshp7} & \texttt{L109P} & alleluia.\\
 \lneume{trlss1lss3} & \texttt{trlss1lss3} & \texttt{L103P} & Christus.\\
@@ -2063,6 +2079,7 @@ only present in the font source file to help drawing the glyphs.}
 \lneume{qlppn1sun1lsc5} & \texttt{qlppn1sun1lsc5} & \texttt{L54B} & quoniam\\
 \lneume{qlppn1su1sun1} & \texttt{qlppn1su1sun1} & \texttt{L107H} & fecit\\
 \lneume{qlsu1sun1} & \texttt{qlsu1sun1} & \texttt{L43L} & tua\\
+\lneume{qlsu1sux1} & \texttt{qlsu1sux1} & \texttt{L71D} & aquam\\
 \lneume{qlsu2} & \texttt{qlsu2} & \texttt{L67S} & tua,\\
 \lneume{qlsux1} & \texttt{qlsux1} & \texttt{L53C} & quoniam\\
 \lneume{qlsun1su2} & \texttt{qlsun1su2} & \texttt{L44I} & mearum\\
@@ -2317,6 +2334,8 @@ only present in the font source file to help drawing the glyphs.}
 \lneume{trsu2lst3lsm8} & \texttt{trsu2lst3lsm8} & \texttt{L136A} & vobis\\
 \lneume{trsun1su2} & \texttt{trsun1su2} \textit{Cf.} \lneume{trsun1su2lsa3} & \multicolumn{3}{l}{\texttt{trsun1su2lsa3} minus letter} \\
 \lneume{trsun1su2lsa3} & \texttt{trsun1su2lsa3} & \texttt{L149C} & Domini\\
+\lneume{trsun1lsa3lsa5} & \texttt{trsun1lsa3lsa5} & \texttt{L18L} & terra\\
+\lneume{trsun1lsa5} & \texttt{trsun1lsa5} \textit{Cf.} \lneume{trsun1lsa3lsa5} & \multicolumn{3}{l}{\texttt{trsun1lsa3lsa5} minus letter} \\
 \lneume{bvsun4} & \texttt{bvsun4} & \texttt{L8U} & me.\\
 \lneume{oc!cl} & \texttt{oc!cl} & \texttt{L31D} & Domine.\\
 \lneume{oc!clM} & \texttt{oc!clM} & \texttt{L77S} & peccatorum.\\
diff --git a/Master/texmf-dist/doc/luatex/gregoriotex/GregorioRef.lua b/Master/texmf-dist/doc/luatex/gregoriotex/GregorioRef.lua
index fb28a8886f9..d6964dab4ad 100644
--- a/Master/texmf-dist/doc/luatex/gregoriotex/GregorioRef.lua
+++ b/Master/texmf-dist/doc/luatex/gregoriotex/GregorioRef.lua
@@ -119,19 +119,27 @@ local EXCLUDE = {
   QuilismaLineTR = true,
   VirgaLineBR = true,
   SalicusOriscus = true,
-  ['Virgula.2'] = true,
-  ['Virgula.3'] = true,
-  ['Virgula.5'] = true,
-  ['DivisioMinima.2'] = true,
-  ['DivisioMinima.3'] = true,
-  ['DivisioMinima.5'] = true,
-  ['DivisioMinor.2'] = true,
-  ['DivisioMinor.3'] = true,
-  ['DivisioMinor.5'] = true,
-  ['DivisioMaior.2'] = true,
-  ['DivisioMaior.3'] = true,
-  ['DivisioMaior.5'] = true,
   VirgaBaseLineBL = true,
+  ['VirgulaTwo'] = true,
+  ['VirgulaThree'] = true,
+  ['VirgulaFive'] = true,
+  ['VirgulaSix'] = true,
+  ['DivisioMinimaTwo'] = true,
+  ['DivisioMinimaThree'] = true,
+  ['DivisioMinimaFive'] = true,
+  ['DivisioMinimaSix'] = true,
+  ['DivisioMinorTwo'] = true,
+  ['DivisioMinorThree'] = true,
+  ['DivisioMinorFive'] = true,
+  ['DivisioMaiorTwo'] = true,
+  ['DivisioMaiorThree'] = true,
+  ['DivisioMaiorFive'] = true,
+  ['DivisioMaiorDottedTwo'] = true,
+  ['DivisioMaiorDottedThree'] = true,
+  ['DivisioMaiorDottedFive'] = true,
+  ['DivisioMaiorDottedBackingTwo'] = true,
+  ['DivisioMaiorDottedBackingThree'] = true,
+  ['DivisioMaiorDottedBackingFive'] = true,
 }
 
 -- &&& in the following two tables is a placeholder for the cavum shape 'r'
@@ -175,9 +183,11 @@ local GABC = {
   DescendensPunctumInclinatum = [[G&&&0]],
   DivisioDominican = [[,3]],
   DivisioDominicanAlt = [[,4]],
-  DivisioMaior = [[:]],
-  DivisioMinima = [[,]],
-  DivisioMinor = [[;]],
+  DivisioMaiorFour = [[:]],
+  DivisioMaiorDottedFour = [[:?]],
+  DivisioMaiorDottedBackingFour = [[\excluded{:?}]],
+  DivisioMinimaFour = [[,]],
+  DivisioMinorFour = [[;]],
   FClefChange = [[f3]],
   FClef = [[f3]],
   Flat = [[gx]],
@@ -256,7 +266,7 @@ local GABC = {
   VirgaReversa = [[g&&&V]],
   VirgaReversaLongqueue = [[h&&&V]],
   VirgaReversaOpenqueue = [[a&&&V]],
-  Virgula = [[^^^^0060]],
+  VirgulaFour = [[^^^^0060]],
 }
 
 local GABC_AMBITUS_ONE = {
@@ -522,15 +532,21 @@ function GregorioRef.emit_score_glyphs(cs_normal, cs_hollow)
   local first = true
   local i, name
   for i, name in ipairs(glyph_names) do
-    if not EXCLUDE[name[2]] then
-      if (name[3] == '' and name[5] == '') or name[3] == '' or only_twos:match(name[3])
-          or (GABC_AMBITUS_ONE[name[2]] and ambitus_one:match(name[3])) then
+    local shape = name[2]
+    local ambitus = name[3]
+    if shape:match('^Virgula') or shape:match('^Divisio') then
+      shape = shape..ambitus
+      ambitus = ''
+    end
+    if not EXCLUDE[shape] then
+      if (ambitus == '' and name[5] == '') or ambitus == '' or only_twos:match(ambitus)
+          or (GABC_AMBITUS_ONE[shape] and ambitus_one:match(ambitus)) then
         if first then
           first = false
         else
           tex.print([[\hline]])
         end
-        emit_score_glyph(name[1], name[2], name[3], name[4], name[5])
+        emit_score_glyph(name[1], shape, ambitus, name[4], name[5])
       end
     end
   end
diff --git a/Master/texmf-dist/doc/luatex/gregoriotex/GregorioRef.pdf b/Master/texmf-dist/doc/luatex/gregoriotex/GregorioRef.pdf
index fafc860c950..3568550e308 100644
--- a/Master/texmf-dist/doc/luatex/gregoriotex/GregorioRef.pdf
+++ b/Master/texmf-dist/doc/luatex/gregoriotex/GregorioRef.pdf
diff --git a/Master/texmf-dist/doc/luatex/gregoriotex/GregorioRef.tex b/Master/texmf-dist/doc/luatex/gregoriotex/GregorioRef.tex
index 8932a0b42dd..7e564e85a1c 100644
--- a/Master/texmf-dist/doc/luatex/gregoriotex/GregorioRef.tex
+++ b/Master/texmf-dist/doc/luatex/gregoriotex/GregorioRef.tex
@@ -164,8 +164,13 @@
 }
 \makeatother
 
+\newcommand{\pitchchar}{\textit{p\kern-.25em{}c}}%
+\newcommand{\Pitchchar}{\textit{P\kern-.25em{}c}}%
+
 \setlength{\parindent}{0mm} % Default is 15pt
 
+\gresetspecial{\string\126\string\126}{\textasciitilde{}}%
+
 \begin{document}
 
 \begin{titlepage}
@@ -177,7 +182,7 @@
 
 		\vspace{1cm}
 
-		\large Version \textbf{5.0.2}, 24 May 2017 %% PARSE_VERSION_DATE
+		\large Version \textbf{5.1.0}, 11 March 2018 %% PARSE_VERSION_DATE
 
 		\vspace{1.5cm}
 	\end{center}
diff --git a/Master/texmf-dist/doc/luatex/gregoriotex/README.md b/Master/texmf-dist/doc/luatex/gregoriotex/README.md
index 4bbd40f2dab..2085baa0ce1 100644
--- a/Master/texmf-dist/doc/luatex/gregoriotex/README.md
+++ b/Master/texmf-dist/doc/luatex/gregoriotex/README.md
@@ -17,3 +17,37 @@ To compile the pdf you must have
  * the [`pygments` library](http://pygments.org/)
 
 Once you have run `./configure` in the main directory, run `make doc` in this directory.
+
+
+Developer notes on extending the gregall and grelaon fonts
+==========================================================
+
+The glyphs are drawn with cropped pictures of the neumes
+from the manuscripts.  The gregall glyphs are coming from
+multiple manuscripts with different neume sizes and furthermore
+in some manuscripts like Einsiedeln codex 121 even the sizes of
+neumes varies between different folios and often even on the same
+folio.  Therefore, when loading the images as background images
+in fontforge (version used so far is 20120731), they need to be
+scaled accordingly.  The easiest way is to measure the height in
+pixels of a clivis with episema (cl-) neume from the highest to
+the lowest extreme and divide by 42.0 pixels which is corresponding
+height of the original cl- background picture.  The result is the
+scale factor listed in GregiorioNabcRef.tex.  After loading the
+background image, the background layer in fontforge should be scaled
+(same in both axis) by the height of the glyph image in pixels
+divided by the scale factor computed above and divided by 52.0 (the
+pixel height of the cl- background picture).  The cl- background
+picture in the gregall font had the height of 1000 fontforge units.
+The grelaon font has as a source only a single manuscript with
+approximately comparable neume sizes everywhere, so if using as the
+source images with heights around 3500-3600 pixels, the scale factor
+is just 1 and height 52 pixels should correspond to 1000 fontforge
+units.  Each neume should be named in fontforge with the corresponding
+nabc string, with - replaced by N, > replaced by B, ! replaced by E
+and ~ replaced by T.  After adding any glyph, GregorioNabcRef.tex
+should be updated to list the source of the neume and if the corresponding
+gregorian piece is not listed yet, also update list of them, if possible
+with a reference to Graduale Triplex, Antiphonale Monasticum,
+Nocturnale Romanum etc. book pages where the gregorian piece can be
+found.
diff --git a/Master/texmf-dist/doc/luatex/gregoriotex/examples/PopulusSion.gabc b/Master/texmf-dist/doc/luatex/gregoriotex/examples/PopulusSion.gabc
index 856dde3d091..dd8eafe8213 100644
--- a/Master/texmf-dist/doc/luatex/gregoriotex/examples/PopulusSion.gabc
+++ b/Master/texmf-dist/doc/luatex/gregoriotex/examples/PopulusSion.gabc
@@ -16,7 +16,7 @@ style: modern;
 
 %%
 
-% The syntax in this part is called gabc. Please refer to http://home.gna.org/gregorio/gabc/#basis
+% The syntax in this part is called gabc. Please refer to http://gregorio-project.github.io/gabc/index.html
 
 Pó(c3eh/hi)pu(h)lus(h) Si(hi)on,(hgh.) *(;) ec(hihi)ce(e.) Dó(e.f!gwhhi)mi(h){n}us(h) vé(hi)ni(ig//ih)et(h.) (,) ad(iv./hig) sal(fe~)ván(ghg)das(fg) gen(e_f_e_)tes(e.) :(:)
 
diff --git a/Master/texmf-dist/doc/luatex/gregoriotex/pitches2.gabc b/Master/texmf-dist/doc/luatex/gregoriotex/pitches2.gabc
new file mode 100644
index 00000000000..05f4b8aa29c
--- /dev/null
+++ b/Master/texmf-dist/doc/luatex/gregoriotex/pitches2.gabc
@@ -0,0 +1,4 @@
+name: two-line pitch diagram;
+staff-lines: 2;
+%%
+( ) a(a) b(b) c(c) d(d) e(e) f(f) g(g) h(h) i(i) ( )
diff --git a/Master/texmf-dist/doc/luatex/gregoriotex/pitches3.gabc b/Master/texmf-dist/doc/luatex/gregoriotex/pitches3.gabc
new file mode 100644
index 00000000000..4b67cda0ac6
--- /dev/null
+++ b/Master/texmf-dist/doc/luatex/gregoriotex/pitches3.gabc
@@ -0,0 +1,4 @@
+name: three-line pitch diagram;
+staff-lines: 3;
+%%
+( ) a(a) b(b) c(c) d(d) e(e) f(f) g(g) h(h) i(i) j(j) k(k) ( )
diff --git a/Master/texmf-dist/doc/luatex/gregoriotex/pitches4.gabc b/Master/texmf-dist/doc/luatex/gregoriotex/pitches4.gabc
new file mode 100644
index 00000000000..d7b85e865ba
--- /dev/null
+++ b/Master/texmf-dist/doc/luatex/gregoriotex/pitches4.gabc
@@ -0,0 +1,4 @@
+name: four-line pitch diagram;
+staff-lines: 4;
+%%
+( ) a(a) b(b) c(c) d(d) e(e) f(f) g(g) h(h) i(i) j(j) k(k) l(l) m(m) ( )
diff --git a/Master/texmf-dist/doc/luatex/gregoriotex/pitches5.gabc b/Master/texmf-dist/doc/luatex/gregoriotex/pitches5.gabc
new file mode 100644
index 00000000000..c4a4969c962
--- /dev/null
+++ b/Master/texmf-dist/doc/luatex/gregoriotex/pitches5.gabc
@@ -0,0 +1,4 @@
+name: five-line pitch diagram;
+staff-lines: 5;
+%%
+( ) a(a) b(b) c(c) d(d) e(e) f(f) g(g) h(h) i(i) j(j) k(k) l(l) m(m) n(n) p(p) ( )