summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/luatex/gregoriotex/Command_Index_User.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/luatex/gregoriotex/Command_Index_User.tex')
-rw-r--r--Master/texmf-dist/doc/luatex/gregoriotex/Command_Index_User.tex147
1 files changed, 102 insertions, 45 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 99c985f9ec3..ccd0130ab42 100644
--- a/Master/texmf-dist/doc/luatex/gregoriotex/Command_Index_User.tex
+++ b/Master/texmf-dist/doc/luatex/gregoriotex/Command_Index_User.tex
@@ -1,7 +1,7 @@
% !TEX root = GregorioRef.tex
% !TEX program = LuaLaTeX+se
%
-% Copyright (C) 2006-2019 The Gregorio Project (see CONTRIBUTORS.md)
+% Copyright (C) 2006-2021 The Gregorio Project (see CONTRIBUTORS.md)
%
% This file is part of Gregorio.
%
@@ -94,7 +94,7 @@ Once you've included the package in your document (as explained above) the follo
\subsubsection{Including scores}
\macroname{\textbackslash gregorioscore}{[\optional{\#1}]\{\#2\}}{gregoriotex-main.tex}
-Macro for including scores. Works on both gabc and tex files.
+Macro for including scores. Works on both gabc and gtex files.
\begin{argtable}
\#1 & \texttt{n} & Optional. \#2 will be included as is. \\
@@ -150,6 +150,16 @@ When called with the optional argument \texttt{[f]} Gregorio\TeX\ will
compile the gabc file into a gtex file. This is similar to
\texttt{[a]} except the gabc is compiled every time.
+\macroname{\textbackslash gresetgregpath}{\{\#1\}}{gregoriotex-main.tex}
+Set a list of additional directories which should be searched for scores. Directories may be absolute or relative, but must end with a slash (\verb=/=) and enclosed in braces (\verb={}=), even if there is only one additional directory. For example, to look in a directory called “Scores” which is alongside the main project directory, one could use the following:
+
+\begin{latexcode}
+ \gresetgregpath{{../Scores/}}
+\end{latexcode}
+
+Note that these directories are not searched recursively. If you want to include subdirectories, then each subdirectory must be included individually.
+
+
\macroname{\textbackslash gresetcompilegabc}{\{\#1\}}{gregoriotex-main.tex}
A macro to change the behavior of the way Gregorio\TeX\ includes scores. This is similar to using the package options \verb=[forcecompile]=, \verb=[autocompile]=, and \verb=[nevercompile]=, but does not necessarly apply to the entire document.
@@ -166,17 +176,17 @@ without doing anything else.
\medskip This macro can be combined in the same document with different arguments to
switch between different behaviors: \par\medskip
\begin{latexcode}
- \usepackage{gregoriotex} % [nevercompile] is the default.
+ \usepackage{gregoriotex} % [autocompile] is the default.
----
- \gregorioscore{TecumPrincipium} % gabc never compiled.
- \gregorioscore[f]{TecumPrincipium} % gabc always compiled.
- \gregorioscore[a]{TecumPrincipium} % gabc auto compiled.
-
- \gresetcompilegabc{auto}
\gregorioscore{TecumPrincipium} % gabc auto compiled.
\gregorioscore[n]{TecumPrincipium} % gabc never compiled.
\gregorioscore[f]{TecumPrincipium} % gabc always compiled.
+ \gresetcompilegabc{never}
+ \gregorioscore{TecumPrincipium} % gabc never compiled.
+ \gregorioscore[f]{TecumPrincipium} % gabc always compiled.
+ \gregorioscore[a]{TecumPrincipium} % gabc auto compiled.
+
\gresetcompilegabc{force}
\gregorioscore{TecumPrincipium} % gabc always compiled.
\gregorioscore[n]{TecumPrincipium} % gabc never compiled.
@@ -251,17 +261,6 @@ Macro to adjust the thickness of the staff lines.
\subsubsection{Fine Tuning Dimensions}
In addition to providing control over the overall size of your scores, Gregorio\TeX\ allows you to fine tune the spacings around and between the various elements using the following functions.
-\macroname{\textbackslash grecreatedim}{\{\#1\}\{\#2\}\{\#3\}}{gregoriotex-spaces.tex}
-Macro to create one of Gregorio\TeX’s distances. Used to initialize distances in a space configuration file. For an example of such a file, please see \textit{gsp-default.tex}, which contains the default spacing configuration for Gregorio\TeX.
-
-\begin{argtable}
- \#1 & string & The name of the distance to be changed. See \nameref{distances} below.\\
- \#2 & string & The distance in string format. \textbf{Note:} You cannot use a length register for this argument. You \emph{must} use a string because of the way that Gregorio\TeX\ handles spaces.\\
- \#3 & \texttt{fixed} & Distance will not scale when staff size is changed.\\
- & \texttt{scalable} & Distance will scale when staff size is changed.\\
- & \texttt{inherited} & Distance will inherit its value from another distance. When this argument is used, then \#2 should be the name of another Gregorio\TeX\ distance.
-\end{argtable}
-
\macroname{\textbackslash grechangedim}{\{\#1\}\{\#2\}\{\#3\}}{gregoriotex-spaces.tex}
Macro to change one of Gregorio\TeX’s distances. This function will check to make sure the distance you are trying to change exists first.
@@ -322,7 +321,7 @@ Changes one of Gregorio\TeX’s counts or penalties for a given line in the next
\end{argtable}
\macroname{\textbackslash greloadspaceconf}{\{\#1\}}{gregoriotex-spaces.tex}
-Macro to load a space configuration file. Space configuration file names have the format \verb=gsp-identifier.tex= and must be in the same directory as your project or in your texmf directory.
+Macro to load a space configuration file. Space configuration file names have the format \verb=gsp-identifier.tex= and must be in the same directory as your project or in your texmf directory. See \verb=gsp-sample.tex= for an example file.
\begin{argtable}
\#1 & string & The identifier of the space configuration file.
@@ -330,13 +329,13 @@ Macro to load a space configuration file. Space configuration file names have t
Example:\par\medskip
\begin{latexcode}
- % loads gsp-default.tex, the default configuration file
+ % loads gregoriotex-gsp-default.tex, the default configuration file
\greloadspaceconf{default}
% loads a custom configuration called gsp-myspaces.tex
\greloadspaceconf{myspaces}
\end{latexcode}
-\macroname{\textbackslash greconffactor}{}{gsp-default.tex}
+\macroname{\textbackslash greconffactor}{}{gregoriotex-gsp-default.tex}
A count which indicates the staff size that a space configuration file is designed for. Each space configuration file must have this value set as Gregorio\TeX\ will compare it to the current staff size to determine if the configuration file being loaded needs to be rescaled.
\macroname{\textbackslash gresetlineheightexpansion}{\{\#1\}}{gregoriotex-main.tex}
@@ -400,6 +399,13 @@ staff). The \texttt{\textit{n}} should be set to indicate whether the
system should act as if the ledger line exists (\texttt{1}) or not
(\texttt{0}).
+\macroname{\textbackslash gresetnoteadditionalspacelinestext}{\{\#1\}}{gregoriotex-main.tex}
+Macro which determines how much additional space between the notes and the lyrics for really low notes.
+
+\begin{argtable}
+ \#1 & \texttt{automatic} & additional space between the notes and the lyrics is computed automatically (default)\\
+ & \texttt{manual} & additional space between the notes and the lyrics is based on the user setting of \texttt{noteadditionalspacelinestext} (a spacing adjustable using \verb=\grechangedim=)
+\end{argtable}
\subsubsection{Staff Lines}
@@ -461,6 +467,8 @@ Note that the font will be looked up by name through luaotfload, see the documen
& \texttt{granapadano} & Use the Grana Padano font.\\
\end{argtable}
+\textbf{Nota Bene:} The Gregorio and Grana Padano fonts are not included by default in a basic installation. To get them you need to download and install them from the \verb=supp-fonts-##.zip= file (where \#\# is the version number of your release). See \url{https://github.com/gregorio-project/gregorio/releases} for the list of releases.
+
\macroname{\textbackslash gresetgregoriofontscaled}{[\optional{\#1}]\{\#2\}\{\#3\}}{gregoriotex-main.tex}
This function is the same as above, with a third argument to scale the font. The fonts shipped with Gregorio do not need to use this function, but some custom fonts do. Note that you cannot use this to scale glyphs up or down, as they would not be placed correctly on the staff.
@@ -919,6 +927,22 @@ Sets the visibility of the lyrics.
& \texttt{invisible} & Lyrics are not visible.\\
\end{argtable}
+\macroname{\textbackslash gresettranslation}{\{\#1\}}{gregoriotex-main.tex}
+Sets the visibility of the translations.
+
+\begin{argtable}
+ \#1 & \texttt{visible} & Translations are visible (default).\\
+ & \texttt{invisible} & Translations are not visible.\\
+\end{argtable}
+
+\macroname{\textbackslash gresetabovelinestext}{\{\#1\}}{gregoriotex-main.tex}
+Sets the visibility of the above lines text.
+
+\begin{argtable}
+ \#1 & \texttt{visible} & Above lines text are visible (default).\\
+ & \texttt{invisible} & Above lines text are not visible.\\
+\end{argtable}
+
\subsubsection{Text Alignment}
Gregorio\TeX\ allows you to manipulate the global alignment behavior of some text elements using the following commands.
@@ -964,8 +988,8 @@ Macro to specify how the translation text should be aligned with it respective s
Macro to specify which line of the annotation should be used to determine its starting placement (i.e. before \texttt{annotationraise} is applied).
\begin{argtable}
- \#1 & \texttt{firstline} & Annotation placement is determined by the first line (default)\\
- & \texttt{lastline} & annotation placement is determined by the last line\\
+ \#1 & \texttt{topline} & Annotation placement is determined by the first line (default)\\
+ & \texttt{bottomline} & annotation placement is determined by the last line\\
\end{argtable}
\macroname{\textbackslash gresetannotationvalign}{\{\#1\}}{gregoriotex-main.tex}
@@ -1000,7 +1024,7 @@ protrusion factors will be used for various characters as well as for
\verb=<pr>= tags with no specified protrusion factor. A protrusion factor of 0
means no protrusion and 1 means full protrusion. Any floating-point value from
0 to 1 is allowed. All of these global protrusion factors may be set in
-gsp-default.tex or in your own \TeX\ files.
+a spacing configuration file (gsp-*.tex) or in the project \TeX\ file.
\begin{argtable}
\#1 & \texttt{,} & Sets the automatic protrusion factor for a comma at
@@ -1394,10 +1418,8 @@ baseline.
\end{gcount}
\begin{gcount}{noteadditionalspacelinestextthreshold}
-The number of low notes which will add on the
-\texttt{noteadditionalspacelinestext} space. For instance, with a threshold of
-\texttt{2}, every note below \texttt{c} will add {noteadditionalspacelinestext}
-space for each pitch needed below \texttt{c}, accounting for the various signs.
+The number of low notes which will add space between the lines and the lyrics. For instance, with a threshold of
+\texttt{2}, every note below \texttt{c} will add space for each pitch needed below \texttt{c}, accounting for the various signs.
\end{gcount}
\subsection{Distances}\label{distances}
@@ -1612,6 +1634,10 @@ Space between a punctum inclinatum and a no-bar (stemless) glyph three or four
pitches above.
\end{gdimension}
+\begin{gdimension}{uprightpunctuminclinatumshift}
+Space after after a non-punctum inclinatum and before the upright punctum inclinatum.
+\end{gdimension}
+
\begin{gdimension}{maximumspacewithoutdash}
Maximal space between two syllables for which we consider a dash is not needed.
\end{gdimension}
@@ -1699,11 +1725,6 @@ The space above the lines.
The space between the lines and the bottom of the text.
\end{gdimension}
-\begin{gdimension}{noteadditionalspacelinestext}
-The space added between the lines and the bottom of the text for every pitch
-below the \texttt{noteadditionalspacelinestextthreshold}.
-\end{gdimension}
-
\begin{gdimension}{spacebeneathtext}
The space beneath the text.
\end{gdimension}
@@ -1846,7 +1867,7 @@ This space is added before the final divisio final of a score (old bar spacing a
Spaces around bars when they are typeset inside a syllable. The \verb=@short=
suffix for virgula and divisio minima indicates the space used when the notes
-surrounding the bar are strictly lower than \texttt{g} (in a four-line score).
+surrounding the bar are strictly lower than \texttt{g} (in a four-line score).
For divisio minimis, the \verb=@short= suffix is for notes lower than
\texttt{h}. When applied to ``high'' positions (on the ledger line above
the staff), the \verb=@short= distances will be used for up to two pitches
@@ -1858,6 +1879,12 @@ higher.
\begin{gdimension}{bar@virgula@short}
\end{gdimension}
+\begin{gdimension}{bar@virgulaparen}
+\end{gdimension}
+
+\begin{gdimension}{bar@virgulaparen@short}
+\end{gdimension}
+
\begin{gdimension}{bar@minimis}
\end{gdimension}
@@ -1870,6 +1897,12 @@ higher.
\begin{gdimension}{bar@minima@short}
\end{gdimension}
+\begin{gdimension}{bar@minimaparen}
+\end{gdimension}
+
+\begin{gdimension}{bar@minimaparen@short}
+\end{gdimension}
+
\begin{gdimension}{bar@minor}
\end{gdimension}
@@ -1890,6 +1923,12 @@ Spaces around bars in standalone syllables, when these have text (new bar spacin
\begin{gdimension}{bar@virgula@standalone@text@short}
\end{gdimension}
+\begin{gdimension}{bar@virgulaparen@standalone@text}
+\end{gdimension}
+
+\begin{gdimension}{bar@virgulaparen@standalone@text@short}
+\end{gdimension}
+
\begin{gdimension}{bar@minimis@standalone@text}
\end{gdimension}
@@ -1902,6 +1941,12 @@ Spaces around bars in standalone syllables, when these have text (new bar spacin
\begin{gdimension}{bar@minima@standalone@text@short}
\end{gdimension}
+\begin{gdimension}{bar@minimaparen@standalone@text}
+\end{gdimension}
+
+\begin{gdimension}{bar@minimaparen@standalone@text@short}
+\end{gdimension}
+
\begin{gdimension}{bar@minor@standalone@text}
\end{gdimension}
@@ -1925,6 +1970,12 @@ Spaces around bars in standalone syllables, when these have no text (new bar spa
\begin{gdimension}{bar@virgula@standalone@notext@short}
\end{gdimension}
+\begin{gdimension}{bar@virgulaparen@standalone@notext}
+\end{gdimension}
+
+\begin{gdimension}{bar@virgulaparen@standalone@notext@short}
+\end{gdimension}
+
\begin{gdimension}{bar@minimis@standalone@notext}
\end{gdimension}
@@ -1937,6 +1988,12 @@ Spaces around bars in standalone syllables, when these have no text (new bar spa
\begin{gdimension}{bar@minima@standalone@notext@short}
\end{gdimension}
+\begin{gdimension}{bar@minimaparen@standalone@notext}
+\end{gdimension}
+
+\begin{gdimension}{bar@minimaparen@standalone@notext@short}
+\end{gdimension}
+
\begin{gdimension}{bar@minor@standalone@notext}
\end{gdimension}
@@ -2029,7 +2086,7 @@ The club penalty (determines how important it is to prevent orphans from occurri
The widow penalty (determines how important it is to prevent widows from occurring).
\end{gcount}
-\macroname{emergencystretch}{}{gsp-default.tex}
+\macroname{emergencystretch}{}{gregoriotex-gsp-default.tex}
The value of the last ditch stretch for overfull boxes. This should be set using \verb=\grechangedim=.
Default: \verb=\emergencystretch=
@@ -2038,27 +2095,27 @@ Default: \verb=\emergencystretch=
The end after bar penalty.
\end{gcount}
-\begin{gcount}{endafterbaraltpenalty}{}{gsp-default.tex}
+\begin{gcount}{endafterbaraltpenalty}{}{gregoriotex-gsp-default.tex}
The alternate end after bar penalty (used when there is no text under the bar).
\end{gcount}
-\begin{gcount}{endofelementpenalty}{}{gsp-default.tex}
+\begin{gcount}{endofelementpenalty}{}{gregoriotex-gsp-default.tex}
The end of element penalty.
\end{gcount}
-\begin{gcount}{endofsyllablepenalty}{}{gsp-default.tex}
+\begin{gcount}{endofsyllablepenalty}{}{gregoriotex-gsp-default.tex}
The end of element penalty.
\end{gcount}
-\begin{gcount}{endofwordpenalty}{}{gsp-default.tex}
+\begin{gcount}{endofwordpenalty}{}{gregoriotex-gsp-default.tex}
The end of element penalty.
\end{gcount}
-\begin{gcount}{hyphenpenalty}{}{gsp-default.tex}
+\begin{gcount}{hyphenpenalty}{}{gregoriotex-gsp-default.tex}
The hyphen penalty.
\end{gcount}
-\begin{gcount}{nobreakpenalty}{}{gsp-default.tex}
+\begin{gcount}{nobreakpenalty}{}{gregoriotex-gsp-default.tex}
Penalty to prevent a line break.
\end{gcount}
@@ -2070,7 +2127,7 @@ Penalty to force a line break.
The penalty applied after the final element of a score.
\end{gcount}
-\macroname{looseness}{}{gsp-default.tex}
+\macroname{looseness}{}{gregoriotex-gsp-default.tex}
The \TeX\ looseness within a score.
Default: \verb=\looseness=
@@ -2079,12 +2136,12 @@ Default: \verb=\looseness=
The \TeX\ tolerance within a score. See \url{https://en.wikibooks.org/wiki/TeX/tolerance} for an explanation of what tolerance is.
\end{gcount}
-\macroname{pretolerance}{}{gsp-default.tex}
+\macroname{pretolerance}{}{gregoriotex-gsp-default.tex}
The \TeX\ pretolerance within a score. See \url{https://en.wikibooks.org/wiki/TeX/pretolerance} for an explanation of what pretolerance is.
Default: $-1$ (Lua\TeX\ versions prior to 0.80) or \verb=\pretolerance= (versions after, and including, 0.80)]
-\textit{Nota bene:} For more details on why this is necessary see the comments in gsp-default.tex.
+\textit{Nota bene:} For more details on why this is necessary see the comments in gregoriotex-gsp-default.tex.