Added the ability to change a dimension for a given line in a score.

CHANGELOG.md

@@ -11,6 +11,9 @@ As of v3.0.0 this project adheres to [Semantic Versioning](http://semver.org/).
 - In cases of a syllable without note, the space between notes of the previous and next syllables was sometimes not enough (see [#1137](https://github.com/gregorio-project/gregorio/issues/1137)).
 - `moraadjustment` and `moraadjustmentbar` did not scale when changing factor, they do now.
 
+### Added
+- Some vertical spaces can now be adjusted for a particular line in a score.  Use `\grechangenextscorelinedim` prior to including the score to set the desired values.  `spaceabovelines`, `spacebeneathtext`, and `spacelinestext` may be changed with this command.  See GregorioRef and [#1156](https://github.com/gregorio-project/gregorio/issues/1156) for details.
+
 ### Changed
 - When the clef and the first note are at a reasonable vertical distance, `shortspaceafterlineclef` is used instead of `spaceafterlineclef` (make them equal if you don't want this feature). This is used only on the first line, when there is an initial on one line. See [#1138](https://github.com/gregorio-project/gregorio/issues/1138).
 - When an alteration follows a bar, it is not completely taken into consideration in the new bar spacing algorithm (similarly to the punctum mora), this behavior can be tuned with the newly introduced space `alterationadjustmentbar`. See [#1146](https://github.com/gregorio-project/gregorio/issues/1146).

doc/Command_Index_User.tex

@@ -249,6 +249,18 @@ \subsubsection{Fine Tuning Dimensions}
   & \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 grechangenextscorelinedim}{\{\#1\}\{\#2\}\{\#3\}\{\#4\}}{gregoriotex-spaces.tex}
+Changes one of Gregorio\TeX’s distances for a given line in the next included score.  This works with \texttt{spaceabovelines}, \texttt{spacebeneathtext}, and \texttt{spacelinestext}.
+
+\begin{argtable}
+  \#1 & integer & The number of the line in the next score to be adjusted.\\
+  \#2 & string & The name of the distance to be changed.  See \nameref{distances} below.\\
+  \#3 & 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.\\
+  \#4 & \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 \#3 should be the name of another Gregorio\TeX\ distance.
+\end{argtable}
+
 \macroname{\textbackslash grescaledim}{\{\#1\}\{\#2\}}{gregoriotex-spaces.tex}
 Macro to turn on or off scaling with the staff size for a particular distance.
 

doc/Command_Index_internal.tex

@@ -1209,6 +1209,11 @@ \section{Gregorio\TeX{} Controls}
 \macroname{\textbackslash gre@dimension}{}{gregoriotex-spaces.tex}
 Workhorse function for setting distances in \verb=\grecreatedim= and \verb=\grechangedim=.
 
+\macroname{\textbackslash gre@changedimforline}{\#1\#2\#3}{gregoriotex-spaces.tex}
+Saves the current value of the dimension and then changes it.  The arguments
+are the same as \verb=\grechangedim=.  Used to temporarily change the dimension
+for a given line, which is restored at the next beginning of the next line.
+
 \macroname{\textbackslash gre@setstafflines}{\#1}{gregoriotex-main.tex}
 Sets the number of staff lines.
 

doc/Makefile.am

@@ -30,7 +30,7 @@ GregorioRef.pdf: $(SRCFILES)
 	$(MAKE) $(AM_MAKEFLAGS) -C ../src gregorio
 	../src/gregorio -o factus.gtex $(<D)/factus.gabc
 	TEXINPUTS=$(<D):$(<D)/../tex: LUAINPUTS=$(<D):$(<D)/../tex: \
-		 TTFONTS=$(<D)/../fonts: PATH=../src:${PATH} latexmk -recorder -pdf \
+		 TTFONTS=$(<D)/../fonts: PATH=../src:${PATH} latexmk -f -recorder -pdf \
 		 -interaction=nonstopmode -halt-on-error \
 		 -pdflatex='lualatex --shell-escape %O %S' \
 		 -jobname=GregorioRef $< || rm $@

tex/gregoriotex-spaces.tex

@@ -1412,6 +1412,40 @@
   \fi%
 }
 
+% same arguments as \grechangedim, but used for setting the dimension for a
+% single line
+\def\gre@changedimforline#1#2#3{%
+  \gre@rubberpermit{#1}%
+  \ifgre@rubber%
+    \def\gre@prefix{skip}%
+  \else%
+    \def\gre@prefix{dimen}%
+  \fi%
+  \directlua{%
+    gregoriotex.save_dim(%
+      "\luatexluaescapestring{\gre@prefix @#1}",%
+      "\luatexluaescapestring{\expandafter\unexpanded%
+        \expandafter\expandafter\expandafter{%
+          \csname gre@space@\gre@prefix @#1\endcsname%
+        }%
+      }"%
+    )%
+  }%
+  \grechangedim{#1}{#2}{#3}%
+}%
+
+% #1 : line number
+% #2-#4 : same as #1-#3 of \grechangedim
+\def\grechangenextscorelinedim#1#2#3#4{%
+  \directlua{%
+    gregoriotex.change_next_score_line_dim(#1,%
+      "\luatexluaescapestring{#2}",%
+      "\luatexluaescapestring{#3}",%
+      "\luatexluaescapestring{#4}"%
+    )%
+  }%
+}%
+
 \newcount\gre@space@count@newlinepenalty%
 \newcount\gre@space@count@nobreakpenalty%
 \newcount\gre@space@count@endofwordpenalty%

tex/gregoriotex.lua

@@ -104,6 +104,9 @@ local capture_header_macro = {}
 local hashed_spaces = {}
 local space_hash = ''
 
+local per_line_dims = {}
+local saved_dims = {}
+
 local catcode_at_letter = luatexbase.catcodetables['gre@atletter']
 
 local user_defined_subtype = node.subtype('user_defined')
@@ -221,8 +224,8 @@ local function write_greaux()
       for id, tab in pairs(new_line_heights) do
         aux:write(string.format('  ["%s"]={\n', id))
         for id2, line in pairs(tab) do
-          aux:write(string.format('   [%d]={%d,%d,%d,%d},\n', id2, line[1],
-              line[2], line[3], line[4]))
+          aux:write(string.format('   [%d]={%d,%d,%d,%d,%d},\n', id2, line[1],
+              line[2], line[3], line[4], line[5]))
         end
         aux:write('  },\n')
       end
@@ -530,7 +533,7 @@ local function post_linebreak(h, groupcode, glyphes)
           addash=false
         end
         if line_id then
-          new_score_heights[prev_line_id] = { line_top, line_bottom,
+          new_score_heights[prev_line_id] = { linenum, line_top, line_bottom,
               line_has_translation and 1 or 0,
               line_has_abovelinestext and 1 or 0 }
           prev_line_id = line_id
@@ -664,6 +667,8 @@ end
 local function atScoreEnd()
   luatexbase.remove_from_callback('post_linebreak_filter', 'gregoriotex.post_linebreak')
   luatexbase.remove_from_callback("hyphenate", "gregoriotex.disable_hyphenation")
+  per_line_dims = {}
+  saved_dims = {}
 end
 
 local function clean_old_gtex_files(file_withdir)
@@ -1038,16 +1043,46 @@ local function adjust_line_height(inside_discretionary)
   if score_heights then
     local heights = score_heights[tex.getattribute(glyph_id_attr)]
     if heights then
+      -- restore saved dims
+      local name, value
+      for name, value in pairs(saved_dims) do
+        tex.sprint(catcode_at_letter, string.format(
+            [[\def\gre@space@%s{%s}]], name, value))
+      end
+      -- clear saved dims
+      saved_dims = {}
+      -- apply per-line dims
+      local line_dims = per_line_dims[heights[1]]
+      if line_dims ~= nil then
+        for name, value in pairs(line_dims) do
+          tex.sprint(catcode_at_letter, string.format(
+              [[\gre@changedimforline{%s}{%s}{%s}]], name, value[1], value[2]))
+        end
+      end
+      -- recalculate spaces
       tex.sprint(catcode_at_letter, string.format(
           [[\gre@calculate@additionalspaces{%d}{%d}{%d}{%d}]],
-          heights[1], heights[2], heights[3], heights[4]))
+          heights[2], heights[3], heights[4], heights[5]))
       if inside_discretionary == 0 then
         tex.sprint(catcode_at_letter, [[\gre@updateleftbox ]])
       end
     end
   end
 end
 
+local function save_dim(name, value)
+  saved_dims[name] = value
+end
+
+local function change_next_score_line_dim(linenum, name, value, modifier)
+  local line_dims = per_line_dims[linenum]
+  if line_dims == nil then
+    line_dims = {}
+    per_line_dims[linenum] = line_dims
+  end
+  line_dims[name] = { value, modifier }
+end
+
 local function prep_save_position(index, fn)
   if saved_positions[cur_score_id] == nil then
     saved_positions[cur_score_id] = {}
@@ -1244,40 +1279,42 @@ local function hash_spaces(name, value)
   space_hash = md5.sumhexa(mash)
 end
 
-gregoriotex.number_to_letter         = number_to_letter
-gregoriotex.init                     = init
-gregoriotex.include_score            = include_score
-gregoriotex.atScoreEnd               = atScoreEnd
-gregoriotex.atScoreBeginning         = atScoreBeginning
-gregoriotex.check_font_version       = check_font_version
-gregoriotex.get_gregorioversion      = get_gregorioversion
-gregoriotex.map_font                 = map_font
-gregoriotex.init_variant_font        = init_variant_font
-gregoriotex.change_score_glyph       = change_score_glyph
-gregoriotex.reset_score_glyph        = reset_score_glyph
-gregoriotex.scale_score_fonts        = scale_score_fonts
-gregoriotex.set_font_factor          = set_font_factor
-gregoriotex.def_symbol               = def_symbol
-gregoriotex.font_size                = font_size
-gregoriotex.direct_gabc              = direct_gabc
-gregoriotex.adjust_line_height       = adjust_line_height
-gregoriotex.var_brace_len            = var_brace_len
-gregoriotex.save_length              = save_length
-gregoriotex.mark_translation         = mark_translation
-gregoriotex.mark_abovelinestext      = mark_abovelinestext
-gregoriotex.width_to_bp              = width_to_bp
-gregoriotex.hypotenuse               = hypotenuse
-gregoriotex.rotation                 = rotation
-gregoriotex.scale_space              = scale_space
-gregoriotex.set_header_capture       = set_header_capture
-gregoriotex.capture_header           = capture_header
-gregoriotex.is_ypos_different        = is_ypos_different
-gregoriotex.save_euouae              = save_euouae
-gregoriotex.mode_part                = mode_part
-gregoriotex.set_debug_string         = set_debug_string
-gregoriotex.late_save_position       = late_save_position
-gregoriotex.is_last_syllable_on_line = is_last_syllable_on_line
-gregoriotex.hash_spaces              = hash_spaces
+gregoriotex.number_to_letter           = number_to_letter
+gregoriotex.init                       = init
+gregoriotex.include_score              = include_score
+gregoriotex.atScoreEnd                 = atScoreEnd
+gregoriotex.atScoreBeginning           = atScoreBeginning
+gregoriotex.check_font_version         = check_font_version
+gregoriotex.get_gregorioversion        = get_gregorioversion
+gregoriotex.map_font                   = map_font
+gregoriotex.init_variant_font          = init_variant_font
+gregoriotex.change_score_glyph         = change_score_glyph
+gregoriotex.reset_score_glyph          = reset_score_glyph
+gregoriotex.scale_score_fonts          = scale_score_fonts
+gregoriotex.set_font_factor            = set_font_factor
+gregoriotex.def_symbol                 = def_symbol
+gregoriotex.font_size                  = font_size
+gregoriotex.direct_gabc                = direct_gabc
+gregoriotex.adjust_line_height         = adjust_line_height
+gregoriotex.var_brace_len              = var_brace_len
+gregoriotex.save_length                = save_length
+gregoriotex.mark_translation           = mark_translation
+gregoriotex.mark_abovelinestext        = mark_abovelinestext
+gregoriotex.width_to_bp                = width_to_bp
+gregoriotex.hypotenuse                 = hypotenuse
+gregoriotex.rotation                   = rotation
+gregoriotex.scale_space                = scale_space
+gregoriotex.set_header_capture         = set_header_capture
+gregoriotex.capture_header             = capture_header
+gregoriotex.is_ypos_different          = is_ypos_different
+gregoriotex.save_euouae                = save_euouae
+gregoriotex.mode_part                  = mode_part
+gregoriotex.set_debug_string           = set_debug_string
+gregoriotex.late_save_position         = late_save_position
+gregoriotex.is_last_syllable_on_line   = is_last_syllable_on_line
+gregoriotex.hash_spaces                = hash_spaces
+gregoriotex.save_dim                   = save_dim
+gregoriotex.change_next_score_line_dim = change_next_score_line_dim
 
 dofile(kpse.find_file('gregoriotex-nabc.lua', 'lua'))
 dofile(kpse.find_file('gregoriotex-signs.lua', 'lua'))