gregorio-project#1189: doc

CHANGELOG.md

@@ -3,6 +3,9 @@ All notable changes to this project will be documented in this file.
 As of v3.0.0 this project adheres to [Semantic Versioning](http://semver.org/). It follows [some conventions](http://keepachangelog.com/).
 
 [Unreleased][unreleased]
+## Changed
+- Notes are now left-aligned as if all clefs had the same width as the largest clef in the score. You can get previous behavior back with `\grebolshiftcleftype{current}`, or temporary force alignment until the end of a score with `\grelocalbolshiftcleftype`. See Documentation of these functions and [#1189](https://github.com/gregorio-project/gregorio/issues/1189).
+
 ### Added
 - More cavum shapes are now available.  To use them, simply add `r` in gabc to any note in a glyph.  See [#844](https://github.com/gregorio-project/gregorio/issues/844).
 - Square brackets can be placed around notes by using `[[` and `]]` to surround said notes in gabc (see [#844](https://github.com/gregorio-project/gregorio/issues/844)).

doc/Command_Index_User.tex

@@ -1008,6 +1008,26 @@ \subsubsection{End of Line Behavior}
   & \texttt{disable} & The shifts are not applied.
 \end{argtable}
 
+\macroname{\textbackslash grebolshiftcleftype}{\{\#1\}}{gregoriotex-spaces.tex}
+Macro to determine how notes should be left aligned in the case where clefs of different widths appear in the same score.
+
+\begin{argtable}
+  \#1 & \texttt{largest} & The notes are aligned as if all clefs had the width of the largest clef (default)\\
+  & \texttt{current} & The notes are aligned on the current clef, which leads to unaligned notes. This was the default of Gregorio < \texttt{5.0}.
+\end{argtable}
+
+\macroname{\textbackslash grelocalbolshiftcleftype}{\{\#1\}}{gregoriotex-spaces.tex}
+Equivalent of \verb=\grebolshiftcleftype= but valid only until the next end of a score, and with more options. This can be used inside gabc for corner cases like different alignment on a score taking two pages.
+
+\begin{argtable}
+  \#1 & \texttt{largest} & same as in \verb=\grebolshiftcleftype=\\
+  & \texttt{current} & idem\\
+  & \texttt{f} & force left alignment of notes as if all clef were f clef\\
+  & \texttt{c} & idem with c clef\\
+  & \texttt{fb} & idem with flatted f clef\\
+  & \texttt{cb} & idem with flatted c clef\\
+\end{argtable}
+
 \macroname{\textbackslash gresetlastline}{\{\#1\}}{gregoriotex-main.tex}
 Macro to determine whether the last line of the score should be justified or not.
 

doc/Command_Index_gregorio.tex

@@ -802,7 +802,7 @@ \section{Gregorio Controls}
   \#7 & integer & \texttt{0} if clef and first note are far enough to use a shorter space, 1 otherwise.\\
 \end{argtable}
 
-\macroname{\textbackslash GreSetLinesClef}{\#1\#2\#3\#4\#5\#6\#7}{gregoriotex-main.tex}
+\macroname{\textbackslash GreSetLinesClef}{\#1\#2\#3\#4\#5\#6\#7}{gregoriotex-signs.tex}
 Macro to define the clef that will appear at the beginning of the lines.
 
 \begin{argtable}
@@ -816,6 +816,11 @@ \section{Gregorio Controls}
   \#7 & integer & Height of flat in secondary clef (\texttt{3} for no flat).\\
 \end{argtable}
 
+\macroname{\textbackslash GreSetLargestClef}{\#1\#2\#3\#4\#5\#6}{gregoriotex-signs.tex}
+Macro defining the largest clef of the score (for notes left alignment).
+The arguments are the same as \verb=\GreSetInitialClef= without the \#7th one, which is always considered
+to be \texttt{1}.
+
 \macroname{\textbackslash GreSetNabcAboveLines}{\#1}{gregoriotex-main.tex}
 Macro to place argument containing Nabc neumes above the lines and empty
 \verb=\gre@currenttextabovelines= when done.

tex/gregoriotex-signs.tex

@@ -143,9 +143,11 @@
 }%
 
 %% marcro to define the clef that will appear at the beginning of the lines
-% the first argument is the type : f or c, and the second is the height
-% the third argument is whether we must type a space after or not (0 if not, 1 if yes)
-% if the fourth argument is 3, it means that we must not put a flat after the key, otherwise it's the height of the flat
+%% #1 c or f: type of first clef
+%% #2 int: line of first clef
+%% #3 int: 0 if not space, 1 if normal space, 2 for short space
+%% #4 int: height of the flat of first clef, 3 for no flat
+%% #5, #6, #7 = #1, #2, #3 for second clef
 \def\GreSetLinesClef#1#2#3#4#5#6#7{%
   \gre@localleftbox{%
     \gre@skip@temp@four = \gre@dimen@additionalleftspace\relax%
@@ -165,9 +167,12 @@
   \relax%
 }%
 
-\def\GreSetLargestClef#1#2#3#4#5#6#7{%
-  \gre@boxclef{#1}{#2}{0}{#3}{#4}{#5}{#6}{#7}%
-  \gre@update@clefwidth@max{\wd\gre@box@temp@width}%
+% defines the largest clef of the score
+% arguments are the same as \GreSetLinesClef except that the #3 of
+% \GreSetLineClef is removed (always 1)
+\def\GreSetLargestClef#1#2#3#4#5#6{%
+  \gre@boxclef{#1}{#2}{0}{1}{#3}{#4}{#5}{#6}%
+  \gre@update@clefwidth@largest{\wd\gre@box@temp@width}%
   \relax%
 }%
 
@@ -189,6 +194,7 @@
 \newbox\gre@box@temp@clef%
 \newbox\gre@box@temp@cleftwo%
 
+% sets \gre@box@temp@width with the clef, the arguments are the same as \gre@typeclef
 \def\gre@boxclef#1#2#3#4#5#6#7#8{%
   \global\setbox\gre@box@temp@width=\hbox{%
     \ifcase#7%

tex/gregoriotex-spaces.tex

@@ -410,7 +410,7 @@
     % we don't want to kern more than clefwidth + spaceafterlineclef - minimalspaceatlinebeginning
     % violating this would mean that either the notes are closer than (clefwidth + spaceafterlineclef)
     % or that the lyrics are closer than minimalspaceatlinebeginning
-    \gre@skip@temp@one = \glueexpr(\gre@dimen@clefwidth@bol %
+    \gre@skip@temp@one = \glueexpr(\gre@dimen@clefwidth@current %
       + \gre@space@skip@spaceafterlineclef %
       - \gre@space@dimen@minimalspaceatlinebeginning)\relax %
     \ifdim\gre@skip@temp@three < \gre@skip@temp@one %
@@ -426,7 +426,7 @@
 % the width of the current
 \newdimen\gre@dimen@clefwidth@current\relax%
 % the width of the max clef
-\newdimen\gre@dimen@clefwidth@max\relax%
+\newdimen\gre@dimen@clefwidth@largest\relax%
 % the width to compute bolshift with
 \newdimen\gre@dimen@clefwidth@bol\relax%
 
@@ -439,8 +439,8 @@
   \relax %
 }
 
-\def\gre@update@clefwidth@max#1{%
-  \global\gre@dimen@clefwidth@max=#1\relax %
+\def\gre@update@clefwidth@largest#1{%
+  \global\gre@dimen@clefwidth@largest=#1\relax %
   \ifnum\gre@bolshiftcleftypelocal=1\relax %
     \global\gre@dimen@clefwidth@bol=#1\relax %
   \fi %
@@ -450,43 +450,47 @@
   \global\gre@dimen@clefwidth@bol=#1\relax %
 }
 
-% 1 for max, 2 for current and 3 for forced
+% 1 for largest, 2 for current and 3 for forced
 \xdef\gre@bolshiftcleftypeglobal{1}
 \xdef\gre@bolshiftcleftypelocal{1}
 
 \def\grebolshiftcleftype#1{
     \IfStrEqCase{#1}{%
-    {max}%
+    {largest}%
       {\xdef\gre@bolshiftcleftypeglobal{1}\xdef\gre@bolshiftcleftypelocal{1}}%
     {current}%
       {\xdef\gre@bolshiftcleftypeglobal{2}\xdef\gre@bolshiftcleftypelocal{2}}%
     }[% all other cases
-      \gre@error{Unrecognized option "#1" for \protect\grebolshiftcleftype\MessageBreak Possible options are: 'max' and 'current'.}%
+      \gre@error{Unrecognized option "#1" for \protect\grebolshiftcleftype\MessageBreak Possible options are: 'largest' and 'current'.}%
     ]%
 }
 
 \def\grelocalbolshiftcleftype#1{
     \IfStrEqCase{#1}{%
-    {max}%
+    {largest}%
       {\xdef\gre@bolshiftcleftypelocal{1}%
-      \global\gre@dimen@clefwidth@bol=\gre@dimen@clefwidth@max\relax }%
+      \global\gre@dimen@clefwidth@bol=\gre@dimen@clefwidth@largest\relax }%
     {current}%
       {\xdef\gre@bolshiftcleftypelocal{2}%
       \global\gre@dimen@clefwidth@bol=\gre@dimen@clefwidth@current\relax }%
     {c}%
-      {\gre@boxclef{c}{4}{0}{3}{c}{0}{3}{1}%
+      {\gre@boxclef{c}{3}{0}{1}{3}{c}{0}{3}%
        \xdef\gre@bolshiftcleftypelocal{3}%
        \gre@update@clefwidth@forced{\wd\gre@box@temp@width}}%
     {f}%
       {\gre@boxclef{f}{3}{0}{1}{3}{c}{0}{3}%
        \xdef\gre@bolshiftcleftypelocal{3}%
        \gre@update@clefwidth@forced{\wd\gre@box@temp@width}}%
     {cb}%
-      {\global\let\GreHyph\gre@char@zerohyph}%
+      {\gre@boxclef{c}{3}{0}{1}{8}{c}{0}{3}%
+       \xdef\gre@bolshiftcleftypelocal{3}%
+       \gre@update@clefwidth@forced{\wd\gre@box@temp@width}}%
     {fb}%
-      {\global\let\GreHyph\gre@char@zerohyph}%
+      {\gre@boxclef{f}{3}{0}{1}{8}{c}{0}{3}%
+       \xdef\gre@bolshiftcleftypelocal{3}%
+       \gre@update@clefwidth@forced{\wd\gre@box@temp@width}}%
     }[% all other cases
-      \gre@error{Unrecognized option "#1" for \protect\grelocalbolshiftcleftype\MessageBreak Possible options are: 'max', 'current', 'c', 'f', 'cb' and 'fb'.}%
+      \gre@error{Unrecognized option "#1" for \protect\grelocalbolshiftcleftype\MessageBreak Possible options are: 'largest', 'current', 'c', 'f', 'cb' and 'fb'.}%
     ]%
 }