summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/snotez/snotez_en.tex
blob: 5859ff025f7d1b60df99cfc9ecde996b72c3459e (plain)
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
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
% arara: pdflatex
% arara: biber
% arara: pdflatex
% arara: pdflatex
% --------------------------------------------------------------------------
% the SNOTEZ package
% 
%   Sidenotes for LaTeX2e
% 
% --------------------------------------------------------------------------
% Clemens Niederberger
% Web:    https://bitbucket.org/cgnieder/snotez/
% E-Mail: contact@mychemistry.eu
% --------------------------------------------------------------------------
% Copyright 2012--2013 Clemens Niederberger
% 
% 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 Clemens Niederberger.
% --------------------------------------------------------------------------
% The snotez package consists of the files
%  - snotez.sty, snotez_en.tex, snotez_en.pdf, README
% --------------------------------------------------------------------------
% If you have any ideas, questions, suggestions or bugs to report, please
% feel free to contact me.
% --------------------------------------------------------------------------
% in order to compile this documentation you need the document class
% `cnpkgdoc' which you can get here:
%   https://bitbucket.org/cgnieder/cnpkgdoc/
%
\PassOptionsToPackage{supstfm=libertinesups}{superiors}
\documentclass[toc=index,toc=bib,mpinclude]{cnpkgdoc}
\setlength{\marginparwidth}{2\marginparwidth}
\docsetup{
  pkg={[footnote,perpage,dblarg]snotez},
  subtitle=sidenote support for \LaTeXe
}
\addcmds{
  RaggedRight,
  sidenote,setsidenotes,superiors@spaced,
  textsu
}
% Layout:
\cnpkgusecolorscheme{friendly}
\renewcommand*\othersectionlevelsformat[3]{%
  \textcolor{main}{#3\autodot}\enskip}
\renewcommand*\partformat{%
  \textcolor{main}{\partname~\thepart\autodot}}
\usepackage{fnpct}
\AdaptNoteOpt\sidenote\multsidenote
\pagestyle{headings}

\usepackage[biblatex]{embrac}[2013/03/22]
\ChangeEmph{[}[,.02em]{]}[.055em,-.08em]
\ChangeEmph{(}[-.01em,.04em]{)}[.04em,-.05em]

\robustify\snotez

\usepackage{libertinehologopatch}
\usepackage{ragged2e}

\normalmarginpar

% Index:
\usepackage{imakeidx}
\usepackage{filecontents}
\begin{filecontents*}{\jobname.ist}
 heading_prefix "{\\bfseries "
 heading_suffix "\\hfil}\\nopagebreak\n"
 headings_flag  1
 delim_0 "\\dotfill\\hyperpage{"
 delim_1 "\\dotfill\\hyperpage{"
 delim_2 "\\dotfill\\hyperpage{"
 delim_r "}\\textendash\\hyperpage{"
 delim_t "}"
 suffix_2p "\\nohyperpage{\\,f.}"
 suffix_3p "\\nohyperpage{\\,ff.}"
\end{filecontents*}
\indexsetup{othercode=\footnotesize}
\makeindex[options={-s \jobname.ist},intoc,columns=3]

\usepackage[backend=biber,style=alphabetic]{biblatex}
\addbibresource{\jobname.bib}
\begin{filecontents}{\jobname.bib}
@package{pkg:chngcntr,
  title   = {\paket*{chngcntr}},
  author  = {Peter Wilson and Will Robertson},
  date    = {2009-09-02},
  version = {1.0a},
  url     = {http://mirror.ctan.org/macros/latex/contrib/chngcntr}
}
@package{pkg:etoolbox,
  title   = {\paket*{etoolbox}},
  author  = {Philipp Lehman},
  date    = {2011-01-21},
  version = {2.1},
  url     = {http://mirror.ctan.org/macros/latex/contrib/etoolbox}
}
@package{pkg:fnpct,
  title   = {\paket*{fnpct}},
  author  = {Clemens Niederberger},
  date    = {2013-04-07},
  version = {0.2k},
  url     = {http://mirror.ctan.org/macros/latex/contrib/fnpct}
}
@package{pkg:marginnote,
  title   = {\paket*{marginnote}},
  author  = {Markus Kohm},
  date    = {2012-03-29},
  version = {1.1i},
  url     = {http://mirror.ctan.org/macros/latex/contrib/marginnote}
}
@package{cls:memoir,
  title   = {\klasse{memoir}},
  author  = {Lars Madsen and Peter Wilson},
  date    = {2011-03-06},
  version = {3.6j patch 6.0g},
  url     = {http://mirror.ctan.org/macros/latex/contrib/memoir}
}
@package{pkg:perpage,
  title   = {\paket*{perpage}},
  author  = {David Kastrup},
  date    = {2006-07-15},
  version = {1.12},
  url     = {http://mirror.ctan.org/macros/latex/contrib/perpage}
}
@package{pkg:pgfopts,
  title   = {\paket*{pgfopts}},
  author  = {Joseph Wright},
  date    = {2011-06-02},
  version = {2.1},
  url     = {http://mirror.ctan.org/macros/latex/contrib/pgfopts}
}
@package{pkg:ragged2e,
  title   = {\paket*{ragged2e}},
  author  = {Martin Schröder},
  date    = {2009-05-21},
  version = {2.1},
  url     = {http://mirror.ctan.org/macros/latex/contrib/ragged2e}
}
@package{pkg:sidenotes,
  title   = {\paket*{sidenotes}},
  author  = {Andy Thomas and Oliver Schebaum},
  date    = {2012-11-09},
  version = {0.92},
  url     = {http://mirror.ctan.org/macros/latex/contrib/sidenotes}
}
@package{pkg:superiors,
  title   = {\paket*{superiors}},
  author  = {Michael Sharpe},
  date    = {2012-08-13},
  version = {1.02},
  url     = {http://mirror.ctan.org/macros/latex/contrib/superiors}
}
@package{cls:tufte,
  title   = {\klasse{tufte-latex}},
  author  = {Kevin Godby and Bil Kleb and Bill Wood},
  date    = {2009-12-11},
  version = {3.5.0},
  url     = {http://mirror.ctan.org/macros/latex/contrib/sidenotes}
}
\end{filecontents}

\newcommand*\Default[1]{%
  \hfill\llap{%
    \ifblank{#1}
      {(initially~empty)}
      {Default:~\code{#1}}%
    }\newline
}

\makeatletter
\providecommand*\sinceversion[1]{%
  \@bsphack
  \marginnote{%
    \footnotesize\sffamily\RaggedRight
    \textcolor{black!75}{Introduced in version~#1}}%
  \@esphack}
\providecommand*\changedversion[1]{%
  \@bsphack
  \marginnote{%
    \footnotesize\sffamily\RaggedRight
    \textcolor{black!75}{Changed in version~#1}}%
  \@esphack}

\newcommand*\defaultsidenotes{%
  \setsidenotes{
    note-mark-format = \@textsuperscript{\normalfont##1},
    text-format      = \footnotesize
  }}
\setsidenotes{
  note-mark-format=#1.,
  text-mark-format=\textsu{\hspace*{\superiors@spaced}#1},
  text-format+=\RaggedRight
}
\makeatother

\begin{document}

\section{License and Requirements}\label{sec:license}\secidx{License}
\snotez is placed under the terms of the \LaTeX{} Project Public License,
version 1.3 or later (\url{http://www.latex-project.org/lppl.txt}). It has the
status ``maintained.''

\snotez needs and loads the packages
\paket*{etoolbox}\sidenote[*-2][]{\textcite{pkg:etoolbox}},
\paket*{pgfopts}\sidenote[*-][]{\textcite{pkg:pgfopts}},
\paket*{marginnote}\sidenote{\textcite{pkg:marginnote}} and
\paket*{perpage}\sidenote{\textcite{pkg:perpage}}.
\secidx*{License}

\section{Motivation}
This has just been an exercise on a lazy
afternoon\sidenote[*-2][]{\url{http://www.youtube.com/watch?v=PPRiaYH1iTk}}.
Well, more or less at least. Since there already is Andy Thomas' \paket*{sidenotes}
package\sidenote[*-][]{\textcite{pkg:sidenotes}} there is probably
no real need for \snotez. Moreover, the tufte classes\sidenote{\textcite{cls:tufte}}
as well as \klasse{memoir}\sidenote{\textcite{cls:memoir}} also provide corresponding
mechanisms. Besides the fun I had my motivation was also based on the fact that
I didn't like some smaller things (\emph{not} bugs) done by the \paket{sidenotes}
package such as inserting kerns and superscripted commas for multiple marks. I
prefer to let my \paket*{fnpct}\sidenote{\textcite{pkg:fnpct}} package handle
these things. Anyways, here it is and it seems to be working as intended so I
don't see a reason why it shouldn't be available for use.

By the way: the \paket*{fnpct} package v0.2k and later knows about \snotez and
automatically adapts the note commands. Please note that you need to enable
the \key{dblarg} option (see page~\pageref{key:dblarg}) when you're using
\paket*{fnpct} together with \snotez!

\section{Introduction}\secidx{Introduction}
The \snotez Package introduces a \cmd{sidenote} command%
\begingroup\defaultsidenotes
\sidenote{This is an example demonstrating the default appearance.}
\endgroup
that typesets sidenotes the
same way \cmd{footnote} typesets footnotes. It provides some options that allow
formatting the appearance of the sidenotes\sidenote[*][]{In all sidenotes in this
document the mark is typeset on the baseline and the text is set ragged right.}.
As a default sidenotes are typeset in a \cmd{marginpar} but there are possibilities
using Markus Kohm's \paket{marginnote}~\cite{pkg:marginnote} package as well.

As with footnotes it is possible to set mark and text separately using the
equivalent commands \cmd{sidenotemark} and \cmd{sidenotetext}, respectively.
Instead of lots of code examples this documentation will use the \cmd{sidenote}
macro itself extensively. It is assumend you know how to use \cmd{footnote} and
are able to transfer your knowledge.
\secidx*{Introduction}

\section{Usage}\secidx{Usage}
The basic usage is the very same as with \LaTeX's \cmd{footnote}, \cmd{footnotemark}
and \cmd{footnotetext}. Unsurprisingly the presented commands are these:
\begin{beschreibung}
 \Befehl{sidenote}\oa{<mark>}\ma{<text>}\newline
   The basic command. The syntax is the very same as for \cmd{footnote}.
 \Befehl{sidenote}\oa{<offset>}\oa{<mark>}\ma{<text>}\newline
   Actually I lied: \cmd{sidenote} has a second option that smuggles itself
   before the \oa{<mark>} option if you use it: an argument for a vertical offset
   that takes a length. An empty second option assumes you want the automatic
   mark. If you use this argument the note is set with the \cmd{marginnote}
   command\sidenote[*-3][]{From the \paket{marginnote} package}.
   Please see its documentation\sidenote[*-2][]{For example with \texttt{texdoc
   marginnote} on your command line.}~\cite{pkg:marginnote} for the \da{<offset>}
   argument. \snotez only passes the value on.\par
   \sinceversion{0.3} Actually, this is only part of the truth: while typing this
   documentation I repeatedly found myself shifting notes by multiples of
   \cmd{baselineskip} so the argument accepts a shortcut for this. A star \code{*}
   followed by a (positive or negative) number denotes a multiple of \cmd{baselineskip}.
   By the way: a positive value shifts the note \emph{down}.\par
   When you're using the \key{dblarg}{false} option this second optional argument
   has parentheses instead of square brackets!
 \Befehl{sidenotemark}\oa{<text>}\newline
   This command has the same purpose as \cmd{footnotemark} but for sidenotes.
 \Befehl{sidenotetext}\oa{<mark>}\ma{<text>}\newline
   The same as \cmd{footnotetext} but for sidenotes. Beware where you place it:
   it calls \cmd{marginpar} or \cmd{marginnote} and thus determines where the
   actual note is placed.
 \Befehl{sidenotetext}\oa{<offset>}\oa{<mark>}\ma{<text>}\newline
   I lied again: \cmd{sidenotetext} also has the second optional argument
   \oa{<offset>} that again smuggles itself before the \oa{<mark>} option if you
   use it. For details see the second description of the \cmd{sidenote} command.
\end{beschreibung}

Here is one short example of the usage.

\begin{beispiel}[code only]
 % produces a sidenote with automatic number in a
 % \marginpar:
 \sidenote{A note}

 % produces a sidenote with mark `a' in a
 % \marginpar:
 \sidenote[a]{A note}

 % produces a sidenote with automatic number in a
 % \marginnote:
 \sidenote[][]{A note}
 % alternative syntax (dblarg=false):
 \sidenote(){A note}

 % produces a sidenote with automatic number in a
 % \marginnote shifted down by \baselineskip:
 \sidenote[*][]{A note}
 % alternative syntax (dblarg=false):
 \sidenote(*){A note}

 % produces a sidenote with automatic number in a
 % \marginnote shifted up by 2ex:
 \sidenote[-2ex][]{A note}
 % alternative syntax (dblarg=false):
 \sidenote(-2ex){A note}

 % produces a sidenote with mark `a' in a
 % \marginnote shifted down by 2\baselineskip:
 \sidenote[*2][a]{A note}
 % alternative syntax (dblarg=false):
 \sidenote(*2)[a]{A note}
\end{beispiel}
\secidx*{Usage}

\section{Options}\secidx{Options}
Although all options can be used as package option you can also set all options
(locally) with a setup command:
\begin{beschreibung}
 \Befehl{setsidenotes}{<options>}
\end{beschreibung}
Available options are these:
\begin{beschreibung}
 \Option{dblarg}{\default{true}|false}\Default{true}
   \sinceversion{0.3}\emph{This option can only be used as a package option!}
   Prior to version~0.3 \snotez' \cmd{sidenote} and \cmd{sidenotetext} had both
   their optional arguments with square brackets where the use of one argument
   referred to the mark but when both were used the first argument referred to
   the offset and the second to the mark. This syntax is kept with this option.
   Setting it to \code{false} changes the \oa{<offset>} argument syntax into
   \da{<offset>}.\par
   \emph{If you're using \snotez together with the \paket*{fnpct} package~\cite{pkg:fnpct}
   you cannot set \key{dblarg} to \code{false}. Otherwise the \da{<offset>}
   argument get's lost!}
 \Option{marginnote}{\default{true}|false}\Default{false}
   Use \paket{marginnote}'s \cmd{marginnote}~\cite{pkg:marginnote} for all
   \cmd{sidenote}s. In the default setting \cmd{sidenote} uses \cmd{marginpar}s
   to set the sidenote unless you use the \oa{<offset>} argument. If you use
   this option \emph{all} sidenotes are set with \cmd{marginnote}. \emph{This
   option can only be used in the preamble}.
 \Option{text-format}{<code>}\Default{\cmd*{footnotesize}}
   The format of the sidenote text.
 \Option{text-format+}{<code>}\Default{}
   Code to be appended to the format set with \key{text-format}\sidenote{This
   document, for example, appends \paket*{ragged2e}'s \cmd*{RaggedRight}~\cite{pkg:ragged2e}
   to the sidenote's format.}.
 \Option{perpage}{\default{true}|false}\Default{false}
   Make sidenotes counter per page. \emph{This option can only be set in the
   preamble}. It uses package \paket{perpage}'s~\cite{pkg:perpage}
   \cmd{MakeSortedPerPage} macro for the task. Otherwise the macro
   \cmd{MakeSorted} is used. In the default setting sidenotes are counted per
   chapter. If you want sidenotes counted document-wise together with a class
   that defines a counter \code{chapter} then use for example the package
   \paket*{chngcntr}~\cite{pkg:chngcntr} and issue
   \cmd*{counterwithout}{sidenote}\ma{chapter} after loading \snotez.
   This documentation is an example for the use of the option.
 \Option{note-mark-sep}{<code>}\Default{\cmd*{space}}
   The separator between sidenote mark and sidenote text in the sidenote.
 \Option{note-mark-format}{<code>}\Default{\cmd*{@textsuperscript}\{\cmd*{normalfont}\#1\}}
   The format of the sidenote mark in the sidenote. Please refer to the actual
   mark with \code{\#1}.
 \Option{text-mark-format}{<code>}\Default{\cmd*{@textsuperscript}\{\cmd*{normalfont}\#1\}}
   The format of the sidenote mark in the text\sidenote[*-][]{This document uses
   Michael Sharpe's \paket*{superiors} package~\cite{pkg:superiors} and redefines
   the mark formats to use its \cmd*{textsu} command.}. Please refer to the actual
   mark with \code{\#1}.
 \Option{footnote}{\default{true}|false}\Default{false}
   Let\sidenote[*][]{In the sense of \cmd*{let}} \cmd{footnote} to be \cmd{sidenote},
   \cmd{footnotemark} to be \cmd{sidenotemark} and \cmd{footnotetext} to be
   \cmd{sidenotetext}. \emph{This option can only be used in the preamble}.
\end{beschreibung}

As a short example this is how the sidenotes for this document are formatted:
\begin{beispiel}[code only]
\setsidenotes{
  note-mark-format=#1.,
  text-mark-format=\textsu{\hspace*{\superiors@spaced}#1},
  text-format+=\RaggedRight,
  perpage=true
}
\end{beispiel}
\secidx*{Options}

\setlength{\linewidth}{\dimexpr\textwidth+.5\marginparwidth}
\printbibliography

\section{Implementation}
In the following code the lines 1--30 have been omitted. They only repeat the
license statement which has already been mentioned in section~\ref{sec:license}.

\implementation[linerange={31-1000},firstnumber=31]

\indexprologue{\noindent Section titles are indicated \textbf{bold}, packages
\textsf{sans serif}, commands \code{\textbackslash\textcolor{code}{brown}}
 and options \textcolor{key}{\code{yellow}}.\par\bigskip}
 
\printindex

\end{document}