From 9d0bdc017d2c211e0b87ffad503d0b306c7de7ca Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Tue, 13 Nov 2012 00:18:04 +0000 Subject: sidenotes (11nov12) git-svn-id: svn://tug.org/texlive/trunk@28239 c570f23f-e606-0410-a88d-b1316a301751 --- .../source/latex/sidenotes/sidenotes.dtx | 282 +++++++++++---------- 1 file changed, 154 insertions(+), 128 deletions(-) (limited to 'Master/texmf-dist/source') diff --git a/Master/texmf-dist/source/latex/sidenotes/sidenotes.dtx b/Master/texmf-dist/source/latex/sidenotes/sidenotes.dtx index 63184c9097f..b4a08ccb7a1 100644 --- a/Master/texmf-dist/source/latex/sidenotes/sidenotes.dtx +++ b/Master/texmf-dist/source/latex/sidenotes/sidenotes.dtx @@ -2,7 +2,7 @@ % % sidenotes.dtx % -% Copyright (C) 2011 by Andy Thomas +% Copyright (C) 2011 by Andy Thomas % % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either version 1.3 @@ -19,16 +19,13 @@ % %\ProvidesPackage{sidenotes}[% %<*driver|package> - 2011/11/29 v0.81 rich text in the margin for LaTeX] + 2012/11/09 v0.92 rich text in the margin for LaTeX] % %\RequirePackage{marginnote} % puts the stuff in the margin and provides an offset option instead of a float %\RequirePackage{caption} % handles the figure caption (in the margin) %\RequirePackage{xifthen} % provide an if command -%\newboolean{@sidenotes@bibtex}% -%\setboolean{@sidenotes@bibtex}{false}% -%\DeclareOption{bibtex}{\setboolean{@sidenotes@bibtex}{true}}% -%\ProcessOptions -%\ifthenelse{\boolean{@sidenotes@bibtex}}{\RequirePackage{bibentry}}{} +%\RequirePackage{twoopt} % two optional arguments possible +%\RequirePackage[strict]{changepage} % Changepage package for symmetric twoside handling %<*driver> \documentclass{ltxdoc} \CodelineIndex @@ -64,21 +61,24 @@ % % \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 } +% \author{Andy Thomas\\ \texttt{andythomas(at)web.de}\\ \\Oliver Schebaum } % % \maketitle % % \changes{v0.51}{2011/10/05}{Extent the documentation of the macros.} +% \changes{v0.90}{2012/06/02}{two opt package is required, the definitions are too confusing otherwise} +% \changes{v0.92}{2012/11/09}{corrected typo in email address} % \begin{abstract} -% This package tries to allow typesetting of rich content in the margin. +% This package tries to allow the typesetting of rich content in the margin. % This includes text, but also figures, captions, tables and citations. -% This is common in science textbooks such as Feyman's \textit{Lectures on Physics}. +% This is common in science textbooks such as Feynman's \textit{Lectures on Physics}. % \end{abstract} % % \tableofcontents % % \changes{v0.2}{2011/08/21}{Initial version} % \changes{v0.7}{2011/11/09}{rewrite without optional offsets} +% \changes{v0.91}{2012/06/03}{deleted marginfullcite} % % \section{Usage} % @@ -86,90 +86,78 @@ % 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: -% \verb+\sidenote[number]{text}+. The sidenote moves up or down (floats) -% to not overlap with other floats in the margin. All the sidenotes are subsequently numbered. The -% first, optional parameter will manually change the numbering of the sidenote. +% same parameters as footnote, plus an additional offset: +% \verb+\sidenote[number][offset]{text}+. The sidenote moves up or down (floats) +% to not overlap with other floats in the margin if no offset is given. +% and all the sidenotes are subsequently numbered. The +% first, optional parameter will manually change the numbering. +% The sidenote will be fixed at a particular position in the margin if the +% offset parameter is used. % % \DescribeMacro{\sidenotemark} % Sidenote tries to mimic the footnote behavior and tries to provide the same solutions. % Sometimes it is not possible to directly % call a sidenote macro, e.g. in particular environments. Then, -% you can also use \verb+\sidenotemark[number]+ and \verb+\sidenotetext[number]{text}+ +% you can also use \verb+\sidenotemark[number]+ and \verb+\sidenotetext[number][offset]{text}+ % commands. \verb+\sidenotemark+ puts a mark at the current position. Then, outside of the environment % \DescribeMacro{\sidenotetext} -% that causes the trouble, it is possible the call \verb+\sidenotetext{text}+ to actually make the sidenote. -% The -% first, optional parameter will manually change the numbering of the sidenote. +% that causes the trouble, it is possible the call \verb+\sidenotetext[number][offset]{text}+ +% to actually make the sidenote. The +% first, optional parameter will change the numbering of the sidenote and the offset +% parameter will change the position manually. % % \changes{v0.61}{2011/10/17}{documentation of sidetext} % -% \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+. It is used as a prefix of the sidenotetext and sidetext. -% -% \DescribeMacro{\sidecite} -% The macro \verb+\sidecite+ puts a citation in the margin. It uses the biblatex package or bibtex, -% load sidecite with the option [bibtex] for the latter. -% The macro has the same set of parameters. -% \verb+\sidecite[prenote][postnote]{key}+ for biblatex and \verb+\sidecite{key}+ for bibtex. -% The behavior is the same as in \verb+\sidenote+ and auto floating. -% For post- and prenote please refer to the biblatex manual, the parameters are directly passed -% to biblatex. -% %\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. -% -% \DescribeEnv{sidefigure} -% The sidefigure environment puts a figure and its caption in the margin. Instead of -% \verb+\begin{figure}[htb]+ use \verb+\begin{sidefigure}+. Please note, that -% the use of caption before \verb+\includegraphics+ puts the caption in line with the -% top of the figure -% and the use after \verb+\includegraphics+ puts it in line with the bottom of the actual figure. -% -% \DescribeEnv{sidetable} -% The sidetable environment works similarly, but with table environments. Use \verb+\begin{sidetable}+ instead -% of \verb+\begin{table}+. -% -% \section{Technical notes and further macros} -% -% \DescribeMacro{\marginpar} -% Sometimes it is useful to put text in the margin without a mark in the text. This can be achieved -% with \verb+\marginpar{text}+. The \verb+\sidecaption+ macro relies on the -% marginnote package by Markus Kohm. -% -% 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 convenience. If you are -% looking for a package that provides formatting defaults as well you might want to look into the tufte-latex packages. +% The \verb+\sidecaption[entry][offset]{text}+ macro can be used if the caption of a figure or table +% is supposed to be in the margin. The caption has to be adjacent to the figure, so a float is not an option +% here. Therefore, the caption might overlap with sidenotes that have to be manually adjusted. +% Please note, that the formatting is done by the caption package by defining a sidecaption style. +%\DescribeMacro{\sidecaption*} +% This macro has a sister \verb+\sidecaption*[offset]{text}+ that generates no entry. +% +% \DescribeEnv{marginfigure} +% The marginfigure environment puts a figure and its caption in the margin. Instead of +% \verb+\begin{figure}[htbp]+ use \verb+\begin{marginfigure}[offset]+. The offset switches the behavior +% from float to fixed position. +% +% \DescribeEnv{margintable} +% The margintable environment works similarly, but with table environments. Use \verb+\begin{margintable}[offset]+ instead +% of \verb+\begin{table}[htbp]+. +% +% \DescribeEnv{figure*} +% The \verb+figure*+ environment is used to position figures across the full page, i.e. the text width plus +% margin. The captions type can be changed by changing the widefigure style. +% \DescribeEnv{table*} +% The \verb+table*+ environment is very similar, but for tables. Use widetable for its caption style. +% +% \section{Technical note} +% +% When writing the package, we tried to provide a minimum extension to standard \LaTeX{} for typesetting +% rich content in the margin. Also, we tried to not break compatibility with packages the user might +% want to additionally load in a custom class file or a document. However, the following packages are +% needed by this package and might introduce side effects with other packages. % % \section{Required packages} % % \changes{v0.52}{2011/10/06}{added a section that the package needs marginnote, caption and xifthen.} -% This package requires the following packages: +% \changes{v0.90}{2012/06/02}{added a section that the package needs twoopt and changepage.} % \begin{description} % \item[marginnote] -% supports another command to create notes in the margin. The notes are no floats and can be shifted up or down. +% supports another command to create notes in the margin. The notes are not floats and can be shifted up or down. % \item[caption] % is used to set figure and table captions in the margin and to allow formatting of these captions. -% \item[xifthen] is used to test for empty, optional arguments. +% \item[xifthen] is used to test for empty, optional arguments. +% \item[twoopt] is used to define macros with two optional arguments. +% \item[changepage] is used to correctly shift figure* and table*. It has to use the option [strict]. % \end{description}% % % \section{Implementation} % % \iffalse %<*package> -% \fi% -% \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} +% \fi +% \changes{v0.91}{2012/06/03}{sidenotetextstyle is not needed any more} % We need a counter similar to the footnote counter and we want to % have a buffer. % \begin{macrocode} @@ -179,18 +167,17 @@ % \end{macrocode} % \begin{macro}{\sidenote} -% Introduce the sidenote macro with an additional optional argument postfix to set the offset. +% Introduce the sidenote macro with an additional optional argument to set the offset. % \changes{v0.53}{2011/10/07}{bugfix, now optional number and offset possible} % \changes{v0.80}{2011/11/10}{unstar the newcommand.} % \changes{v0.81}{2011/11/29}{added a comma between subsequent sidenotes} +% \changes{v0.90}{2012/06/02}{add optional offset for sidenote} % \begin{macrocode} -\newcommand{\sidenote}[2][]{% -\ifthenelse{\isempty{#1}}% -{\sidenotemark% -\sidenotetext{#2}}% -{\sidenotemark[#1]% -\sidenotetext[#1]{#2}}% -\@ifnextchar\sidenote{\kern-0.07em\textsuperscript{,}}{\@ifnextchar\sidecite{\kern-0.07em\textsuperscript{,}}{ }}% +\newcommandtwoopt{\sidenote}[3][][]{% +\sidenotemark[#1]% +\sidenotetext[#1][#2]{#3}% +\@ifnextchar\sidenote{\kern-0.07em\textsuperscript{,}}% +{\@ifnextchar\sidecite{\kern-0.07em\textsuperscript{,}}{ }}% } % \end{macrocode} % \end{macro} @@ -214,89 +201,128 @@ % \end{macro} % % \begin{macro}{\sidenotetext} -% Sidenotetext is supposed to work similarly to footnotetext. The additional, optional argument postfix sets the offset. +% Sidenotetext is supposed to work similarly to footnotetext. The additional, optional argument sets the offset. % \changes{v0.80}{2011/11/10}{unstar the newcommand.} +% \changes{v0.90}{2012/06/02}{add optional offset for sidenotetext} % \begin{macrocode} -\newcommand{\sidenotetext}[2][]{% +\newcommandtwoopt{\sidenotetext}[3][][]{% \ifthenelse{\isempty{#1}}{% sitenotemark given? \addtocounter{sidenote}{-1}% -\marginpar{\textsuperscript{\thesidenote}{} \sidestyle#2}% +\ifthenelse{\isempty{#2}}% offset given? +{\marginpar{\textsuperscript{\thesidenote}{} #3}}% +{\marginnote{\textsuperscript{\thesidenote}{} #3}[#2]}% \addtocounter{sidenote}{1}}% -{\marginpar{\textsuperscript{#1} \sidestyle#2}% -}% fi +{\ifthenelse{\isempty{#2}}% offset given? +{\marginpar{\textsuperscript{#1} #3}} +{\marginnote{\textsuperscript{#1} #3}[#2]}} }% % \end{macrocode} % \end{macro} % -% -% \begin{macro}{\sidecite} -% \changes{v0.5}{2011/10/05}{define the sidecite macro without the twoopt package} -% \changes{v0.80}{2011/11/10}{allow the use of bibtex} -% 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} -\ifthenelse{\boolean{@sidenotes@bibtex}} -{\newcommand{\sidecite}[1]{% -\sidenote{\bibentry{#1}}% -}} -{\newcommand{\sidecite}[1][]{% - \@ifnextchar[{% - \expandafter\@sidenotes@sidecitedo\@sidenotes@getnextopt{#1}% - }{% - \@sidenotes@sidecitedo{#1}{}% - }% -} -\newcommand{\@sidenotes@getnextopt}{} -\long\def\@sidenotes@getnextopt#1[#2]{{#1}{#2}} -\newcommand{\@sidenotes@sidecitedo}[3]{% -\sidenote{\fullcite[#1][#2]{#3}}% -}}% -% \end{macrocode} -% \end{macro} -% % \begin{macro}{\sidecaption} +% \changes{v0.91}{2012/06/03}{sidecaption* accompanies sidecaption} % Sidecaption puts the caption in the margin. -% It never floats with the other text in the margin, it has to be next to the figure. +% It never floats with the other text in the margin, since it has to be next to the figure. +% Sidecaption* works similarly to sidecaption, but without an entry. % \begin{macrocode} -\newcommand{\sidecaption}[2][]{% -\ifthenelse{\isempty{#1}}% -{\marginnote{\caption{#2}}}% -{\marginnote{\caption[#1]{#2}}}% -}% +\DeclareCaptionStyle{sidecaption}{font=footnotesize} +\newcommand{\sidecaption}{\@ifstar\@sidenotes@sidecaption@starred\@sidenotes@sidecaption@unstarred} +\newcommandtwoopt{\@sidenotes@sidecaption@unstarred}[3][][]{% +\captionsetup{style=sidecaption}% +\ifthenelse{\isempty{#2}}{\marginnote{\caption[#1]{#3}}}{\marginnote{\caption[#1]{#3}}[#2]}}% +\newcommand{\@sidenotes@sidecaption@starred}[2][]{% +\captionsetup{style=sidecaption}% +\ifthenelse{\isempty{#1}}{\marginnote{\caption*{#2}}}{\marginnote{\caption*{#2}}[#1]}}% +% % \end{macrocode} % \end{macro} % -% \begin{environment}{sidefigure} +% \begin{environment}{marginfigure} % \changes{v0.3}{2011/09/29}{define the sidefigure enviroment without the environ package} -% The sidefigure is similar to the figure environment. But the figure is put in the margin. +% \changes{v0.90}{2012/06/02}{the optional offset parameter is back, renamed environment from sidefigure to marginfigure} +% The marginfigure is similar to the figure environment. But the figure is put in the margin. % \begin{macrocode} \newsavebox{\@sidenotes@sidefigurebox} -\newenvironment{sidefigure}[1][]% -{\begin{lrbox}{\@sidenotes@sidefigurebox}% +\newboolean{@sidenotes@sidefigure@skip} +\newcommand{\@sidenotes@sidefigure@skiplength}{} +\DeclareCaptionStyle{marginfigure}{font=footnotesize} +\newenvironment{marginfigure}[1][]% +{\ifthenelse{\isempty{#1}}% offset? +{\setboolean{@sidenotes@sidefigure@skip}{false}}% +{\setboolean{@sidenotes@sidefigure@skip}{true}% +\renewcommand{\@sidenotes@sidefigure@skiplength}{#1}}% +\begin{lrbox}{\@sidenotes@sidefigurebox}% \begin{minipage}{\marginparwidth}% -\captionsetup{type=figure}}% +\captionsetup{type=figure,style=marginfigure}}% {\end{minipage}% \end{lrbox}% -\marginpar{\usebox{\@sidenotes@sidefigurebox}} +\ifthenelse{\boolean{@sidenotes@sidefigure@skip}}% offset? +{\marginnote{\usebox{\@sidenotes@sidefigurebox}}[\@sidenotes@sidefigure@skiplength]}% offset +{\marginpar{\usebox{\@sidenotes@sidefigurebox}}}% no offset } % \end{macrocode} % \end{environment} % -% \begin{environment}{sidetable} +% \begin{environment}{margintable} % \changes{v0.4}{2011/09/30}{define the sidetable enviroment without the environ package} +% \changes{v0.90}{2012/06/02}{the optional offset parameter is back, renamed environment from sidetable to margintable} % The sidetable is similar to the table environment. But the table is put in the margin. % \begin{macrocode} -\newsavebox{\@sidenotes@sidetablebox} -\newenvironment{sidetable}[1][]% -{\begin{lrbox}{\@sidenotes@sidetablebox}% +\newsavebox{\@sidenotes@margintablebox} +\newboolean{@sidenotes@margintable@skip} +\newcommand{\@sidenotes@margintable@skiplength}{} +\DeclareCaptionStyle{margintable}{font=footnotesize} +\newenvironment{margintable}[1][]% +{\ifthenelse{\isempty{#1}}% +{\setboolean{@sidenotes@margintable@skip}{false}}% +{\setboolean{@sidenotes@margintable@skip}{true}% +\renewcommand{\@sidenotes@margintable@skiplength}{#1}}% +\begin{lrbox}{\@sidenotes@margintablebox}% \begin{minipage}{\marginparwidth}% -\captionsetup{type=table}% -\sidestyle}% +\captionsetup{type=table,style=margintable}}% {\end{minipage}% \end{lrbox}% -\marginpar{\usebox{\@sidenotes@sidetablebox}} -}% \end{macrocode} +\ifthenelse{\boolean{@sidenotes@margintable@skip}}% +{\marginnote{\usebox{\@sidenotes@margintablebox}}[\@sidenotes@margintable@skiplength]}% +{\marginpar{\usebox{\@sidenotes@margintablebox}}} % +}% +% \end{macrocode} % \end{environment} % +%\begin{environment}{figure*} +% \changes{v0.85}{2011/06/01}{added the figure* environment} +% The figure* environment provides a figure environment for figures across text and margin width +% \begin{macrocode} +\AtBeginDocument{% +\newlength{\@sidenotes@extrawidth} +\setlength{\@sidenotes@extrawidth}{\marginparwidth} +\addtolength{\@sidenotes@extrawidth}{\marginparsep} +} +\DeclareCaptionStyle{widefigure}{margin={0pt,-\@sidenotes@extrawidth},font=footnotesize} +\newcommand{\@sidenotes@adjust}{% + \checkoddpage% + \ifoddpage% + % + \else% + \hspace{-\@sidenotes@extrawidth}% + \fi} +\renewenvironment{figure*}[1][htbp]{\begin{figure}[#1]% + \@sidenotes@adjust% + \captionsetup{style=widefigure}% +}{\end{figure}}% +% \end{macrocode} +% \end{environment} + +%\begin{environment}{table*} +% \changes{v0.85}{2011/06/01}{added the table* environment} +% The table* environment provides a table environment for figures across text and margin width +% \begin{macrocode} +\DeclareCaptionStyle{widetable}{margin={0pt,-\@sidenotes@extrawidth},font=footnotesize} +\renewenvironment{table*}[1][htbp]{\begin{table}[#1]% + \@sidenotes@adjust% + \captionsetup{style=widetable}% +}{\end{table}}% +% \end{macrocode} +% \end{environment} % \Finale \endinput -- cgit v1.2.3