Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Moved initial handling to TeX #671

Merged
merged 12 commits into from
Dec 3, 2015
13 changes: 13 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,24 @@ 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
- Initial handling has been simplified. The initial style should now be specified from TeX by using the `\gresetinitiallines` command, rather than from a gabc header. Big initials and normal initials are now governed by a single `initial` style, meant to be changed between scores as appropriate. See [UPGRADE.md](UPGRADE.md) and GregorioRef for details (for the change request, see [#632](https://github.com/gregorio-project/gregorio/issues/632)). Deprecations for this change are listed in the Deprecation section, below.

### Added
- Salicus flexus glyphs (See [#631](https://github.com/gregorio-project/gregorio/issues/631)).

### Deprecated
- `initial-style` gabc header, supplanted by the `\gresetinitiallines` TeX command.
- `biginitial` style, consolidated into the `initial` style.


## [4.0.0-rc2] - 2015-11-05
### Deprecated
- `initial-style` gabc header, supplanted by the `\gresetinitiallines` TeX command.
- `biginitial` style, consolidated into the `initial` style.


## [Unreleased][unreleased]
### Fixed
- The spacing of manual in-line custos (`(f+)` in gabc) is now consistent with the spacing of automatic in-line custos (`(z0)` in gabc). See [#642](https://github.com/gregorio-project/gregorio/issues/642).
- Signs on the climacus praepunctis deminutus `(ghgf~)` neume are now positioned correctly. See [#650](https://github.com/gregorio-project/gregorio/issues/650)
Expand Down
14 changes: 14 additions & 0 deletions UPGRADE.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,20 @@

This file contains instructions to upgrade to a new release of Gregorio.

## 4.1

### Initial handling

Initial handling has been simplified. This deprecates the `initial-style` gabc header and the `biginitial` style.

Rather than using the `initial-style` gabc header, set the number of lines the initial should use in Tex with the `\gresetinitiallines` command. It currently accepts 0 (for no initial), 1 (for a one-line initial), or 2 (for a two-line initial).

As for the `biginitial` style, the intent is that the `initial` style be changed within the TeX document whenever the initial style should change, regardless of how many lines the initial requires. For example, before including a score that has a two-line initial, you would probably want to redefine the `initial` style to use a larger font. Then, before including a score which requires a one-line initial, you would then redefine the `initial` style back to what it was before.

In order to allow a smoother transition to the new behavior, GregorioTeX will behave differently depending on whether or not deprecated usage is allowed (controlled by the `[allowdeprecated]` package option). If deprecated usage is allowed, GregorioTeX will use the deprecated `biginitial` style for big initials. If not, GregorioTeX will use the `initial` style for big initials.

Since the `biginitial` style will disappear with Gregorio 5.0, please consider disabling deprecated usage (set `[allowdeprecated=false]` when using the `gregoriotex` package) and use the `initial` style as just described.

## 4.0

### Font changes
Expand Down
22 changes: 12 additions & 10 deletions doc/Command_Index_User.tex
Original file line number Diff line number Diff line change
Expand Up @@ -165,20 +165,17 @@ \subsubsection{Including scores}
\gregorioscore[a]{TecumPrincipium} % gabc auto compiled.
\end{latexcode}

\macroname{\textbackslash gabcsnippet}{[\optional{\#1}]\{\#2\}}{gregoriotex-main.tex}
Converts the gabc notation specified in \texttt{\#2} to Gregorio\TeX\ and
includes it directly in the document. The optional argument \texttt{[\#1]}
may be used to specify a gabc \texttt{initial-style}, which defaults to
\texttt{1}.
\macroname{\textbackslash gabcsnippet}{\{\#1\}}{gregoriotex-main.tex}
Converts the gabc notation specified in \texttt{\#1} to Gregorio\TeX\ and
includes it directly in the document.

\begin{argtable}
\#1 & number & Optional. The gabc \texttt{initial-style} value to use.\\
\#2 & string & The gabc to insert into the document.\\
\#1 & string & The gabc to insert into the document.\\
\end{argtable}

\medskip For example:\par\medskip
\begin{latexcode}
\gabcsnippet[0]{(c3) Al(eg~)le(gv.fhg)lu(efe___)ia(e.) (::)}
\gabcsnippet{(c3) Al(eg~)le(gv.fhg)lu(efe___)ia(e.) (::)}
\end{latexcode}


Expand Down Expand Up @@ -611,8 +608,7 @@ \subsubsection{Styling}
\begin{tabular}{lp{7cm plus .5cm}r}
Element Name & Description & Default\\
\hline
\stylename{initial} & Normal Initials & 40 pt font\\
\stylename{biginitial} & Big (2-Line) Initials & 80 pt font\\
\stylename{initial} & Score initial (the first letter of the score, when offset from the rest of the text) & 40 pt font\\
\stylename{translation} & Translation text (appears below lyrics) & {\it italics}\\
\stylename{abovelinestext} & Above line text (\texttt{<alt></alt>} in gabc, appears above the staff) & normal\\
\stylename{normalstafflines} & Full length staff lines & none\\
Expand Down Expand Up @@ -698,6 +694,12 @@ \subsubsection{Text Elements}

\textbf{Nota Bene:} Usually the argument of this command should be an \verb=\includegraphics= command, but you may use what ever you want as the illuminated initial.

\macroname{\textbackslash gresetinitiallines}{\#1}{gregoriotex-syllable.tex}
Sets the number of lines the score initial requires.

\begin{argtable}
\#1 & number & The number of lines required by the initial. If \texttt{0}, the score will have no separated initial.\\
\end{argtable}

\subsubsection{Text Alignment}
Gregorio\TeX\ allows you to manipulate the global alignment behavior of some text elements using the following commands.
Expand Down
42 changes: 24 additions & 18 deletions doc/Command_Index_gregorio.tex
Original file line number Diff line number Diff line change
Expand Up @@ -54,13 +54,6 @@ \section{Gregorio Controls}
\#3 & integer & Set horizontal episema (0), horizontal episema under a note (1), line at top of staff (2), line at bottom of staff (3), choral sign (4).\\
\end{argtable}

\macroname{\textbackslash GreAdjustSecondLine}{}{gregoriotex.tex}
%didn't actually find this one in gregoriotex-write.c, classified it here based on it’s related function GreAdjustThirdLine
Macro to call before first syllable, but after \verb=\GreSetInitialClef=.

\macroname{\textbackslash GreAdjustThirdLine}{}{gregoriotex-main.tex}
Macro to call during the second line.

\macroname{\textbackslash GreAugmentumDuplex}{\#1\#2\#3}{gregoriotex-signs.tex}
Macro for typesetting an augmentum duplex (a pair of punctum mora)

Expand Down Expand Up @@ -114,9 +107,6 @@ \section{Gregorio Controls}
& \texttt{1} & Call came from translation centering.
\end{argtable}

\macroname{\textbackslash GreBeginNotes}{}{gregoriotex.tex}
Macro to draw the staff lines. Comes after the initial but before the clef.

\macroname{\textbackslash GreBold}{\#1}{gregoriotex.sty and gregoriotex.tex}
Makes argument bold. Accesses \LaTeX\ \verb=\textbf= (\textit{gregoriotex.sty}) or Plain \TeX\ \verb=\bf= (\textit{gregoriotex.tex}) as appropriate. Corresponds to ``<b></b>'' tags in gabc.

Expand Down Expand Up @@ -532,9 +522,6 @@ \section{Gregorio Controls}
\#1 & integer & Height number of the custos.\\
\end{argtable}

\macroname{\textbackslash GreNoInitial}{}{gregoriotex-main.tex}
Macro called when no initial is being set.

\macroname{\textbackslash GreOverBrace}{\#1\#2\#3\#4}{gregoriotex-signs.tex}
Macro to typeset a round brace above the lines.

Expand Down Expand Up @@ -625,6 +612,16 @@ \section{Gregorio Controls}
\#2 & string & Type of glyph the semicirculus is attached to. See \nameref{EpisemaSpecial} argument for description of options.\\
\end{argtable}

\macroname{\textbackslash GreScoreOpening}{\#1\#2\#3\#4}{gregoriotex-syllable.tex}
Opens the score.

\begin{argtable}
\#1 & \TeX\ code & Macros rendering the things after the initial but before the notes.\\
\#2 & \TeX\ code & Macros rendering the things after starting notes but before the syllable.\\
\#3 & \TeX\ control sequence & Control sequence for the syllable.\\
\#4 & \TeX\ code & Macros rendering the first syllable; should emit the initial and populate \verb=\gre@opening@syllabletext=.\\
\end{argtable}

\macroname{\textbackslash GreScoreReference}{\#1}{gregoriotex-main.tex}
Currently does nothing.

Expand All @@ -636,8 +633,17 @@ \section{Gregorio Controls}
\#2 & string & Type of glyph the semicirculus is attached to. See \nameref{EpisemaSpecial} argument for description of options.\\
\end{argtable}

\macroname{\textbackslash GreSetBigInitial}{}{gregoriotex-main.tex}
Macro which indicates that a 2-line initial is desired.
\macroname{\textbackslash GreSetFirstSyllableText}{\#1\#2\#3\#4\#5\#6}{gregoriotex-syllable.tex}
Sets the first syllable text.

\begin{argtable}
\#1 & \TeX\ code & Initial.\\
\#2 & \TeX\ code & First letter after the initial.\\
\#3 & \TeX\ code & Everything else in the syllable.\\
\#4 & \TeX\ code & Three syllable parts when there is a separated initial.\\
\#5 & \TeX\ code & Three syllable parts where there is no separated initial.\\
\#6 & \TeX\ code & Extra macros to run if there is an initial.\\
\end{argtable}

\macroname{\textbackslash GreSetFixedNextTextFormat}{\#1}{gregoriotex-syllable.tex}
Same as \verb=\GreSetFixedTextFormat= except for next syllable.
Expand Down Expand Up @@ -669,9 +675,6 @@ \section{Gregorio Controls}
& \texttt{5} & underline
\end{argtable}

\macroname{\textbackslash GreSetInitial}{\#1}{gregoriotex-main.tex}
Macro to set the initial in the score.

\begin{argtable}
\#1 & character & The initial letter of the score.\\
\end{argtable}
Expand Down Expand Up @@ -705,6 +708,9 @@ \section{Gregorio Controls}
\#3 & string & the end letters, they don't count for alignment\\
\end{argtable}

\macroname{\textbackslash GreSetNoFirstSyllableText}{}{gregoriotex-syllable.tex}
Macro that indicates there is no next in the first syllable.

\macroname{\textbackslash GreSetTextAboveLines}{\#1}{gregoriotex-main.tex}
Macro to place argument above the lines and empty
\verb=\gre@currenttextabovelines= when done.
Expand Down
54 changes: 42 additions & 12 deletions doc/Command_Index_internal.tex
Original file line number Diff line number Diff line change
Expand Up @@ -259,15 +259,6 @@ \section{Gregorio\TeX{} Controls}
\#1 & string & Snippet of gabc code.\\
\end{argtable}

\macroname{\textbackslash gre@gabcsnippet@option}{[\#1]\#2}{gregoriotex-main.tex}
Macro that handles \verb=\gabcsnippet= calls when they have an optional
argument.

\begin{argtable}
\#1 & int & Value of initial style to be passed to gregorio \\
\#2 & string & Snippet of gabc code.\\
\end{argtable}

\macroname{\textbackslash gre@writemode}{\#1}{gregoriotex-main.tex}
Macro that writes its argument with \verb=\greannotation=. The
argument typically is given to this macro by \verb=\GreMode= in the
Expand Down Expand Up @@ -369,6 +360,27 @@ \section{Gregorio\TeX{} Controls}
\#1 & integer & height of the custos character to be placed\\
\end{argtable}

\macroname{\textbackslash gre@beginnotes}{}{gregoriotex-main.tex}
Macro to draw the staff lines. Comes after the initial but before the clef.

\macroname{\textbackslash gre@noinitial}{}{gregoriotex-main.tex}
Macro called when no initial is being set.

\macroname{\textbackslash gre@setbiginitial}{}{gregoriotex-main.tex}
Macro which indicates that a 2-line initial is desired.

\macroname{\textbackslash gre@setinitial}{\#1}{gregoriotex-main.tex}
Macro to set the initial in the score.

\macroname{\textbackslash gre@adjustsecondline}{}{gregoriotex.tex}
Macro to call before first syllable, but after \verb=\GreSetInitialClef=.

\macroname{\textbackslash gre@adjustthirdline}{}{gregoriotex-main.tex}
Macro to call during the second line.

\macroname{\textbackslash gre@adjustlineifnecessary}{}{gregoriotex-main.tex}
Macro that calls \verb=\gre@adjustthirdline= if indicated by \verb=\ifgre@thirdlineadjustmentnecessary=.

\macroname{\textbackslash gre@addspaceabove}{}{gregoriotex-main.tex}
Macro to increase the space above the lines to account for above lines text.

Expand Down Expand Up @@ -458,6 +470,24 @@ \section{Gregorio\TeX{} Controls}
& \texttt{0} & otherwise\\
\end{argtable}

\macroname{\textbackslash gre@setfirstsyllabletext}{\#1\#2\#3\#4\#5\#6}{gregoriotex-syllable.tex}
Internal macro to set the first syllable text after all parts are known.

\begin{argtable}
\#1 & \TeX\ code & First part of the syllable (before the vowel)\\
\#2 & \TeX\ code & Middle part of the syllable (the vowel)\\
\#3 & \TeX\ code & Last part of the syllable (after the vowel)\\
\#4 & \TeX\ code & First letter of the syllable\\
\#5 & \TeX\ code & Everything after the first letter of the syllable\\
\#6 & \TeX\ code & Macros to run after the text is emitted\\
\end{argtable}

\macroname{\textbackslash gre@opening@syllabletext}{}{gregoriotex-syllable.tex}
Macro that stores the computed \TeX\ code for rendering the text of the first syllable.

\macroname{\textbackslash gre@opening@initialstyle}{}{gregoriotex-syllable.tex}
Macro used by \verb=GreSetInitialStyle= to store the initial style

\macroname{\textbackslash gre@exhyphencharsave}{}{gregoriotex-main.tex}
Macro for saving the ex hyphen character so that it can be restored at the end of the score.

Expand Down Expand Up @@ -942,9 +972,6 @@ \subsection{Fonts}
\macroname{\textbackslash gre@font@nabc}{}{gregoriotex-nabc.tex}
The font for ancient notation.

\macroname{\textbackslash gre@font@biginitial}{}{gregoriotex.tex}
The font for the default big initial format in Plain \TeX.

\macroname{\textbackslash gre@font@initial}{}{gregoriotex.tex}
The font for the default initial format in Plain \TeX.

Expand Down Expand Up @@ -1209,6 +1236,9 @@ \subsection{Flags}
\macroname{\textbackslash ifgre@showhyphenafterthissyllable}{}{gregoriotex-syllable.tex}
Boolean used by \verb=\GreSyllable= to decide if a hyphen should be shown after the syllable.

\macroname{\textbackslash ifgre@thirdlineadjustmentnecessary}{}{gregoriotex-syllable.tex}
Boolean which indicates that a third-line adjustment to staff line width is necessary.

\macroname{\textbackslash ifgre@scale@stafflinefactor}{}{gregoriotex-spaces.tex}
Boolean indicating whether the stafflinefactor should scale with changes of \texttt{grefactor}, or not.

Expand Down
Loading