diff options
Diffstat (limited to 'Build/source/texk/gregorio/gregorio-src/doc/Gabc.tex')
-rw-r--r-- | Build/source/texk/gregorio/gregorio-src/doc/Gabc.tex | 104 |
1 files changed, 94 insertions, 10 deletions
diff --git a/Build/source/texk/gregorio/gregorio-src/doc/Gabc.tex b/Build/source/texk/gregorio/gregorio-src/doc/Gabc.tex index b770c35b457..27ef298188b 100644 --- a/Build/source/texk/gregorio/gregorio-src/doc/Gabc.tex +++ b/Build/source/texk/gregorio/gregorio-src/doc/Gabc.tex @@ -220,9 +220,8 @@ line (\textit{d}). Most of the time they will take a short form: 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 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 any note of a glyph to -force the stem of the glyph to get its short form, or \texttt{[ll:1]} to force -its long form. +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{ @@ -283,22 +282,107 @@ 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} + +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. + +\subsection{Horizontal Episema Tuning} + +The horizontal episema position within the space can be adjusted should the +defaults not be satisfactory. + +There are five tunable dimensions: + +\begin{tabularx}{\textwidth}{l|X} + Dimension & Description \\ + \hline + \texttt{overhepisemalowshift} & The shift for positioning a horizontal episema that is over a note in a low position in the space\\ + \texttt{overhepisemahighhift} & The shift for positioning a horizontal episema that is over a note in a high position in the space\\ + \texttt{underhepisemalowshift} & The shift for positioning a horizontal episema that is under a note in a low position in the space\\ + \texttt{underhepisemahighhift} & The shift for positioning a horizontal episema that is under a note in a high position in the space\\ + \texttt{hepisemamiddleshift} & The shift for centering the horizontal episema in the middle of a space\\ +\end{tabularx} + +In addition, gabc allows you to adjust the positioning of a given episema by +appending \texttt{[oh:\textit{p}]} (for the episema over the note) or +\texttt{[uh:\textit{p}]} (for the episema under the note). Here, +\texttt{\textit{p}} is an optional position specifier followed by an optional +nudge. However at least one or the other must be specified. + +The position specifier allows you to select which of the five tunable +dimensions will be used for the base position: + +\begin{tabularx}{\textwidth}{l|X} + Specifier & Base shift \\ + \hline + \textit{omitted} & Use the default shift based on the position of the episema relative to the note\\ + \texttt{m} & Use \texttt{hepisemamiddleshift}.\\ + \texttt{l} & Use \texttt{overhepisemalowshift} or \texttt{underhepisemalowshift} depending on whether the episema is over or under the note.\\ + \texttt{h} & Use \texttt{overhepisemahighshift} or \texttt{underhepisemahighshift} depending on whether the episema is over or under the note.\\ + \texttt{ol} & Use \texttt{overhepisemalowshift}.\\ + \texttt{oh} & Use \texttt{overhepisemahighshift}.\\ + \texttt{ul} & Use \texttt{underhepisemalowshift}.\\ + \texttt{uh} & Use \texttt{underhepisemahighshift}.\\ +\end{tabularx} + +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 +be drawn at the base position. + +In addition, gabc also allows you to specify that a block of notes---possibly +separated with spaces and in different syllables--should be considered a single +unit when it comes to positioning the horizontal episema. To do this, put +\texttt{[oh:\textit{p}\{]} (for the episema over the note) or +\texttt{[uh:\textit{p}\{]} (for the episema under the note) before the first +note of the block and the corresponding \texttt{[oh\}]} or \texttt{[uh\}]} +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} Gregorio centers the text of each syllable around the first note of each -syllable. There are three basic modes: \verb:syllable:, \verb:vowel:, and \verb:firstletter:, which are selected with the command \verb=\gresetlyriccentering{<mode>}=. In \texttt{syllable} mode, the -entire syllable is centered around the first note. This is common in -modern music. In \texttt{vowel} mode, the vowel sound of the syllable is -centered around the first note. This is common in most Gregorian chant -books with text in Latin. In \texttt{firstletter} mode, the first letter of the syllable is centered around the first note. While not a common choice, this was explicitly requested by a user and we try to be responsive to our user base. +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. + +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{Vowel detection} 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. Gregorio will look for a file named +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. + +\subsubsection{Vowel file} + +When run, Gregorio will look for a file named \texttt{gregorio-vowels.dat} in your working directory or amongst the -GregorioTeX files. If it finds the requested language (matched in a +GregorioTeX files. If it finds the language requested by the header (matched in a \emph{case-sensitive} fashion) in one of these files (henceforth called vowel files), Gregorio will use the rules contained within for vowel centering. If it cannot find the requested language in any of the vowel |