path: root/macros/latex/contrib/liturg/liturg.sty

% \iffalse
% +AMDG  This document was begun on 17 Jan 2008, the Feast of St.
% Antonius the Abbot, and it is humbly dedicated to him, to St.
% Gregory the Great, and to the Immaculate Heart of Mary for their
% prayers, and to the Sacred Heart of Jesus for His mercy, and to
% all those who died for the integrity of the Catholic liturgy, and
% for the aid and succor of those who fight for it today.
% \fi
%
% \maketitle
% \begin{abstract}
% The |liturg| package is a simple package which makes easy the
% typesetting of Catholic liturgical texts.  It requires all the
% packages necessary to typeset Latin properly; it also takes care of
% appropriate color management and headings, providing commands for
% both Missal and Breviary constructs.  For the typesetting of entire
% liturgical books, most of the higher-level issues are left to the
% user, as the typesetting of something as complex as an entire
% Missal or Breviary is best quite individualized, though the forms
% are well-settled and definite.  However, for selections, even
% long selections, including headings and instructions, this
% package is ideal, and would be a great help even in the large
% works mentioned above.
% \end{abstract}
% 
% \tableofcontents
% 
% \section{Introduction}
% \label{sect:intro}
% 
% \LaTeX\ had, prior to this package, absolutely no facility for the
% easy and beautiful typesetting of liturgical texts whatsoever, much
% less the Catholic liturgical texts at which this package is
% particularly aimed.  This package aims to rectify that
% circumstance, and I believe that it largely succeeds.
% 
% Those interested in a package to automate the typesetting of entire
% liturgical books---missals or breviaries, for example---will
% probably be disappointed.  This package does nothing to solve the
% many problems of doing so:  several different streams of
% pagination being the only one not basically trivial.  However, such
% persons should not be disappointed.  Missals and breviaries are
% ordered texts; thus, the contents, indices, and similar structures
% are minimal, if not nonexistent.  Just search through the days
% until you get to the right one.  The most difficult part of
% typesetting such texts is getting each individual feast correct.
% This package has automated that process for you; it is now easy.
% 
% This document was typeset in accordance with the \LaTeX\
% \textsc{docstrip} utility.
% 
% \section{Language Commands}
% \label{sect:lang}
% 
% |liturg|'s first contribution to the facilitation of typesetting
% liturgical texts is allowing the liturgical language to be selected
% easily.  The |babel| and |ecclesiastic|\footnote{If you don't have
% |ecclesiastic| --- it's default in neither \TeX Live nor % Mik\TeX\
% --- do download it and put it in your tree.  It makes the
% typesetting of liturgical Latin immensely easier.} packages take
% care of the innards of the process; this package merely provides a
% wrapper, making the commands less cumbersome when they must be
% entered frequently, as in bilingual liturgical texts.
% 
% \DescribeMacro{\latin}|\latin| very simply and easily changes the text
% enclosed in its braces to Latin, typeset according to the
% guidelines of the |ecclesiastic| package.  The command is properly
% issued as follows:
% \begin{quote}
% \cs{latin}\marg{latin text}
% \end{quote}
% The other language-control macros offered by |liturg| are
% \DescribeMacro{\latinpart}|\latinpart| and
% \DescribeMacro{\englishpart}|\englishpart|.  These two, rather than
% requiring one to enclose a rather short text in braces, allow
% simply issuing the command, which will then cause the text to be
% typeset in that language until another language command is reached.
% This command \emph{must} be used whenever, for example, there are
% paragraph breaks in the Latin text.
% 
% Now, we can move on to some of |liturg|'s other commands.
% 
% \section{Missal Texts}
% \label{sect:missal}
% 
% Missal texts generally contain two things:  prayers and
% instructions.  This package provides for both eventualities.
% 
% For instructions, the command is simple:
% \DescribeMacro{\instruct}|\instruct| typesets the instructions in a
% small size (with |\small|) and in red, as is the general practice.
% There is no indent, as the small size and variant color is
% generally sufficient reason to consider it a separate text even in
% the absence of indentation.  Furthermore, it's not unheard of for
% texts to include instructions flowed into the paragraph, so all in
% all an indentation and a full |\par| construct seemed in
% appropriate.  Simply include the instruction text in braces
% following this command; it takes one argument, the text of the
% instruction.
% 
% For prayers, there are two main commands and some associated ones.
% The first main command is \DescribeMacro{\priest}|\priest|, which 
% takes one
% argument; namely, the text that is going to be stated by the
% priest.  Since most text is stated by the priest, this is generally
% only used in sections with a response, which leads us to the next
% command, \DescribeMacro{\server}|\server|, which gives the text
% stated in response by the server.
% 
% By default these commands print the text of its first argument,
% preceded by ``S.'' and ``M.'' respectively.  These stand for
% \textit{Sacerdos} (priest) and \textit{Minister} (server).  They
% can be changed by redefining the macros
% \DescribeMacro{\priestword}|\priestword| and
% \DescribeMacro{\serverword}|\serverword| if, say, English
% typesetting is desired.  Simply issue the appropriate redefinition
% commands, as in the following:
% \begin{quote}
% |\renewcommand\priestword{P.  }| \\
% |\renewcommand\serverword{S.  }| \\
% \end{quote}
% Indeed, this is taken up automatically by the |\massenglish| macro,
% which will be discussed shortly.
% 
% |liturg| presumes Latin typesetting as the norm, that being the
% normative language even for the newer rites; therefore, typesetting 
% liturgical texts in English may be somewhat difficult.
% Consequently, the package provides a simple command,
% \DescribeMacro{\massenglish}|\massenglish|, to take care of these
% issues for the user.  This, among other things, alters the
% definitions of |\priestword| and |\serverword| appropriately.  No
% facilities for other languages are currently supported; we would
% be happy to add them should they be provided.
% 
% \section{Breviary Texts}
% \label{sect:brev}
% 
% This package was developed with the old liturgy in mind, and
% consequently does not contain any provisions for automatically
% typesetting breviary texts in English.  That said, most of these
% commands should work equally well for translations of breviary
% texts.  
% 
% For starters, there are a number of simple commands which provide
% simple but commonly required output.  The first of these is
% \DescribeMacro{\markup}|\markup|.  The Breviary contains many
% portions of text which are not instructions, yet not text; it is
% simply markup; for example, antiphons contain a label indicating
% their status as antiphons, with a number at the starter antiphon.
% No automatic numbering has been provided, as I can't forsee any
% situation in which an author would be producing original texts
% rather than typesetting existing, inalterable ones.  However, such
% antiphon text qualifies as |\markup| within the |liturg| package.
% The command takes one argument, the text of the markup.  So an
% antiphon may be typeset as:
% \begin{quote}
% \markup{Ant.\ 1}  Followed by the text of the antiphon.
% \end{quote}
% produced by
% \begin{quote}
% |\markup{Ant.\ 1}  Followed by the text of the antiphon.|\\
% \end{quote}
% By default, |\markup| produces normal sized text in red.  It makes
% no effort to suppress indentation.  This seemed to be normal
% practice in the Roman Breviary.
% 
% Also available, for instructions, is the |\instruct| command
% discussed under missal texts.\footnote{\textit{See supra}, Section
% \ref{sect:missal}, at \pageref{sect:missal}.}  As a corollary, also
% available is \DescribeMacro{\blackinstruct}|\blackinstruct|, which
% provides the same functionality but colored in black.  A more
% general name would have been desirable, but I was unable to find a
% consistent reason for preferring one color over the other for
% entire citations.  Within instructions (and |\markup|s, for that
% matter) there are frequently page numbers, which are always printed
% in black, rather than red.  For this requirement, use the
% \DescribeMacro{\page}|\page| command within the argument of
% |\instruct| or |\markup|.
% 
% Also commonly necessary are psalm titles, prayer titles, lesson
% titles, and so on.  The package provides a number of commands to
% cover these needs.  For prayer titles (generally simply ``Oratio,''
% but sometimes other things), the command
% \DescribeMacro{\prayerheading}|\prayerheading| is used.  For psalms, use
% \DescribeMacro{\psalmheading}|\psalmheading|.  All take a single
% argument, the text of the heading.  Once again, this is generally
% simply ``Oratio,'' ``Psalmus 22,'' or something similar, but this
% is not universal.
% 
% The lessons especially, but also many prayers and other parts of
% the Breviary, begin with a lettrine; that is, a large letter which
% takes up two lines, printed in red.  The |lettrine| package does
% all the work in the case, but a more or less trivial wrapper for it
% is provided by the package for this purpose, namely,
% \DescribeMacro{\leslettrine}|\leslettrine|.  It takes one argument,
% the letter to be enlarged, as the second argument to |\lettrine| is
% not applicable here.  It also prints the letter in red, as is the
% normal case.  In third readings, however, often there are two texts
% used, the Gospel and a commentary by a great Church Father or
% doctor.  The second of these readings will begin with a lettrine,
% but not in red.  For this purpose, the macro
% \DescribeMacro{\caplettrine}|\caplettrine|, because this second
% reading is also called the ``chapter'' (Latin ``caput''), is
% provided.
% 
% Lesson headings also present some unique typesetting requirements.
% Generally they will include the number of the lesson (or
% ``reading'') in romanettes, one through nine; the word ``Lectio''
% (for ``lesson'' or ``reading''), with the number, all in red.  This
% much is universal; even brief statements of the lives of the saints
% (as from Lectio iii in the office of St. Thomas Aquinas, to be seen
% in test.pdf, will show) contain at least this.  However, often more
% information is present.  For example, if the reading is Scriptural
% (quite often, of course), the source of the reading will be printed
% below the lesson heading, in red.  The book, however, as opposed to
% the chapter and verse of that book, will be in black, but only in
% the first reading from that source; further readings from that
% source will contain only the chapter and verse citations.  Rather
% than try to automate all this, and again presuming that users will
% not be composing original texts, I have provided simple commands
% for these circumstances.
% 
% \DescribeMacro{\lessonheading}|\lessonheading| prints the simple
% ``Lectio iii'' (or whatever text is entered as its one and only
% argument).  This is the universal part and thus seemed to deserve
% the title of ``heading.''
% \DescribeMacro{\lessontitle}|\lessontitle| give that optional part
% which generally contains the book of Holy Scripture from which the
% lesson is drawn, e.g., ``De Epistola beati Pauli Apostoli ad
% Colossenses.''  \DescribeMacro{\lessonsource}|\lessonsource| gives the 
% citation to
% the particular part of the book in red; e.g., ``Cap.\ 1, 3--23.''
% These macros are easily adjustable to those readings drawn from
% other sources; e.g., papal encyclicals, writings of the Fathers.
% In the event some black text is required within the red text, the
% use of the |\page| command is probably best.  This makes semantic
% sense, as most of these, while not page references, do identify
% with particularity a reference.  E.g.,
% \begin{quote}
% \lessonsource{Litt.\ % Encycl.\ \page{Quas Primas,} diei 
% 11 decembris 1925}
% \end{quote}
% 
% Hours themselves (e.g., Matins, Lauds, \textit{et cetera}) must
% also be headed, and the command
% \DescribeMacro{\hourheading}|\hourheading| provides amply for this
% need.  Simply include the hour's name in the mandatory
% argument for |\hourheading| and you've got yourself a
% heading (e.g., |\hourheading{Ad Matutinum}|).
% 
% For typesetting the actual entries in the breviary (as in,
% individual feast entries), the command
% \DescribeMacro{\feasttitle}|\feasttitle| is provided.  This command
% is considerably more complex to use than the rest offered thus far.
% Specifically, it takes four mandatory arguments and one optional;
% if nothing else, it taxes the memory more.  Its formatting is
% simple, however:
% \begin{quote}
% \cs{feasttitle}\oarg{miscellaneous}\marg{date}\marg{saint}\marg{type}\marg{class}
% \end{quote}
% The mandatory arguments mostly speak for themselves.  The date of
% the feast; the saint (or event, such as the translation of some
% relics) celebrated; the type of the saint (such as bishop and
% confessor, martyr, and so on); and the class of the feast (just the
% number, in Roman numerals).  For the class, I have actually
% provided some generalization.  By default, the macro prints the
% class of the feast entered, followed by ``classis,'' the Latin.
% However, by redefining the macro
% \DescribeMacro{\classword}|\classword|, this can be altered.  As I
% hardcoded in some text here, I felt that options were appropriate.
% 
% The optional argument contains ``other''; things that don't quite
% fit in the other category.  Generally, this will be a reference to
% the Common for the particular type of saint, plus a reference
% (e.g., ``Commune vide (132),'' as in the example test.pdf).  Many
% feasts will not have such a line, but most will; so it was made
% optional.
% 
% This provides a general interface for saints' feasts; however, a
% much simpler one is provided for the simpler cases:  that of great
% feasts, which are generally headed by only a line or two
% identifying the feast and its class.  This is the command
% \DescribeMacro{\greatfeast}|\greatfeast|, which is much
% simpler than the |\feasttitle| macro.  It simply prints,
% in all caps, the name of the feast in slightly larger
% type, followed by the class in the normal type.  It
% utilizes \DescribeMacro{\greatsize}|\greatsize| for the
% size of the title (by default it's just |\Large|), and
% also |\classword|, already discussed.
% 
% \section{Implementation}
% \label{implement}
% 
% Here's the implementation of the package.  It's so basic
% that it will probably be uninteresting to everyone, but
% it's standard practice to include it, so here it is.  It's
% also easier to read than the raw code, so if you want to
% hack any of the macros, this is a good place to look at
% them beforehand to see how they tick.
%    \begin{macrocode}
\ProvidesPackage{liturg}

\RequirePackage[latin,english]{babel}
\RequirePackage{color}
\RequirePackage{lettrine}
\RequirePackage{ecclesiastic}

\newcommand{\latin}[1]{%
\foreignlanguage{latin}{#1}%
}

\newcommand{\latinpart}{%
\selectlanguage{latin}%
}

\newcommand\englishpart{%
\selectlanguage{english}%
}

\renewcommand{\LettrineFontHook}{\color{red}}

\newcommand{\leslettrine}[1]{%
\lettrine{#1}{}
}

\newcommand{\caplettrine}[1]{%
\lettrine{\textcolor{black}{#1}}{}
}

\newcommand\classword{classis}

% 1: optional stuff; 2: date; 3: saint; 4: type; 5: class
\newcommand\feasttitle[5][]{%
\begin{center}
\noindent\normalsize\textcolor{red}{#2}\\%
\uppercase{#3}\\%
#4\\%
\textcolor{red}{#5 \classword}\\%
\small\textcolor{red}{#1}%
\end{center}
}

\newcommand\page[1]{%
\textcolor{black}{#1}%
}

\newcommand\hourheading[1]{%
\begin{center}
\normalsize\textbf{#1}\\%
\end{center}
}

\newcommand\versic[1]{%
\textcolor{red}{V.  }#1%
}

\newcommand\response[1]{%
\textcolor{red}{R.  }#1%
}

\newcommand{\lessontitle}[1]{%
\begin{center}
\vspace{-2em}
\noindent\normalsize\textcolor{black}{#1}
\end{center}
}

\newcommand{\psalmheading}[1]{%
\begin{center}
\noindent\normalsize\textcolor{red}{#1}
\end{center}
}

\newcommand{\lessonheading}[1]{%
\begin{center}
\noindent\normalsize\textcolor{red}{#1}
\end{center}
}

\newcommand{\prayerheading}[1]{%
\begin{center}
\noindent\normalsize\textcolor{red}{#1}
\end{center}
}

\newcommand{\lessonsource}[1]{%
\begin{center}
\vspace{-1em}
\noindent\footnotesize\textcolor{red}{#1}
\end{center}
}

\newcommand\instruct[1]{%
\noindent\footnotesize\textcolor{red}{#1}\normalsize\\% 
}

\newcommand\blackinstruct[1]{%
\small\textcolor{black}{#1}\normalsize%
}

\newcommand\markup[1]{%
\noindent\normalsize\textcolor{red}{#1}%
}

\newcommand\priestword{S.  }
\newcommand\serverword{M.  }

\newcommand{\massenglish}{%
\renewcommand\priestword{P.  }
\renewcommand\serverword{S.  }
}

\newcommand\priest[1]{%
\noindent\textcolor{red}{\priestword}{#1}\\%
}

\newcommand\server[1]{%
\noindent\textcolor{red}{\serverword}{#1}\\%
}

\newcommand\greatsize{\Large}

\newcommand\greatfeast[2]{%
\begin{center}%
\noindent\greatsize\uppercase{#1}\\%
\normalsize\vspace*{0.5em}\textcolor{red}{#2 \classword}%
\end{center}
}
%    \end{macrocode}