Add option to print only the first flat on each line

CHANGELOG.md

@@ -21,6 +21,7 @@ As of v3.0.0 this project adheres to [Semantic Versioning](http://semver.org/).
 - Added a configurable setting `\gresetunisonbreakbehavior` to control automatic line breaks between unison notes above a syllable.  Defaults to `breakable` for backwards compatibility, but may be set to `unbreakable` if that behavior is desired.  See [#1504](https://github.com/gregorio-project/gregorio/issues/1504).
 - Added the ability to fuse upwards to a virga.  See [#1558](https://github.com/gregorio-project/gregorio/issues/1558)
 - Added the ability to use the "stroke" form of a clivis instead of the default two-notes form by specifying `[shape:stroke]` after the clivis to change.  See [#1558](https://github.com/gregorio-project/gregorio/issues/1558)
+- Added new alterations: soft flat (X) and sharp (##), which appear when there is no previous flat or sharp (respectively) in effect, and soft natural (Y), which appears when there is a previous flat or sharp in effect. A new option `\gresetalterationeffect` determines what the "effect" of an alteration is. It defaults to `line`, which is useful for Dominican chant. See [#157](https://github.com/gregorio-project/gregorio/issues/157) and also [#1575](https://github.com/gregorio-project/gregorio/issues/1575).
 
 
 ## [6.0.0] - 2021-03-13

UPGRADE.md

@@ -2,6 +2,10 @@
 
 This file contains instructions to upgrade to a new release of Gregorio.  These instructions are cumulative; meaning that you should apply the instructions from all versions between the one you are upgrading from and the current version.
 
+## [Unreleased][develop]
+
+GABC now has some new alterations: soft flat (`X`) and sharp (`##`), which appear when there is no previous flat or sharp (respectively) in effect, and soft natural (`Y`), which appears when there is a previous flat or sharp in effect. A new option `\gresetalterationeffect` determines what the "effect" of an alteration is. It defaults to `line`, meaning that an alteration's effect extends to the end of the line. Thus, for Dominican chant, type a soft flat (`X`) in front of _every_ note that is to be sung a half-step flat; naturals should also be soft (`Y`), but only naturals that cancel flats need to be typed.
+
 ## 6.0
 
 ### Upright punctum inclinatum

doc/Command_Index_User.tex

@@ -1408,6 +1408,24 @@ \subsubsection{Ancient Notation}
   \#2 & integer & point size at which the font should be loaded\\
 \end{argtable}
 
+\subsubsection{Alterations (Flats, Naturals, and Sharps)}\label{setalterationeffect}
+
+\macroname{\textbackslash gresetalterationeffect}{\{\#1\}}{gregoriotex-signs.tex}
+Macro to set the effect of alterations (flats and sharps), for the purpose of deciding whether to print soft alterations (see \S\ref{softalterations}).
+
+\begin{argtable}
+  \#1 & \texttt{line} (default) & effect ends at the end of the line \\
+      & \texttt{note} & effect ends immediately \\
+\end{argtable}
+
+Soft flats are printed if no previous flat (on the same pitch) is in effect. Similarly for soft sharps. Soft naturals are printed if a previous flat or sharp (on the same pitch) is in effect.
+
+Thus, under \verb|\gresetalterationeffect{line}|, all sharps and flats are in effect until the end of the line (unless cancelled by a natural), which is the convention used in Dominican chant scores. For the currently envisioned uses of soft alterations, this is the right setting.
+
+Under \verb|\gresetalterationeffect{note}|, all sharps and flats lose their effect immediately, so all soft flats and sharps are printed (but no soft naturals are printed).
+
+(Argument \#1 is actually a comma-separated list of options. If multiple options are given, then an alteration's effect ends as soon as \emph{any} of the options says it should end. However, currently, the list must not be empty, and \texttt{note,line} has the same effect as \texttt{note}, because ``immediately'' always occurs before the end of the line. In the future, other options like \texttt{word} and \texttt{bar} may be added; \texttt{word,bar} would then be the convention used in most Gregorian chant scores.)
+
 \subsection{Counts}\label{counts}
 
 Each of the following counts controls some aspect of the configuration of the Gregorio\TeX\ score.  They are changed using \verb=\grechangecount=, documented above.

doc/Command_Index_gregorio.tex

@@ -513,7 +513,7 @@ \section{Gregorio Controls}
   \#1 & integer & Height number of the flat.\\
   \#2 & \texttt{0} & The flat is not part of the clef.\\
   & \texttt{1} & The flat is part of the clef.\\
-  \#3 & \TeX\ code & signs to typeset before the glyph (typically additional bars, as they must be "behind" the glyph)\\
+  \#3 & \TeX\ code & signs to typeset before the glyph (typically additional bars, as they must be ``behind'' the glyph)\\
   \#4 & \TeX\ code & signs to typeset after the glyph (almost all signs)\\
   \#5 & string & the line, byte offset, and column address for textedit links when point-and-click is enabled\\
 \end{argtable}
@@ -525,7 +525,19 @@ \section{Gregorio Controls}
   \#1 & integer & Height number of the flat.\\
   \#2 & \texttt{0} & The flat is not part of the clef.\\
   & \texttt{1} & The flat is part of the clef.\\
-  \#3 & \TeX\ code & signs to typeset before the glyph (typically additional bars, as they must be "behind" the glyph)\\
+  \#3 & \TeX\ code & signs to typeset before the glyph (typically additional bars, as they must be ``behind'' the glyph)\\
+  \#4 & \TeX\ code & signs to typeset after the glyph (almost all signs)\\
+  \#5 & string & the line, byte offset, and column address for textedit links when point-and-click is enabled\\
+\end{argtable}
+
+\macroname{\textbackslash GreFlatSoft}{\#1\#2\#3\#4\#5}{gregoriotex-signs.tex}
+Macro to typeset a soft flat.
+
+\begin{argtable}
+  \#1 & integer & Height number of the flat.\\
+  \#2 & \texttt{0} & The flat is not part of the clef.\\
+  & \texttt{1} & The flat is part of the clef.\\
+  \#3 & \TeX\ code & signs to typeset before the glyph (typically additional bars, as they must be ``behind'' the glyph)\\
   \#4 & \TeX\ code & signs to typeset after the glyph (almost all signs)\\
   \#5 & string & the line, byte offset, and column address for textedit links when point-and-click is enabled\\
 \end{argtable}
@@ -561,7 +573,7 @@ \section{Gregorio Controls}
   & \texttt{7} & case of a stropha\\
   & \texttt{8} & flexus with an ambitus of one\\
   & \texttt{9} & flexus deminutus\\
-  \#5 & \TeX\ code & signs to typeset before the glyph (typically additional bars, as they must be "behind" the glyph)\\
+  \#5 & \TeX\ code & signs to typeset before the glyph (typically additional bars, as they must be ``behind'' the glyph)\\
   \#6 & \TeX\ code & signs to typeset after the glyph (almost all signs)\\
   \#7 & string & the line, byte offset, and column address for textedit links when point-and-click is enabled
 \end{argtable}
@@ -609,7 +621,7 @@ \section{Gregorio Controls}
   & \texttt{r} & a small episema aligned right\\
   \#6 & integer & Replacement for \#1 if a bridge causes a height substitution.\\
   \#7 & \TeX\ code & code that sets heuristics\\
-  \#8 & string & a positive or negative "nudge" (dimension) for the vertical position of the horizontal episema\\
+  \#8 & string & a positive or negative ``nudge'' (dimension) for the vertical position of the horizontal episema\\
   \#9 & \texttt{0} & for horizontal episema cases, use automatic positioning within the space\\
   & \texttt{1} & for horizontal episema cases, position in the middle of the space\\
   & \texttt{2} & for horizontal episema cases, position low within the space as if the episema is over the note\\
@@ -639,7 +651,7 @@ \section{Gregorio Controls}
   & \texttt{10} & Space between puncta inclinata (also debilis for now), larger ambitus (range=3rd).\\
   & \texttt{11} & Space between puncta inclinata (also debilis for now), larger ambitus (range=4th or more).\\
   \#4 & \TeX\ code & code that sets heuristics\\
-  \#5 & string & a positive or negative "nudge" (dimension) for the vertical position of the horizontal episema\\
+  \#5 & string & a positive or negative ``nudge'' (dimension) for the vertical position of the horizontal episema\\
   \#6 & \texttt{0} & for horizontal episema cases, use automatic positioning within the space\\
   & \texttt{1} & for horizontal episema cases, position in the middle of the space\\
   & \texttt{2} & for horizontal episema cases, position low within the space as if the episema is over the note\\
@@ -793,7 +805,7 @@ \section{Gregorio Controls}
   \#1 & integer & Height number of the natural.\\
   \#2 & \texttt{0} & The natural is not part of the clef.\\
   & \texttt{1} & The natural is part of the clef (doesn't happen).\\
-  \#3 & \TeX\ code & signs to typeset before the glyph (typically additional bars, as they must be "behind" the glyph)\\
+  \#3 & \TeX\ code & signs to typeset before the glyph (typically additional bars, as they must be ``behind'' the glyph)\\
   \#4 & \TeX\ code & signs to typeset after the glyph (almost all signs)\\
   \#5 & string & the line, byte offset, and column address for textedit links when point-and-click is enabled\\
 \end{argtable}
@@ -805,7 +817,19 @@ \section{Gregorio Controls}
   \#1 & integer & Height number of the natural.\\
   \#2 & \texttt{0} & The natural is not part of the clef.\\
   & \texttt{1} & The natural is part of the clef (doesn't happen).\\
-  \#3 & \TeX\ code & signs to typeset before the glyph (typically additional bars, as they must be "behind" the glyph)\\
+  \#3 & \TeX\ code & signs to typeset before the glyph (typically additional bars, as they must be ``behind'' the glyph)\\
+  \#4 & \TeX\ code & signs to typeset after the glyph (almost all signs)\\
+  \#5 & string & the line, byte offset, and column address for textedit links when point-and-click is enabled\\
+\end{argtable}
+
+\macroname{\textbackslash GreNaturalSoft}{\#1\#2\#3\#4\#5}{gregoriotex-signs.tex}
+Macro to typeset a soft natural.
+
+\begin{argtable}
+  \#1 & integer & Height number of the natural.\\
+  \#2 & \texttt{0} & The natural is not part of the clef.\\
+  & \texttt{1} & The natural is part of the clef (doesn't happen).\\
+  \#3 & \TeX\ code & signs to typeset before the glyph (typically additional bars, as they must be ``behind'' the glyph)\\
   \#4 & \TeX\ code & signs to typeset after the glyph (almost all signs)\\
   \#5 & string & the line, byte offset, and column address for textedit links when point-and-click is enabled\\
 \end{argtable}
@@ -1063,7 +1087,7 @@ \section{Gregorio Controls}
   \#1 & integer & Height number of the sharp.\\
   \#2 & \texttt{0} & The sharp is not part of the clef.\\
   & \texttt{1} & The sharp is part of the clef (doesn't happen).\\
-  \#3 & \TeX\ code & signs to typeset before the glyph (typically additional bars, as they must be "behind" the glyph)\\
+  \#3 & \TeX\ code & signs to typeset before the glyph (typically additional bars, as they must be ``behind'' the glyph)\\
   \#4 & \TeX\ code & signs to typeset after the glyph (almost all signs)\\
   \#5 & string & the line, byte offset, and column address for textedit links when point-and-click is enabled\\
 \end{argtable}
@@ -1075,7 +1099,19 @@ \section{Gregorio Controls}
   \#1 & integer & Height number of the sharp.\\
   \#2 & \texttt{0} & The sharp is not part of the clef.\\
   & \texttt{1} & The sharp is part of the clef (doesn't happen).\\
-  \#3 & \TeX\ code & signs to typeset before the glyph (typically additional bars, as they must be "behind" the glyph)\\
+  \#3 & \TeX\ code & signs to typeset before the glyph (typically additional bars, as they must be ``behind'' the glyph)\\
+  \#4 & \TeX\ code & signs to typeset after the glyph (almost all signs)\\
+  \#5 & string & the line, byte offset, and column address for textedit links when point-and-click is enabled\\
+\end{argtable}
+
+\macroname{\textbackslash GreSharpSoft}{\#1\#2\#3\#4\#5}{gregoriotex-signs.tex}
+Macro to typeset a soft sharp.
+
+\begin{argtable}
+  \#1 & integer & Height number of the sharp.\\
+  \#2 & \texttt{0} & The sharp is not part of the clef.\\
+  & \texttt{1} & The sharp is part of the clef (doesn't happen).\\
+  \#3 & \TeX\ code & signs to typeset before the glyph (typically additional bars, as they must be ``behind'' the glyph)\\
   \#4 & \TeX\ code & signs to typeset after the glyph (almost all signs)\\
   \#5 & string & the line, byte offset, and column address for textedit links when point-and-click is enabled\\
 \end{argtable}

doc/Command_Index_internal.tex

@@ -510,7 +510,7 @@ \section{Gregorio\TeX{} Controls}
   \#3 & character alias & the hole of the alteration\\
   \#4 & \texttt{1} & the alteration is part of the clef\\
   & \texttt{0} & the alteration is not part of the clef\\
-  \#5 & \TeX\ code & signs to typeset before the glyph (typically additional bars, as they must be "behind" the glyph)\\
+  \#5 & \TeX\ code & signs to typeset before the glyph (typically additional bars, as they must be ``behind'' the glyph)\\
   \#6 & \TeX\ code & signs to typeset after the glyph (almost all signs)\\
   \#7 & string & the line, byte offset, and column address for textedit links when point-and-click is enabled\\
 \end{argtable}
@@ -685,7 +685,7 @@ \section{Gregorio\TeX{} Controls}
   & \texttt{l} & a small episema aligned left\\
   & \texttt{c} & a small episema aligned center\\
   & \texttt{r} & for a small episema aligned right\\
-  \#6 & string & a positive or negative "nudge" (dimension) for the vertical position of the horizontal episema\\
+  \#6 & string & a positive or negative ``nudge'' (dimension) for the vertical position of the horizontal episema\\
   \#7 & \texttt{0} & for horizontal episema cases, use automatic positioning within the space\\
   & \texttt{1} & for horizontal episema cases, position in the middle of the space\\
   & \texttt{2} & for horizontal episema cases, position low within the space as if the episema is over the note\\
@@ -2386,7 +2386,10 @@ \subsection{Alteration Type}\label{alterationtype}
   \texttt{3} & sharp\\
   \texttt{4} & parenthesized flat\\
   \texttt{5} & parenthesized natural\\
-  \texttt{6} & parenthesized sharp
+  \texttt{6} & parenthesized sharp \\
+  \texttt{7} & soft flat\\
+  \texttt{8} & soft natural\\
+  \texttt{9} & soft sharp\\
  \end{tabulary}
 
 \subsection{Note Offset Specifier}\label{NoteOffset}

doc/Gabc.tex

@@ -452,10 +452,6 @@ \subsubsection{One-Note Neumes}
 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
@@ -480,6 +476,12 @@ \subsubsection{One-Note Neumes}
   \pitchchar\texttt{x} & flat \\
   \pitchchar\texttt{\#} & sharp \\
   \pitchchar\texttt{y} & natural \\
+  \pitchchar\texttt{x?} & parenthesized flat \\
+  \pitchchar\texttt{\#?} & parenthesized sharp \\
+  \pitchchar\texttt{y?} & parenthesized natural \\
+  \pitchchar\texttt{X} & soft flat \\
+  \pitchchar\texttt{\#\#} & soft sharp \\
+  \pitchchar\texttt{Y} & soft natural \\
 \end{tabularx}
 
 In the above table, \pitchchar{} represents a pitch character and
@@ -490,17 +492,49 @@ \subsubsection{One-Note Neumes}
 {
   \gresetinitiallines{0}\gresetlyriccentering{firstletter}%
   \gresetclef{invisible}\gresetlastline{justified}\greseteolcustos{manual}%
+  \ttfamily
   \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<sp>~~</sp>(G~) G>(G>) Gr(Gr) gx(gx)
-    g#(g#) gy(gy)
+    g#(g#) gy(gy) gx?(gx?) g#?(g#?) gy?(gy?)
     ( )
   }
 }
 
+\subsubsection{Alterations (Flats, Naturals, and Sharps)} \label{softalterations}
+
+Things like flats, sharps, and naturals (called ``alterations''), while not technically notes, are
+treated as one-note neumes by Gregorio\TeX.  Thus, they are also added by
+appending characters to pitch letters.
+
+Flats, sharps, and naturals each have a ``soft'' version (\verb|X|, \verb|##|, and \verb|Y|, respectively). Soft flats are printed if no previous flat (on the same pitch) is in effect. Similarly for soft sharps. Soft naturals are printed if a previous flat or sharp (on the same pitch) is in effect.
+What ``in effect'' means is controlled by the \verb|\gresetalterationeffect| macro (see \S\ref{setalterationeffect}). Soft alterations currently have two use cases.
+
+For Dominican chant (in which flats take effect until the end of a line or until cancelled by a natural), use \verb|\gresetalterationeffect{line}| (which is the default), and type a soft flat (\verb|X|) in front of \emph{every} note that is to be sung a half-step flat. Naturals should also be soft (\verb|Y|), but only naturals that cancel flats need to be typed. For example:
+
+\begin{center}\parbox{5in}{%
+  \gresetinitiallines{0}\gresetlyriccentering{firstletter}%
+  \grechangedim{spacelinestext}{0.4cm}{scalable}%
+  \grechangedim{spaceabovelines}{0.5cm}{scalable}%
+  \gresetalterationeffect{line}%
+  \ttfamily
+  \gabcsnippet{(e) (e) (e) gX(gXge) (f)gX(gXghED) (eddc) (;) (efef//hhv) gX(gXfe//fgED//efDC//ef) (;) (hhvFEf)(fv_//hhf)gY(gYghghf) (::)}
+}\end{center}
+
+Even under the convention that flats only take effect until the end of a word, if a long word has a flat that applies to two notes, one may want a flat to appear on the second note if a line break occurs between them. To do this, again use \verb|\gresetalterationeffect{line}| (the default) and type a soft flat (\verb|X|) before the second note. For example:
+\begin{center}\parbox{4in}{%
+  \gresetinitiallines{0}\gresetlyriccentering{firstletter}%
+  \grechangestyle{translation}{\ttfamily}%
+  \grechangedim{spacelinestext}{0.4cm}{scalable}%
+  \grechangedim{translationheight}{0.4cm}{scalable}%
+  \grechangedim{spaceabovelines}{0.5cm}{scalable}%
+  \gresetalterationeffect{line}%
+  \gabcsnippet{(c3) (d)(fh) (fe/hh)(ih..) (,) (hij) (kvJIH'i)(h.) (,) (k)(ij)(k) (jvIH'i) (h.) (;) mi[gx](gxfghz)se[gX](gXhvGF)re(e[ll:1]d)re(ef) (d_[oh:h]e_[oh:h]d_[oh:h])(d.) (::)}
+}\end{center}
+
 \subsubsection{Oriscus Orientation}
 
 Under the default rules for oriscus orientation, the direction of an oriscus
@@ -527,9 +561,9 @@ \subsubsection{Complex Neumes}
   \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
+  \pitchchar\texttt{q} & quadratum (for making a ``square'' pes shape; see
                example below) \\
-  \pitchchar\texttt{W} & quilisma quadratum (similarly, for making a "square"
+  \pitchchar\texttt{W} & quilisma quadratum (similarly, for making a ``square''
                quilisma shape) \\
   \pitchchar\texttt{ss} & distropha \\
   \pitchchar\texttt{sss} & tristropha \\
@@ -1148,7 +1182,7 @@ \subsection{Vowel file}\label{customvowels}
 
 \item[secondary]
 
-The "secondary" keyword lists strings of characters which do not contain
+The \texttt{secondary} keyword lists strings of characters which do not contain
 vowels, but for which, when there are no vowels present in a syllable,
 define the center of the syllable.  These strings follow the keyword and
 must be separated by space and end with a semicolon.  Examples of

src/gabc/gabc-glyphs-determination.c

@@ -138,10 +138,13 @@ static char add_note_to_a_glyph(gregorio_glyph_type current_glyph_type,
         break;
     case S_FLAT:
     case S_FLAT_PAREN:
+    case S_FLAT_SOFT:
     case S_SHARP:
     case S_SHARP_PAREN:
+    case S_SHARP_SOFT:
     case S_NATURAL:
     case S_NATURAL_PAREN:
+    case S_NATURAL_SOFT:
         next_glyph_type = G_ALTERATION;
         *end_of_glyph = DET_END_OF_BOTH;
         break;