summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/semantic-markup
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/semantic-markup
Initial commit
Diffstat (limited to 'macros/latex/contrib/semantic-markup')
-rw-r--r--macros/latex/contrib/semantic-markup/README13
-rw-r--r--macros/latex/contrib/semantic-markup/semantic-markup.pdfbin0 -> 274152 bytes
-rw-r--r--macros/latex/contrib/semantic-markup/semantic-markup.sty165
-rw-r--r--macros/latex/contrib/semantic-markup/semantic-markup.tex174
4 files changed, 352 insertions, 0 deletions
diff --git a/macros/latex/contrib/semantic-markup/README b/macros/latex/contrib/semantic-markup/README
new file mode 100644
index 0000000000..66bb540d2b
--- /dev/null
+++ b/macros/latex/contrib/semantic-markup/README
@@ -0,0 +1,13 @@
+The semantic-markup package provides a set of simple commands to allow for semantic markup.
+The commands are inspired by the XML elements of the Text Encoding Initiative (http://www.tei-c.org).
+They are intended especially for scholarly writing in the humanities, including about music.
+The goal is simply to allow scholars to write with attention to meaning and content rather than to formatting.
+
+The package provides several semantic replacements for \emph and quoting commands, such as \term, \foreign, \mentioned, \soCalled, and \quoted.
+It also provides a Footnote environment so that long footnotes can be more cleanly separated from the main text.
+Because the author is a music scholar, the package also includes some macros for musical symbols and other basic notations for musical analysis.
+All the commands can be easily redefined as needed.
+
+This material is subject to the current version of the LaTeX Project Public License.
+The author and maintainer is Andrew A. Cashner, andrewacashner@gmail.com.
+
diff --git a/macros/latex/contrib/semantic-markup/semantic-markup.pdf b/macros/latex/contrib/semantic-markup/semantic-markup.pdf
new file mode 100644
index 0000000000..cc01f01022
--- /dev/null
+++ b/macros/latex/contrib/semantic-markup/semantic-markup.pdf
Binary files differ
diff --git a/macros/latex/contrib/semantic-markup/semantic-markup.sty b/macros/latex/contrib/semantic-markup/semantic-markup.sty
new file mode 100644
index 0000000000..e6d33668f9
--- /dev/null
+++ b/macros/latex/contrib/semantic-markup/semantic-markup.sty
@@ -0,0 +1,165 @@
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{semantic-markup}[2018/05/21
+ Macros for TEI-like semantic markup]
+% Copyright 2018 Andrew A. Cashner, andrewacashner@gmail.com
+
+% This work may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either
+% version 1.3 of this license or (at your option) any
+% later version.
+% The latest version of this license is in
+% http://www.latex-project.org/lppl.txt
+% and version 1.3 or later is part of all distributions
+% of LaTeX version 2005/12/01 or later.
+%
+% This work has the LPPL maintenance status `maintained'.
+% The Current Maintainer of this work is Andrew A. Cashner.
+% This work consists of the package file semantic-markup.sty
+% and the documentation file semantic-markup.tex.
+
+% CHANGE LOG
+% 2018-05-21 - Use fontspec's definition of `\strong` if it is loaded
+% - Use musicography's definition of `\fl`, `\sh`, `\na` commands if
+% it is loaded
+% - `\wtitle` and `\ptitle` shorthands added
+% - Customizable commands added for endnotes option
+%
+% 2016-09-22 - `endnotes' option added
+% 2016-09-01 - First version on CTAN
+
+% Option to use csquotes default behavior instead of the
+% US localized punctuation used in this package
+\newif\ifdefaultquotes
+\defaultquotesfalse
+\DeclareOption{defaultquotes}{\defaultquotestrue}
+
+% Option to convert footnotes to endnotes, include
+% Footnote environment
+\newif\ifendnotes
+\endnotesfalse
+\DeclareOption{endnotes}{\endnotestrue}
+
+\ProcessOptions\relax
+%**************************
+
+\RequirePackage{xparse}
+
+\RequirePackage{csquotes}
+\ifdefaultquotes\else
+ % Put end punctuation inside quotation marks
+ % for the specified marks
+ \renewcommand{\mktextquote}[6]{#1#2#4#5#3#6}
+ \DeclareAutoPunct{.,!?}
+\fi
+
+% NB: fontspec defines its own \strong command, so only define this if fontspec
+% not loaded
+\@ifpackageloaded{fontspec}{}{%
+ \NewDocumentCommand{\strong}{}
+ {\textbf}
+}
+
+
+\NewDocumentCommand{\quoted}{}
+{\textquote}
+\NewDocumentCommand{\soCalled}{}
+{\textquote}
+
+\NewDocumentCommand{\code}{}
+{\texttt}
+\NewDocumentCommand{\term}{}
+{\emph}
+\NewDocumentCommand{\mentioned}{}
+{\emph}
+\NewDocumentCommand{\foreign}{}
+{\emph}
+
+\NewDocumentCommand{\worktitle}{}
+{\emph}
+\NewDocumentCommand{\parttitle}{}
+{\textquote}
+
+% Shorter versions of these frequently used commands
+\NewDocumentCommand{\wtitle}{}{\worktitle}
+\NewDocumentCommand{\ptitle}{}{\parttitle}
+
+% editorial addition
+\NewDocumentCommand{\add}{ m }
+{[#1]}
+% editorial ellipsis
+\NewDocumentCommand{\Dots}{}{\add{\dots}}
+% explanatory gloss of technical or foreign term
+\NewDocumentCommand{\gloss}{ m m }{%
+ \mentioned{#1} (#2)%
+}
+% explanatory gloss of word in quotation marks
+\NewDocumentCommand{\quotedgloss}{ m m }{%
+ \quoted{#1} (#2)%
+}
+
+%*******************
+% Identify problem spot in draft
+\NewDocumentCommand{\XXX}{ O{\add{FIX}} }{%
+ \strong{#1}%
+}
+% Indicate citation to be filled in later
+% Optional argument for indicating the source
+\NewDocumentCommand{\citXXX}{ o }{%
+ \footnote{\strong{\add{Citation needed}\IfValueTF{#1}{#1}{}}}%
+}
+
+%*******************
+% Footnote as environment
+\RequirePackage{environ}
+\NewEnviron{Footnote}{\footnote{\BODY}}[]
+
+%******************
+% Endnotes, if desired
+
+\ifendnotes
+ \RequirePackage{endnotes}
+
+ % Customize these commands with \renewcommand
+ \NewDocumentCommand{\DoBeforeEndnotes}{}{\clearpage}
+ \NewDocumentCommand{\EndnoteFont}{}{}
+
+ % Optionally remove this (\renewcommand{\MakeEndnotes}{})
+ % to avoid conflicts with endnotes or other packages
+ \NewDocumentCommand{\SetupEndnotes}{}{%
+ \let\footnote=\endnote
+ \AtEndDocument{\DoBeforeEndnotes{\EndnoteFont\theendnotes}}%
+ }
+
+ \AtBeginDocument{%
+ \SetupEndnotes{}%
+ % Footnote environment adjusted to fix expansion problem
+ \RenewEnviron{Footnote}{\expandafter\footnote\expandafter{\BODY}}[]%
+ }%
+\fi
+%******************
+
+%****************************************
+% MUSIC SYMBOLS
+
+% Accidentals using LaTeX symbols
+% Use better definitions from musicography if it was loaded first
+\@ifpackageloaded{musicography}{}{%
+ \NewDocumentCommand{\fl}{}{$\flat$}
+ \NewDocumentCommand{\na}{}{$\natural$}
+ \NewDocumentCommand{\sh}{}{$\sharp$}
+}
+
+% Octave subscripts
+\NewDocumentCommand{\octave}{ }{\textsubscript}
+
+% Music figures
+\RequirePackage{amsmath}
+\NewDocumentCommand{\musfig}{ m m }{%
+ $\genfrac{}{}{0pt}{1}{\text{#1}}{\text{#2}}$%
+}
+
+% Meter signatures
+\RequirePackage[rm]{harmony}
+\NewDocumentCommand{\meter}{ m m }{\Takt{#1}{#2}}
+
+\endinput
diff --git a/macros/latex/contrib/semantic-markup/semantic-markup.tex b/macros/latex/contrib/semantic-markup/semantic-markup.tex
new file mode 100644
index 0000000000..c53f395306
--- /dev/null
+++ b/macros/latex/contrib/semantic-markup/semantic-markup.tex
@@ -0,0 +1,174 @@
+\documentclass{article}
+\usepackage{lmodern}
+\usepackage[T1]{fontenc}
+\usepackage[utf8]{inputenc}
+\usepackage{tabularx}
+\usepackage{fancyvrb}
+\usepackage{booktabs}
+\usepackage{semantic-markup}
+\frenchspacing
+\usepackage
+ [pdftitle={The semantic-markup Package for Meaningful Markup},
+ pdfauthor={Andrew A. Cashner},
+ pdfsubject={LaTeX package},
+ pdfkeywords={LaTeX, semantic markup, TEI, humanities}]{hyperref}
+
+
+\title{The \texttt{semantic-markup} Package for Meaningful Markup}
+\author{Andrew A. Cashner%
+ \thanks{\href{mailto:andrewacashner@gmail.com}{\nolinkurl{andrewacashner@gmail.com}}}%
+}
+
+\begin{document}
+\maketitle
+
+The \texttt{semantic-markup} package provides a set of simple commands to allow for semantic markup.
+The commands are inspired by the XML elements of the Text Encoding Initiative (\url{http://www.tei-c.org}).
+They are intended especially for scholarly writing in the humanities, including about music.
+The goal is simply to allow scholars to write with attention to meaning and content rather than to formatting.
+
+\tableofcontents
+
+\section{Package Options}
+
+\subsection{\texttt{defaultquotes}}
+
+The package configures \texttt{csquotes} to place end punctuation inside quotation marks, according to United States usage.
+Use the \texttt{defaultquotes} package option to restore the default behavior of \texttt{csquotes}.
+
+\subsection{\texttt{endnotes}}
+
+The \texttt{endnotes} option converts footnotes to endnotes, including footnotes created with this package's \texttt{Footnote} environment.
+On its own, this option loads the \texttt{endnotes} package and does everything
+necessary for endnotes.
+You can define the following commands to adjust the behavior:
+
+\begin{center}
+\begin{tabular}{ll}
+ Command & Default value \\ \hline
+ \verb|\DoBeforeEndnotes| & \verb|\clearpage| \\
+ \verb|\EndnoteFont| & Empty (normal font) \\
+\end{tabular}
+\end{center}
+
+If you want to setup the endnotes in a completely different way or avoid
+conflicts with another package, you can do
+\verb|\renewcommand{\SetupEndnotes}{}| to eliminate all of this or you can renew
+the command to do something else.
+
+\section{Semantic Commands Defined Without Arguments}
+
+The following commands are defined (using \texttt{xparse}) as aliases to standard \LaTeX{} commands or \verb|\textquote| from the \texttt{csquotes} package.
+In other words, they are not defined with an argument.
+For example, the command for a technical term, typically set in italics is defined this way:
+\begin{verbatim}
+\NewDocumentCommand{\term}{}{\emph}
+\end{verbatim}
+To redefine it to be set in bold, for example, you can use the basic \LaTeX{} command \verb|\renewcommand{\term}{\textbf}|.
+
+The \verb|\strong| command is already defined in the \texttt{fontspec} package;
+if that package is loaded, this package will not redefine its command.
+
+\begin{center}
+\begin{tabularx}{\linewidth}{llX}
+\toprule
+Package Command & Alias & Use\\
+\midrule
+\verb|\quoted| & \verb|\textquote| & Quoted material, taking care of end punctuation: instead of \verb|``word,''| write \verb|\quoted{word},|\\
+\verb|\soCalled| & \verb|\textquote| & Scare quotes\\
+\verb|\strong| & \verb|\textbf| & Highlight emphasis just as in HTML\\
+\verb|\code| & \verb|\texttt| & Computer code in teletype font (not verbatim)\\
+\verb|\term| & \verb|\emph| & Technical terms, set in italics\\
+\verb|\mentioned| & \verb|\emph| & Referring to a word as a word rather than to its meaning, as in philological discussion\\
+\verb|\foreign| & \verb|\emph| & Foreign term\\
+\verb|\worktitle| & \verb|\emph| & Title of a complete work (of literature, art, music), set in italics; use for books, journal titles\\
+\verb|\parttitle| & \verb|\textquote| & Title of a portion of a work, set in quotation marks, such as a journal article, song on an album\\
+\bottomrule
+\end{tabularx}
+\end{center}
+
+\section{Semantic Commands With Arguments}
+
+These commands have slightly more complex definitions, but can still be easily redefined.
+See the \texttt{xparse} documentation on the syntax of these commands.
+
+\begin{center}
+\begin{tabularx}{\linewidth}{lXX}
+\toprule
+Command & Definition & Usage\\
+\midrule
+\verb|\add| & One argument: Put square brackets around argument & For editorial additions\\
+\verb|\Dots| & Put ellipsis in square brackets & For editorial omissions from quotations\\
+\verb|\gloss| & Two arguments: Put first in italics and second in parentheses & Use a technical or foreign term and give its definition\\
+\verb|\quotedgloss| & Two arguments: Put first in quotation marks and second in parentheses & Same as \verb|\gloss| but using \verb|\quoted| for the first argument instead of \verb|\mentioned|\\
+\verb|\XXX| & One optional argument with default value of \verb|\add{FIX}| & Identify problem spot in draft\\
+\verb|\citXXX| & One optional argument & Make footnote indicating a missing citation; optional argument may be used for reminder of the citation name or description\\
+\bottomrule
+\end{tabularx}
+\end{center}
+
+\section{Footnote Environment}
+
+When writing many long footnotes it can be useful to have an environment for footnotes.
+Here one is defined using the \texttt{environ} package.
+You still have to escape the end of the line before the footnote begins.
+Use like so:
+
+\begin{verbatim}
+Body text.%
+\begin{Footnote}
+ Footnote text.
+ More footnote text.
+\end{Footnote}
+Continuation of body text.
+\end{verbatim}
+
+\section{Musical Symbols}
+
+Shorthands are defined for musical accidentals, using \LaTeX{} math-mode symbols.
+These could be redefined to use Unicode symbols if the font contains them, or with commands from the \texttt{lilyglyphs} package.
+Remember that like all commands without arguments, \LaTeX{} will ignore the space after the command-name, so you will need to write \verb|\fl{}| or \verb|\fl\ |.
+There is also a command for octave numbers, for the system in which middle C begins the fourth octave.
+
+If the \texttt{musicography} package is loaded, it will redefine the commands
+\verb|\fl|, \verb|\sh|, and \verb|\na| to use nicer symbols from the MusiX\TeX{}
+fonts.
+
+\begin{center}
+\begin{tabular}{ll}
+\toprule
+Command & Alias\\
+\midrule
+\verb|\fl| & \verb|$\flat$|\\
+\verb|\na| & \verb|$\natural$|\\
+\verb|\sh| & \verb|$\sharp$|\\
+\verb|\octave| & \verb|\textsubscript|\\
+\bottomrule
+\end{tabular}
+\end{center}
+
+For stacked numerals, as in meter signatures or figured bass, we provide two simple options, \verb|\musfig| using \verb|\genfrac| from \texttt{amsmath}, and \verb|\meter|, which uses \verb|\Takt| from the \texttt{harmony} package, which spaces the numerals more closely.
+Both commands take two arguments, one for the top numeral and the second for the bottom numeral.
+You could write, for example:
+
+\begin{verbatim}
+There is a \musfig{6--5}{4--3} cadential pattern
+before the shift to \meter{3}{4} time.
+The melody begins on F\sh\octave{4}.
+\end{verbatim}
+
+\begin{center}
+\fbox{\parbox{\textwidth}{%
+There is a \musfig{6--5}{4--3} cadential pattern
+before the shift to \meter{3}{4} time.
+The melody begins on F\sh\octave{4}.
+}}
+\end{center}
+
+For more complex notation, such as three-level numerals, or stacked figured-bass symbols with accidentals or slashes, you will have to devise your own solution.
+
+\section{Code}
+
+\VerbatimInput{semantic-markup.sty}
+
+\end{document}