Addresses gregorio-project#1036

`interwordspacetext` distances are changed to be dependent on the font
Instructions are added to GregorioRef for how the above is accomplished so that the user can do the same.

CHANGELOG.md

@@ -20,6 +20,7 @@ As of v3.0.0 this project adheres to [Semantic Versioning](http://semver.org/).
 - A podatus followed by a virga `(eghv)` will now be kept together (no line break between the shapes),  If you would like to allow a line break there, use `(eg/hv)` instead (see UPGRADE.md and [#1045](https://github.com/gregorio-project/gregorio/issues/1045)).
 - Penalties must now be changed using the `\grechangecount` command.  See GregorioRef and [UPGRADE.md](UPGRADE.md) for details (for the change request, see [#1021](https://github.com/gregorio-project/gregorio/issues/1021)).
 - `\greemergencystretch` must now be set by changing `emergencystretch` using `\grechangedim` instead of redefining the macro.
+- `interwordspacetext` and it's related distances are now defined as fixed distances based on the `\fontdimen` values.  This means that they will scale according to the font, not the staff size.  The documenation has been updated to explain how this is done and provide the default definitions.  See [#1036](https://github.com/gregorio-project/gregorio/issues/1036).
 
 ### Removed
 - `\grescorereference`

doc/Command_Index_User.tex

@@ -1291,10 +1291,6 @@ \subsection{Distances}\label{distances}
 Minimum space between notes of syllables from different words.
 \end{gdimension}
 
-\begin{gdimension}{interwordspacetext}
-Minimum space between texts of different words. Please keep the same \texttt{plus} and \texttt{minus} as \texttt{interwordspacenotes}.
-\end{gdimension}
-
 \begin{gdimension}{interwordspacenotes@alteration}
 Same as \texttt{interwordspacenotes} for the case where the second syllable starts with an alteration.
 \end{gdimension}
@@ -1307,10 +1303,6 @@ \subsection{Distances}\label{distances}
 Same as \texttt{interwordspacenotes} for \texttt{euouae} blocks.
 \end{gdimension}
 
-\begin{gdimension}{interwordspacetext@euouae}
-Same as \texttt{interwordspacetext} for \texttt{euouae} blocks.
-\end{gdimension}
-
 \begin{gdimension}{bitrivirspace}
 Space between notes of a bivirga or trivirga.
 \end{gdimension}
@@ -1587,7 +1579,7 @@ \subsection{Distances}\label{distances}
 Distance to place a ``rare'' sign above the top space in a score.
 \end{gdimension}
 
-\subsubsection*{Bar distances}
+\subsubsection{Bar distances}
 
 \begin{gdimension}{bar@finalfinalis}
 This space is added before the final divisio final of a score (old bar spacing algorithm only).
@@ -1669,22 +1661,6 @@ \subsubsection*{Bar distances}
 \textbf{Nota Bene:} This distance should always have a base value of 0pt.
 \end{gdimension}
 
-\begin{gdimension}{interwordspacetext@bars}
-Minimum space between texts of different words when one of the syllable contains only a bar (new bar spacing algorithm only).
-\end{gdimension}
-
-\begin{gdimension}{interwordspacetext@bars@euouae}
-Same as \texttt{interwordspacetext@bars} for \texttt{euouae} blocks (so quite rare).
-\end{gdimension}
-
-\begin{gdimension}{interwordspacetext@bars@notext}
-Minimum space between texts of adjacent words when they are separated by a bar syllable which has no text associated with it (new bar spacing algorithm only).
-\end{gdimension}
-
-\begin{gdimension}{interwordspacetext@bars@notext@euouae}
-Same as \texttt{interwordspacetext@bars@notext} for \texttt{euouae} blocks (so quite rare).
-\end{gdimension}
-
 \begin{gdimension}{textbartextspace}
 Space between the text of previous syllable and the text associated with the bar (old bar spacing algorithm only).
 \end{gdimension}
@@ -1717,6 +1693,65 @@ \subsubsection*{Bar distances}
 Same as \texttt{maxbaroffsettextleft@eol} but when the center of the text goes right of the center of the bar.
 \end{gdimension}
 
+\subsubsection{Distances tied to font size}
+In some cases it is desirable to link a distance with the size of the text font, rather than the score's staff size.  This can be accomplished in the following way:
+
+\begin{enumerate}
+  \item The distance should be defined in terms of the various \texttt{\textbackslash fontdimen} values (there are 7).  These should be prepended by \verb=\the= and can be combined or scaled using \verb=\dimexpr= and \verb=\glueexpr= (which also need to be prepended by \verb=\the= when used).
+  \item To prevent premature expansion, the entire value for the distance should be enclosed in \verb=\unexpanded=.
+  \item The distance should be defined as \texttt{fixed} relative to the staff size.  If the distance is \texttt{scalable} then any link between the distance and the font size will be broken if \verb=\grechangestaffsize= is called.
+\end{enumerate}
+
+Example:\par\medskip
+{\footnotesize
+\begin{latexcode}
+  \grechangedim{interwordspacetext}{\unexpanded{\the\fontdimen6\font}}{fixed}%
+\end{latexcode}
+}
+
+This definition for \texttt{interwordspacetext} will make it equal to the size of the font.
+
+Each of the following distances has a default which is defined in this way.  The actual definition is shown first (without the \verb=\unexpanded=), followed by the numerical default for 12pt Linux Libertine (the font in use in this document).
+
+\begin{gdimension}{interwordspacetext}
+Minimum space between texts of different words. 
+
+\textbf{Nota Bene:} To avoid unpredictable differences in the stretching/shrinking between words, the same \texttt{plus} and \texttt{minus} as \texttt{interwordspacenotes} should be used.  To ensure this here, we make use of \verb=\gluestretch= and \verb=\glueshrink= in order to call those values directly.  When combined with the call of \verb=\unexpanded= which is necessary for linking the base distance to a \texttt{\textbackslash fontdimen}, this ensures that they will always match.
+
+\definition{interwordspacetext}
+\end{gdimension}
+
+\begin{gdimension}{interwordspacetext@euouae}
+Same as \texttt{interwordspacetext} for \texttt{euouae} blocks.
+
+\definition{interwordspacetext@euouae}
+\end{gdimension}
+
+\begin{gdimension}{interwordspacetext@bars}
+Minimum space between texts of different words when one of the syllable contains only a bar (new bar spacing algorithm only).
+
+\definition{interwordspacetext@bars}
+\end{gdimension}
+
+\begin{gdimension}{interwordspacetext@bars@euouae}
+Same as \texttt{interwordspacetext@bars} for \texttt{euouae} blocks (so quite rare).
+
+\definition{interwordspacetext@bars@euouae}
+\end{gdimension}
+
+\begin{gdimension}{interwordspacetext@bars@notext}
+Minimum space between texts of adjacent words when they are separated by a bar syllable which has no text associated with it (new bar spacing algorithm only).
+
+\definition{interwordspacetext@bars@notext}
+\end{gdimension}
+
+\begin{gdimension}{interwordspacetext@bars@notext@euouae}
+Same as \texttt{interwordspacetext@bars@notext} for \texttt{euouae} blocks (so quite rare).
+
+\definition{interwordspacetext@bars@notext@euouae}
+\end{gdimension}
+
+
 
 \subsection{Penalties}\label{penalties}
 Penalties are used by \TeX\ to determine where line and page breaks should occur.  Gregorio\TeX\ modifies or defines a few of its own to help with that process in scores.  With the exception of \texttt{emergencystretch} (which should be changed using \verb=\grechangedim=) these should be changed using \verb=\grechangecount=, described above.

doc/GregorioRef.tex

@@ -87,7 +87,7 @@
   \ifbreakable%
     \filbreak%
   \else%
-    \breakabletrue%
+    \global\breakabletrue%
   \fi%
   \makebox[\linewidth]{\ttfamily\bfseries #1#2%
   \hspace{\fill}\normalfont\itshape #3}%
@@ -137,6 +137,27 @@
   Default: \expandafter$\expandafter\the\csname gre@space@count@#1\endcsname$
 }
 
+\newcommand\definition[1]{%
+  \gre@rubberpermit{#1}%
+  \ifgre@rubber%
+    \expandafter
+      \let
+    \expandafter
+      \temp
+    \csname gre@space@skip@#1\endcsname%
+  \else%
+    \expandafter
+      \let
+    \expandafter
+      \temp
+    \csname gre@space@dimen@#1\endcsname%
+  \fi%
+  Definition:
+  {\ttfamily%
+  \expandafter\strip@prefix\meaning\temp
+  }%
+}
+
 \newcommand{\writemode}[3]{%
   \gre@style@modeline #1\endgre@style@modeline %
   \gre@style@modemodifier #2\endgre@style@modemodifier %

tex/gsp-default.tex

@@ -130,12 +130,12 @@
 % stretching added in the case where the text of two syllables of the same word are
 % separated with an automatic hyphen
 \grecreatedim{intersyllablespacestretchhyphen}{0cm plus 0.05cm}{scalable}%
-% minimal space between letters of different words. Makes sense to have
-% the same plus and minus as interwordspacenotes.
-\grecreatedim{interwordspacetext}{0.38 cm plus 0.15 cm minus 0.05 cm}{scalable}%
+% minimal space between letters of different words.
+% The use of the various `\fontdimen` values ties this distance (and others which do the same) to the font size of the lyrics.  In order to make this tie dynamic, we use eTeX's `\unexpanded` primitive to prevent premature expansion (we want the `\fontdimen` values to expand at time of use, not right now).  We also declare this distance as "fixed" so that it GregorioTeX won't try to scale it when the staff size changes, as doing so would break the tie to the lyric font size.
+\grecreatedim{interwordspacetext}{\unexpanded{\the\fontdimen2\font plus \the\gluestretch\gre@space@skip@interwordspacenotes minus \the\glueshrink\gre@space@skip@interwordspacenotes}}{fixed}%
 % Versions of interword spaces for euouae blocks
 \grecreatedim{interwordspacenotes@euouae}{0.19 cm plus 0.1 cm minus 0.05 cm}{scalable}%
-\grecreatedim{interwordspacetext@euouae}{0.27 cm plus 0.1 cm minus 0.05 cm}{scalable}%
+\grecreatedim{interwordspacetext@euouae}{\unexpanded{\the\dimexpr((\the\fontdimen2\font) * 8 / 10)\relax plus \the\gluestretch\gre@space@skip@interwordspacenotes@euouae minus \the\glueshrink\gre@space@skip@interwordspacenotes@euouae\relax}}{fixed}%
 % versions of note spaces when the first note of the second syllable is an alteration
 % those are used in euouae blocks
 \grecreatedim{interwordspacenotes@alteration}{0.1 cm plus 0.07 cm minus 0.01 cm}{scalable}%
@@ -224,14 +224,14 @@
 %
 % minimal space between letters of different syllable texts for text around bars
 % (new bar spacing algorithm only)
-\grecreatedim{interwordspacetext@bars}{0.15 cm}{scalable}%
+\grecreatedim{interwordspacetext@bars}{\unexpanded{\the\dimexpr((\the\fontdimen2\font)*7/10)\relax}}{fixed}%
 % minimal space between letters of different syllable texts for text around bars,
 % euouae context
-\grecreatedim{interwordspacetext@bars@euouae}{0.15 cm}{scalable}%
-\grecreatedim{interwordspacetext@bars@notext}{0.4 cm}{scalable}%
+\grecreatedim{interwordspacetext@bars@euouae}{\unexpanded{\the\dimexpr((\the\fontdimen2\font)*7/10)\relax}}{fixed}%
+\grecreatedim{interwordspacetext@bars@notext}{\unexpanded{\the\fontdimen2\font}}{fixed}%
 % minimal space between letters of different syllable texts for text around bars,
 % euouae context
-\grecreatedim{interwordspacetext@bars@notext@euouae}{0.3 cm}{scalable}%
+\grecreatedim{interwordspacetext@bars@notext@euouae}{\unexpanded{\the\dimexpr((\the\fontdimen2\font)*7/10)\relax}}{fixed}%
 % rubber length that will be added around bars in new bar spacing algorithm
 \grecreatedim{bar@rubber}{0 cm plus 0.22787 cm minus 0.02 cm}{scalable}%
 % additional space that will appear around bars that are preceded by a custos and followed by a key.