summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/sidenotes/sidenotes.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2011-08-24 00:07:33 +0000
committerKarl Berry <karl@freefriends.org>2011-08-24 00:07:33 +0000
commit10322a6edc9530dda41f6d12e340caf7b3d6cd9a (patch)
treed81f2af36cc59d9a5b7cf933b576e417c31bfa2f /Master/texmf-dist/source/latex/sidenotes/sidenotes.dtx
parent5ee555b18c5d1b514f56d1583cb66ad016b9c0c6 (diff)
sidenotes (23aug11)
git-svn-id: svn://tug.org/texlive/trunk@23664 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/sidenotes/sidenotes.dtx')
-rw-r--r--Master/texmf-dist/source/latex/sidenotes/sidenotes.dtx303
1 files changed, 303 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/sidenotes/sidenotes.dtx b/Master/texmf-dist/source/latex/sidenotes/sidenotes.dtx
new file mode 100644
index 00000000000..5a12e994e07
--- /dev/null
+++ b/Master/texmf-dist/source/latex/sidenotes/sidenotes.dtx
@@ -0,0 +1,303 @@
+% \iffalse meta-comment
+%
+% Copyright (C) 2011 by Andy Thomas <andy.thomas(at)uni.bielefeld.de>
+%
+% 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 2003/12/01 or later.
+%
+% The author of this work is Andy Thomas
+%
+%<*driver>
+\ProvidesFile{sidenotes.dtx}[%
+%</driver>
+%<package>\ProvidesPackage{sidenotes}[%
+%<*driver|package>
+ 2011/08/21 v0.2 footnotes in the margin for LaTeX]
+%</driver|package>
+%<package>\RequirePackage{marginnote} % puts the stuff in the margin and provides an offset option instead of a float
+%<package>\RequirePackage{caption} % handles the figure caption (in the margin)
+%<package>\RequirePackage{environ} % to define new environments more easily
+%<package>\RequirePackage{xifthen} % provide an if command
+%<package>\RequirePackage{twoopt} % cite in the biblatex package has 2 optional arguments
+%<*driver>
+\documentclass{ltxdoc}
+\EnableCrossrefs
+\CodelineIndex
+\RecordChanges
+\begin{document}
+ \DocInput{sidenotes.dtx}
+ \PrintChanges
+ \PrintIndex
+\end{document}
+%</driver>
+% \fi
+%
+% \CheckSum{0}
+%
+% \CharacterTable
+% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
+% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
+% Digits \0\1\2\3\4\5\6\7\8\9
+% Exclamation \! Double quote \" Hash (number) \#
+% Dollar \$ Percent \% Ampersand \&
+% Acute accent \' Left paren \( Right paren \)
+% Asterisk \* Plus \+ Comma \,
+% Minus \- Point \. Solidus \/
+% Colon \: Semicolon \; Less than \<
+% Equals \= Greater than \> Question mark \?
+% Commercial at \@ Left bracket \[ Backslash \\
+% Right bracket \] Circumflex \^ Underscore \_
+% Grave accent \` Left brace \{ Vertical bar \|
+% Right brace \} Tilde \~}
+%
+%
+% \changes{v0.2}{2011/08/21}{Initial version}
+%
+% \GetFileInfo{sidenotes.dtx}
+%
+% \DoNotIndex{\newcommand,\newenvironment}
+%
+%
+% \title{The \textsf{sidenotes} package\thanks{This document
+% corresponds to \textsf{sidenotes}~\fileversion, dated \filedate.}}
+% \author{Andy Thomas\\ \texttt{andy.thomas(at)uni-bielefeld.de}\\ \\Oliver Schebaum }
+%
+% \maketitle
+%
+% \begin{abstract}
+% This package tries to allow typesetting of texts with notes,
+% figures, citations, captions and tables in the margin. This is common
+% in science textbooks such as Feyman's \textit{Lectures on Physics}.
+% \end{abstract}
+%
+% \tableofcontents
+%
+% \section{Usage}
+%
+% \DescribeMacro{\sidenote}
+% The macro \verb+\sidenote+ is the main feature of the package. The macro is very similar to
+% the footnote macro and tries to emulate its behavior. But like the name
+% says, the note is put in the margin, hence the name sidenote. It has the
+% same parameters as footnote plus an additional, optional offset:
+% \verb+\sidenote[number]{text}[offset]+. If no offset is given, the sidenote moves up or down (floats)
+% to not overlap with other floats in the margin. If you use the offset
+% (e.g. \verb+\sidenote{foo}[10pt]+) the sidenote is shifted 10pt down in the margin.
+% It might overlap with other floats now. This means, omitting the offset and [0pt] do
+% not lead to the same result, but you will only notice if there are a moderate number
+% of sidenotes or other marginals.
+% \DescribeMacro{\sidenotemark}
+% Sidenote tries to mimic the footnote behavior,
+% so you can also use \verb+\sidenotemark[number]+ and \verb+\sidenotetext[number]{text}+ commands.
+% \DescribeMacro{\sidenotetext}
+% This is especially useful, if your are in an environment that does not allow to evoke foot- or sidenote macros.
+% \DescribeMacro{\sidestyle}
+% You can use \verb+\renewcommand{\sidestyle}{something}+
+% if you want to change the font, text size, text color or something else of the sidenotes.
+% It it initialized with \verb+\footnotesize+.
+%
+% \DescribeMacro{\sidecite}
+% The macro \verb+\sidecite+ puts a citation in the margin. It uses the biblatex package
+% so you have to go with biblatex instead of bibtex to use this feature. Therefore, the
+% macro has the same set of parameters plus the offset:
+% \verb+\sidecite[prenote][postnote]{key}[offset]+.
+% The behavior is the same as in \verb+\sidenote+, no offset means auto floating. If an offset
+% value is given the position is fixed at a certain place, even if it overlaps with other text or objects.
+%
+%\DescribeMacro{\sidecaption}
+% The \verb+\sidecaption+ macro can be used if the caption of a figure or table
+% is supposed to be in the margin. Please note, that the formatting is done by the
+% caption package. If the object is referenced by the use of \verb+\label{somelabel}+
+% the label should go in the sidecaption macro: For example
+% \verb+\sidecaption{I am a figure\label{fig:1}}+.
+%
+% \DescribeEnv{sidefigure}
+% The sidefigure environment puts a figure and its caption in the margin. Instead of
+% \verb+\begin{figure}[htb]+ use \verb+\begin{sidefigure}[offset]+. Please note, that
+% the use of caption before \verb+\includegraphics+ or such puts the caption on top
+% and the use after puts it below the actual figure.
+%
+% \DescribeEnv{sidetable}
+% The sidetable environment works similarly, use \verb+\begin{sidetable}[offset]+ instead
+% of \verb+\begin{table}+.
+%
+% \section{Technical notes and further macros}
+%
+% \DescribeMacro{\marginnote}
+% \DescribeMacro{\marginpar}
+% Sometimes it is useful to put text in the margin without the mark in the text. This can be achieved
+% with \verb+\marginnote{text}[offset]+ or \verb+\marginpar{text}+. This feature is not provided
+% by this package, but by the
+% marginnote package by Markus Kohm. The sidenotes package heavily uses the marginnote package.
+% Technically, every time something is evoked with an offset, \verb+\marginnote+ is called. If it is called without
+% an offset, it calls the normal \LaTeX{} macro \verb+\marginpar+. This is not true for the sidecaption, since
+% the caption has to be adjacent to the figure or table. In that case, \verb+\marginnote+ is always used.
+% The package also relies on the caption package by Harald Axel Sommerfeldt.
+% The formatting of the figure and table captions
+% has to be done through the caption package.
+%
+% Right now, the package also requires the packages twoopt, environ and xifthen as well. At least the dependence
+% on twoopt and environ should be omitted in the next versions.
+%
+% When writing the package, we tried to be as general as possible. Someone can e.g.\ use sidenotes mixed with
+% footnotes. Also, the package tries to provide only functionality and does not know anything about formatting
+% such as margin text size, color or anything else. Only \verb+\sidestyle+ was added for convinience. If you are
+% looking for a package that provides formatting defaults as well you might want to look into the tufte-latex packages.
+% \StopEventually{}
+%
+% \section{Implementation}
+%
+% \begin{macro}{\sidestyle}
+% This macro changes the text formatting of the sidenotes.
+% Initially it just sets the text size to the footnote text size.
+% \begin{macrocode}
+\newcommand*{\sidestyle}{\footnotesize}
+% \end{macrocode}
+% \end{macro}
+% We need a counter similar to the footnote counter and we want to
+% have a buffer.
+% \begin{macrocode}
+\newcounter{sidenote} % make counter
+\newcounter{@sidenotes@buffer}
+\setcounter{sidenote}{1} % init counter
+% \end{macrocode}
+
+% \begin{macro}{\sidenote}
+% Introduce the sidenote macro with an additional optional argument postfix to set the offset.
+% \begin{macrocode}
+\newcommand*{\sidenote}[2][]{%
+ \begingroup%
+ \@ifnextchar [{\@sidenotes@sidenote[{#1}]{#2}}{\@sidenotes@sidenote[{#1}]{#2}[]}%
+}
+
+\newcommand{\@sidenotes@sidenote}{}
+\def\@sidenotes@sidenote[#1]#2[#3]{%
+ \endgroup%
+ \@sidenotes@@sidenote[{#1}]{#2}[{#3}]%
+}
+
+\newcommand{\@sidenotes@@sidenote}{}
+\def\@sidenotes@@sidenote[#1]#2[#3]{%
+ \ifthenelse{\isempty{#1}}%
+ {\sidenotemark%
+ \sidenotetext{#2}[#3]}%
+ {\sidenotemark[#1]%
+ \sidenotetext[#1]{#2}}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\sidenotemark}
+% Sidenotemark is supposed to work similarly to footnotemark.
+% \begin{macrocode}
+\newcommand{\sidenotemark}[1][]{%
+ \nobreak\hspace{0.1pt}\nobreak%
+ \ifthenelse{\isempty{#1}}%
+ {\textsuperscript{\thesidenote}%
+ \refstepcounter{sidenote}}% if no argument is given use sidenote counter%
+ % else
+ {\setcounter{@sidenotes@buffer}{\value{sidenote}}%
+ \setcounter{sidenote}{#1}%
+ \textsuperscript{\thesidenote}% print out the argument otherwise
+ \setcounter{sidenote}{\value{@sidenotes@buffer}}}%
+ \ignorespaces%
+}%
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\sidenotetext}
+% Sidenotetext is supposed to work similarly to footnotetext. The additional, optional argument postfix sets the offset.
+% \begin{macrocode}
+\newcommand*{\sidenotetext}[2][]{%
+ \begingroup%
+ \@ifnextchar [{\@sidenotes@sidenotetext[{#1}]{#2}}{\@sidenotes@sidenotetext[{#1}]{#2}[]}%
+}
+
+\newcommand{\@sidenotes@sidenotetext}{}
+\def\@sidenotes@sidenotetext[#1]#2[#3]{%
+ \endgroup%
+ \@sidenotes@@sidenotetext[{#1}]{#2}[{#3}]%
+}
+
+\newcommand{\@sidenotes@@sidenotetext}{}
+\def\@sidenotes@@sidenotetext[#1]#2[#3]{%
+ \ifthenelse{\isempty{#1}}{% sitenotemark given?
+ \addtocounter{sidenote}{-1}%
+ \ifthenelse{\isempty{#3}}{% offset?
+ \marginpar{\textsuperscript{\thesidenote}{} \sidestyle#2}}% no offset
+ {\marginnote{\textsuperscript{\thesidenote}{} \sidestyle#2}[#3]} % with offest
+ \addtocounter{sidenote}{1}}%
+ % else
+ {\ifthenelse{\isempty{#3}}% offset?
+ {\marginpar{\textsuperscript{#1} \sidestyle#2}}% no offset
+ {\marginnote{\textsuperscript{\thesidenote}{} \sidestyle#2}}% with offset
+ }% fi
+}%
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\sidecite}
+% Sidecite puts the citation in the margin. The additional, optional argument postfix sets the offset.
+% Please note, that it only works with biblatex and uses its syntax.
+% \begin{macrocode}
+\newcommandtwoopt{\sidecite}[3][][]{%
+ \begingroup%
+ \@ifnextchar [{\@sidenotes@sidecite[{#1}][{#2}]{#3}}{\@sidenotes@sidecite[{#1}][{#2}]{#3}[]}%
+}
+\newcommand{\@sidenotes@sidecite}{}
+\def\@sidenotes@sidecite[#1][#2]#3[#4]{%
+ \endgroup%
+ \@sidenotes@@sidecite[{#1}][{#2}]{#3}[{#4}]%
+}
+
+\newcommand{\@sidenotes@@sidecite}{}
+\def\@sidenotes@@sidecite[#1][#2]#3[#4]{%
+ \sidenote{\fullcite[#1][#2]{#3}}[#4]%
+}%
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\sidecaption}
+% Sidecaption puts the caption in the margin. The additional, optional argument postfix sets the offset.
+% It never floats with the other text in the margin, it has to be next to the figure.
+% \begin{macrocode}
+\newcommand{\sidecaption}[2][]{%
+ \ifthenelse{\isempty{#1}}%
+ {\marginnote{\caption{#2}}}%
+ % else
+ {\marginnote{\caption[#1]{#2}}}%
+}%
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{environment}{sidefigure}
+% The sidefigure is similar to the figure environment. But the figure is put in the margin and the positioning
+% is not h or b, but rather an offset, e.g.\ 10pt.\
+% \begin{macrocode}
+\NewEnviron{sidefigure}[1][]{%
+ \ifthenelse{\isempty{#1}} % offset?
+ {\marginpar{\captionsetup{type=figure}\BODY}} % no offset
+ {\marginnote{\captionsetup{type=figure}\BODY}[#1]} % with offset
+}%
+% \end{macrocode}
+% \end{environment}
+%
+% \begin{environment}{sidetable}
+% The sidetable is similar to the table environment. But the table is put in the margin and the positioning
+% is not h or b, but rather an offset, e.g.\ 10pt.\
+% \begin{macrocode}
+\NewEnviron{sidetable}[1][]{%
+ \ifthenelse{\isempty{#1}} % offset?
+ {\marginpar{\captionsetup{type=table}\sidestyle\BODY}} % no offset
+ {\marginnote{\captionsetup{type=table}\sidestyle\BODY}[#1]} % with offset
+}%
+% \end{macrocode}
+% \end{environment}
+%
+% \Finale
+\endinput