1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
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}
|
