Trace

VersionManager.py

@@ -61,6 +61,7 @@
                   "tex/gregoriotex-nabc.tex",
                   "tex/gregoriotex-nabc.lua",
                   "tex/gregoriosyms.sty",
+                  "tex/gregoriotex-common.tex",
                   "fonts/squarize.py",
                  ]
 

contrib/system-setup.bat

@@ -96,6 +96,7 @@ gregoriotex-nabc.tex ^
 gregoriotex-signs.tex ^
 gregoriotex-spaces.tex ^
 gregoriotex-syllable.tex ^
+gregoriotex-common.tex ^
 gregoriotex-symbols.tex
 
 for %%G in (%files%) do (

contrib/system-setup.command

@@ -130,6 +130,7 @@ gregoriotex-spaces.tex
 gregoriotex-syllable.tex
 gregoriotex-symbols.lua
 gregoriotex-symbols.tex
+gregoriotex-common.tex
 gregoriotex.lua"
 
 for f in $files

doc/Command_Index_internal.tex

@@ -47,7 +47,7 @@ \section{Gregorio\TeX{} Controls}
   \#1 & \MP{} commands & The \MP{} commands to execute.
 \end{argtable}
 
-\macroname{\textbackslash gre@deprecated}{\#1\#2}{gregoriotex-main.tex}
+\macroname{\textbackslash gre@deprecated}{\#1\#2}{gregoriotex-common.tex}
 Macro that handles deprecation messages. By default, deprecated macros
 are allowed and a warning is printed. If the package option
 \texttt{deprecated=false} is set, then deprecated macros raise a
@@ -58,7 +58,7 @@ \section{Gregorio\TeX{} Controls}
   \#2 & string & name of the correct macro to use\\
 \end{argtable}
 
-\macroname{\textbackslash gre@obsolete}{\#1\#2}{gregoriotex-main.tex}
+\macroname{\textbackslash gre@obsolete}{\#1\#2}{gregoriotex-common.tex}
 Macro that handles obsolescence errors.
 
 \begin{argtable}
@@ -929,14 +929,27 @@ \section{Gregorio\TeX{} Controls}
 \macroname{\textbackslash gre@debug}{}{gregoriotex.sty \textup{and} gregoriotex.tex}
 Macro to hold the list of debug messages which should be designated as printing.  Contains comma-separated values from \Nameref{DebugCategory}, set via the \texttt{debug} package keyword parameter.
 
-\macroname{\textbackslash gre@debugmsg}{\#1\#2}{gregoriotex-main.tex}
+\macroname{\textbackslash gre@debugmsg}{\#1\#2}{gregoriotex-common.tex}
 Macro to print debugging messages.
 
 \begin{argtable}
   \#1 & string & The category of the message (used in conjunction with \verb=\gre@debug= to determine whether to print the message or not; see \Nameref{DebugCategory}\\
   \#2 & string & The debug message\\
 \end{argtable}
 
+\macroname{\textbackslash gre@trace}{\#1}{gregoriotex-common.tex}
+Macro to mark the beginning of a function in the log with a GreTrace message.
+
+\begin{argtable}
+  \#1 & string & name and argument list of the function being identified.
+\end{argtable}
+
+\macroname{\textbackslash gre@trace@end}{\#1}{gregoriotex-common.tex}
+Macro to mark the end of a function in the log with a GreTrace message.
+
+\macroname{\textbackslash gre@trace@prefix}{gregoriotex-common.tex}
+Macro to hold the prefix of GreTrace messages (value is manipulated to control indentation and indicate nesting).
+
 \macroname{\textbackslash gre@declarefileversion}{\#1\#2}{gregoriotex-main.tex}
 Macro which checks for version consistency between Gregorio\TeX\ files.
 
@@ -1015,7 +1028,7 @@ \section{Gregorio\TeX{} Controls}
 \macroname{\textbackslash gre@nextmiddlesyllablepart}{}{gregoriotex-syllable.tex}
 Macro which stores the middle part of the next syllable (the part which aligns with the notes).
 
-\macroname{\textbackslash gre@fixdebug}{}{gregoriotex-main.tex}
+\macroname{\textbackslash gre@fixdebug}{}{gregoriotex-common.tex}
 Fixes the raw \verb=\gre@debug= value for use with \verb=\gre@debugmsg=.
 
 \macroname{\textbackslash gre@fixedtextformat}{\#1}{gregoriotex-syllable.tex}
@@ -2343,6 +2356,7 @@ \subsection{Debug Category}\label{DebugCategory}
   \item[spacing] Random spacing-related messages.
   \item[syllablerewriting] Syllable rewrite messages.  Generated when rewriting syllables for better kerning and ligaturing.
   \item[syllablespacing] Syllable spacing computations.
+  \item[trace] Messages to trace the calling of functions.
 \end{description}
 \end{shaded*}
 

tex/Makefile.am

@@ -20,4 +20,5 @@ EXTRA_DIST = gregoriotex.tex gregoriotex.lua gregoriotex.sty \
 			 gregoriotex-spaces.tex gregoriotex-signs.tex \
 			 gregoriosyms.sty gsp-default.tex gregoriotex-chars.tex \
 			 gregoriotex-main.tex gregoriotex-nabc.tex gregoriotex-nabc.lua \
-			 gregoriotex-signs.lua gregoriotex-symbols.lua gregorio-vowels.dat
+			 gregoriotex-signs.lua gregoriotex-symbols.lua gregorio-vowels.dat \
+			 gregoriotex-common.tex

tex/gregoriosyms.sty

@@ -59,44 +59,8 @@
 
 \ProcessKeyvalOptions*
 
-\def\gre@debugmsg#1#2{%
-  \IfStrEq{\gre@debug}{}{}%
-    %false
-    {\IfStrEq{#1}{all}%
-      %true
-      {\gre@error{Debug error: ‘all’ is not a permitted keyword}}%
-      %false
-      {\IfStrEq{\gre@debug}{all}%
-        %true
-        {\gre@typeout{GregorioTeX debug: (#1) #2}}%
-        %false
-        {\IfSubStr{\gre@debug}{#1}%
-          %true
-          {\gre@typeout{GregorioTeX debug: (#1) #2}}%
-          %false
-          {\relax}%
-        }%
-      }%
-    }%
-}%
-
-% Macro to handle deprecated macros.
-% #1 - the deprecated macro
-% #2 - the correct macro to use
-\def\gre@deprecated#1#2{%
-  \ifgre@allowdeprecated%
-    \gre@warning{#1\space is deprecated.\MessageBreak Use #2\space instead}%
-  \else%
-    \gre@error{#1\space is deprecated.\MessageBreak Use #2\space instead}%
-  \fi%
-  \relax%
-}%
+\input gregoriotex-common.tex
 
-\def\gre@obsolete#1#2{%
-  \gre@error{#1\space is obsolete.\MessageBreak Use #2\space instead}%
-  \relax%
-}%
-\AtBeginDocument{\IfStrEq{\gre@debug}{}{}{\typeout{GregorioTeX is in debug mode}\typeout{\gre@debug\space messages will be printed to the log.}}}%
 
 \long\def\gre@iflatex#1{#1}
 \long\def\gre@ifnotlatex#1{}

tex/gregoriotex-chars.tex

@@ -30,6 +30,7 @@
 % horizontal episema
 \newbox\gre@box@hep%
 \def\gre@def@char@he#1#2{%
+  \gre@trace{gre@def@char@he{#1}{#2}}%
   \expandafter\def\csname gre@char@he@#1\endcsname##1{%
     \ifx##1f\csname GreCPHEpisema#2\endcsname%
     \else%
@@ -41,8 +42,10 @@
       }%
     \fi%
   }%
+  \gre@trace@end%
 }%
 \def\gre@def@char@he@porr#1#2{%
+  \gre@trace{gre@def@char@he@porr{#1}{#2}}%
   \expandafter\def\csname gre@char@he@#1\endcsname##1##2{%
     \ifcase##1\gre@char@he@punctum{##2}%
     \or\csname GreCPHEpisema#2One\endcsname%
@@ -52,6 +55,7 @@
     \or\csname GreCPHEpisema#2Five\endcsname%
     \fi%
   }%
+  \gre@trace@end%
 }%
 \gre@def@char@he{punctum}{Punctum}%
 \gre@def@char@he{punctum@line@br}{PunctumLineBR}%

tex/gregoriotex-common.tex

@@ -0,0 +1,111 @@
+%GregorioTeX common file (stuff needed by both gregoriotex and gregoriosyms)
+%
+% Copyright (C) 2007-2017 The Gregorio Project (see CONTRIBUTORS.md)
+%
+% This file is part of Gregorio.
+%
+% Gregorio is free software: you can redistribute it and/or modify
+% it under the terms of the GNU General Public License as published by
+% the Free Software Foundation, either version 3 of the License, or
+% (at your option) any later version.
+%
+% Gregorio is distributed in the hope that it will be useful,
+% but WITHOUT ANY WARRANTY; without even the implied warranty of
+% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+% GNU General Public License for more details.
+%
+% You should have received a copy of the GNU General Public License
+% along with Gregorio.  If not, see <http://www.gnu.org/licenses/>.
+
+\gre@declarefileversion{gregoriotex-commonx.tex}{5.0.0-beta2}% GREGORIO_VERSION
+
+
+%%%%%%%%%
+%% Debugging
+%%%%%%%%%
+
+\def\gre@debugmsg#1#2{%
+  \IfStrEq{\gre@debug}{}{}%
+    %false
+    {\IfStrEq{#1}{all}%
+      %true
+      {\gre@error{Debug error: ‘all’ is not a permitted keyword}}%
+      %false
+      {\IfStrEq{\gre@debug}{,all,}%
+        %true
+        {\gre@typeout{GregorioTeX debug: (#1) #2}}%
+        %false
+        {\IfSubStr{\gre@debug}{,#1,}%
+          %true
+          {\gre@typeout{GregorioTeX debug: (#1) #2}}%
+          %false
+          {\relax}%
+        }%
+      }%
+    }%
+}%
+
+\def\gre@fixdebug{%
+  {% we're starting a group in order to localize \exploregroups
+    \exploregroups%
+    \StrRemoveBraces{\gre@debug}[\gre@debug]%
+    \xdef\gre@debug{,\gre@debug,}%
+  }%
+}%
+
+\IfStrEq{\gre@debug}{}{% then
+}{% else
+  \typeout{GregorioTeX is in debug mode}%
+  \typeout{\gre@debug\space messages will be printed to the log.}%
+  \gre@fixdebug\relax %
+}%
+
+%%%%%%%%%%%%%
+% Macros to handle deprecation path.
+%%%%%%%%%%%%%
+
+% #1 - the deprecated macro
+% #2 - the correct macro to use
+\def\gre@deprecated#1#2{%
+  \ifgre@allowdeprecated%
+    \gre@warning{#1\space is deprecated.\MessageBreak Use #2\space instead}%
+  \else%
+    \gre@error{#1\space is deprecated.\MessageBreak Use #2\space instead}%
+  \fi%
+  \relax%
+}%
+
+\def\gre@obsolete#1#2{%
+  \gre@error{#1\space is obsolete.\MessageBreak Use #2\space instead}%
+  \relax%
+}%
+
+%%%%%%%%%%%%%
+% Internal function tracing
+%%%%%%%%%%%%%
+
+% Each function in the internal name space (\gre@...) should have an invocation of
+% \gre@trace as its first line with the argument being the name of the function (without
+% the backslash) and the list of arguments.
+% The last line of these functions should be \gre@trace@end.
+% Macros which merely store a value are not considered to be functions and thus not
+% included in the trace stack.
+% We also exempt the internal aliases for functions defined elsewhere.
+% The tracing messages are turned on via the debug interface, keyword: trace.
+
+\def\gre@trace@prefix{GreTrace: }
+\def\gre@trace#1{%
+  \IfSubStr{\gre@debug}{,trace,}%
+    {%print tracing messages and increase indent
+      \gre@typeout{\gre@trace@prefix \unexpanded{#1}}%
+      \edef\gre@trace@prefix{\gre@trace@prefix| }%
+    }{}%do nothing if not tracing
+}%
+\def\gre@trace@end{%
+  \IfSubStr{\gre@debug}{,trace,}%
+    {%dedent trace messages and mark end
+      \StrGobbleRight{\gre@trace@prefix}{2}[\gre@trace@prefix]%
+      \gre@typeout{\gre@trace@prefix -----}%
+    }{}%do nothing if not tracing
+}
+