diff options
author | Karl Berry <karl@freefriends.org> | 2007-09-03 16:40:01 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2007-09-03 16:40:01 +0000 |
commit | 3299cb982528e3a87d5b444ecd92a98b412970a3 (patch) | |
tree | 061a04d39afb8fd2b363de46bf6fa0746cb82fdf /Master/texmf-dist/source/latex | |
parent | 207e5dcc5a4444530c13477ace667f18656d592d (diff) |
new latex package notes2bib (30aug07)
git-svn-id: svn://tug.org/texlive/trunk@4859 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex')
-rw-r--r-- | Master/texmf-dist/source/latex/notes2bib/notes2bib.dtx | 1161 | ||||
-rw-r--r-- | Master/texmf-dist/source/latex/notes2bib/notes2bib.ins | 33 |
2 files changed, 1194 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/notes2bib/notes2bib.dtx b/Master/texmf-dist/source/latex/notes2bib/notes2bib.dtx new file mode 100644 index 00000000000..06c26173a56 --- /dev/null +++ b/Master/texmf-dist/source/latex/notes2bib/notes2bib.dtx @@ -0,0 +1,1161 @@ +%\iffalse meta-comment +% +% Copyright (C) 2007 by +% Joseph Wright <joseph.wright@morningstar2.co.uk> +% +% Released under the GNU General Public License v2 +% See http://www.gnu.org/licenses/gpl.txt +% +% This work consists of the main source file notes2bib.dtx +% and the derived files notes2bib.sty and notes2bib.pdf +% +%<*driver> +\PassOptionsToClass{a4paper}{article} +\documentclass{ltxdoc} +\EnableCrossrefs +\CodelineIndex +\RecordChanges +%\OnlyDescription +\usepackage[T1]{fontenc} +\usepackage[english,UKenglish]{babel} +\usepackage{mathpazo,booktabs,array,url,graphicx,courier,unitsdef} +\usepackage{upgreek} +\usepackage[scaled=0.95]{helvet} +\usepackage[version=3]{mhchem} +\usepackage[final]{microtype} +% Some tricks from Heiko Oberdiek +\RequirePackage{embedfile} +\embedfile[% + stringmethod=escape,% + mimetype=plain/text,% + desc={LaTeX docstrip source archive for package `\jobname'}% + ]{\jobname.dtx} +\usepackage{\jobname} +\usepackage[numbered]{hypdoc} +\begin{document} + \DocInput{\jobname.dtx} +\end{document} +%</driver> +%\fi +% +%\CheckSum{486} +% +%\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 \~} +% +%\GetFileInfo{\jobname.sty} +% +%\changes{v1.0}{2007/08/30}{Initial public release} +% +%\DoNotIndex{\@arabic,\@bsphack,\@esphack,\@fileswfalse} +%\DoNotIndex{\@ifclassloaded,\@ifnextchar,\@ifpackageloaded} +%\DoNotIndex{\@ifundefined,\@makeother,\@onelevel@sanitize} +%\DoNotIndex{\@undefined,\AtBeginDocument,\AtEndDocument,\autocite} +%\DoNotIndex{\begingroup,\bib@gadd,\blx@bibfiles,\catcode,\cite} +%\DoNotIndex{\closeout,\csname,\DeclareOption,\def,\do,\dospecials} +%\DoNotIndex{\edef,\else,\endcsname,\endgroup,\endnote,\endnotemark} +%\DoNotIndex{\endnotetext,\ExecuteOptions,\expandafter,\fi} +%\DoNotIndex{\footnot,\footnotemark,\footnotetext,\gdef,\global} +%\DoNotIndex{\if@filesw,\ifdefined,\ifnum,\ifx,\ignorespaces} +%\DoNotIndex{\immediate,\jobname,\let,\long,\MessageBreak} +%\DoNotIndex{\NeedsTeXFormat,\newcommand,\newcounter,\newif} +%\DoNotIndex{\newwrite,\nocite,\openout,\PackageInfo,\PackageWarning} +%\DoNotIndex{\patchcmd,\printbibliography,\ProcessOptions,\protect} +%\DoNotIndex{\ProvidesPackage,\relax,\renewcommand,\RequirePackage} +%\DoNotIndex{\space,\stepcounter,\string,\supercite,\the} +%\DoNotIndex{\theendnotes,\value,\write,\xdef,\xspace,\z@} +%\DoNotIndex{\DeclareRobustCommand} +% +%\title{\texttt{notes2bib} --- Integrating notes into the +% bibliography% +% \thanks{This file describes version \fileversion, last revised +% \filedate.}} +%\author{Joseph Wright% +% \thanks{E-mail: joseph.wright@morningstar2.co.uk}} +%\date{Released \filedate} +% +%\maketitle +% +%\begin{abstract} +% The |notes2bib| package defines a new type of note, |bibnote|, +% which will always be added to the bibliography. The package allows +% footnotes and endnotes to be moved into the bibliography in the +% same way. The package can be used with |natbib| and |biblatex| as +% well as plain LaTeX citations. Both sorted and unsorted +% bibliography styles are supported. +%\end{abstract} +% +%\begin{multicols}{2} +%\tableofcontents +%\end{multicols} +% +%\section{Background} +% In most subject areas, bibliographic citations and notes are +% separate entities. However, in some parts of the physical sciences +% (chemistry and physics) it is usual for references to the +% literature and notes to be given together in a ``References and +% Notes'' section. By default, this requires that BibTeX users +% create a notes database for each document that they write. +% +% The |endnotes| package allows the user to create endnotes rather +% than footnotes. However, this does not place the notes in the +% bibliography. The \textsc{aps} have developed the REVTeX document +% class, which allows footnotes and endnotes to be added to the +% bibliography. Notes can only be placed at the end of the +% bibliography using this system. Furthermore, the code to achieve +% this effect is not available as a package separate from REVTeX. +% +% The aim of the |notes2bib| package is to make integration of notes +% into the bibliography easy. Notes can be written as normal in the +% LaTeX source, and are automatically moved to the bibliography. The +% package is compatible with sorted and unsorted bibliography styles. +% The package has been designed for use with numerical citations , +% although it will work with other systems. +% +%\section{Basic use} +%\DescribeMacro{\bibnote} +% In the most basic form, the package can be used simply by loading +% it in the preamble as normal. This adds a new type of note to the +% existing \cmd{\footnote} type: \cmd{\bibnote}. This can be used in +% exactly the same way as a footnote, taking one mandatory argument +% \marg{text}. The \meta{text} will be made available as to the +% bibliography as a note (henceforth referred to as a bibnote). By +% default, each bibnote is given an automatically-generated label +% (see Section \ref{custom} for details of modifying the automatic +% system). However, \cmd{\bibnote} accepts an optional argument +% \oarg{label}, which can be used to over-ride this. This is +% particularly useful when a note will be referenced several times. +% +%\DescribeMacro{\bibnotemark} +%\DescribeMacro{\bibnotetext} +% In common with \cmd{\footnote}, the basic \cmd{\bibnote} macro has +% companion macros \cmd{\bibnotemark} and \cmd{\bibnotetext}. The +% text provided for each not is not ``fragile,'' and so it should not +% be necessary to use \cmd{\bibnotemark} directly. It is needed when +% replacing footnotes by bibnotes. Notice that there \emph{are} +% places where bibnotes will be problematic, for example in section +% headings which also appear in the Table of Contents. In these +% contexts, use \cmd{\cite} to reference the note, or use an optional +% argument to the \cmd{\section}, \emph{etc.} +% +%\subsection{Package options} +% The |notes2bib| package currently accepts a number of options. The +% |footnotes| option turns standard LaTeX footnotes into bibnotes +% \bibnote{The |\thanks| macro used in making titles uses the +% footnote mechanism. This is unaffected by loading |notes2bib| even +% with the |footnote| option.}. Thus footnotes then appear in the +% bibliography with no further user input. The \cmd{\footnotemark} +% and \cmd{\footnotetext} macros are supported, and are aliased to +% \cmd{\bibnotemark} and \cmd{\bibnotetext}, respectively. +% +% The |endnotes| option works in the same way as the |footnotes| one, +% but in this case \cmd{\endnote} text is added to the bibliography. +% The \cmd{\endnote} command is defined by the |endnotes| package, +% but it is not necessary to load the |endnotes| package for this +% function to work in |notes2bib|. +% +% The |head| and |tail| options affect the placement of notes +% relative to ``real'' citations. By default, all bibliographic +% citations are written in the order they appear in the source. Thus, +% with an unsorted bibliography style, they will appear in the order +% given. The |tail| option will force all notes to appear after real +% citations, whereas the |head| option causes notes to come first +% \bibnote{The |head| option is provided primarily for consistency +% with the |tail| option. The system used to give |head| notes is +% something of a hack, and is \emph{not} a core part of the +% package.}. This has been designed to work with both sorted and +% unsorted bibliography styles. +% +% Finally, the package takes the |killpercent| option. This affects +% the handling of percentage characters within notes. By default, +% the percentage character is treated as a comment marker (as +% normal). Thus the rest of the line is ignored. With the +% |killpercent| option, the \% is completely skipped over, +% \emph{e.g.}~writing \verb*=Some text % A comment= will place +% \verb*=Some text A comment= in the notes database \bibnote{When +% producing the documentation for the package, this was something of +% a headache until the problem was solved.}. +% +%\subsection{Output of notes} +% Bibnotes are only printed when a bibliography is created. This +% means that at the very least a \cmd{\bibliographystyle} command +% must appear in the source \bibnote{|biblatex| users will define a +% style when loading |biblatex|, of course}. Under most +% circumstances, the user will be citing literature, and so will also +% include a \cmd{\bibliography} command in their source. +% Bibliography notes are automatically added to the citations to be +% printed. +% +%\DescribeMacro{\printbibnotes} +% If bibnotes are being used without any other citations, then the +% user cannot place \cmd{\bibliography} in the source +% \bibnote[verbhack]{LaTeX will complain if the user puts +% |\bibliography{}|}. The package therefore +% provides the macro \cmd{\printbibnotes}, which will output only the +% notes. If the |endnotes| package has been loaded, the +% \cmd{\theendnotes} macro is redefined to achieve the same effect. +% +%\subsection{Cross-referencing notes} +% As explained above, each note is automatically assigned a label, or +% the user can provide one as an optional argument to the note. In +% either case, notes may then be cross-referenced. This should be +% done using the \cmd{\cite} command (or similar) as the labels are +% bibliographic citations. +% +%\subsection{Interaction with other packages} +% |notes2bib| is designed to work well with as many other packages as +% possible. It tries to avoid changing anything which other packages +% may rely on. That said, it is best to load |notes2bib| after other +% packages that affect citations, footnotes or endnotes. As usual, +% the |notes2bib| package should be loaded before |hyperref| +% \bibnote{It is usually the case that |hyperref| should be the very +% last package loaded in the preamble.}. +% +% The |notes2bib| package is compatible with the current release of +% |biblatex| (v0.6). As |biblatex| works very differently from other +% citation systems, |notes2bib| must be loaded \emph{after} +% |biblatex|. This allows the package to adjust correctly for some +% important differences in operation of the bibliography environment. +% +%\section{Customisation\label{custom}} +% The |notes2bib| package provides a number of possibilities for +% customisation. Some of these will be useful only in somewhat +% unusual circumstances. These more low-level macros all begin +% \texttt{\textbackslash niib\dots}. +% +%\DescribeMacro{\bibnotename} +%\DescribeMacro{\thebibnote} +% Each note created by |notes2bib| is automatically given a label, +% unless one has been specified by user as an optional argument. By +% default, this is the text of \cmd{\bibnotename} (normally +% \bibnotename), followed by the note number (counted automatically). +% By redefining \cmd{\bibnotename} all notes can be given a new +% label, still bearing the note number. More complex effects can +% be achieved by altering \cmd{\thebibnote}. This is defined as +% |\bibnotename\the\value{bibnote}| by default. +% +%\DescribeMacro{\niibcite} +% The macro used to cite notes is set in \cmd{\niibcite}. By default +% this is \cmd{\cite}, but can be altered, for example +% |\renewcommand{\niibcite}{\citep}| if using |natbib|. +% +%\DescribeMacro{\niibprefix} +% The temporary BibTeX database used to store the notes has the +% default name |niib-\jobname.bib|. The prefix (``\niibprefix'') can +% be altered by redefining \cmd{\niibprefix}. +% +%\DescribeMacro{\niibrecord} +%\DescribeMacro{\niibfield} +% When the notes database is written, each record is saved as type +% \texttt{\niibrecord}, and the text is stored in a +% \texttt{\niibfield} field. Both of these can be altered by +% redefining \cmd{\niibrecord} and \cmd{\niibfield}. This could be +% useful with a bibliography style that has an explicit ``Notes'' +% record type, for example \bibnote{The |rsc| and |achemso| packages +% contain styles of this type.}. +% +% |notes2bib| attempts to maintain the correct ordering of notes with +% sorted bibliography styles. This is done by setting up suitable +% information in the temporary database to ensure correct sorting. +% The mechanism for this is available for modification. +% +%\DescribeMacro{\niibkeyhead} +%\DescribeMacro{\niibkeynone} +%\DescribeMacro{\niibkeytail} +% For users of standard bibliography styles, this is achieved by +% generating a |key| field in the database, containing the label used +% for the note. When using the |head| or |tail| option, this is +% prefixed by \texttt{\niibkeyhead} or \texttt{\niibkeytail}, +% respectively. The prefix can be altered by redefining +% \cmd{\niibkeyhead} or \cmd{\niibkeytail}, for example when +% numerical labels need to be taken into account. The package also +% provides a \cmd{\niibkeynone} macro, which defaults to an empty +% prefix. +% +%\DescribeMacro{\niibpresorthead} +%\DescribeMacro{\niibpresortnone} +%\DescribeMacro{\niibpresorttail} +% When using |biblatex|, the |presort| field can be used to control +% sorting of the citations. Again, three macros +% \cmd{\niibpresorthead}, \cmd{\niibpresortnone} and +% \cmd{\niibpresorttail} are provided, which are used in the correct +% context. The default values of \texttt{\niibpresorthead}, +% \texttt{\niibpresortnone} and \texttt{\niibpresorttail}, +% respectively, are designed to achieve the desired effect while +% allowing the user full control of sorting. +% +%\section{Special effects} +% +%\DescribeMacro{\Percent} +% As explained in the description of the |killpercent| option, the +% default behaviour of the package is to treat the \% sign as a +% comment marker, as normal. However, no ``escape'' is available +% while writing the note to file, and so |\%| will also start a +% comment. The package therefore provides the \cmd{\Percent} macro +% to produce the percentage sign in notes \bibnote{There is no +% perfect way of getting unexpanded output from TeX. The +% |\unexpanded| e-TeX primitive, for example, adds extra spaces to +% control sequences. The package author thinks that having to type +% |\Percent| to get \Percent is the least inconvenient solution.}. +% +%\DescribeMacro{\flushcitestack} +% When using the |head| or |tail| options, citations are added to a +% stack as they are made. This stack is then flushed to the |.aux| +% file at the end of the document. If references are given by +% chapter (or other unit), this may not give the desired effect. The +% \cmd{\flushcitestack} macro will cause all saved citations to be +% written at that point, and will reset the stack for continued use. +% This can therefore be used to control when citation occurs. +% +%\DescribeMacro{\delaycite} +% When using the |head| option, normal citations have to be saved to +% the stack described above. This requires the modification of the +% citation commands. By default, |notes2bib| modifies the +% \cmd{\cite} command and most of the standard citation commands of +% |natbib| and |biblatex| \bibnote{Notice that |\nocite| is not +% modified}. However, if problems are encountered with citation +% order, the user can use the \cmd{\delaycite} macro to patch any +% arbitrary citation command. This macro takes a single argument +% \marg{macro-name}, which is the name of the citation command to +% modify \emph{minus} the leading backslash. For example, the +% \cmd{\cite} command is patched using |\delaycite{cite}|. The +% \cmd{\delaycite} macro checks that a citation command is not +% already modified, and so may be used again on the same command with +% no ill effects. +% +% If a sorted bibliography style is in use, and more than nine notes +% are created, the sort order will be incorrect. This is because by +% default |notes2bib| does not pad the automatically-created labels +% with zeros. To get the correct sort order, \cmd{\thebibnote} +% should be redefined: +%\begin{verbatim} +%\renewcommand*{\thebibnote}{% +% \bibnotename% +% \ifnum\value{bibnote} < 9 0\fi% +% \the\value{bibnote}% +%} +%\end{verbatim} +% +%\section{Known issues} +% +% Currently, when using the |head| option citations can take only one +% optional argument. This is fine for normal citation styles, but +% means that |biblatex| users may have some issues. The package +% author will look again at this if it is a serious problem. A work +% around is to cite as follows (here assuming you wish to use the +% ``\cmd{\mycite}'' command): +%\begin{verbatim} +%\makeatletter +% \begingroup +% \@fileswfalse +% \niib@orig@mycite[argument-one][argument-two]{citation} +% \endgroup +% \edef\niib@stack{\niib@stack,citation} +%\makeatother +%\end{verbatim} +% Where ``argument-one,'' ``argument-two'' and ``citation'' should be +% altered to the desired information. +% +% Users of |cite| will find that |notes2bib| does not move citations +% for notes to after punctuation. The note will be cited where it +% is given in the source. +% +% |biblatex| does not like notes that contain verbatim text. This is +% due to the methods |biblatex| employs to work. Currently, there +% does not seem to be a great deal |notes2bib| can do about this. +% +%\bibliographystyle{unsrt} +%\renewcommand*{\refname}{Notes} +%\StopEventually{\printbibnotes} +% +%\section{The mechanism} +% The mechanism for positioning notes in the bibliography is somewhat +% involved. Rather than expect interested users to read all of the +% code that follows, a condensed overview is given here. The +% thinking behind the system used is explained first, by considering +% the |endnotes| package and REVTeX class. Both of these provided +% inspiration for this package. +% +%\subsection{The \texttt{endnotes} approach} +% The |endnotes| package \bibnote{% +% \url{http://tug.ctan.org/macros/latex/contrib/misc/endnotes.sty}} +% allows the user to generate endnotes in the same way as footnotes. +% In |endnotes|, the text of the note is written to a |.ent| file. +% This is achieved in an unexpanded form using the \cmd{\meaning} TeX +% primitive. To produce the list of endnotes, this file is read back +% into LaTeX, with the extra information \cmd{\meaning} also writes +% being stripped off in the process. +% +% This method is relativity simple in concept, but obviously does +% not integrate with BibTeX. The use of \cmd{\meaning} for unexpanded +% output also means that information requires further processing before +% it can be included in the bibliography. +% +%\subsection{The REVTeX approach} +% REVTeX takes a similar approach to creating endnotes, but also +% allows footnotes to be converted into endnotes. This results in a +% file containing all of the non-literature citations in a document +% in a single external file (in this case a |.end| file). REVTeX +% also uses a different method to achieve unexpanded output, meaning +% that several macros are not ``active'' in notes. +% +% The second part of the REVTeX approach is to (optionally) read the +% notes back into the document. This is achieved by modifying the +% \cmd{\bibliography} environment to output each note in the +% bibliography. This takes place \emph{en masse}, after the normal +% citations. +% +% REVTeX makes a number of modifications to LaTeX, and is dependent +% on using |natbib|. The method used is also not compatible with +% interspersing normal citations and notes. +% +%\subsection{The \texttt{notes2bib} approach} +% +% In |notes2bib|, notes are again written to an external file. +% However, in contrast to the methods those outlined above, +% |notes2bib| writes its output in the well-known BibTeX database +% format. All of the note text is written almost completely +% unexpanded to the file, the only requirement being that the braces +% match within the argument \bibnote{Many thanks to Ulrich Diez for +% the code to achieve the unexpanded writing.}. Notice that by +% default the \% character still acts as a comment marker. Percentage +% signs in the notes database would cause problems on reading the data +% back in after running BibTeX. +% +% Each note results in a citation being placed by |notes2bib| in the +% |.aux| file. The \cmd{\bibliography} command is also modified so +% that the new database will be used by BibTeX. After the BibTeX run, +% the note text will appear in the |.bbl| file, in the same way as +% any other citation. Using an unsorted BibTeX style, this results +% in notes interspaced with the normal citations. For sorted styles, +% |notes2bib| allows various methods for controlling the placement of +% notes, based on writing appropriate fields in the BibTeX database. +% +% The |head| and |tail| options use an additional technique. Both +% delay writing of selected citations (either notes or real ones) +% into the |.aux| file, to control citation position in unsorted +% bibliographies. +% +%\iffalse +%<*package> +%\fi +%\section{The package code} +% +%\subsection{Package setup code} +% +% The package starts with the usual identification code. +% \begin{macrocode} +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{notes2bib} + [2007/08/30 v1.0 Integrating notes into the bibliography] +\RequirePackage{xspace} +% \end{macrocode} +% Option processing takes place. Redefining \cmd{\footnote} or +% \cmd{\endnote} is delayed until the start of the document, to avoid +% the danger of other packages being loaded and overwriting this. +% \begin{macrocode} +\newif\ifniib@fn\niib@fnfalse +\DeclareOption{footnotes}{% + \niib@fntrue + \AtBeginDocument{% + \let\footnote\bibnote% +}} +\DeclareOption{endnotes}{% + \AtBeginDocument{% + \let\endnote\bibnote% + \let\endnotemark\bibnotemark% + \let\endnotetext\bibnotetext% +% \end{macrocode} +% If the user has used the |endnotes| package, they may still have +% \cmd{\theendnotes} commands in their source. So this is defined to +% print out all of the bibnotes. +% \begin{macrocode} + \@ifpackageloaded{endnotes}% + {\let\theendnotes\printbibnotes}{}% +}} +% \end{macrocode} +% Stephen Dalton suggested an option for all notes to come after +% ``real'' citations. This is done here, along with a mirror options +% to have all for the citations come first. +% \begin{macrocode} +\newif\ifniib@tail\niib@tailfalse +\newif\ifniib@head\niib@headfalse +\DeclareOption{tail}{\niib@tailtrue} +\DeclareOption{head}{\niib@headtrue} +% \end{macrocode} +%\begin{macro}{\niib@percent} +% For handling percentage signs in notes, an option is needed +% to alter handling. +% \begin{macrocode} +\def\niib@percent{\catcode`\%=14\relax} +\DeclareOption{killpercent}{% + \def\niib@percent{\catcode`\%=9\relax} +} +% \end{macrocode} +% For |.dtx| files, the |killpercent| option is necessary. +% \begin{macrocode} +\@ifclassloaded{ltxdoc}{\ExecuteOptions{killpercent}}{} +% \end{macrocode} +%\end{macro} +% Finally, the options are put into effect. +% \begin{macrocode} +\ProcessOptions +% \end{macrocode} +% +% If the |footnote| option is active, there is some work to do +% because of the \cmd{\thanks} macro. +% \begin{macrocode} +\ifniib@fn +% \end{macrocode} +% The \cmd{\thanks} macro can only be patched if e-TeX extensions are +% available. This is because |elatex| is used for the actual +% patching. +% \begin{macrocode} + \@ifundefined{eTeXversion}{% + \PackageWarning{notes2bib}{% + e-TeX extensions unavailable\MessageBreak + \protect\footnotemark and \protect\footnotetext% + \MessageBreak unmodified}% + }{% +% \end{macrocode} +%\begin{macro}{\niib@fnmark} +%\begin{macro}{\niib@fntext} +%\begin{macro}{\niib@thanks} +% With e-TeX available, the |elatex| package can be used to do the +% patching needed. Firstly, it is necessary to back up the original +% definitions for \cmd{\footnotetext} and \cmd{\footnotetext}. The +% \cmd{\thanks} macro is also backed up. +% \begin{macrocode} + \let\niib@fnmark\footnotemark + \let\niib@fntext\footnotetext + \let\niib@thanks\thanks +% \end{macrocode} +%\end{macro} +%\end{macro} +%\end{macro} +%\begin{macro}{\thanks} +% Now the \cmd{\thanks} command is patched to use the saved +% definitions. The patching is nested so that everything has to go +% right before things are finalised. +% \begin{macrocode} + \RequirePackage{elatex} + \patchcmd{\thanks}{\footnotemark}{\niib@fnmark}{% + \patchcmd{\thanks}{\footnotetext}{\niib@fntext}{% + \AtBeginDocument{% + \let\footnotemark\bibnotemark + \let\footnotetext\bibnotetext + }% + }% +% \end{macrocode} +% Thinks have gone wrong if the following lines are reached. So everything +% is put back to normal. +% \begin{macrocode} + {\let\thanks\niib@thanks% + \PackageWarning{notes2bib}% + {Could not patch \protect\thanks}}% + }{% + \let\thanks\niib@thanks% + \PackageWarning{notes2bib}% + {Could not patch \protect\thanks}}% + }% +\fi +% \end{macrocode} +%\end{macro} +% +% The |head| and |tail| options are mutually exclusive, so a check is +% made that both have not been selected. If they have, the package +% ignores both options after a suitable warning. +% \begin{macrocode} +\ifniib@head + \ifniib@tail + \PackageWarning{notes2bib} + {You've given both ``head'' and ``tail'' as + options\MessageBreak + I'm ignoring both!} + \niib@headfalse\niib@tailfalse + \fi +\fi +% \end{macrocode} +% For the |head| option, the normal citation commands are modified to +% get the necessary delay in writing to the |.aux| file. +% \begin{macrocode} +\AtBeginDocument{% + \ifniib@head +% \end{macrocode} +% The \cmd{\cite} command is always defined, so it can be redefined in all +% cases. +% \begin{macrocode} + \delaycite{cite}% +% \end{macrocode} +% If |natbib| is loaded, there a several citation commands that will +% definitely be defined. They are all run through \cmd{\delaycite}. +% \begin{macrocode} + \@ifpackageloaded{natbib}{% + \delaycite{citet}% + \delaycite{citep}% + \delaycite{citenum}% + \delaycite{citealt}% + \delaycite{citealp}% + \delaycite{citetext}% + \delaycite{citeauthor}% + \delaycite{citeyear}% + \delaycite{citeyearpar}% + \delaycite{Citet}% + \delaycite{Citep}% + \delaycite{Citealt}% + \delaycite{Citealp}% + \delaycite{Citeauthor}% + }{% +% \end{macrocode} +% For |biblatex|, some citation commands are always defined. +% \begin{macrocode} + \@ifpackageloaded{biblatex}{% + \delaycite{Cite}% + \delaycite{parencite}% + \delaycite{Parencite}% + \delaycite{footcite}% + \delaycite{Footcite}% + \delaycite{textcite}% + \delaycite{Textcite}% +% \end{macrocode} +% Now there are several citation commands that may be defined. As +% |biblatex| requires e-TeX, the |\ifdefined| primitive can be +% used. +% \begin{macrocode} + \ifdefined\autocite% + \delaycite{autocite}% + \fi% + \ifdefined\supercite% + \delaycite{supercite}% + \fi% + }{}% + }% + \fi% +} +% \end{macrocode} +% +%\subsection{User configuration macros} +% +% The |notes2bib| package makes quite a number of configuration +% defaults available as macros. These are all set up here. Most of +% these are of the form \texttt{\textbackslash niib\dots}, as in the +% main they are unlikely to be altered by most users. +% +%\begin{macro}{\bibnotename} +% By default, all of the new citations take the prefix +% ``\bibnotename.'' The default can be altered, and this is set up +% here. +% \begin{macrocode} +\newcommand*\bibnotename{Bibnote} +% \end{macrocode} +%\end{macro} +%\begin{macro}{\thebibnote} +% A counter is needed for the notes created. In analogy to other +% counters in LaTeX, this is given a \texttt{\textbackslash +% the\dots} name. The user should not really need to use this +% macro, but convention dictate that it has a user-space name. +% \begin{macrocode} +\newcounter{bibnote} +\renewcommand*{\thebibnote}{\bibnotename\the\value{bibnote}} +% \end{macrocode} +%\end{macro} +%\begin{macro}{\niibprefix} +% The package works by creating a new BibTeX database file containing +% the notes. By default, this fix is called +% \texttt{\niibprefix\textbackslash jobname.bib}, but the prefix may +% be altered by redefining \cmd{\niibprefix}. The default follows +% the pattern used by the |biblatex| package (which uses |blx-|). +% \begin{macrocode} +\newcommand*\niibprefix{niib-} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\niibrecord} +%\begin{macro}{\niibfield} +% When creating the temporary database of notes, the BibTeX records +% created are of record type \cmd{\niibrecord}, and the notes are +% stored in the \cmd{\niibfield} field type. For some BibTeX styles, +% a better choice than the defaults (\texttt{\niibrecord} and +% \texttt{\niibfield}, respectively) may be available. Thus the +% values used are definable. +% \begin{macrocode} +\newcommand*\niibrecord{Misc} +\newcommand*\niibfield{note} +% \end{macrocode} +%\end{macro} +%\end{macro} +%\begin{macro}{\niibpresorthead} +%\begin{macro}{\niibpresortnone} +%\begin{macro}{\niibpresorttail} +% When using |biblatex|, sorting can be controlled using the +% |presort| field. Default values to be used are given here; these +% are ``soft'' as |biblatex| allows much more definite pushing to the +% top and bottom of the sorted list. +% \begin{macrocode} +\newcommand*\niibpresorthead{ml} +\newcommand*\niibpresortnone{mm} +\newcommand*\niibpresorttail{mn} +% \end{macrocode} +%\end{macro} +%\end{macro} +%\end{macro} +%\begin{macro}{\niibkeyhead} +%\begin{macro}{\niibkeynone} +%\begin{macro}{\niibkeytail} +% For traditional BibTeX styles, the |key| field can be used to +% influence the sort order. Default values to alter sorting are +% given here, but may need to be altered for other languages and so +% on. +% \begin{macrocode} +\newcommand*\niibkeyhead{aaa} +\newcommand*\niibkeynone{} +\newcommand*\niibkeytail{zzz} +% \end{macrocode} +%\end{macro} +%\end{macro} +%\end{macro} +% +%\begin{macro}{\niibcite} +% Bibliography notes are marked by citations, like any other +% bibliography entry. The citation command use is controlled here. +% \begin{macrocode} +\newcommand*\niibcite{\cite} +% \end{macrocode} +%\end{macro} +% +%\subsection{User macros} +% +%\begin{macro}{\bibnote} +% Each new bibnote increments the note counter, then checks for an +% optional label, before handing off to the internal macro +% \cmd{\niib@bibnote}. +% \begin{macrocode} +\DeclareRobustCommand\bibnote{% + \stepcounter{bibnote}% + \@ifnextchar[% + {\niib@bibnote}% + {\niib@bibnote[\thebibnote]}% +} +% \end{macrocode} +%\end{macro} +%\begin{macro}{\bibnotemark} +% The \cmd{\bibnotemark} macro works in the same way as +% \cmd{\bibnote}, but calls \cmd{\niib@mark} rather than +% \cmd{\niib@bibnote}. +% \begin{macrocode} +\DeclareRobustCommand\bibnotemark{% + \stepcounter{bibnote}% + \@ifnextchar[% + {\niib@mark}% + {\niib@mark[\thebibnote]}% +} +% \end{macrocode} +%\end{macro} +%\begin{macro}{\bibnotetext} +% The text companion to the mark macro above, with no increment of +% the counter. +% \begin{macrocode} +\DeclareRobustCommand\bibnotetext{% + \@ifnextchar[% + {\niib@text}% + {\niib@text[\thebibnote]}% +} +% \end{macrocode} +%\end{macro} +%\begin{macro}{\printbibnotes} +% To allow for the possibility of there being no other notes, a +% command to print only notes is given. In the |biblatex| case, the +% best that can be done is to issue \cmd{\printbibliography}. +% \begin{macrocode} +\@ifpackageloaded{biblatex}{% + \let\printbibnotes\printbibliography% +}{% + \newcommand*{\printbibnotes}{\niib@bib% + {\niibprefix\jobname}}% +}% +% \end{macrocode} +%\end{macro} +%\begin{macro}{\flushcitestack} +% In order to delay citations to the end of the bibliography (and +% thus force others to the start), a ``stack'' is created of +% citations which need to be written to the |.aux| file. This +% is done here, and the stack is cleared so collection can begin +% again. +% \begin{macrocode} +\newcommand*\flushcitestack{% + \ifx\niib@stack\relax\else% + \expandafter\nocite\expandafter{\niib@stack}% + \global\let\niib@stack\relax% + \fi% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\delaycite} +% Normal citations have to be stacked up in the stack when in +% ``head'' mode. To do this, the citation command has to be modified +% to do this, while leaving note citations alone. The trick used in +% this is to set \cmd{\@filesw} to false while the citation takes +% place. +% \begin{macrocode} +\newcommand*\delaycite[1]{% + \expandafter\ifx\csname niib@orig@#1\endcsname\@undefined% + \expandafter\expandafter\expandafter\let\expandafter% + \csname niib@orig@#1\expandafter\endcsname\csname #1\endcsname% + \expandafter\renewcommand\csname #1\endcsname[2][\relax]{% +% \end{macrocode} +% If a note is being cited, then there will be no optional argument, +% and |##1| will expand to \cmd{\relax}. +% \begin{macrocode} + \ifniib@cn% + \csname niib@orig@#1\endcsname{##2}% + \else% + \begingroup% + \@fileswfalse% +% \end{macrocode} +% If an optional argument has been given, then |##1| will expand to +% something other than \cmd{\relax}. So the original citation +% command is called with the optional argument. +% \begin{macrocode} + \ifx##1\relax% + \csname niib@orig@#1\endcsname{##2}% + \else% + \csname niib@orig@#1\endcsname[##1]{##2}% + \fi% + \endgroup% + \edef\niib@temp{##2}% + \ifx\niib@stack\relax% + \xdef\niib@stack{\niib@temp}% + \else% + \xdef\niib@stack{\niib@stack,\niib@temp}% + \fi% + \fi% + }% + \else% + \PackageInfo{notes2bib}% + {Citation type ``#1'' already delayed}% + \fi% +} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\Percent} +% Finally, a way of producing a percentage sign in note is needed. +% This is because inside the note, no method for escaping a comment +% is available. +% \begin{macrocode} +\newcommand*{\Percent}{\%\xspace} +% \end{macrocode} +%\end{macro} +% +%\subsection{Internal setup macros} +% +%\begin{macro}{\niib@keyname} +% If |biblatex| is in use, the key field in the BibTeX database +% should be called ``keysort,'' whereas otherwise it should be +% ``key.'' +% \begin{macrocode} +\@ifpackageloaded{biblatex} + {\def\niib@keyname{keysort}} + {\def\niib@keyname{key}} +% \end{macrocode} +%\end{macro} +%\begin{macro}{\niib@presort} +%\begin{macro}{\niib@key} +% The values taken by \cmd{\niib@presort} and \cmd{\niib@key} depend +% on the desired positioning of notes in the bibliography. +% \begin{macrocode} +\ifniib@head + \def\niib@presort{\niibpresorthead} + \def\niib@key{\niibkeyhead} +\else + \ifniib@tail + \def\niib@presort{\niibpresorttail} + \def\niib@key{\niibkeytail} + \else + \def\niib@presort{\niibpresortnone} + \def\niib@key{\niibkeynone} + \fi +\fi +% \end{macrocode} +%\end{macro} +%\end{macro} +% +%\begin{macro}{\niib@msg} +% To inform the user, the automatically-created BibTeX database needs +% to carry suitable information on its source. +% \begin{macrocode} +\edef\niib@msg{% + This is an auxiliary file used by the `notes2bib' package.^^J% + This file may safely be deleted. It will be recreated as + required.^^J} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\niib@stack} +% This macro is needed to store any citations at the end of the +% bibliography. Initially, this expands to \cmd{\relax}. +% \begin{macrocode} +\let\niib@stack\relax +% \end{macrocode} +%\end{macro} +% +% A switch is needed to tell if a note is being cited when using +% ``head'' mode. +% \begin{macrocode} +\newif\ifniib@cn\niib@cnfalse +% \end{macrocode} +% +%\subsection{Internal macros} +% +%\begin{macro}{\niib@text} +% Here the label and the text for the note are separated out before +% writing to the bibliography file. +% \begin{macrocode} +\long\def\niib@text[#1]{% + \niib@@text{#1}% +} +% \end{macrocode} +%\end{macro} +%\begin{macro}{\niib@bibnote} +% Very similar processing to \cmd{\niib@text} is carried out here, +% but in this case a citation is also added to the file. +% \begin{macrocode} +\long\def\niib@bibnote[#1]{% + \niib@citenote{#1}% + \niib@@text{#1}% +} +% \end{macrocode} +%\end{macro} +%\begin{macro}{\niib@mark} +% If only a mark is asked for, this is simply converted into a +% citation. This cannot be done directly as the optional has to be +% processed correctly. +% \begin{macrocode} +\def\niib@mark[#1]{\niib@citenote{#1}} +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\niib@citenote} +% To allow the notes to ``tail'' the real citations, a special +% version of the \cmd{\cite} command is needed that can allow +% delaying writing the \cmd{\citation} command to the aux file. +% \begin{macrocode} +\def\niib@citenote#1{% + \niib@cntrue% +% \end{macrocode} +%\begin{macro}{\niib@temp} +% \cmd{\niib@temp} is needed to hold the expanded citation. +% \begin{macrocode} + \edef\niib@temp{#1}% +% \end{macrocode} +% If ``tail''-ing is needed, the \texttt{\textbackslash cite\dots} +% command is told not to write to the |.aux| file using +% \cmd{\@filesw}. +% \begin{macrocode} + \ifniib@tail% + \begingroup% + \@fileswfalse% + \niibcite{#1}% + \endgroup% +% \end{macrocode} +% The citation is added to the stack for writing later. +% \cmd{\niib@stack} will always expand to \cmd{\relax} if it is +% empty. +% \begin{macrocode} + \ifx\niib@stack\relax% + \xdef\niib@stack{\niib@temp}% + \else% + \xdef\niib@stack{\niib@stack,\niib@temp}% + \fi% + \else% +% \end{macrocode} +% When tailing is not in operation, writing takes place as normal. +% The run of \cmd{\expandafter}s is needed to close the |\if| +% cleanly. +% \begin{macrocode} + \expandafter\niibcite\expandafter% + {\expandafter\niib@temp\expandafter}% + \fi% + \niib@cnfalse% +}% +% \end{macrocode} +%\end{macro} +%\end{macro} +% +% The next set of macros provides the direct writing of the +% unexpanded note to file. The code is a modified from a usenet post +% by Ulrich Diez at |comp.text.tex|, but with everything stripped +% down to do just what is needed here. The package author takes +% responsibility for the code eating your socks! +% +%\begin{macro}{\niib@verbtext} +%\begin{macro}{\niib@@verbtext} +%\begin{macro}{\niib@tempa} +% The two macros here set up the necessary catcode changes and +% grouping. Notice that they do not have the note text as an +% argument. That is left to \cmd{\niib@tempa} +% \begin{macrocode} +\newcommand\niib@verbtext[2][\ignorespaces]{% + \begingroup% + \let\do\@makeother\dospecials% + \catcode`\{=1\relax% + \catcode`\}=2\relax% + \niib@@verbtext{#1}{#2}% +}% +\newcommand\niib@@verbtext[2]{% + \begingroup% + \long\def\niib@tempa##1{% + \def\niib@tempa{##1}% + \@onelevel@sanitize\niib@tempa% + \expandafter\endgroup% + \expandafter\def% + \expandafter#2% + \expandafter{% + \niib@tempa}% + #1% + }% +% \end{macrocode} +% New lines are set to be spaces. +% \begin{macrocode} + \catcode`\^^M=10\relax% +% \end{macrocode} +% Unlike the ``real'' unexpanded write, the catcode of \texttt{\%} +% needs to be something that will be safe, so that comments do not +% cause problems. There is no escape character, so an alternative +% method for printing \% is given elsewhere in the package. For +% |dtx| files and so on, this will not work. So an option is +% needed to ignore percentage signs entirely. +% \begin{macrocode} + \niib@percent% + \expandafter\endgroup% + \niib@tempa% +}% +% \end{macrocode} +%\end{macro} +%\end{macro} +%\end{macro} +%\begin{macro}{\niib@write} +% This provides the access end of the unexpanded write. Once again, +% the note is not an argument. +% \begin{macrocode} +\newcommand*\niib@write{% + \@bsphack% + \begingroup% + \niib@verbtext[\niib@@write\ignorespaces]\niib@tempa% +}% +% \end{macrocode} +%\end{macro} +%\begin{macro}{\niib@@write} +% Writing actually takes place here. In order to get all of the code +% needed into the |.bib| file, it is set out here. Thus this macro +% is the specialised part of the mechanism. +% \begin{macrocode} +\newcommand*\niib@@write[1]{% + \immediate\write\niib@out{% + @\niibrecord\string{\niib@tempb,^^J% + presort = \string{\niib@presort\string},^^J% + \niib@keyname\space= \string{\niib@key\niib@tempb\string},^^J% + \niibfield\space= \string{\niib@tempa\string}^^J% + \string}^^J}% + \endgroup% + \@esphack% +}% +% \end{macrocode} +%\end{macro} +% +%\begin{macro}{\niib@@text} +% The ``business end'' of writing the notes to file. +% \begin{macrocode} +\long\def\niib@@text#1{% +% \end{macrocode} +%\begin{macro}{\niib@out} +%\begin{macro}{\niib@stream} +% If this is the first note, then a new output stream is needed, +% otherwise it will already be open. +% \begin{macrocode} + \ifx\niib@out\@undefined% + \newwrite\niib@out% + \gdef\niib@stream{\niibprefix\jobname.bib}% + \immediate\openout\niib@out\niib@stream\relax% +% \end{macrocode} +% The new file starts with the message that it has been automatically +% generated by |notes2bib|. +% \begin{macrocode} + \immediate\write\niib@out{\niib@msg}% + \fi% +% \end{macrocode} +%\end{macro} +%\end{macro} +%\begin{macro}{\niib@tempb} +% As long files are being written, \cmd{\niib@tempb} is used to +% store the label, before calling the \cmd{\niib@write} macro to +% output the note text. \cmd{\niib@write} will pick up the next +% thing in the input, which should be the grouped note text. +% \begin{macrocode} + \if@filesw% + \edef\niib@tempb{#1}% + \expandafter\niib@write% + \fi% +} +% \end{macrocode} +%\end{macro} +%\end{macro} +% +% The \cmd{\bibliography} macro is patached to ensure that when it is +% executed the note file is also processed. |biblatex| does things +% very differently, but this actually makes it much easier to patch +% for. +% \begin{macrocode} +\@ifpackageloaded{biblatex}{% + \expandafter\bib@gadd\expandafter\blx@bibfiles\expandafter% + {\niibprefix\jobname}% + }{% +% \end{macrocode} +%\begin{macro}{\niib@bib} +%\begin{macro}{\bibliography} +% The bibliography command is patched so that it will run on the +% automatically-generated BibTeX database. +% \begin{macrocode} + \let\niib@bib\bibliography% + \renewcommand{\bibliography}[1]{% + \ifnum\the\value{bibnote} > \z@% + \niib@bib{\niibprefix\jobname,#1}% + \else% + \niib@bib{#1}% + \fi}}% +% \end{macrocode} +%\end{macro} +%\end{macro} +%% +% At the end of the document, any delayed citations are written to the +% |.aux| file, and the database file is closed cleanly. +% \begin{macrocode} +\AtEndDocument{% + \flushcitestack% + \ifx\niib@out\@undefined\else% + \immediate\closeout\niib@out% + \fi% +} +% \end{macrocode} +% +%\iffalse +%</package> +%\fi +% \PrintChanges +% \PrintIndex +% \Finale +% diff --git a/Master/texmf-dist/source/latex/notes2bib/notes2bib.ins b/Master/texmf-dist/source/latex/notes2bib/notes2bib.ins new file mode 100644 index 00000000000..27bf9c5683a --- /dev/null +++ b/Master/texmf-dist/source/latex/notes2bib/notes2bib.ins @@ -0,0 +1,33 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% notes2bib is free software; you can redistribute it and/or modify it +% under the terms of the GNU General Public License as published by +% the Free Software Foundation; either version 2, or (at your option) +% any later version. +% +% notes2bib is distributed in the hope that it will be useful, but +% WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see +% <http://www.gnu.org/licenses/>. +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\input docstrip.tex +\askonceonly +\preamble + ---------------------------------------------------------------- + note2bib --- Integrating notes into the bibliography + Maintained by Joseph Wright + E-mail: joseph.wright@morningstar2.co.uk + Released under the GNU General Public License + See http://www.gnu.org/licenses/gpl.txt + ---------------------------------------------------------------- +\endpreamble +\Msg{Generating notes2bib files:} +\usedir{tex/latex/contib/notes2bib} +\generate{\file{notes2bib.sty}{\from{notes2bib.dtx}{package}} +} +\endbatchfile |