%\iffalse meta-comment
%
% Copyright (C) 2007-2008 by
%    Joseph Wright <joseph.wright@morningstar2.co.uk>
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either
% version 1.3c 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.3c 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 Joseph Wright.
%
% This work consists of the file  notes2bib.dtx
%                                 xnotes2bib.dtx
%           and the derived files notes2bib.pdf,
%                                 notes2bib.sty,
%                                 notes2bib.ins,
%                                 xnotes2bib.pdf,
%                                 xnotes2bib.sty and
%                                 xnotes2bib.ins.
%
% TDS-ready files:
%    The compressed file notes2bib.tds.zip contains an unpacked
%    version of all of the files included here, and pre-compiled
%    documentation in PDF format.  Simply decompress
%    notes2bib.tds.dtx in your local TeX directory, run your hash
%    program (texhash, initexmf --update-fndb, etc.) and everything
%    will be ready to go.  The user documentation for the package is
%    called notes2bib-manual.pdf; the file notes2bib.pdf includes the
%    user manual and the fully-indexed source code.
%
% Unpacking:
%    (a) If notes2bib.ins is present:
%           tex notes2bib.ins
%    (b) Without notes2bib.ins:
%           tex notes2bib.dtx
%    (c) If you use LaTeX to generate files:
%           latex \let\install=y\input{notes2bib.dtx}
%
% Documentation:
%    (a) Without write18 enabled:
%          pdflatex notes2bib.dtx
%          bibtex8 --wolfgang notes2bib
%          makeindex -s gind.ist notes2bib.idx
%          makeindex -s gglo.ist -o notes2bib.gls  notes2bib.glo
%          pdflatex notes2bib.dtx
%          pdflatex notes2bib.dtx
%    (b) With write18 enabled:
%          pdflatex notes2bib.dtx
%          bibtex8 --wolfgang notes2bib
%          pdflatex notes2bib.dtx
%          pdflatex notes2bib.dtx
%
% Installation:
%     Copy notes2bib.sty to a location searched by TeX, and if
%     required by your TeX installation, run the appropriate command
%     to build a hash of files (texhash, initexmf --update-fndb,
%     etc.)
%
% Note:
%     The jawltxdoc.sty file is not needed for installation,
%     only for building the documentation; it may be deleted
%     after producing the documentation (if necessary).
%
%<*ignore>
% This is all taken verbatim from Heiko Oberdiek's packages
\begingroup
  \def\x{LaTeX2e}%
\expandafter\endgroup
\ifcase 0\ifx\install y1\fi\expandafter
         \ifx\csname processbatchFile\endcsname\relax\else1\fi
         \ifx\fmtname\x\else 1\fi\relax
\else\csname fi\endcsname
%</ignore>
%<*install>
\input docstrip.tex
\keepsilent
\askforoverwritefalse
\preamble
 ----------------------------------------------------------------
 note2bib --- Integrating notes into the bibliography
 Maintained by Joseph Wright
 E-mail: joseph.wright@morningstar2.co.uk
 Released under the LaTeX Project Public License v1.3 or later
 See http://www.latex-project.org/lppl.txt
 ----------------------------------------------------------------

\endpreamble
\Msg{Generating notes2bib files:}
\generate{\file{jawltxdoc.sty}{\from{\jobname.dtx}{jawltxdoc}}
}
\usedir{tex/latex/notes2bib}
\generate{\file{\jobname.sty}{\from{\jobname.dtx}{package}}
}
\usedir{source/latex/notes2bib}
\generate{\file{\jobname.ins}{\from{\jobname.dtx}{install}}
}
\nopreamble\nopostamble
\usedir{doc/latex/notes2bib}
\generate{\file{README.txt}{\from{\jobname.dtx}{readme}}
}
\endbatchfile
%</install>
%<*readme>
----------------------------------------------------------------
The notes2bib package --- Integrating notes into the
  bibliography
Maintained by Joseph Wright
E-mail: joseph.wright@morningstar2.co.uk
Released under the LaTeX Project Public License v1.3c or later
See http://www.latex-project.org/lppl.txt
----------------------------------------------------------------

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.
%</readme>
%<*ignore>
\fi
% Will Robertson's trick
\immediate\write18{bibtex8 --wolfgang  \jobname}
\immediate\write18{makeindex -s gind.ist -o \jobname.ind  \jobname.idx}
\immediate\write18{makeindex -s gglo.ist -o \jobname.gls  \jobname.glo}
%</ignore>
%<*driver>
\PassOptionsToClass{a4paper}{article}
\documentclass[german,english,UKenglish]{ltxdoc}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\OnlyDescription
\usepackage{jawltxdoc}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
%\fi
%
%\CheckSum{881}
%
%\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}
%\changes{v1.1}{2007/09/29}{License changed from GPL to LPPL}
%\changes{v1.1}{2007/09/29}{\cs{Percent} macro removed}
%\changes{v1.1}{2007/09/29}{Documentation improvements}
%\changes{v1.1}{2007/09/29}{Several code sections re-factored}
%\changes{v1.1}{2007/09/29}{Improvements to documentation and
%  \texttt{dtx} file}
%\changes{v1.2}{2007/10/26}{Altered implementation of \texttt{head}
%   and \texttt{tail} options to allow moving of superscript
%   citations}
%\changes{v1.3}{2008/01/08}{Added \pkg{xkeyval} option interface}
%\changes{v1.3}{2008/01/08}{All options now work anywhere in input}
%\changes{v1.3}{2008/01/08}{Fixed serious errors with \opt{head}
%  and \opt{tail} implementation}
%\changes{v1.4}{2008/06/21}{\eTeX\ made optional (again), with
%  control option to turn off use even if available}
%\changes{v1.5}{2008/09/08}{Bundle now includes experimental
%  \LaTeX3 support}
%\changes{v1.6}{2008/10/21}{Fixed issue with \cs{nofiles}}
%\changes{v1.6}{2008/10/21}{Advice extended on various issues}
%
%\DoNotIndex{\@auxout,\@empty,\@fileswfalse,\@for,\@ifnextchar}
%\DoNotIndex{\@ifpackagelater,\@ifpackageloaded,\@ifundefined}
%\DoNotIndex{\@nameuse,\AtBeginDocument,\AtEndDocument}
%\DoNotIndex{\AtNextCite,\begingroup,\closeout}
%\DoNotIndex{\csname,\DeclareRobustCommand,\def,\define@boolkey}
%\DoNotIndex{\define@choicekey,\define@cmdkeys,\do,\edef,\else}
%\DoNotIndex{\endcsname,\endgroup,\endinput,\expandafter,\fi}
%\DoNotIndex{\g@addto@macro,\gappto,\gdef,\if@filesw,\iffalse,\ifnum}
%\DoNotIndex{\ifx,\immediate,\jobname,\let,\long,\MessageBreak}
%\DoNotIndex{\NeedsTeXFormat,\newcommand,\newcounter,\newif}
%\DoNotIndex{\nocite,\noexpand,\openout,\PackageError,\PackageInfo}
%\DoNotIndex{\newwrite,\PackageWarning,\patchcmd,\printbibliography}
%\DoNotIndex{\ProcessOptionsX,\ProvidesPackage,\relax,\renewcommand}
%\DoNotIndex{\RequirePackage,\setkeys,\space,\stepcounter,\string}
%\DoNotIndex{\the,\typeout,\unexpanded,\value,\write,\xdef,\z@}
%\DoNotIndex{\protected@xdef,\protect}
%
%\DoNotIndex{\@bsphack,\@esphack,\@makeother,\@onelevel@sanitize}
%\DoNotIndex{\@thanks,\AtEndOfPackage}
%\DoNotIndex{\c@footnote,\catcode,\define@key,\dospecials,\global}
%
%\setkeys{lst}{language=[LaTeX]{TeX},moretexcs={bibnote,%
%  bibnotemark,bibnotetext,citenote,niibsetup,newif,printbibliography}}
%
%\title{\currpkg\ --- Integrating notes into the
%  bibliography^^A
%  \thanks{This file describes version \fileversion, last revised
%          \filedate.}}
%\author{Joseph Wright^^A
%  \thanks{E-mail: joseph.wright@morningstar2.co.uk}}
%\date{Released \filedate}
%
%\maketitle
%
%\begin{abstract}
% The \currpkg package defines a new type of note, \cs{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 \pkg{natbib} and
% \pkg{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.
%
%\newcommand*{\APS}{\textsc{aps}\xspace}
%\newcommand*{\REVTeX}{REV\TeX\xspace}
% The \pkg{endnotes} package allows the user to create endnotes
% rather than footnotes.  However, this does not place the notes in
% the bibliography.  The \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 \currpkg 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 \cs{footnote} type: \cs{bibnote}\marg{text}. This can be
% used in exactly the same way as a footnote, taking one mandatory
% argument \meta{text}.  The \meta{text} will be made available as to
% the bibliography as a note (henceforth referred to as a bibnote).
%\begin{LaTeXexample}
%  A very simple example of a bibliography note
%  \bibnote{Note for the first example}.
%\end{LaTeXexample}
% By default, each bibnote is given an automatically-generated label.
% However, \cs{bibnote} accepts an optional argument \meta{label},
% which can be used to over-ride this. This is particularly useful
% when a note will be referenced several times (The use of the
% \cs{citenote} command is covered in
% Section~\ref{subsec:cross-ref}).
%\begin{LaTeXexample}
%  An example of a named note \bibnote[labelled-note]{Note for the
%  second example}. The text can then continue and reference the note
%  again later \citenote{labelled-note}.
%\end{LaTeXexample}
%
%\DescribeMacro{\bibnotemark}
%\DescribeMacro{\bibnotetext}
% In common with \cs{footnote}, the basic \cs{bibnote} macro has
% companion macros \cs{bibnotemark} and \cs{bibnotetext}. The text
% provided for each not is not ``fragile,'' and so it should not be
% necessary to use \cs{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 \cs{citenote} to reference the note, or use an
% optional argument to the \cs{section}, \etc
%\begin{LaTeXexample}
%  It is hard to write a good example for this \bibnotemark! The text
%  continues here\bibnotetext{Note for the third example}.
%\end{LaTeXexample}
%
%\subsection{Package control}
%\DescribeMacro{\niibsetup}
% The \currpkg package can be controlled using package options, and
% also dynamically using the \cs{niibsetup} macro.  In both cases the
% same list of \pkg{keyval} options are recognised, in a similar
% manner to the \pkg{graphicx} or \pkg{hyperref} packages.  Several
% of the package options are aimed at controlling the package
% internally, but by providing a single macro to control this, use is
% made easier.\footnote{Users upgrading from earlier versions of
% \currpkg will note that the large number of control macros have all
% been removed from v1.3.}
%
%\DescribeOption{footnote}
%\DescribeOption{endnotes}
% Some options control the general behaviour of \currpkg in the body
% of the \LaTeX\ source.  The \opt{footnote} and \opt{endnotes}
% options control whether \cs{footnote} and \cs{endnote} macros are
% converted into bibnotes. Both are Boolean options, and are
% \defaultopt{false} by default.
%\DescribeOption{cite}
% The citation command used by \currpkg to insert bibnotes.  It
% should be the name of a \LaTeX\ command (a ``csname''), and is set
% to \defaultopt{cite} on loading \currpkg; this means that \cs{cite}
% will be used as the citation command.
%
%\DescribeOption{field}
%\DescribeOption{name}
%\DescribeOption{record}
%\DescribeOption{keyword}
%\changes{v1.6}{2008/10/22}{New option \opt{keyword}}
% A number of options control the data added to the \BibTeX\
% database. The \opt{field} and \opt{record} options control the type
% of \BibTeX\ entry created by \currpkg.  On loading, \opt{record} is
% set to \defaultopt{Misc} an \opt{field} is set as
% \defaultopt{note}.  Depending on the \BibTeX\ style in use, better
% choices may exist for these settings. The \opt{name} option is used
% to automatically generate citation names. The option starts with
% the value \defaultopt{Bibnote}, which may need to change for
% author--year styles in particular. For separating notes from other
% citations when using \pkg{biblatex}, the \opt{keyword} option is used
% for the name of the keyword used to control this.
%\DescribeOption{prefix}
% The name of the database itself is controlled by the \opt{prefix}
% option.  This contains the ``marker'' used by \currpkg to attach to
% the job name when creating the storage database.  The default is
% \defaultopt{niib-}.
%
%\DescribeOption{sort}
%\DescribeOption{head}
%\DescribeOption{tail}
% Bibnotes can be created so that thy will be sorted before or after
% normal citations.  A list of values are recognised:
% \defaultopt{none} (no control of sorting), \opt{head} (notes appear
% before real citations) and \opt{tail} (notes appear after real
% citations).  The shortcut options \opt{head} and \opt{tail}
% are also available.
%\DescribeOption{keyhead}
%\DescribeOption{keynone}
%\DescribeOption{keytail}
% A number of mechanisms are used to ensure correct sorting of
% bibnotes.  For normal \BibTeX\ users, the options \opt{keyhead},
% \opt{keynone} and \opt{keytail} are used to control sorting.  These
% values are added to the start of the citation name in the
% \texttt{key} field, which controls sorting.  The default values are
% \defaultopt{aaa}, nothing and \defaultopt{zzz}, respectively.
%\DescribeOption{presorthead}
%\DescribeOption{presortnone}
%\DescribeOption{presorttail}
% For \pkg{biblatex} users, control is made using the \opt{presort}
% system made available there.  The \currpkg options
% \opt{presorthead}, \opt{presortnone} and \opt{presorttail} set up
% the appropriate values; default values are \defaultopt{ml},
% \defaultopt{mm} and \defaultopt{ml}, respectively.
%
%\DescribeOption{writekey}
% When using the package with \pkg{natbib}, it may be necessary to avoid
% writing the \texttt{key} field to the temporary database.  This is
% seen with the style \texttt{unsrtnat}, for example.  The Boolean
% option \opt{writekey} is available to turn off writing the
% \texttt{key} field under these circumstances.
%
%\DescribeOption{log}
%\DescribeOption{debug}
% The amount of detail to add to the log; expects a value from the
% list \opt{debug} (very detailed information), \opt{verbose} (the
% same as \opt{debug}), \defaultopt{normal}, \opt{errors} (errors
% only), \opt{none} (what it says).  As a shortcut, the \opt{debug}
% option is provided as an alias to \opt{log=debug}.
%\DescribeOption{etex}
% The package has a single load-time only option, \opt{etex}.  This
% is a Boolean switch, and determines whether \eTeX\ extensions are
% used if available.  This is \defaultopt{true} by default; the
% intension here is for testing when sending to publishers, \etc.,
% where \eTeX\ may be an issue.
%
%\subsection{Output of notes}
% Bibnotes are only printed when a bibliography is created.  This
% means that at the very least a \cs{bibliographystyle} command must
% appear in the source.\footnote{For \pkg{biblatex} users, the
% package must be loaded!}  Under most circumstances, the user will
% be citing literature, and so will also include a \cs{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 \cs{bibliography} in the source.\footnote{\LaTeX\
% will complain if the user puts \cs{bibliography\{\}}.}  The package
% therefore provides the macro \cs{printbibnotes}, which will output
% only the notes.  If the \pkg{endnotes} package has been loaded, the
% \cs{theendnotes} macro is redefined to achieve the same effect.
%
%\subsection{Cross-referencing notes\label{subsec:cross-ref}}
%\DescribeMacro{\citenote}
% 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.  Notes are
% available to be cited directly using the \cs{cite} command.
% However, this can cause problems when using the \opt{sort=tail}
% option. The \cs{citenote} command is therefore provided.  This is
% aware of the options, and will act correctly in all circumstances.
%\begin{LaTeXexample}
%  Cross-references to the note labelled earlier
%  using \cite{labelled-note} and using
%  \citenote{labelled-note}.
%\end{LaTeXexample}
%
%\subsection{Interaction with other packages}
% \currpkg is designed to work well with as many other packages as
% possible. It has been tested with \pkg{cite}, \pkg{natbib},
% \pkg{hyperref} and \pkg{mciteplus} with no problems. The \currpkg
% package is compatible with the current release of \pkg{biblatex}
% (v0.7); older versions of \pkg{biblatex} may or may not
% work.\footnote{As \pkg{biblatex} is experimental and is not
% currently added to \TeX\ distributions, users have little excuse
% for not using the latest release.}
%
%\section{Special effects}
%\DescribeMacro{\flushnotestack}
% When using the \opt{sort=tail} option, citations are added to a
% stack as they are made.  This stack is then flushed to the
% \ext{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 \cs{flushnotestack} 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.\footnote{This macro was called \cs{flushcitestack} prior to
% v1.3.}
%
%\DescribeMacro{\thebibnote}
% 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 \currpkg does not pad the automatically-created labels with
% zeros.  To get the correct sort order, \cs{thebibnote} should be
% redefined.
%\begin{LaTeXexample}[noexample]
%  \makeatletter
%  \renewcommand*{\thebibnote}{%
%    \niib@name
%    \ifnum\value{bibnote} < 9 0\fi
%    \the\value{bibnote}}
%  \makeatother
%\end{LaTeXexample}
%
% Using the package with \pkg{natbib} may require some work, for example
% when using the \texttt{unsrtnat} style.  This requires a couple of
% setting changes to get the correct labelling.\footnote{This is due to
% the method used by \pkg{natbib} when creating labels.}
%\begin{LaTeXexample}[noexample]
%  \niibsetup{writekey=false,name={}}
%\end{LaTeXexample}
%
% Notes can be separated from other citations easily using
% \pkg{biblatex}. Using the \opt{keyword} option, a key phrase can be
% used to mark notes. The optional argument to the
% \cs{printbibliography} can then be used to separate notes and
% other citations based on the keyword used. The following example
% also places note citations in the margin, and makes a switch available
% to control the appearance of notes. Note that the standard keyword is
% \opt{bibnote}.
%\begin{LaTeXexample}[noexample]
%  \documentclass{article}
%  \begin{filecontents}{demo.bib}
%  @article{Test,
%    title = {A test article},
%    author = {A. N. Other},
%    year = {2008},
%    pages = {1-10}
%  }
%  \end{filecontents}
%  \usepackage{notes2bib,biblatex}
%  \defbibheading{notes}{\section*{Notes}}
%  \bibliography{demo}
%  \newif\ifprintbibnotes\printbibnotesfalse
%  \niibsetup{cite=mycite}
%  \ifprintbibnotes
%   \newcommand*{\mycite}[1]{\marginpar{\cite{#1}}}
%  \else
%    \newcommand*{\mycite}[1]{}
%  \fi
%  \begin{document}
%  Some text\bibnote{A first note} and some more\bibnote{A second note}.
%  A real citation \cite{Test}.
%  \printbibliography[notkeyword=bibnote]
%  \ifprintbibnotes
%    \printbibliography[heading=notes,keyword=bibnote]
%  \fi
%  \end{document}
%\end{LaTeXexample}
%
%\section{Package requirements}
% The package has only one requirement, \pkg{xkeyval} version 2.5 or
% later.  \eTeX\ is used if available, but is not a requirement.
%
%\section{Known issues}
% From v1.1, the method for writing notes to the \BibTeX\ database has
% been modified.  This means that bibnotes cannot contain verbatim
% text.\footnote{Actually, they can, but the spacing will go wrong.
% \LaTeX\ will only complain if a note ends with verbatim text.
% However, verbatim text is not supported in bibnotes: don't do it!}
% This is the same as for normal footnotes, and so the usual
% work-arounds are applicable.
%\begin{LaTeXexample}
%  The next note contains some awkward text
%  \bibnote{Some \texttt{\textbackslash verb}-like output}.
%\end{LaTeXexample}
%
% The package relies on \BibTeX\ being able to open and process the
% temporary database containing the note text.  The name of this file
% contains \cs{jobname}, the name of the main \LaTeX\ file being
% processed.  This must consist only of characters that \BibTeX\ can
% handle.  In particular, spaces in the file name will lead to
% problems.
%
%\bibliographystyle{unsrt}
%\renewcommand*{\refname}{Notes}
%\StopEventually{%
%  \printbibnotes
%  \PrintChanges
%  \PrintIndex}
%
%\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 \pkg{endnotes} package and \REVTeX class.  Both of these
% provided inspiration for this package.
%
%\subsection{The \texttt{endnotes} approach}
% The \pkg{endnotes} package\footnote{%
% \url{http://tug.ctan.org/macros/latex/contrib/misc/endnotes.sty}}
% allows the user to generate endnotes in the same way as footnotes.
% In \pkg{endnotes}, the text of the note is written to a \ext{ent}
% file. This is achieved in an unexpanded form using the \cs{meaning}
% \TeX\ primitive.  To produce the list of endnotes, this file is
% read back into \LaTeX, with the extra information \cs{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 \cs{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 \ext{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
% \cs{bibliography} environment to output each note in the
% bibliography. This takes place \latin{en masse}, after the normal
% citations.
%
% \REVTeX makes a number of modifications to \LaTeX, and is dependent
% on using \pkg{natbib}.  The method used is also not compatible with
% interspersing normal citations and notes.
%
%\subsection{The \texttt{notes2bib} approach}
%
% In \currpkg, notes are again written to an external file. However,
% in contrast to the methods those outlined above, \currpkg 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.\footnote{Writing to the file uses the \eTeX\
% \cs{unexpanded} primitive.}
%
% Each note results in a citation being placed by \currpkg in the
% \ext{aux} file.  The  \cs{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 \ext{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, \currpkg allows various methods for controlling the
% placement of notes, based on writing appropriate fields in the
% \BibTeX\ database.
%
%\DescribeMacro{niibheadcite}
% The \opt{sort=head} option works by adding an additional macro to
% the \ext{aux} file: \cs{niibheadcite}.  On the next \LaTeX\ run,
% this causes the relevant notes to be cited right at the beginning
% of the document, before any real citations.\footnote{Thanks to
% Michael Shell for the idea for this method.}  For \opt{sort=tail},
% the value of \cs{if@filesw} is temporarily altered to prevent
% writing of a citation to the \ext{aux} file.  The citation is added
% to a stack, and is written at the end of the document.
%
%\iffalse
%<*package>
%\fi
%\section{The package code}
%
%\subsection{Package setup code}
%\changes{v1.1}{2007/09/29}{Removed use of \pkg{xspace}}
% The package starts with the usual identification code and support
% loading.
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{notes2bib}
  [2008/10/22 v1.6 Integrating notes into the bibliography]
\RequirePackage{xkeyval}[2005/05/07]
%    \end{macrocode}
%\begin{macro}{\niib@tempa}
%\begin{macro}{\niib@tempb}
% Some private temporary macros are declared.
%    \begin{macrocode}
\newcommand*{\niib@tempa}{}
\newcommand*{\niib@tempb}{}
%    \end{macrocode}
%\end{macro}
%\end{macro}
%
%\subsection{Logging}
%\begin{macro}{\ifniib@debug}
%\begin{macro}{\ifniib@logmin}
%\begin{macro}{\ifniib@lognone}
% To control logging, some new switches are declared.
%    \begin{macrocode}
\newif\ifniib@debug
\newif\ifniib@logmin
\newif\ifniib@lognone
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\end{macro}
%\begin{macro}{\niib@log@err}
%\begin{macro}{\niib@log@warn}
%\begin{macro}{\niib@log@inf}
% Some handy re-usable macros are defined here.  These all take names
% beginning  These pop up in various places.  First errors, warnings
% and information are handled.  Package options are used to control
% how much output is given.
%    \begin{macrocode}
\newcommand*{\niib@log@err}[2]{%
  \ifniib@lognone\else
    \ifniib@logmin
      \PackageWarning{notes2bib}{#1}%
    \else
      \PackageError{notes2bib}{#1}{#2}%
    \fi
  \fi}
\newcommand*{\niib@log@warn}[1]{%
  \ifniib@lognone\else
    \ifniib@logmin\else
      \PackageWarning{notes2bib}{#1}%
    \fi
  \fi}
\newcommand*{\niib@log@inf}[1]{%
  \ifniib@lognone\else
    \ifniib@logmin\else
      \PackageInfo{notes2bib}{#1}%
    \fi
  \fi}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\niib@log@debug}
% The debug macro only gives output if the appropriate package option
% is set.
%    \begin{macrocode}
\newcommand*{\niib@log@debug}[1]{%
  \ifniib@lognone\else
    \ifniib@debug
      \PackageInfo{notes2bib}{#1}%
    \fi
  \fi}
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\end{macro}
%
%\subsection{Package options}
%\begin{macro}{\niib@opt@boolkey}
% To aid maintenance, some shortcuts are defined for generating keys.
% These also allow the debugging messages to be added automatically
% to every key.
%    \begin{macrocode}
\newcommand*{\niib@opt@boolkey}[2][]{%
  \define@boolkey[niib]{opt}[niib@]{#2}[true]
  {#1\niib@log@debug{Option #2 set to ##1}}}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\niib@opt@choicekey}
% A ``fill in the blanks'' choice key.  In all cases, \cs{niib@tempa}
% is used to hold the value given to the key, so that \cs{ifx}
% testing can occur.
%    \begin{macrocode}
\newcommand*{\niib@opt@choicekey}[5][]{%
  \define@choicekey*+[niib]{opt}{#2}[\niib@tempa]{#3}[#1]
    {#4\niib@log@debug{Option #2 set to ##1}}
    {#5\niib@log@debug{Option #2 set to ##1}}}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\niib@opt@cmdkeys}
% A shortcut for \pkg{xkeyval} command keys.
%    \begin{macrocode}
\newcommand*{\niib@opt@cmdkeys}[1]{%
  \define@cmdkeys[niib]{opt}[niib@]{#1}}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\niibsetup}
%\changes{v1.3}{2008/01/08}{New macro}
% To allow modification of options at run time, a setup macro is
% provided.  The run of strange tests are to prevent problems in
% arrays and the like.
%    \begin{macrocode}
\newcommand*{\niibsetup}{\setkeys[niib]{opt}}
%    \end{macrocode}
%\end{macro}
% The \pkg{xkeyval} package option for logging is declared. This is
% then processed to set the switches correctly.
%    \begin{macrocode}
\niib@opt@choicekey[normal]{log}
  {debug,verbose,normal,errors,none}
%    \end{macrocode}
% A series of comparisons are made to assign the logging mode.  The
% \opt{normal} option is not tested, as executing the option sets the
% switches appropriately.
%    \begin{macrocode}
  {\niib@debugfalse
   \niib@logminfalse
   \niib@lognonefalse
   \renewcommand*{\niib@tempb}{none}%
   \ifx\niib@tempa\niib@tempb
     \niib@lognonetrue
   \fi
   \renewcommand*{\niib@tempb}{minimal}%
   \ifx\niib@tempa\niib@tempb
     \niib@logmintrue
   \fi
   \renewcommand*{\niib@tempb}{debug}%
   \ifx\niib@tempa\niib@tempb
     \niib@debugtrue
   \fi
   \renewcommand*{\niib@tempb}{verbose}%
   \ifx\niib@tempa\niib@tempb
     \niib@debugtrue
   \fi}
%    \end{macrocode}
% The option has not been recognised: give a warning (if
% appropriate).
%    \begin{macrocode}
   {\niib@log@warn{Unrecognised value `#1' for option log}}
%    \end{macrocode}
%\begin{macro}{\niib@opt@debug}
% A quick method to set \opt{log=debug}.
%    \begin{macrocode}
\niib@opt@boolkey{debug}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\ifniib@footnotes}
%\begin{macro}{\ifniib@endnotes}
% The \opt{footnote} and \opt{endnote} options are declared here.
%    \begin{macrocode}
\niib@opt@boolkey[\niib@swapfoot]{footnotes}
\niib@opt@boolkey[\niib@swapend]{endnotes}
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\begin{macro}{\ifniib@head}
%\begin{macro}{\ifniib@tail}
% Switches are needed for placing notes before and after normal
% citations.
%    \begin{macrocode}
\newif\ifniib@tail
\newif\ifniib@head
%    \end{macrocode}
%\end{macro}
%\end{macro}
% This option controls the position of notes \latin{versus} normal
% citations. The \pkg{xkeyval} option replaces the earlier \opt{head}
% and \opt{tail} options, which are retained for backward
% compatibility.
%    \begin{macrocode}
\niib@opt@choicekey[none]{sort}{none,head,tail}
  {\niib@headfalse
   \niib@tailfalse
   \renewcommand*{\niib@tempb}{head}%
   \ifx\niib@tempa\niib@tempb
     \niib@headtrue
   \fi
   \renewcommand*{\niib@tempb}{tail}%
   \ifx\niib@tempa\niib@tempb
     \niib@tailtrue
   \fi}
  {\niib@log@warn{Unrecognised value `#1' for option sort}}
%    \end{macrocode}
% The back-compatibility code; unlike earlier versions, this will
% take whatever the \opt{sort}-type key is given.
%    \begin{macrocode}
\niib@opt@boolkey[%
  \ifniib@head
    \ifniib@tail
      \niib@tailfalse
      \niib@log@inf{Option head cancels existing\MessageBreak
        tail or sort=tail option}
    \fi
  \fi]{head}
\niib@opt@boolkey[%
  \ifniib@tail
    \ifniib@head
      \niib@headfalse
      \niib@log@inf{Option tail cancels existing\MessageBreak
        head or sort=head option}
    \fi
  \fi]{tail}
%    \end{macrocode}
%\begin{macro}{\niib@writekey}
%\changes{v1.6}{2008/10/21}{Added \opt{writekey} option}
% Control of writing \texttt{key} to disk.
%    \begin{macrocode}
\niib@opt@boolkey{writekey}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\niib@cite}
%\begin{macro}{\niib@name}
%\begin{macro}{\niib@prefix}
%\begin{macro}{\niib@record}
%\begin{macro}{\niib@field}
%\begin{macro}{\niib@presorthead}
%\begin{macro}{\niib@presortnone}
%\begin{macro}{\niib@presorttail}
%\begin{macro}{\niib@keyhead}
%\begin{macro}{\niib@keynone}
%\begin{macro}{\niib@keytail}
%\begin{macro}{\niib@keyword}
% The various internal control values are set up as command keys.
%    \begin{macrocode}
\niib@opt@cmdkeys{%
  cite,
  name,
  prefix,
  record,
  field,
  presorthead,
  presortnone,
  presorttail,
  keyhead,
  keynone,
  keytail,
  keyword}
\niibsetup{
  cite=cite,
  name=Bibnote,
  prefix=niib-,
  record=Misc,
  field=note,
  presorthead=ml,
  presortnone=mm,
  presorttail=mn,
  keyhead=aaa,
  keynone={},
  keytail=zzz,
  keyword=bibnote,
  writekey=true}
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\end{macro}
%\end{macro}
%\end{macro}
%\end{macro}
%\end{macro}
%\end{macro}
%\end{macro}
%\end{macro}
%\end{macro}
%\end{macro}
%\begin{macro}{\ifniib@etex}
% The option to turn off \eTeX\ needs to ensure that the user does
% not ask for \eTeX\ if it is not there.  On the other hand, the
% default is to use \eTeX\ if it is available.
%    \begin{macrocode}
\niib@opt@boolkey{etex}
\begingroup
  \@ifundefined{eTeXversion}
    {}
    {\global\niib@etextrue}
\endgroup
%    \end{macrocode}
%\end{macro}
%
%\subsection{Footnote and endnote handling}
%\begin{macro}{\niib@org@footnote}
%\changes{v1.3c}{2008/02/26}{Saved in package}
%\begin{macro}{\niib@org@footnotemark}
%\changes{v1.3c}{2008/02/26}{Saved in package}
%\begin{macro}{\niib@org@footnotetext}
%\changes{v1.3c}{2008/02/26}{Saved in package}
% To allow dynamic handling of footnotes and endnotes, the original
% definitions are backed up.
%    \begin{macrocode}
\let\niib@org@footnote\footnote
\let\niib@org@footnotemark\footnotemark
\let\niib@org@footnotetext\footnotetext
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\end{macro}
%\begin{macro}{\niib@org@endnote}
%\begin{macro}{\niib@org@endnotemark}
%\begin{macro}{\niib@org@endnotetext}
%\begin{macro}{\niib@org@theendnotes}
% If \pkg{endnotes} is loaded, then \cs{endnote} and friends have to
% be saved.
%    \begin{macrocode}
\AtBeginDocument{
  \@ifpackageloaded{endnotes}
    {\let\niib@org@endnote\endnote
     \let\niib@org@endnotemark\endnotemark
     \let\niib@org@endnotetext\endnotetext
     \let\niib@org@theendnotes\theendnotes}{}}
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\end{macro}
%\end{macro}
%\begin{macro}{\thanks}
%\changes{v1.3c}{2008/02/26}{Altered redefinition method}
%\changes{v1.3c}{2008/02/26}{Redefinition in preamble}
% The \cs{thanks} macro is redefined.
%    \begin{macrocode}
\@ifundefined{thanks}{}
  {\renewcommand*{\thanks}[1]{%
     \niib@org@footnotemark
     \protected@xdef\@thanks{\@thanks
     \protect\niib@org@footnotetext[\the\c@footnote]{#1}}}}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\niib@swapfoot}
%\changes{v1.3c}{2008/02/26}{Simplified code}
%\begin{macro}{\footnote}
%\begin{macro}{\footnotemark}
%\begin{macro}{\footnotetext}
% The swapping code can now be implemented.
%    \begin{macrocode}
\newcommand*{\niib@swapfoot}{%
  \ifniib@footnotes
    \let\footnote\bibnote
    \let\footnotemark\bibnotetext
    \let\footnotetext\bibnotemark
    \niib@log@debug{Converting footnotes to bibnotes}%
  \else
    \let\footnote\niib@org@footnote
    \let\footnotemark\niib@org@footnotemark
    \let\footnotetext\niib@org@footnotetext
    \niib@log@debug{Using kernel definition of footnotes}%
    \fi}
\AtBeginDocument{\niib@swapfoot}
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\end{macro}
%\end{macro}
%\begin{macro}{\niib@swapend}
%\begin{macro}{\endnote}
%\begin{macro}{\endnotemark}
%\begin{macro}{\endnotetext}
%\begin{macro}{\theendnotes}
% For endnotes, the code needed depends on whether the \pkg{endnotes}
% package is available or not.  If it is, then swapping the two
% definitions is set up.
%    \begin{macrocode}
\newcommand*{\niib@swapend}{}
\AtBeginDocument{
  \@ifpackageloaded{endnotes}
    {\renewcommand*{\niib@swapend}{%
       \ifniib@endnotes
         \let\endnote\bibnote
         \let\endnotemark\bibnotemark
         \let\endnotetext\bibnotetext
         \let\theendnotes\printbibnotes
         \niib@log@debug{Converting endnotes to bibnotes}%
       \else
         \let\endnote\niib@org@endnote
         \let\endnotemark\niib@org@endnotemark
         \let\endnotetext\niib@org@endnotetext
         \let\theendnotes\niib@org@theendnotes
         \niib@log@debug{Using endnotes package to handle
           endnotes}%
       \fi}
     \niib@swapend}
%    \end{macrocode}
% \pkg{endnotes} is not loaded; once the \opt{endnotes} option has been
% given, there is nothing to go back.  Of course, if the user does not
% give the \opt{endnotes} option, \cs{endnote} is not defined at all.
%    \begin{macrocode}
    {\ifniib@endnotes
       \let\endnote\bibnote
       \let\endnotemark\bibnotemark
       \let\endnotetext\bibnotetext
       \let\theendnotes\printbibnotes
       \niib@log@debug{Converting endnotes to bibnotes}%
     \fi
     \renewcommand*{\niib@swapend}{%
       \ifniib@endnotes
         \let\endnote\bibnote
         \let\endnotemark\bibnotemark
         \let\endnotetext\bibnotetext
         \let\theendnotes\printbibnotes
         \niib@log@debug{Converting endnotes to bibnotes}%
       \else
         \niib@log@inf{endnotes package not loaded\MessageBreak
           endnotes=false ignored}%
       \fi}}}
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\end{macro}
%\end{macro}
%\end{macro}
% Options can now be processed.
%    \begin{macrocode}
\ProcessOptionsX[niib]<opt>
\AtEndOfPackage{
  \define@key[niib]{opt}{etex}
    {\niib@log@warn{Option `etex' only available
       \MessageBreak when loading notes2bib}}}
\begingroup
  \@ifundefined{eTeXversion}
    {\ifniib@etex
       \niib@log@warn{e-TeX unavailable}%
       \global\niib@etexfalse
     \fi}
    {\ifniib@etex\else
       \niib@log@inf{Use of e-TeX disabled}%
     \fi}
\endgroup
%    \end{macrocode}
%
%\subsection{User macros}
%\begin{macro}{\thebibnote}
% A counter is needed for the notes created.  In analogy to other
% counters in \LaTeX, this is given a \cs{the\dots} name.  The user
% should not really need to use this macro, but convention dictate
% that it has a user-space name.  The \LaTeX\ \cs{newcounter} macro
% is used (rather than the \TeX\ \cs{newcount}) as the automatic
% system expects the numbers to be globally unique.
%    \begin{macrocode}
\newcounter{bibnote}
\renewcommand*{\thebibnote}{\niib@name\the\value{bibnote}}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\bibnote}
%\changes{v1.1}{2007/09/29}{Macro made robust}
% Each new bibnote increments the note counter, then checks for an
% optional label, before handing off to the internal macro
% \cs{niib@bibnote}.
%    \begin{macrocode}
\DeclareRobustCommand*{\bibnote}{%
  \stepcounter{bibnote}%
  \@ifnextchar[%]
    {\niib@bibnote}
    {\niib@bibnote[\thebibnote]}}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\bibnotemark}
%\changes{v1.1}{2007/09/29}{Macro made robust}
% The \cs{bibnotemark} macro works in the same way as \cs{bibnote},
% but calls \cs{niib@mark} rather than \cs{niib@bibnote}.
%    \begin{macrocode}
\DeclareRobustCommand*{\bibnotemark}{%
  \stepcounter{bibnote}%
  \@ifnextchar[%]
    {\niib@mark}
    {\niib@mark[\thebibnote]}}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\bibnotetext}
%\changes{v1.1}{2007/09/29}{Macro made robust}
% The text companion to the mark macro above, with no increment of
% the counter.  There is nothing special to do, so the \LaTeX\ kernel
% handling of optional arguments can be used.
%    \begin{macrocode}
\DeclareRobustCommand*{\bibnotetext}[1][\thebibnote]{%
  \let\niib@next\niib@gobble
  \niib@text{#1}}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\printbibnotes}
%\changes{v1.1}{2007/09/29}{Macro made robust}
%\changes{v1.3b}{2008/01/16}{Definition moved to beginning of
%  document}
% To allow for the possibility of there being no other notes, a
% command to print only notes is given.  In the \pkg{biblatex} case,
% the best that can be done is to issue \cs{printbibliography}.
%    \begin{macrocode}
\AtBeginDocument{
  \@ifpackageloaded{biblatex}
    {\let\printbibnotes\printbibliography}
    {\DeclareRobustCommand*{\printbibnotes}
       {\niib@org@bib{\niib@prefix\jobname}}}}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\flushnotestack}
%\changes{v1.1}{2007/09/29}{Macro made robust}
%\changes{v1.3}{2008/01/08}{Fixed bug with empty stack}
%\changes{v1.3}{2008/01/08}{Renamed from \cs{flushcitestack}}
%\changes{v1.3b}{2008/01/16}{Writes stack to \ext{aux} file}
%\changes{v1.3b}{2008/01/16}{Added check for correct \opt{tail}
%  citations in \ext{aux} file}
% 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 \ext{aux} file.  This
% is done here, and the stack is cleared so collection can begin
% again.
%    \begin{macrocode}
\DeclareRobustCommand*{\flushnotestack}{%
  \let\niib@taillist\niib@stack
  \ifniib@rerun\else
    \niib@checkrerun{tail}%
  \fi
  \ifx\@empty\niib@stack\@empty
    \niib@log@debug{Citation stack empty: nothing for
      \MessageBreak\noexpand\flushnotestack to do}%
  \else%
    \niib@log@debug{Flushing note citations to aux file}%
    \if@filesw
      \immediate\write\@auxout{%
        \string\niibtailcite{\niib@stack}}%
    \fi
    \expandafter\nocite\expandafter{\niib@stack}%
    \gdef\niib@stack{}%
  \fi}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\citenote}
%\changes{v1.0a}{2007/09/03}{New macro}
%\changes{v1.1}{2007/09/29}{Macro made robust}
%\changes{v1.3}{2008/01/08}{Now a wrapper for \cs{niib@mark}}
% Problems arise with \cs{cite} and the \opt{sort=tail} option.
% Rather than overload \cs{cite} with all of the problems that can
% bring, a new command is provided that can be guaranteed to work.
%    \begin{macrocode}
\DeclareRobustCommand*{\citenote}[1]{\niib@mark[#1]}
%    \end{macrocode}
%\end{macro}
%
%\subsection{Internal macros}
%\begin{macro}{\niib@keyname}
%\changes{v1.3}{2008/01/08}{Moved to \cs{AtBeginDocument}}
% If \pkg{biblatex} is in use, the key field in the \BibTeX\ database
% should be called ``keysort,'' whereas otherwise it should be
% ``key.''
%    \begin{macrocode}
\AtBeginDocument{
  \@ifpackageloaded{biblatex}
    {\niib@log@debug{Using field `keysort' for sorting key}%
     \newcommand*{\niib@keyname}{keysort}}
    {\niib@log@debug{Using field `key' for sorting key}%
     \newcommand*{\niib@keyname}{key}}}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\niib@presort}
%\changes{v1.3}{2008/01/08}{Dynamic rather than static definition}
%\begin{macro}{\niib@key}
%\changes{v1.3}{2008/01/08}{Dynamic rather than static definition}
% The values taken by \cs{niib@presort} and \cs{niib@key} depend
% on the desired positioning of notes in the bibliography.
%    \begin{macrocode}
\newcommand*{\niib@presort}{%
  \ifniib@head
    \niib@presorthead
  \else
    \ifniib@tail
      \niib@presorttail
    \else
      \niib@presortnone
    \fi
  \fi}
\newcommand*{\niib@key}{%
  \ifniib@head
    \niib@keyhead
  \else
    \ifniib@tail
      \niib@keytail
    \else
      \niib@keynone
    \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 is empty.
%    \begin{macrocode}
\newcommand*{\niib@stack}{}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\niib@addtostack}
%\changes{v1.3}{2008/01/08}{Macro renamed from \cs{niib@stackup}}
% The various optional argument tricks above all use the same core
% code, which adds the mandatory argument of the citation to the
% stack.  The stack is global (see also \cs{flushnotestack}).
%    \begin{macrocode}
\newcommand*{\niib@addtostack}[1]{%
  \niib@log@debug{Adding citation #1\MessageBreak to `tail'
    stack}%
  \edef\niib@tempa{#1}%
  \ifx\@empty\niib@stack\@empty
    \xdef\niib@stack{\niib@tempa}%
  \else
    \xdef\niib@stack{\niib@stack,\niib@tempa}%
  \fi}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\niib@bibnote}
%\changes{v1.3}{2008/01/08}{Use \cs{niib@mark} for citation}
% Two steps are needed here, writing the text of the note to file
% (handled by \cs{niib@text}, and marking the citation (using
% \cs{niib@cite}).
%    \begin{macrocode}
\long\def\niib@bibnote[#1]#2{%
  \let\niib@next\niib@mark
  \niib@text{#1}{#2}}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\niib@headlist}
% To inform the user that a re-run of \LaTeX\ is needed, tracking is
% needed of any ``head'' citations.
%    \begin{macrocode}
\newcommand*{\niib@headlist}{}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\niib@mark}
% Adding a citation to the \LaTeX\ file is handled here.  When using
% the \opt{sort=head} option, the citation is written to the
% \ext{aux} file for sorting control.  The normal citation command is
% then called.
%    \begin{macrocode}
\def\niib@mark[#1]{%
  \ifniib@head
    \edef\niib@tempa{#1}%
    \ifx\@empty\niib@headlist\@empty
      \xdef\niib@headlist{\niib@tempa}%
    \else
      \xdef\niib@headlist{\niib@headlist,\niib@tempa}%
    \fi
    \if@filesw
      \niib@log@debug{Adding citation #1 to list for next run}%
      \immediate\write\@auxout{\string\niibheadcite{#1}}%
    \fi
  \fi
%    \end{macrocode}
% When the \opt{sort=tail} option is active, citation is handled by
% another macro, so a switch is needed.
%    \begin{macrocode}
  \ifniib@tail
    \expandafter\niib@tailcite%
  \else
    \expandafter\niib@normcite%
  \fi
  {#1}}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\ifniib@filesw}
% A switch is used to back up \cs{if@filesw}.
%    \begin{macrocode}
\newif\ifniib@filesw
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\niib@tailcite}
% When using the \opt{sort=tail} option, bibnote citation need to be
% stored for later.   With \pkg{biblatex}, the \cs{AtEndCite} macro
% is available to provide a hook for the necessary switch.  In other
% cases, the current value of \cs{if@filesw} is then saved, before
% turning it off and setting up the restore system.
%\end{macro}
%    \begin{macrocode}
\AtBeginDocument{
  \@ifpackageloaded{biblatex}
    {\newcommand{\niib@tailcite}[1]{%
       \niib@addtostack{#1}%
       \AtNextCite{\@fileswfalse}%
       \niib@normcite{#1}}}
    {\newcommand{\niib@tailcite}[1]{%
       \niib@addtostack{#1}%
       \let\ifniib@filesw\if@filesw
       \@fileswfalse
       \let\niib@auxhook\niib@restorefilesw
       \niib@tcite{#1}}}}
%    \end{macrocode}
%\begin{macro}{\niib@restorefilesw}
% Restoring the switch is set up here.  The reference to
% \cs{niib@auxhook} ensures that the mechanism is turned off for the
% next real citation.
%    \begin{macrocode}
\newcommand*{\niib@restorefilesw}{%
  \let\if@filesw\ifniib@filesw
  \let\niib@auxhook\relax}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\niib@tcite}
% Actually carrying out the citation, and restoring the value of
% \cs{if@filesw} depends on whether \pkg{cite} is loaded.
%    \begin{macrocode}
\AtBeginDocument{%
  \@ifpackageloaded{cite}
    {\newcommand*{\niib@tcite}[1]{\niib@normcite{#1}}}
    {\newcommand*{\niib@tcite}[1]{%
       \niib@normcite{#1}%
       \niib@restorefilesw}}}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\niib@normcite}
% The normal citation command.
%    \begin{macrocode}
\newcommand*{\niib@normcite}{\@nameuse{\niib@cite}}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\niib@next}
%\begin{macro}{\niib@gobble}
% To allow correct detection of following punctuation by
% \cs{niib@mark}, it has to follow \cs{niib@text}. However, to
% prevent category code issues, \cs{niib@text} can only take
% \emph{one} argument.  Hence, a ``follow-on'' macro is needed; this
% is provided here.  The no-op here has to gobble a square-bracketed
% argument.
%    \begin{macrocode}
\newcommand*{\niib@next}{}
\def\niib@gobble[#1]{}
\let\niib@next\niib@gobble
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\begin{macro}{\niib@text}
%\begin{macro}{\niib@out}
%\begin{macro}{\niib@stream}
% The \cs{niib@text} macro is the outer part of the writing system.
% It does not absorb the text of note, as without \eTeX\ this is bad
% news.
%    \begin{macrocode}
\newcommand*{\niib@text}{%
  \@bsphack
  \@ifundefined{niib@out}
    {\if@filesw
       \newwrite\niib@out
       \gdef\niib@stream{\niib@prefix\jobname.bib}%
       \niib@log@debug{Creating BibTeX database file
         \MessageBreak\niib@stream\space to contain bibnotes}%
       \immediate\openout\niib@out\niib@stream\relax
       \immediate\write\niib@out{\niib@msg}%
     \fi}
    {}%
  \if@filesw
    \expandafter\niib@write
  \else
    \expandafter\niib@tidy
  \fi}
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\end{macro}
%\begin{macro}{\niib@tidy}
% When not writing to file.
%    \begin{macrocode}
\newcommand*{\niib@tidy}[2]{%
  \@esphack
  \niib@next[#1]}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\niib@write}
% The \cs{niib@write} macro deals with writing data verbatim to the
% \BibTeX\ file.  When \eTeX\ is available, this is easy; the macro
% absorbs the note text and uses \cs{unexpanded}.
%    \begin{macrocode}
\ifniib@etex
  \newcommand*{\niib@write}[2]{%
    \niib@log@debug{Writing bibnote #1 contents
      \MessageBreak---\MessageBreak#2\MessageBreak
      ---\MessageBreak to BibTeX database}%
    \immediate\write\niib@out{%
      @\niib@record\string{#1,^^J%
      presort = \string{\niib@presort\string},^^J%
      \ifniib@writekey
        \niib@keyname\space= \string{\niib@key#1\string},^^J%
      \fi
      keywords = \string{\niib@keyword\string},^^J%
      \niib@field\space= \string{\unexpanded{#2}\string}^^J%
      \string}^^J}%
    \@esphack
    \niib@next[#1]}
%    \end{macrocode}
% Life is more awkward when \eTeX\ is unavailable.  The code here is
% based on a suggestion by Ulrich Diez, with alterations to the
% specifics needed here.
%    \begin{macrocode}
\else
  \newcommand*{\niib@write}[1]{%
    \begingroup
      \let\do\@makeother
      \dospecials
      \catcode`\{=1\relax
      \catcode`\}=2\relax
      \niib@write@{#1}}
\fi
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\niib@write@}
% Two support macros are needed if \eTeX\ is not available.
% \cs{niib@write@} works with the category codes altered as above,
% which means that text is written (essentially) verbatim to the
% \BibTeX\ file.
%    \begin{macrocode}
\newcommand\niib@write@[1]{%
  \long\def\niib@tempa##1{%
    \def\niib@tempa{##1}%
    \@onelevel@sanitize\niib@tempa\expandafter\endgroup
    \expandafter\def\expandafter\niib@tempa\expandafter{%
      \niib@tempa}%
    \niib@write@@{#1}}%
  \catcode`\^^M=10\relax
  \niib@tempa}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\niib@write@@}
% Writing to the file is a very slightly altered version of the
% \eTeX\ version.  In this case, the debugging data is given here,
% after category code changes.
%    \begin{macrocode}
\newcommand*\niib@write@@[1]{%
  \niib@log@debug{Writing bibnote #1 contents
    \MessageBreak---\MessageBreak\niib@tempa\MessageBreak
    ---\MessageBreak to BibTeX database}%
  \immediate\write\niib@out{%
    @\niib@record\string{#1,^^J%
    presort = \string{\niib@presort\string},^^J%
    \niib@keyname\space= \string{\niib@key#1\string},^^J%
    \niib@field\space= \string{\niib@tempa\string}^^J%
    \string}^^J}%
  \@esphack
  \niib@next[#1]}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\niib@headcitelist}
% To inform the user that a re-run of \LaTeX\ is needed, tracking is
% needed of any citations that have been moved to the start of the
% \ext{aux} file. This needs an initially-empty macro.
%    \begin{macrocode}
\newcommand*{\niib@headcitelist}{}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\document}
%\changes{v1.3}{2008/01/08}{Added hook after \ext{aux} files has been
%  read but before document begins}
%\begin{macro}{\niib@dochook}
%\begin{macro}{\niibheadcite}
%\changes{v1.3}{2008/01/08}{New macro}
% When using the \opt{sort=head} option, bibnotes need to appear in
% the \ext{aux} file before other citations.  Other approaches cause
% all sorts of problems, so the suggestion of Michael Shell is
% implemented here. When \opt{head} is active, \cs{niibheadcite} is
% added to the \ext{aux} file.  At the next \LaTeX\ run, this will
% add a citation to the beginning of the \ext{aux} file.  To get the
% \cs{nocite} to work, a hook has to be added to \cs{document}.  The
% reason is that \cs{AtBeginDocument} cannot be used here: it is not
% available once the old \ext{aux} file has been read.
%    \begin{macrocode}
\g@addto@macro{\document}{\niib@dochook}
\newcommand*{\niibheadcite}[1]{%
  \edef\niib@tempa{#1}%
  \ifx\@empty\niib@headcitelist\@empty
    \xdef\niib@headcitelist{\niib@tempa}%
  \else
    \xdef\niib@headcitelist{\niib@headcitelist,\niib@tempa}%
  \fi
  \if@filesw
    \niib@log@debug{Adding citation #1 to start of .aux file}%
  \fi
  \g@addto@macro{\niib@dochook}{\nocite{#1}}}
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\end{macro}
%\begin{macro}{\niib@tailcitelist}
%\changes{v1.3b}{2008/01/16}{New macro}
%\begin{macro}{\niibtailcite}
%\changes{v1.3b}{2008/01/16}{New macro}
% To enable proper logging of citations when \opt{sort=tail}, a
% similar system to the above is employed without the \cs{nocite}
% part.
%    \begin{macrocode}
\newcommand*{\niib@tailcitelist}{}
\newcommand*{\niibtailcite}[1]{%
  \edef\niib@tempa{#1}%
  \ifx\@empty\niib@tailcitelist\@empty
    \xdef\niib@tailcitelist{\niib@tempa}%
  \else
    \xdef\niib@tailcitelist{\niib@tailcitelist,\niib@tempa}%
  \fi}
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\begin{macro}{\niib@auxhook}
%\changes{v1.3}{2008/01/08}{New macro}
%\begin{macro}{\niib@dochook}
%\changes{v1.3}{2008/01/08}{New macro}
%\begin{macro}{\@restore@auxhandle}
% To allow the automatic punctuation-searching of \pkg{cite} to work,
% some code has to be added to the hook available there.  However, as
% that is intended for \pkg{multibib}, care is needed to get the
% desired result.  \cs{niib@dochook} is defined here, even though it
% is needed above, as the code here will always be executed.
%    \begin{macrocode}
\newcommand*{\niib@dochook}{%
  \@ifundefined{@restore@auxhandle}
    {\newcommand*{\@restore@auxhandle}{\niib@auxhook}}
    {\ifx\relax\@restore@auxhandle\relax
       \newcommand*{\@restore@auxhandle}{\niib@auxhook}%
     \else
       \g@addto@macro{\@restore@auxhandle}{\niib@auxhook}%
     \fi}}
\newcommand*{\niib@auxhook}{}
\let\niib@auxhook\relax
%    \end{macrocode}
%\end{macro}
%\end{macro}
%\end{macro}
%\begin{macro}{\blx@bibfiles}
%\changes{v1.2}{2007/10/26}{Fixed bug with \pkg{biblatex} support}
%\changes{v1.3}{2008/01/08}{Modification now at beginning of
%  document}
%\changes{v1.3}{2008/01/08}{Updated for \pkg{biblatex} v0.7: moved
%  to end of preamble, switch from \cs{bib@gadd} to \cs{gappto}}
% The \cs{bibliography} macro is patched to ensure that when it is
% executed the note file is also processed.  \pkg{biblatex} does
% things very differently, but this actually makes it much easier to
% patch for.
%    \begin{macrocode}
\AtBeginDocument{
  \@ifpackageloaded{biblatex}
    {\expandafter\gappto\expandafter\blx@bibfiles\expandafter
       {,\niib@prefix\jobname}
     \niib@log@debug{Added bibnotes database to biblatex file
       list}}%
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\niib@org@bib}
%\begin{macro}{\bibliography}
%\changes{v1.3}{2008/01/08}{Modification now at beginning of
%  document}
% Without \pkg{biblatex}, the bibliography command is patched so that
% it will run on the automatically-generated \BibTeX\ database.  If
% no notes have been added, then the macro doesn't actually do
% anything.
%    \begin{macrocode}
    {\let\niib@org@bib\bibliography
     \renewcommand*{\bibliography}[1]{%
       \ifnum\the\value{bibnote} > \z@
         \niib@org@bib{\niib@prefix\jobname,#1}%
       \else
         \niib@org@bib{#1}%
       \fi}
     \niib@log@debug{Added bibnote database to
       \noexpand\bibliography}}}
%    \end{macrocode}
%\end{macro}
%\end{macro}
%
%\subsection{Finalisation}
%\begin{macro}{\ifniib@rerun}
% A switch is needed for the re-run test.
%    \begin{macrocode}
\newif\ifniib@rerun
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\niib@checkrerun}
%\changes{v1.3b}{2008/01/16}{Added ability to check for both
%  \opt{head} and \opt{tail} re-runs}
%\changes{v1.3b}{2008/01/16}{Bug fix with logging for
%  \opt{debug} logging}
% Any ``head'' notes may mean a second \LaTeX\ run is needed.
%    \begin{macrocode}
\newcommand*{\niib@checkrerun}[1]{%
  \niib@rerunfalse
  \expandafter\ifx\expandafter\@empty
    \csname niib@#1list\endcsname\@empty
    \expandafter\ifx\expandafter\@empty
      \csname niib@#1citelist\endcsname\@empty
      \niib@log@debug{No `#1' notes detected}%
    \else
      \niib@reruntrue
      \niib@log@debug{No `#1' notes found this run\MessageBreak
        but .aux files contained the `#1' requests:
        \MessageBreak\csname niib@#1citelist\endcsname}%
    \fi
  \else
    \expandafter\ifx\expandafter\@empty
      \csname niib@#1citelist\endcsname\@empty
      \niib@reruntrue
      \niib@log@debug{No `#1' requests in .aux file
        \MessageBreak but `#1' notes in this run:
        \MessageBreak\csname niib@#1list\endcsname}%
    \else
%    \end{macrocode}
% If the package gets here, then there are some notes and some
% requests in the aux file.  The two lists are now compared.
%    \begin{macrocode}
      \niib@checklists{#1}%
    \fi
  \fi
  \ifniib@rerun
%    \end{macrocode}
% Both human-readable requests for new runs, and \pkg{biblatex}-style
% automated requests are made.  The package does not know if \BibTeX8
% is in use, so just asks for \BibTeX.
%    \begin{macrocode}
    \niib@log@warn{Rerun LaTeX to get correct \MessageBreak
      `#1' notes}%
    \niib@log@warn{Please (re)run BibTeX on the file(s):
      \MessageBreak\jobname.aux
      \MessageBreak and rerun LaTeX afterwards.}%
    \ifniib@lognone\else
      \typeout{%
        REQ:3:latex:REQ^^J%
        REQ:2:bibtex:REQ^^J%
        REQ:1:latex:REQ}%
    \fi
  \fi}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\niib@checklists}
%\changes{v1.3b}{2008/01/16}{Added ability to check for both
%  \opt{sort=head} and \opt{sort=tail}}
% The business end of comparing the two lists.  Two sweeps are made,
% to check that the lists match entirely.
%    \begin{macrocode}
\newcommand*{\niib@checklists}[1]{%
%    \end{macrocode}
%\begin{macro}{\niib@list}
%\changes{v1.3b}{2008/01/16}{New macro}
%\begin{macro}{\niib@citelist}
%\changes{v1.3b}{2008/01/16}{New macro}
% To allow \cs{niib@checklists} to handle both \opt{sort=head} and
% \opt{sort=tail} citations, the expanded list is needed for the
% \cs{@for} loops.
%    \begin{macrocode}
  \expandafter\edef\expandafter\niib@list\expandafter
    {\csname niib@#1list\endcsname}%
  \expandafter\edef\expandafter\niib@citelist\expandafter
    {\csname niib@#1citelist\endcsname}%
%    \end{macrocode}
%\end{macro}
%\end{macro}
% The loops can now being.
%    \begin{macrocode}
  \@for\niib@tempa:=\niib@list\do{%
    \niib@reruntrue
    \@for\niib@tempb:=\niib@citelist\do{%
      \ifx\niib@tempa\niib@tempb
        \niib@rerunfalse
      \fi}
    \ifniib@rerun
      \niib@log@debug{Note \niib@tempa\space is a `#1' note
        \MessageBreak but request not in .aux file}%
    \fi}
  \ifniib@rerun\else
    \@for\niib@tempa:=\niib@citelist\do{%
      \niib@reruntrue
      \@for\niib@tempb:=\niib@list\do{%
        \ifx\niib@tempa\niib@tempb
          \niib@rerunfalse
        \fi}
      \ifniib@rerun
        \niib@log@debug{Note \niib@tempa\space is set to `#1'
          in .aux\MessageBreak file but is not a `#1' note}%
      \fi}
  \fi}
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\niib@taillist}
%\changes{v1.3b}{2008/01/16}{New macro}
% At the end of the document, any delayed citations are written to the
% \ext{aux} file, and the database file is closed cleanly.  A check is
% also made for the need for an additional \LaTeX\ run for ``head''
% notes.
%    \begin{macrocode}
\AtEndDocument{%
  \niib@rerunfalse
  \niib@checkrerun{head}%
  \flushnotestack
  \@ifundefined{niib@out}{}
    {\immediate\closeout\niib@out
     \niib@log@debug{Closed BibTeX database file\MessageBreak
       \niib@stream}}}
%    \end{macrocode}
%\end{macro}
%
%\iffalse
%</package>
%\fi
% \Finale
%\iffalse
%<*jawltxdoc>
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{jawltxdoc}
\usepackage[T1]{fontenc}
\usepackage{lmodern}
\usepackage[final]{listings,graphicx,microtype}
\usepackage[scaled=0.95]{helvet}
\usepackage[version=3]{mhchem}
\usepackage[osf]{mathpazo}
\usepackage{booktabs,array,url,courier,xspace,varioref}
\usepackage{upgreek,ifpdf,float,caption,longtable,babel}
\begingroup
  \@ifundefined{eTeXversion}
    {\aftergroup\@gobble}
    {\aftergroup\@firstofone}
\endgroup
{\usepackage{etoolbox}}
\floatstyle{plaintop}
\restylefloat{table}
\labelformat{figure}{\figurename~#1}
\labelformat{table}{\tablename~#1}
\ifpdf
  \usepackage{embedfile}
  \embedfile[%
    stringmethod=escape,%
    mimetype=plain/text,%
    desc={LaTeX docstrip source archive for package `\jobname'}%
    ]{\jobname.dtx}
\fi
\IfFileExists{\jobname.sty}
  {\usepackage{\jobname}}{}
\usepackage[numbered]{hypdoc}
\setcounter{IndexColumns}{2}
\newlength\LaTeXwidth
\newlength\LaTeXoutdent
\newlength\LaTeXgap
\setlength\LaTeXgap{1em}
\setlength\LaTeXoutdent{-0.15\textwidth}
\newbox\lst@samplebox
\edef\LaTeXexamplefile{\jobname.tmp}
\lst@RequireAspects{writefile}
\lstnewenvironment{LaTeXexample}[1][example]{%
  \global\let\lst@intname\@empty
  \ifcsname LaTeXcode#1\endcsname
    \expandafter\let\expandafter\LaTeXcode
      \csname LaTeXcode#1\endcsname
    \expandafter\let\expandafter\LaTeXcodeend
      \csname LaTeXcode#1end\endcsname
  \else
    \PackageError{jawltxdoc}
      {Undefined example type `#1'}
      \@ehd
    \let\LaTeXcode\relax
    \let\LaTeXcodeend\relax
  \fi
  \LaTeXcode}
  {\lst@EndWriteFile
   \LaTeXcodeend}
\newcommand*{\LaTeXcodeexample}{%
  \setbox\lst@samplebox=\hbox\bgroup
  \LaTeXcodefloat}
\let\LaTeXcoderesultonly\LaTeXcodeexample
\newcommand*{\LaTeXcodeexampleend}{%
  \egroup
  \setlength\LaTeXwidth{\wd\lst@samplebox}%
  \begin{list}{}{%
    \setlength\itemindent{0pt}
    \setlength\leftmargin\LaTeXoutdent
    \setlength\rightmargin{0pt}}%
    \item
      \setlength\LaTeXoutdent{-0.15\textwidth}
      \begin{minipage}[c]{%
        \textwidth-\LaTeXwidth-\LaTeXoutdent-\LaTeXgap}
        \LaTeXcodefloatend
      \end{minipage}%
      \hfill
      \begin{minipage}[c]{\LaTeXwidth}%
        \hbox to\linewidth{\box\lst@samplebox\hss}%
      \end{minipage}%
  \end{list}}
\newcommand*{\LaTeXcodefloat}{%
  \setkeys{lst}{tabsize=4,gobble=3,breakindent=0pt,
    basicstyle=\small\ttfamily,basewidth=0.51em,
    keywordstyle=\color{blue}}%
  \lst@BeginAlsoWriteFile{\LaTeXexamplefile}}
\let\LaTeXcodenoexample\LaTeXcodefloat
\let\LaTeXcodenoexampleend\@empty
\newcommand*{\LaTeXcodefloatend}{%
  \MakePercentComment\catcode`\^^M=10\relax
  \small
  {\setkeys{lst}{SelectCharTable=\lst@ReplaceInput{\^\^I}%
    {\lst@ProcessTabulator}}%
    \leavevmode \input{\LaTeXexamplefile}}%
  \MakePercentIgnore}
\newcommand*{\LaTeXcoderesultonlyend}{\egroup\LaTeXcodefloatend}
\lstnewenvironment{BibTeXexample}{%
  \global\let\lst@intname\@empty
  \setbox\lst@samplebox=\hbox\bgroup
  \setkeys{lst}{tabsize=4,gobble=3,breakindent=0pt,
    basicstyle=\small\ttfamily,basewidth=0.51em,
    keywordstyle=\color{black}}
  \lst@BeginAlsoWriteFile{\LaTeXexamplefile}}
 {\lst@EndWriteFile
   \LaTeXcodeexampleend}
\newcommand*{\DescribeOption}{%
  \leavevmode\@bsphack\begingroup\MakePrivateLetters
  \Describe@Option}
\newcommand*{\Describe@Option}[1]{\endgroup
              \marginpar{\raggedleft\PrintDescribeEnv{#1}}%
              \SpecialOptionIndex{#1}\@esphack\ignorespaces}
\newcommand*{\SpecialOptionIndex}[1]{\@bsphack
    \index{#1\actualchar{\protect\ttfamily#1}
           (option)\encapchar usage}%
    \index{options:\levelchar#1\actualchar{\protect\ttfamily#1}%
      \encapchar usage}\@esphack}
\newcommand*{\indexopt}[1]{\DescribeOption{#1}\opt{#1}}
\newcommand*{\DescribeOptionInfo}[2]{%
  \DescribeOption{#1}%
  \opt{#1=\meta{#2}}\xspace}
\newcommand*{\ofixarg}[1]{%
  {\ttfamily[}%
  \ifmmode \expandafter \nfss@text \fi
  {%
    \meta@font@select
    \edef\meta@hyphen@restore{%
      \hyphenchar\the\font\the\hyphenchar\font}%
    \hyphenchar\font\m@ne
    \language\l@nohyphenation
    #1\/%
    \meta@hyphen@restore
    }%
    {\ttfamily]}}
\newcommand*{\pkg}[1]{\textsf{#1}}
\newcommand*{\currpkg}{\pkg{\jobname}\xspace}
\newcommand*{\opt}[1]{\texttt{#1}}
\newcommand*{\defaultopt}[1]{\opt{\textbf{#1}}}
\newcommand*{\file}[1]{\texttt{#1}}
\newcommand*{\ext}[1]{\file{.#1}}
\newcommand*{\latin}[1]{\emph{#1}}
\newcommand*{\etc}{%
  \@ifnextchar.
    {\latin{etc}}
    {\latin{etc}.\xspace}}
\newcommand*{\eg}{%
  \@ifnextchar.
    {\latin{e.g}}
    {\latin{e.g}.\xspace}}
\newcommand*{\ie}{%
  \@ifnextchar.
    {\latin{i.e}}
    {\latin{i.e}.\xspace}}
\newcommand*{\etal}{%
  \@ifnextchar.
    {\latin{et~al.}}
    {\latin{et~al}.\xspace}}
\newcommand*{\AMS}{{\protect\usefont{OMS}{cmsy}{m}{n}%
  A\kern-.1667em\lower.5ex\hbox{M}\kern-.125emS}}
\providecommand*{\eTeX}{\ensuremath{\varepsilon}-\TeX}
\DeclareRobustCommand*{\XeTeX}
  {X\kern-.125em\lower.5ex\hbox{\reflectbox{E}}\kern-.1667em\TeX}
\providecommand*{\CTAN}{\textsc{ctan}}
\@ifpackageloaded{etoolbox}
  {\patchcmd{\@addmarginpar}
    {\@latex@warning@no@line {Marginpar on page \thepage\space moved}}
    {\relax}{}{}}
  {}
\newcounter{argument}
\g@addto@macro\endmacro{\setcounter{argument}{0}}
\newcommand*\darg[1]{%
  \stepcounter{argument}%
  {\ttfamily\char`\#\theargument~:~}#1\par\noindent\ignorespaces}
\newcommand*\doarg[1]{%
  \stepcounter{argument}%
  {\ttfamily\makebox[0pt][r]{[}%
   \char`\#\theargument]:~}#1\par\noindent\ignorespaces}
%</jawltxdoc>
%\fi
