\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}}}%
}
\date{January 29, 2020}

\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|\Shortstack| from
\texttt{stackengine}, and \verb|\meter|, which is an alias for the same thing.
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}
