Debian Codegraph @

texmf-dist/source/latex/notes2bib/notes2bib.dtx

raw
1 % \iffalse meta-comment
2 %<*internal>
3 \iffalse
4 %</internal>
5 %<*readme>
6 notes2bib - Integrating notes into the bibliography
7 ===================================================
8
9 The `notes2bib` package defines a new type of note, bibnote,
10 which will always be added to the bibliography. The package
11 allows footnotes and endnotes to be moved into the bibliography
12 in the same way. The package can be used with natbib and
13 biblatex as well as plain LaTeX citations. Both sorted and
14 unsorted bibliography styles are supported.
15
16 Installation
17 ------------
18
19 The package is supplied in `.dtx` format and as a pre-extracted
20 `.zip` file, `notes2bib.tds.zip`. The later is most convenient
21 for most users: simply unzip this in your local `texmf`
22 directory. If you want to unpack the `.dtx` yourself, running
23 `tex notes2bib.dtx` will extract the package whereas `latex
24 notes2bib.dtx` will extract it and also typeset the
25 documentation.
26
27 The package requires LaTeX3 support as provided in the
28 `l3kernel` and `l3packages` bundles. Both of these are available
29 on [CTAN](http://www.ctan.org/) as ready-to-install `.zip`
30 files. Suitable versions are available in MiKTeX 2.9 and TeX
31 Live 2012 (updating the relevant packages online may be
32 necessary). LaTeX3, and so `notes2bib`, requires the e-TeX
33 extensions: these are available on all modern TeX systems.
34
35 Typesetting the documentation requires a number of packages in
36 addition to those needed to use the package. This is mainly
37 because of the number of demonstration items included in the
38 text. To compile the documentation without error, you will
39 need the packages:
40 - `csquotes`
41 - `helvet`
42 - `mathpazo`
43 - `listings`
44 %</readme>
45 %<*internal>
46 \fi
47 \def\nameofplainTeX{plain}
48 \ifx\fmtname\nameofplainTeX\else
49 \expandafter\begingroup
50 \fi
51 %</internal>
52 %<*install>
53 \input l3docstrip.tex
54 \keepsilent
55 \askforoverwritefalse
56 \preamble
57 ---------------------------------------------------------------
58 notes2bib --- Integrating notes into the bibliography
59 Maintained by Joseph Wright
60 E-mail: [email protected]
61 Released under the LaTeX Project Public License v1.3c or later
62 See http://www.latex-project.org/lppl.txt
63 ---------------------------------------------------------------
64
65 \endpreamble
66 \postamble
67
68 Copyright (C) 2007-2013,2016,2019 by
69 Joseph Wright <[email protected]>
70
71 It may be distributed and/or modified under the conditions of
72 the LaTeX Project Public License (LPPL), either version 1.3c of
73 this license or (at your option) any later version. The latest
74 version of this license is in the file:
75
76 http://www.latex-project.org/lppl.txt
77
78 This work is "maintained" (as per LPPL maintenance status) by
79 Joseph Wright.
80
81 This work consists of the file notes2bib.dtx
82 and the derived files notes2bib.ins,
83 notes2bib.pdf and
84 notes2bib.sty.
85
86 \endpostamble
87 \usedir{tex/latex/notes2bib}
88 \generate{
89 \file{\jobname.sty}{\from{\jobname.dtx}{package}}
90 }
91 %</install>
92 %<install>\endbatchfile
93 %<*internal>
94 \usedir{source/latex/notes2bib}
95 \generate{
96 \file{\jobname.ins}{\from{\jobname.dtx}{install}}
97 }
98 \nopreamble\nopostamble
99 \usedir{doc/latex/notes2bib}
100 \generate{
101 \file{README.txt}{\from{\jobname.dtx}{readme}}
102 }
103 \ifx\fmtname\nameofplainTeX
104 \expandafter\endbatchfile
105 \else
106 \expandafter\endgroup
107 \fi
108 %</internal>
109 %<*driver|package>
110 \RequirePackage{xparse}
111 %</driver|package>
112 %<*driver>
113 \documentclass[full]{l3doc}
114 \usepackage{csquotes,helvet,notes2bib}
115 \usepackage[final]{listings}
116 \usepackage[osf]{mathpazo}
117 \begin{document}
118 \DocInput{\jobname.dtx}
119 \end{document}
120 %</driver>
121 % \fi
122 %
123 % \makeatletter
124 %
125 % ^^A For creating examples with nice highlighting of code, and so
126 % ^^A on; based on the system used in the listings source (lstsample).
127 % \lst@RequireAspects{writefile}
128 % \newsavebox{\LaTeXdemo@box}
129 % \lstnewenvironment{LaTeXdemo}[1][code and example]{^^A
130 % \global\let\lst@intname\@empty
131 % \expandafter\let\expandafter\LaTeXdemo@end
132 % \csname LaTeXdemo@#1@end\endcsname
133 % \@nameuse{LaTeXdemo@#1}^^A
134 % }{^^A
135 % \LaTeXdemo@end
136 % }
137 % \newcommand*\LaTeXdemo@new[3]{^^A
138 % \expandafter\newcommand\expandafter*\expandafter
139 % {\csname LaTeXdemo@#1\endcsname}{#2}^^A
140 % \expandafter\newcommand\expandafter*\expandafter
141 % {\csname LaTeXdemo@#1@end\endcsname}{#3}^^A
142 % }
143 % \newcommand*\LaTeXdemo@common{^^A
144 % \setkeys{lst}{
145 % basicstyle = \small\ttfamily,
146 % basewidth = 0.51em,
147 % gobble = 4,
148 % keywordstyle = \color{blue},
149 % language = [LaTeX]{TeX},
150 % moretexcs = {
151 % bibnote ,
152 % bibnotemark ,
153 % bibnotesetup ,
154 % bibnotetext ,
155 % printbibnotes
156 % }
157 % }^^A
158 % }
159 % \newcommand*\LaTeXdemo@input{^^A
160 % \MakePercentComment
161 % \catcode`\^^M=10\relax
162 % \small
163 % \begingroup
164 % \setkeys{lst}{
165 % SelectCharTable=\lst@ReplaceInput{\^\^I}{\lst@ProcessTabulator}
166 % }^^A
167 % \leavevmode
168 % \input{\jobname.tmp}^^A
169 % \endgroup
170 % \MakePercentIgnore
171 % }
172 % \LaTeXdemo@new{code and example}{^^A
173 % \setbox\LaTeXdemo@box=\hbox\bgroup
174 % \lst@BeginAlsoWriteFile{\jobname.tmp}^^A
175 % \LaTeXdemo@common
176 % }{^^A
177 % \lst@EndWriteFile
178 % \egroup
179 % \begin{center}
180 % \ifdim\wd\LaTeXdemo@box>0.48\linewidth\relax
181 % \hbox to\linewidth{\box\LaTeXdemo@box\hss}^^A
182 % \begin{minipage}{\linewidth}
183 % \LaTeXdemo@input
184 % \end{minipage}
185 % \else
186 % \begin{minipage}{0.48\linewidth}
187 % \LaTeXdemo@input
188 % \end{minipage}
189 % \hfill
190 % \begin{minipage}{0.48\linewidth}
191 % \hbox to\linewidth{\box\LaTeXdemo@box\hss}^^A
192 % \end{minipage}
193 % \fi
194 % \end{center}
195 % }
196 % \LaTeXdemo@new{code only}{^^A
197 % \LaTeXdemo@common
198 % }{^^A
199 % }
200 %
201 % \providecommand*\opt[1]{\texttt{#1}}
202 %
203 % \makeatother
204 %
205 % \GetFileInfo{\jobname.sty}
206 %
207 % \changes{v1.0}{2007/08/30}{Initial public release}
208 % \changes{v2.0}{2009/09/24}{Second version of package using \pkg{expl3}
209 % internally}
210 %
211 % \title{^^A
212 % \pkg{notes2bib} --- Integrating notes into the bibliography^^A
213 % \thanks{^^A
214 % This file describes version \fileversion, last revised
215 % \filedate.^^A
216 % }^^A
217 % }
218 % \author{^^A
219 % Joseph Wright\thanks{E-mail: [email protected]}^^A
220 % }
221 % \date{Released \filedate}
222 %
223 % \maketitle
224 %
225 % \begin{abstract}
226 % The \pkg{notes2bib} package defines a new type of note, \cs{bibnote},
227 % which will always be added to the bibliography. The package allows
228 % footnotes and endnotes to be moved into the bibliography in the same
229 % way. The package can be used with \pkg{natbib} and \pkg{biblatex} as
230 % well as plain \LaTeX{} citations. Both sorted and unsorted bibliography
231 % styles are supported.
232 % \end{abstract}
233 %
234 % \tableofcontents
235 %
236 % \begin{documentation}
237 %
238 %\section{Introduction}
239 %
240 % In most subject areas, bibliographic citations and notes are
241 % separate entities. However, in some parts of the physical sciences
242 % (chemistry and physics) it is usual for references to the
243 % literature and notes to be given together in a \enquote{References and
244 % Notes} section. By default, this requires that \BibTeX{} users
245 % create a notes database for each document that they write. This is
246 % also true if complex references are needed, which cannot be handled
247 % automatically.
248 %
249 % The aim of the \pkg{notes2bib} package is to make integration of notes
250 % into the bibliography easy. Notes can be written as normal in the
251 % \LaTeX{} source, and are automatically moved to the bibliography. The
252 % package is compatible with sorted and unsorted bibliography styles.
253 % The package has been designed for use with numerical citations,
254 % although it will work with other systems.
255 %
256 % \section{Installation}
257 %
258 % \changes{v2.0b}{2010/01/08}{Better documentation for unpacking and
259 % installation}
260 % The package is supplied in \file{dtx} format and as a pre-extracted
261 % zip file, \file{\jobname.tds.zip}. The later is most convenient for
262 % most users: simply unzip this in your local texmf directory and
263 % run \texttt{texhash} to update the database of file locations. If
264 % you want to unpack the \file{dtx} yourself, running
265 % \texttt{tex \jobname.dtx} will extract the package whereas
266 % \texttt{latex \jobname.dtx} will extract it and also typeset the
267 % documentation.
268 %
269 % The package requires \LaTeX3 support as provided in the
270 % \pkg{l3kernel} and \pkg{l3packages} bundles. Both of these are available
271 % on \href{http://www.ctan.org}{\textsc{ctan}} as ready-to-install
272 % zip files. Suitable versions are available in MiKTeX 2.9 and
273 % TeX Live 2011 (updating the relevant packages online may be
274 % necessary). \LaTeX3, and so \pkg{notes2bib}, requires the e-\TeX{}
275 % extensions: these are available on all modern \TeX{} systems.
276 %
277 % Typesetting the documentation requires a number of packages in
278 % addition to those needed to use the package. This is mainly
279 % because of the number of demonstration items included in the text. To
280 % compile the documentation without error, you will need the packages:
281 % \begin{itemize}
282 % \item \pkg{csquotes}
283 % \item \pkg{helvet}
284 % \item \pkg{mathpazo}
285 % \item \pkg{listings}
286 % \end{itemize}
287 %
288 % \section{Using the package}
289 %
290 % The package should be loaded as normal in the preamble. The package
291 % recognises a number of options, which can also be used in teh document
292 % body. These are described later in this document.
293 % \begin{LaTeXdemo}[code only]
294 % \usepackage[<options>]{notes2bib}
295 % \end{LaTeXdemo}
296 %
297 % \DescribeMacro {\bibnote}
298 % \begin{syntax}
299 % \cs{bibnote} \oarg{name} \marg{text}
300 % \end{syntax}
301 % The basic function provided by \pkg{notes2bib} is the \cs{bibnote}
302 % macro. This is used in exactly the same way as footnotes, taking
303 % a mandatory argument, the \meta{text} of the note, and an optional
304 % argument, a \meta{name} for the note. The \meta{text} will be saved to
305 % a \BibTeX{} database file for later inclusion in the bibliography, and
306 % a reference will be placed in the body text at the position of the
307 % note.
308 % \begin{LaTeXdemo}
309 % A very simple example of a bibliography note
310 % \bibnote{Note for the first example}.
311 % \end{LaTeXdemo}
312 % When used without the optional \meta{name} argument, each note is
313 % given an automatically-generated name. If notes need to be referred to
314 % again in a document, the optional argument avoids the need to
315 % understand the detail of the automated system.
316 % \begin{LaTeXdemo}
317 % An example of a named note \bibnote[labelled]{Note for the second
318 % example}. The text can then continue and reference the note again
319 % later \bibnotemark[labelled].
320 % \end{LaTeXdemo}
321 %
322 % Verbatim text cannot be added directly to notes (in the same way that
323 % it cannot be used in footnotes). This means that the normal care
324 % will be needed with verbatim-like material.
325 % \begin{LaTeXdemo}
326 % The next note contains some awkward text
327 % \bibnote{Some \texttt{\textbackslash verb}-like output}.
328 % \end{LaTeXdemo}
329 %
330 % \DescribeMacro {\bibnotemark}
331 % \begin{syntax}
332 % \cs{bibnotemark} \oarg{name}
333 % \end{syntax}
334 % \DescribeMacro \bibnotetext
335 % \begin{syntax}
336 % \cs{bibnotetext} \oarg{name} \marg{text}
337 % \end{syntax}
338 % In common with \cs{footnote}, the basic \cs{bibnote} macro has
339 % companion macros \cs{bibnotemark} and \cs{bibnotetext}. In contrast
340 % to the \LaTeXe{} kernel \cs{footnote} macro, \cs{bibnote} is naturally
341 % robust and so \cs{bibnotemark} and \cs{bibnotetext} should be needed
342 % much more rarely than the \cs{footnote} versions.
343 %
344 % As with the related \cs{footnote} functions, \cs{bibnotemark} can be
345 % used alone or will recognise an optional argument giving the
346 % \meta{name} of the note. \cs{bibnotetext} also recognises the same
347 % optional \meta{name} argument as well as the mandatory \meta{text}.
348 % \begin{LaTeXdemo}
349 % A note without a name \bibnotemark{} can be given with some
350 % text \bibnotetext{Text for the fourth example}. Note can also be
351 % given names \bibnotemark[named], which are then used for the
352 % text\bibnotetext[named]{More text for the fourth example}.
353 % \end{LaTeXdemo}
354 %
355 % The \cs{bibnotemark} macro can also be used to cross-reference notes
356 % given earlier in the document. This method is preferred for
357 % referencing notes over using the \cs{cite} macro as
358 % \cs{bibnotemark} will cope correctly with out-of-order notes
359 % (see Section~\ref{out-of-order}).
360 % \begin{LaTeXdemo}
361 % See notes \bibnotemark[labelled] and \bibnotemark[named].
362 % \end{LaTeXdemo}
363 %
364 % \DescribeMacro {\printbibnotes}
365 % \begin{syntax}
366 % \cs{printbibnotes}
367 % \end{syntax}
368 % In most cases, there will be both notes and references in a document.
369 % The notes will be printed along with cited literature in the
370 % bibliography, produced using the \cs{bibliography} macro (or
371 % \cs{printbibliography} when using \pkg{biblatex}). However, it is
372 % possible to print only the notes in a document using the
373 % \cs{printbibnotes} macro.
374 % \bibliographystyle{unsrt}
375 % \begin{LaTeXdemo}
376 % \printbibnotes
377 % \end{LaTeXdemo}
378 %
379 % \DescribeMacro {\bibnotesetup}
380 % \begin{syntax}
381 % \cs{bibnotesetup} \marg{key--value list}
382 % \end{syntax}
383 % The behaviour of \pkg{notes2bib} can be altered by setting one or
384 % more package options. These are given as arguments to the
385 % \cs{bibnotesetup} function, which takes a \meta{key--value list} and
386 % uses this to set up the package. With the exception of the
387 % \opt{file-name} option, all of the settings can be altered in the
388 % preamble or the document body. The various package options are
389 % described below.
390 %
391 % \subsection{Auto-generated note names}
392 %
393 % \DescribeOption {note-name}
394 % When no explicit label is given for a note, one is generated
395 % automatically by the package. This consists of two parts, a name and
396 % a number. The text of the name can be set up using the
397 % \opt{note-name} option. This should not contain any spaces, as
398 % \BibTeX{} does not support records with spaces in names. The numerical
399 % part of the label is always generated automatically, and is the
400 % number of the note. The standard setting for \opt{note-name} is
401 % \opt{Note}.
402 %
403 % \DescribeOption {refsection-name}
404 % \DescribeOption {refsection-separator}
405 % When using \pkg{biblatex}'s \texttt{refsection} system, additional
406 % information is added to all labels from the second \texttt{refsection}
407 % onward (\emph{i.e.}~to all except \texttt{refsection} 0). This
408 % additional text is added before the note name, and always includes the
409 % \texttt{refsection} number. The settings \opt{refsection-name} and
410 % \opt{refsection-separator} determine the exact text added:
411 % \opt{refsection-name} comes before the \texttt{refsection} number and
412 % has default \opt{Refsection}, while \opt{refsection-separator} comes
413 % after it and has default value \opt{-}.
414 %
415 % \subsection{Underlying citation system}
416 %
417 % \DescribeOption {cite-function}
418 % \pkg{notes2bib} works by making the text of notes into citations.
419 % To do this, each note has to be \enquote{cited} in the appropriate
420 % place. \pkg{notes2bib} does not carry out any low-level citation
421 % itself: instead, a general citation macro is called. The nature of
422 % the function is set up using the \opt{cite-function} option,
423 % which should be set to a citation macro taking one mandatory
424 % argument. The initial setting is \opt{cite-function = \cs{cite}}.
425 %
426 % \subsection{Controlling the temporary database}
427 %
428 % \DescribeOption {file-name}
429 % The file name used for the database of notes is set using the
430 % \opt{file-name} option. The standard setting is to call the file
431 % |notes2bib-\jobname|, which may not be appropriate (for example, file
432 % names containing spaces may be problematic). Setting the
433 % \opt{file-name} option will alter the name of the file, with the
434 % file extension fixed as \file{bib}. In contrast to the other package
435 % options, this value can only be set in the preamble.
436 %
437 % \DescribeOption {record-type}
438 % Each note is written to the database as a standard \BibTeX{} record.
439 % The type of record created is set using the \opt{record-type}
440 % option. Usually, this will be set to \opt{misc}; \pkg{biblatex} v1.1a
441 % upwards provides the \opt{bibnote} record type, and this is used if
442 % available. Some \BibTeX{} styles have dedicated support for notes: if
443 % so, the appropriate value should be set for this option.
444 %
445 % \DescribeOption {note-field}
446 % The database field used to store the text of the note is available
447 % for change \emph{via} the \opt{note-field} option. The standard
448 % setting is \opt{note}.
449 %
450 % \DescribeOption {keyword-entry}
451 % Some styles (most notably \pkg{biblatex}) recognise keywords in
452 % \BibTeX{} records, stored in a \texttt{keywords} field. To allow the
453 % selective printing of notes, \pkg{notes2bib} includes a keyword in
454 % each note record. The keyword is set using the \opt{keyword-entry}
455 % option: the standard setting is \opt{note}.
456 %
457 % \subsection{Ordering notes in relation to citations}
458 % \label{out-of-order}
459 %
460 % \DescribeOption {placement}
461 % The standard method used by \pkg{notes2bib} places notes into the
462 % bibliography with no particular control of the relative position of
463 % notes with respect to citations. For unsorted bibliography styles,
464 % this will result in the notes appearing mixed in with citations.
465 % However, \pkg{notes2bib} can create notes so that they appear before
466 % or after citations, with both sorted an unsorted bibliography styles.
467 % This is controlled by the \opt{placement} option, which recognises
468 % the values \opt{before}, \opt{after} and \opt{mixed}. Setting
469 % \opt{placement = before} places notes before citations, with
470 % the \opt{after} setting forcing notes to appear after citation.
471 % The standard setting is \opt{placement = mixed}, which will result
472 % in mixing of notes and citations.
473 %
474 % When notes are placed in the bibliography without any change of order,
475 % it is possible to cross-reference to them using the standard \cs{cite}
476 % macro. However, when notes are out of the normal order this can lead
477 % to problems. These can be avoided by using the \cs{bibnotemark} macro
478 % to cross-reference notes. As this method will always work correctly,
479 % it is the recommended method for referencing notes under all
480 % circumstances.
481 %
482 % \DescribeOption {presort-before}
483 % \DescribeOption {presort-mixed}
484 % \DescribeOption {presort-after}
485 % \DescribeOption {sort-key-before}
486 % \DescribeOption {sort-key-mixed}
487 % \DescribeOption {sort-key-after}
488 % There are a number of different mechanisms used by \pkg{notes2bib} to
489 % achieve the desired ordering. Most standard \BibTeX{} styles recognise
490 % a \texttt{key} field, which can be used to override sorting by author
491 % or title. This is used by \pkg{notes2bib}, with the note name prefixed
492 % by a string to force the sort order. The appropriate strings are
493 % stored using the options \opt{sort-key-before}, \opt{sort-key-mixed}
494 % and \opt{sort-key-after}. These have standard settings
495 % \opt{aaa}, \opt{\meta{blank}} and \opt{zzz}, respectively. When the
496 % \pkg{biblatex} package is in use, a more powerful method is available
497 % to control sorting: the \texttt{presort} field. Data to be written
498 % to this field is set up using the \opt{presort-before},
499 % \opt{presort-mixed} and \opt{presort-after} options. Here, the
500 % standard values are \opt{ml}, \opt{mm} and \opt{mn}, respectively.
501 % These standard values will probably be appropriate in almost all
502 % cases.
503 %
504 % \subsection{Converting footnotes and endnotes}
505 %
506 % \DescribeOption {convert-endnotes}
507 % \DescribeOption {convert-footnotes}
508 % It is possible to convert both \cs{footnote} and \cs{endnote}
509 % entries in a file into \cs{bibnote} entries in a flexible manner.
510 % This behaviour is controlled using the \opt{convert-endnotes} and
511 % \opt{convert-footnotes} options; both recognise the values
512 % \opt{true} and \opt{false}. The original definitions for the
513 % appropriate macros are stored by \pkg{notes2bib}, and so it is
514 % possible to switch this behaviour on and off.
515 %
516 % \DescribeMacro {\thanks}
517 % The package is designed so that converting footnotes to bibliographic
518 % notes will not affect the \cs{thanks} macro. Thus the option
519 % \opt{convert-footnotes = true} can be given before \cs{maketitle}
520 % with no implication for and \cs{thanks}.
521 %
522 % \subsection{Using unsorted bibliography styles}
523 %
524 % \changes{v2.0b}{2010/01/08}{Improvements to details concerning
525 % \opt{use-sort-key} option}
526 % \DescribeOption {use-sort-key}
527 % Some bibliography styles (most notably those using the
528 % author--date system) may not work well with the settings
529 % of the package as supplied. Some of the data written by
530 % \pkg{notes2bib} can be misunderstood by styles such as
531 % \file{unsrtnat}. To suppress creating a \texttt{key} field in the
532 % database, the option \opt{use-sort-key} should be set to \opt{false}
533 % with these problematic styles. At the same time, it may be necessary
534 % to alter the \opt{note-name} option to a blank value.
535 % \begin{LaTeXdemo}[code only]
536 % \bibnotesetup{
537 % note-name = ,
538 % use-sort-key = false
539 % }
540 % \end{LaTeXdemo}
541 %
542 % \section{Data written to the \texttt{aux} file}
543 %
544 % \pkg{notes2bib} writes some information to the \file{aux} file, so
545 % that it is available between runs. The functions added to the
546 % file are not needed directly by the user, but are documented here
547 % for completeness. However, it may be necessary to worry about the
548 % \file{aux} file when splitting bibliographies.
549 %
550 % \DescribeMacro {\recordnotes}
551 % \begin{syntax}
552 % \cs{recordnotes}
553 % \end{syntax}
554 % When notes are placed out-of-order in in a document (using
555 % \opt{placement = before} or \opt{placement = after}) \pkg{notes2bib}
556 % has to record information in the current \file{aux} file. When using
557 % multiple bibliographies, this will not necessarily happen totally
558 % automatically. To force \pkg{notes2bib} to write the current
559 % out-of-order notes to the \file{aux} file, the macro
560 % \cs{recordnotes} is available. It should be used immediately
561 % before changing between auxiliary files.
562 %
563 % \DescribeMacro {\TotalNotes}
564 % \begin{syntax}
565 % \cs{TotalNotes} \marg{number}
566 % \end{syntax}
567 % Records the total number of auto-numbered notes in a run. This
568 % information is needed to check if zero-filling is needed for the
569 % numbers used.
570 %
571 % \DescribeMacro {\NotesAfterCitations}
572 % \begin{syntax}
573 % \cs{NotesAfterCitations} \marg{note-list}
574 % \end{syntax}
575 % \DescribeMacro {\NotesBeforeCitations}
576 % \begin{syntax}
577 % \cs{NotesBeforeCitations} \marg{note-list}
578 % \end{syntax}
579 % These functions record the notes which have been placed outside of
580 % the normal order by the package. This information is used to check
581 % for changes in note order between \LaTeX{} runs, so that the need for
582 % re-running \LaTeX{} and \BibTeX{} can be detected.
583 %
584 % \section{Notes for upgrading from version one}
585 %
586 % Documents which compile with version one of \pkg{notes2bib} should
587 % work equally well with version two. The package recognises the
588 % older options and user functions (for example \cs{niibsetup}). These
589 % are not documented here as all new documents should use the improved
590 % structures provided here. As some auxiliary file functions have been
591 % altered, it may be necessary to delete \file{aux} files for documents
592 % processed initially with older versions of \pkg{notes2bib}.
593 %
594 % \section{Code-level interfaces}
595 %
596 % In common with other \LaTeX3 modules, \pkg{notes2bib} makes functionality
597 % available at a code (\cs{ExplSyntaxOn}) level. End users \emph{do not}
598 % need to read this section!
599 %
600 % Programmers should note that \pkg{notes2bib} uses the module prefix
601 % \texttt{notestobib}, but that the options use the \pkg{l3keys} module
602 % name \texttt{notes2bib}.
603 %
604 % \begin{function}{\notestobib_write_note:nn, \notestobib_write_note:xn}
605 % \begin{syntax}
606 % \cs{notestobib_write_note:nn} \marg{note} \marg{text}
607 % \end{syntax}
608 % Adds the \meta{text} for the \meta{note} to the dynamic database
609 % created by \pkg{notes2bib}. Note that the \meta{note} name should be
610 % unique and that the writing operation is delayed by the package until
611 % either the end of the document or an explicit write request.
612 % \end{function}
613 %
614 % \end{documentation}
615 %
616 % \begin{implementation}
617 %
618 % \section{Implementation}
619 %
620 % \begin{macrocode}
621 %<*package>
622 % \end{macrocode}
623 %
624 % \begin{macrocode}
625 %<@@=notestobib>
626 % \end{macrocode}
627 %
628 % Version data to start with.
629 % \begin{macrocode}
630 \ProvidesExplPackage {notes2bib} {2019-09-28} {2.0m}
631 {Integrating notes into the bibliography}
632 \RequirePackage{l3keys2e}
633 % \end{macrocode}
634 %
635 % \subsection{Variables and constants}
636 %
637 % \begin{macro}{\c_@@_file_message_tl}
638 % A short piece of text that is added to the top of an auto-generated
639 % file. Setting this up as a constant means that it can be changed
640 % (for example for translation) if necessary.
641 % \begin{macrocode}
642 \tl_const:Nn \c_@@_file_message_tl
643 {
644 \iow_char:N \% ~
645 This~is~an~auxiliary~file~used~by~the~'notes2bib'~package.
646 \iow_newline:
647 \iow_char:N \% ~
648 This~file~may~safely~be~deleted.
649 \iow_newline:
650 \iow_char:N \% ~
651 It~will~be~recreated~as~required.
652 \iow_newline:
653 }
654 % \end{macrocode}
655 % \end{macro}
656 %
657 % \begin{macro}{\g_@@_after_clist, \g_@@_before_clist}
658 % Notes to be placed either before or after citations need to be tracked
659 % by the module. Simple comma lists will achieve this.
660 % \begin{macrocode}
661 \clist_new:N \g_@@_after_clist
662 \clist_new:N \g_@@_before_clist
663 % \end{macrocode}
664 % \end{macro}
665 %
666 % \begin{macro}{\g_@@_all_after_clist, \g_@@_all_before_clist}
667 % As notes after citations can be flushed, there is a need for a second
668 % list which is never emptied.
669 % \begin{macrocode}
670 \clist_new:N \g_@@_all_after_clist
671 \clist_new:N \g_@@_all_before_clist
672 % \end{macrocode}
673 % \end{macro}
674 %
675 % \begin{macro}{\g_@@_note_int}
676 % A counter for the automatically-created notes is needed. This is a
677 % global value (life will get very complicated if not).
678 % \begin{macrocode}
679 \int_new:N \g_@@_note_int
680 % \end{macrocode}
681 % \end{macro}
682 %
683 % \begin{macro}{\l_@@_presort_tl, \l_@@_sortkey_tl}
684 % The text used for sorting citations is stored here: it is never set
685 % directly, as it depends on the type of sorting taking place.
686 % \begin{macrocode}
687 \tl_new:N \l_@@_presort_tl
688 \tl_new:N \l_@@_sortkey_tl
689 % \end{macrocode}
690 % \end{macro}
691 %
692 % \begin{macro}{\g_@@_previous_after_clist, \g_@@_previous_before_clist}
693 % For comparison purposes, the lists of out-of-order notes from the
694 % previous \LaTeX{} run are needed.
695 % \begin{macrocode}
696 \clist_new:N \g_@@_previous_after_clist
697 \clist_new:N \g_@@_previous_before_clist
698 % \end{macrocode}
699 % \end{macro}
700 %
701 % \begin{macro}{\g_@@_previous_notes_int}
702 % The total number of notes created is needed, as this is used to see
703 % if any zero-padding is required for the numbers. Of course, for this
704 % to work there has to be a second \LaTeX{} run.
705 % \begin{macrocode}
706 \int_new:N \g_@@_previous_notes_int
707 % \end{macrocode}
708 % \end{macro}
709 %
710 % \begin{macro}{\g_@@_notes_tl}
711 % Used to collect up the note text for writing in a single block
712 % at the end of the document.
713 % \begin{macrocode}
714 \tl_new:N \g_@@_notes_tl
715 % \end{macrocode}
716 % \end{macro}
717 %
718 % \begin{macro}{\l_@@_sortkey_field_tl}
719 % The key for sorting is called \texttt{key} by standard \BibTeX{} and
720 % \texttt{sortkey} by \pkg{biblatex}. It keeps everything clearer if
721 % the appropriate name is stored in a token list. The value itself is
722 % set up later.
723 % \begin{macrocode}
724 \tl_new:N \l_@@_sortkey_field_tl
725 % \end{macrocode}
726 % \end{macro}
727 %
728 % \begin{macro}{\g_@@_total_notes_int}
729 % Tracks the total number of notes created, so that the module can tell
730 % if any have been used.
731 % \begin{macrocode}
732 \int_new:N \g_@@_total_notes_int
733 % \end{macrocode}
734 % \end{macro}
735 %
736 % \subsection{Control options}
737 %
738 % \begin{macro}{\@@_cite:w}
739 % The underlying function for citation starts off with no value:
740 % this is then set up by the key--value settings given next.
741 % \begin{macrocode}
742 \cs_new:Npn \@@_cite:w { }
743 % \end{macrocode}
744 % \end{macro}
745 %
746 % \begin{macro}{\g_@@_filename_tl}
747 % \begin{macro}
748 % {
749 % \l_@@_keyword_tl ,
750 % \l_@@_note_field_tl ,
751 % \l_@@_note_name_tl ,
752 % \l_@@_presort_after_tl ,
753 % \l_@@_presort_before_tl ,
754 % \l_@@_presort_mixed_tl ,
755 % \l_@@_record_type_tl ,
756 % \l_@@_refsection_name_tl,
757 % \l_@@_refsection_sep_tl ,
758 % \l_@@_record_type_tl ,
759 % \l_@@_sortkey_after_tl ,
760 % \l_@@_sortkey_before_tl ,
761 % \l_@@_sortkey_mixed_tl ,
762 % \l_@@_write_sortkey_bool
763 % }
764 % The various package options are created.
765 % \begin{macrocode}
766 \keys_define:nn { notes2bib }
767 {
768 cite-function .code:n =
769 { \AtBeginDocument { \cs_set_eq:NN \@@_cite:w #1 } } ,
770 file-name .tl_gset_x:N = \g_@@_filename_tl ,
771 convert-endnotes .choice: ,
772 convert-endnotes
773 / false .code:n =
774 { \AtBeginDocument { \@@_from_bibnote:n { endnote } } } ,
775 convert-endnotes
776 / true .code:n =
777 { \AtBeginDocument { \@@_to_bibnote:n { endnote } } } ,
778 convert-footnotes .choice: ,
779 convert-footnotes
780 / false .code:n =
781 { \AtBeginDocument { \@@_from_bibnote:n { footnote } } } ,
782 convert-footnotes
783 / true .code:n =
784 { \AtBeginDocument { \@@_to_bibnote:n { footnote } } } ,
785 keyword-entry .tl_set:N = \l_@@_keyword_tl ,
786 note-field .tl_set:N = \l_@@_note_field_tl ,
787 note-name .tl_set:N = \l_@@_note_name_tl ,
788 placement .choice: ,
789 placement
790 / after .code:n =
791 {
792 \cs_set_eq:NN \@@_mark_note:n \@@_mark_note_after:n
793 \tl_set_eq:NN \l_@@_presort_tl \l_@@_presort_after_tl
794 \tl_set_eq:NN \l_@@_sortkey_tl \l_@@_sortkey_after_tl
795 },
796 placement
797 / before .code:n =
798 {
799 \cs_set_eq:NN \@@_mark_note:n \@@_mark_note_before:n
800 \tl_set_eq:NN \l_@@_presort_tl \l_@@_presort_before_tl
801 \tl_set_eq:NN \l_@@_sortkey_tl \l_@@_sortkey_before_tl
802 },
803 placement
804 / mixed .code:n =
805 {
806 \cs_set_eq:NN \@@_mark_note:n \@@_mark_note_mixed:n
807 \tl_set_eq:NN \l_@@_presort_tl \l_@@_presort_mixed_tl
808 \tl_set_eq:NN \l_@@_sortkey_tl \l_@@_sortkey_mixed_tl
809 },
810 presort-after .tl_set:N = \l_@@_presort_after_tl ,
811 presort-before .tl_set:N = \l_@@_presort_before_tl ,
812 presort-mixed .tl_set:N = \l_@@_presort_mixed_tl ,
813 record-type .tl_set:N = \l_@@_record_type_tl ,
814 refsection-name .tl_set:N = \l_@@_refsection_name_tl ,
815 refsection-separator .tl_set:N = \l_@@_refsection_sep_tl ,
816 sort-key-after .tl_set:N = \l_@@_sortkey_before_tl ,
817 sort-key-before .tl_set:N = \l_@@_sortkey_after_tl ,
818 sort-key-mixed .tl_set:N = \l_@@_sortkey_mixed_tl ,
819 use-sort-key .bool_set:N = \l_@@_write_sortkey_bool
820 }
821 % \end{macrocode}
822 % \end{macro}
823 % \end{macro}
824 %
825 % Default values for the keys are set up. Many of these probably never
826 % change, but done in this way the package is much more flexible.
827 % \begin{macrocode}
828 \keys_set:nn { notes2bib }
829 {
830 cite-function = \cite ,
831 file-name = notes2bib-\jobname ,
832 keyword-entry = note ,
833 note-field = note ,
834 note-name = Note ,
835 presort-after = mn ,
836 presort-before = ml ,
837 presort-mixed = mm ,
838 record-type = misc ,
839 refsection-name = Refsection ,
840 refsection-separator = - ,
841 sort-key-after = zzz ,
842 sort-key-before = aaa ,
843 use-sort-key = true
844 }
845 % \end{macrocode}
846 %
847 % A few options need to be altered or deactivated at the start of
848 % the document.
849 % \begin{macrocode}
850 \AtBeginDocument
851 {
852 \@ifpackageloaded { biblatex }
853 {
854 \@ifpackagelater { biblatex } { 2011/01/08 }
855 {
856 \keys_set:nn { notes2bib } { record-type = bibnote }
857 \DeclareBibliographyDriver { bibnote }
858 {
859 \usebibmacro { begentry }
860 \printfield { note }
861 \setunit { \bibpagerefpunct }
862 \newblock
863 \usebibmacro { pageref }
864 \usebibmacro { finentry }
865 }
866 }
867 { }
868 }
869 { }
870 \keys_define:nn { notes2bib }
871 {
872 cite-function .code:n =
873 { \cs_set_eq:NN \@@_cite:w #1 } ,
874 file-name .code:n =
875 { \msg_info:nnn { notes2bib } { preamble-only } { file-name } } ,
876 convert-endnotes / false .code:n =
877 { \@@_from_bibnote:n { endnote } } ,
878 convert-endnotes / true .code:n =
879 { \@@_to_bibnote:n { endnote } } ,
880 convert-footnotes / false .code:n =
881 { \@@_from_bibnote:n { footnote } } ,
882 convert-footnotes / true .code:n =
883 { \@@_to_bibnote:n { footnote } }
884 }
885 }
886 \msg_new:nnn { notes2bib } { preamble-only }
887 { The~option~'#1'~can~only~be~used~in~the~preamble. }
888 % \end{macrocode}
889 %
890 % \subsection{Support for \pkg{biblatex} \texttt{refsection} system}
891 %
892 % \begin{macro}[EXP]{\@@_insert_refsection:}
893 % When using \pkg{biblatex}, it's possible that \texttt{refsection}s are
894 % in use. If so, to ensure that labels are always unique the
895 % \texttt{refsection} number is added to the label.
896 % \begin{macrocode}
897 \cs_new:Npn \@@_insert_refsection: { }
898 \AtBeginDocument
899 {
900 \@ifpackageloaded { biblatex }
901 {
902 \cs_set:Npn \@@_insert_refsection:
903 {
904 \int_compare:nNnT { \value { refsection } } > { 0 }
905 {
906 \tl_use:N \l_@@_refsection_name_tl
907 \arabic { refsection }
908 \tl_use:N \l_@@_refsection_sep_tl
909 }
910 }
911 }
912 { }
913 }
914 % \end{macrocode}
915 % \end{macro}
916 %
917 % \subsection{Options from version one}
918 %
919 % The new option names are preferred, but the old ones still need to
920 % work correctly.
921 % \begin{macrocode}
922 \keys_define:nn { notes2bib }
923 {
924 cite .code:n =
925 {
926 \use:x
927 { \keys_set:nn { notes2bib } { cite-function = \exp_not:c {#1} } }
928 } ,
929 debug .code:n = { } ,
930 endnotes .meta:n = { convert-footnotes = #1 } ,
931 etex .code:n = { } ,
932 field .meta:n = { note-field = #1 } ,
933 footnotes .meta:n = { convert-footnotes = #1 } ,
934 head .meta:n = { placement = before } ,
935 keyhead .meta:n = { sort-key-before = #1 } ,
936 keytail .meta:n = { sort-key-after = #1 } ,
937 keynone .meta:n = { sort-key-mixed = #1 } ,
938 keyword .meta:n = { keyword-entry = #1 } ,
939 log .meta:n = { } ,
940 name .meta:n = { note-name = #1 } ,
941 prefix .meta:n = { file-name = #1 \jobname } ,
942 presorthead .meta:n = { presort-before = #1 } ,
943 presorttail .meta:n = { presort-after = #1 } ,
944 presortnone .meta:n = { presort-mixed = #1 } ,
945 record .meta:n = { record-type = #1 } ,
946 sort .choice: ,
947 sort / head .meta:n = { placement = before } ,
948 sort / none .meta:n = { placement = after } ,
949 sort / tail .meta:n = { placement = mixed } ,
950 tail .meta:n = { placement = after } ,
951 writekey .meta:n = { use-sort-key = #1 }
952 }
953 % \end{macrocode}
954 %
955 % \subsection{Utility functions}
956 %
957 % \begin{macro}[EXP]{\@@_note_name:}
958 % When note citations are generated automatically, the text to indicate
959 % a note plus the number of the current note needs to be turned into
960 % something printable. The value tests here mean that if there are more
961 % than nine notes, notes 1--9 have the number padded to get proper
962 % sorting. This needs two passes, as the total number of notes is only
963 % available at the end of the \LaTeX{} run.
964 % \begin{macrocode}
965 \cs_new:Npn \@@_note_name:
966 {
967 \@@_insert_refsection:
968 \tl_use:N \l_@@_note_name_tl
969 \int_compare:nNnT \g_@@_previous_notes_int > 9
970 { \int_compare:nNnT \g_@@_note_int < { 10 } { 0 } }
971 \int_to_arabic:n { \g_@@_note_int }
972 }
973 % \end{macrocode}
974 % \end{macro}
975 %
976 % \begin{macro}{\@@_filesw:}
977 % Making sorting work means messing about with \cs{if@filesw}. The
978 % function created here is used to store the current status of the
979 % flag. As this is needed for saving \TeX{} true/false status, it's
980 % best to set it up from the start as a conditional.
981 % \begin{macrocode}
982 \cs_new_eq:NN \@@_filesw: \tex_iftrue:D
983 % \end{macrocode}
984 % \end{macro}
985 %
986 % \subsection{Marking notes in the text}
987 %
988 % \begin{macro}{\@@_mark_note:n, \@@_mark_note:x}
989 % The function to mark note positions is initially declared with no
990 % expansion. The real meaning will be set by the key--value setting,
991 % and depends on the placement of notes compared with real citations.
992 % \begin{macrocode}
993 \cs_new_protected:Npn \@@_mark_note:n #1 { }
994 \cs_generate_variant:Nn \@@_mark_note:n { x }
995 % \end{macrocode}
996 % \end{macro}
997 %
998 % \begin{macro}{\@@_mark_note_after:n}
999 % \begin{macro}[aux]{\@@_mark_note_after_aux:n}
1000 % For notes which come after citations, the entry is recorded and an
1001 % auxiliary is called. The nature of the second function is dependent
1002 % on the other packages loaded.
1003 % \begin{macrocode}
1004 \cs_new_protected:Npn \@@_mark_note_after:n #1
1005 {
1006 \int_gincr:N \g_@@_total_notes_int
1007 \clist_gput_right:Nx \g_@@_after_clist {#1}
1008 \@@_mark_note_after_aux:n {#1}
1009 }
1010 \cs_new_protected:Npn \@@_mark_note_after_aux:n #1 { }
1011 % \end{macrocode}
1012 % \end{macro}
1013 % \end{macro}
1014 %
1015 % \begin{macro}{\@@_mark_note_before:n}
1016 % Notes to appear before all citations are simple recorded, as they will
1017 % be set up on the next \LaTeX{} run.
1018 % \begin{macrocode}
1019 \cs_new_protected:Npn \@@_mark_note_before:n #1
1020 {
1021 \int_gincr:N \g_@@_total_notes_int
1022 \clist_gput_right:Nx \g_@@_before_clist {#1}
1023 \@@_cite:w {#1}
1024 }
1025 % \end{macrocode}
1026 % \end{macro}
1027 %
1028 % \begin{macro}{\@@_mark_note_mixed:n}
1029 % Mixed citations are very easy to handle: just use whatever cite
1030 % command is current.
1031 % \begin{macrocode}
1032 \cs_new_protected:Npn \@@_mark_note_mixed:n #1
1033 {
1034 \int_gincr:N \g_@@_total_notes_int
1035 \@@_cite:w {#1}
1036 }
1037 % \end{macrocode}
1038 % \end{macro}
1039 %
1040 % \subsection{Writing note text to the database}
1041 %
1042 % \begin{macro}[EXP]{\@@_write_field:nn, \@@_write_field:Vn}
1043 % To keep the auto-generated database readable, there needs to be some
1044 % formatting. This is provided by using a dedicated function to
1045 % write the various fields to it. Although the \texttt{V} variant is
1046 % not technically needed (writing expands everything), it helps to keep
1047 % the intention of the code here clearer.
1048 % \begin{macrocode}
1049 \cs_new:Npn \@@_write_field:nn #1#2
1050 {
1051 \c_space_tl \c_space_tl #1 \c_space_tl = \c_space_tl {#2} ,
1052 \iow_newline:
1053 }
1054 \cs_generate_variant:Nn \@@_write_field:nn { V }
1055 % \end{macrocode}
1056 % \end{macro}
1057 %
1058 % \begin{macro}{\notestobib_write_note:nn, \notestobib_write_note:xn}
1059 % \begin{macro}[aux]{\@@_write_note:nn}
1060 % The writing function takes two arguments: the name of the note, and
1061 % the text itself. There is a need to check on the \LaTeXe{} system to
1062 % turn off writing, with a hand-over so there is no problem with
1063 % balancing ifs.
1064 % \begin{macrocode}
1065 \cs_new_protected:Npn \notestobib_write_note:nn
1066 {
1067 \if@filesw
1068 \exp_after:wN \@@_write_note:nn
1069 \else:
1070 \exp_after:wN \use_none:nn
1071 \fi:
1072 }
1073 \cs_generate_variant:Nn \notestobib_write_note:nn { x }
1074 \cs_new_protected:Npn \@@_write_note:nn #1#2
1075 {
1076 \tl_gput_right:Nx \g_@@_notes_tl
1077 {
1078 @ \l_@@_record_type_tl
1079 {
1080 #1 , \iow_newline:
1081 \@@_write_field:Vn \l_@@_note_field_tl { \exp_not:n {#2} }
1082 \bool_if:NT \l_@@_write_sortkey_bool
1083 {
1084 \@@_write_field:Vn \l_@@_sortkey_field_tl
1085 { \l_@@_sortkey_tl #1 }
1086 }
1087 \@@_write_field:nn { keywords } { \l_@@_keyword_tl }
1088 \@@_write_field:nn { presort } { \l_@@_presort_tl }
1089 }
1090 \iow_newline:
1091 \iow_newline:
1092 }
1093 }
1094 % \end{macrocode}
1095
1096 % \end{macro}
1097 % \end{macro}
1098 %
1099 % \subsection{Handling out of order notes}
1100 %
1101 % \begin{macro}{\@@_record_notes:}
1102 % \begin{macro}[aux]{\@@_flush_notes_aux:}
1103 % Notes after citations are not written to the \file{aux} file when
1104 % given, but are held in a queue. This is flushed here, which means
1105 % actually doing the citation and also recording the notes so they
1106 % are available in the next \LaTeX{} run. The list is also transferred
1107 % to a secondary one, which is used for comparison purposes right at the
1108 % end of the document.
1109 % \begin{macrocode}
1110 \cs_new_protected:Npn \@@_record_notes:
1111 {
1112 \if@filesw
1113 \exp_after:wN \@@_flush_notes_aux:
1114 \fi
1115 }
1116 \cs_new_protected:Npn \@@_flush_notes_aux:
1117 {
1118 \clist_if_empty:NF \g_@@_before_clist
1119 {
1120 \iow_now:Nx \@auxout
1121 { \NotesBeforeCitations { \exp_not:V \g_@@_before_clist } }
1122 \clist_gput_right:NV \g_@@_all_before_clist \g_@@_before_clist
1123 \clist_gclear:N \g_@@_before_clist
1124 }
1125 \clist_if_empty:NF \g_@@_after_clist
1126 {
1127 \iow_now:Nx \@auxout
1128 { \NotesAfterCitations { \exp_not:V \g_@@_after_clist } }
1129 \exp_args:NV \nocite \g_@@_after_clist
1130 \clist_gput_right:NV \g_@@_all_after_clist \g_@@_after_clist
1131 \clist_gclear:N \g_@@_after_clist
1132 }
1133 }
1134 % \end{macrocode}
1135 % \end{macro}
1136 % \end{macro}
1137 %
1138 % \subsection{Interchanging note types}
1139 %
1140 % \begin{macro}{\@@_to_bibnote:n}
1141 % Converting other notes to bibliography notes is simple: just set
1142 % them equal.
1143 % \begin{macrocode}
1144 \cs_new_protected:Npn \@@_to_bibnote:n #1
1145 {
1146 \cs_set_eq:cN {#1} \bibnote
1147 \cs_set_eq:cN { #1 mark } \bibnotemark
1148 \cs_set_eq:cN { #1 text } \bibnotetext
1149 }
1150 % \end{macrocode}
1151 % \end{macro}
1152 %
1153 % \begin{macro}{\@@_from_bibnote:n}
1154 % The reverse process needs the original definitions, which are saved
1155 % by the module for later recovery.
1156 % \begin{macrocode}
1157 \cs_new_protected:Npn \@@_from_bibnote:n #1
1158 {
1159 \cs_set_eq:cc {#1} { @@_ #1 :w }
1160 \cs_set_eq:cc { #1 mark } { @@_ #1 mark:w }
1161 \cs_set_eq:cc { #1 text } { @@_ #1 text:w }
1162 }
1163 % \end{macrocode}
1164 % \end{macro}
1165 %
1166 % \begin{macro}
1167 % {
1168 % \@@_endnote:w ,
1169 % \@@_endnotemark:w ,
1170 % \@@_endnotetext:w ,
1171 % \@@_footnote:w ,
1172 % \@@_footnotemark:w,
1173 % \@@_footnotetext:w
1174 % }
1175 % At the start of the document, the definitions for endnotes and
1176 % footnotes are saved so that footnotes and endnotes can be turned into
1177 % bibliography notes and back again.
1178 % \begin{macrocode}
1179 \AtBeginDocument
1180 {
1181 \cs_new_eq:NN \@@_endnote:w \endnote
1182 \cs_new_eq:NN \@@_endnotemark:w \endnotemark
1183 \cs_new_eq:NN \@@_endnotetext:w \endnotetext
1184 \cs_new_eq:NN \@@_footnote:w \footnote
1185 \cs_new_eq:NN \@@_footnotemark:w \footnotemark
1186 \cs_new_eq:NN \@@_footnotetext:w \footnotetext
1187 }
1188 % \end{macrocode}
1189 % \end{macro}
1190 %
1191 % \subsection{Package-dependent code}
1192 %
1193 % \begin{macro}{\@@_create_print_notes:, \@@_print_notes:}
1194 % The method for printing notes depends on whether \pkg{biblatex} is
1195 % in use. If it is, then a selective call to \cs{printbibliography} is
1196 % made. Otherwise, the original \cs{bibliography} function is called,
1197 % and passed the name of the notes file.
1198 % \begin{macrocode}
1199 \AtBeginDocument
1200 {
1201 \@ifpackageloaded { biblatex }
1202 {
1203 \cs_new_protected:Npn \@@_print_notes:
1204 {
1205 \cs_set:Npx \@@_create_print_notes:
1206 {
1207 \printbibliography
1208 [ keyword = \exp_not:V \l_@@_keyword_tl ]
1209 }
1210 \@@_create_print_notes:
1211 }
1212 }
1213 {
1214 \cs_new_protected:Npn \@@_print_notes:
1215 { \exp_args:NV \@@_bibliography:n \g_@@_filename_tl }
1216 }
1217 }
1218 \cs_new_protected:Npn \@@_create_print_notes: { }
1219 % \end{macrocode}
1220 % \end{macro}
1221 %
1222 % \begin{macro}{\@@_attach_bibliography:}
1223 % \begin{macro}{\bibliography}
1224 % \begin{macro}{\@@_bibliography:n}
1225 % Getting the database created here to be scanned by \BibTeX{} is
1226 % dependant on whether \pkg{biblatex} is being used. If it is, and it is
1227 % already loaded, then the data can be added now. On the other hand, if
1228 % it is not already loaded a check is made at the end of the preamble.
1229 % The \cs{bibliography} function has to be patched if \pkg{biblatex} is
1230 % not in use.
1231 % \begin{macrocode}
1232 \cs_new_protected:Npn \@@_attach_bibliography:
1233 {
1234 \@ifpackageloaded { biblatex }
1235 {
1236 \@ifpackagelater { biblatex } { 2011/01/08 }
1237 {
1238 \@ifpackagelater { biblatex } { 2011/02/12 }
1239 { \exp_args:No \addglobalbib { \g_@@_filename_tl .bib } }
1240 { \exp_args:NNV \bibliography * \g_@@_filename_tl }
1241 }
1242 { \exp_args:NV \bibliography \g_@@_filename_tl }
1243 }
1244 {
1245 \cs_new_eq:NN \@@_bibliography:n \bibliography
1246 \RenewDocumentCommand \bibliography { m }
1247 {
1248 \int_compare:nNnTF \g_@@_total_notes_int = 0
1249 { \@@_bibliography:n {##1} }
1250 {
1251 \cs_set:Npx \@@_attach_bibliography:
1252 {
1253 \exp_not:N \@@_bibliography:n
1254 { \exp_not:n {##1} , \exp_not:V \g_@@_filename_tl }
1255 }
1256 \@@_attach_bibliography:
1257 }
1258 }
1259 }
1260 }
1261 \@ifpackageloaded { biblatex }
1262 {
1263 \@ifpackagelater { biblatex } { 2011/01/08 }
1264 {
1265 \@ifpackagelater { biblatex } { 2011/02/12 }
1266 { \exp_args:No \addglobalbib { \g_@@_filename_tl .bib } }
1267 { \exp_args:NNV \bibliography * \g_@@_filename_tl }
1268 }
1269 { \exp_args:NV \bibliography \g_@@_filename_tl }
1270 }
1271 { \AtBeginDocument { \@@_attach_bibliography: } }
1272 % \end{macrocode}
1273 % \end{macro}
1274 % \end{macro}
1275 % \end{macro}
1276 %
1277 % \pkg{biblatex} uses the name \texttt{sortkey} for a key to sort by,
1278 % whereas other style call the same concept \texttt{key}.
1279 % \begin{macrocode}
1280 \AtBeginDocument
1281 {
1282 \@ifpackageloaded { biblatex }
1283 { \tl_set:Nn \l_@@_sortkey_field_tl { sortkey } }
1284 { \tl_set:Nn \l_@@_sortkey_field_tl { key } }
1285 }
1286 % \end{macrocode}
1287 %
1288 % To get the correct ordering for notes, writing to the \file{aux} file
1289 % needs to be turned on and off. With \pkg{biblatex}, there is a
1290 % convenient hook for this. Otherwise, everything has to happen after
1291 % the citation command.
1292 % \begin{macrocode}
1293 \AtBeginDocument
1294 {
1295 \@ifpackageloaded { biblatex }
1296 {
1297 \cs_set_protected:Npn \@@_mark_note_after_aux:n #1
1298 {
1299 \AtNextCite { \@fileswfalse }
1300 \@@_cite:w {#1}
1301 }
1302 }
1303 {
1304 \cs_set_protected:Npn \@@_mark_note_after_aux:n #1
1305 {
1306 \cs_set_eq:NN \@@_filesw: \if@filesw
1307 \@fileswfalse
1308 \@@_cite:w {#1}
1309 \cs_set_eq:NN \if@filesw \@@_filesw:
1310 }
1311 }
1312 }
1313 % \end{macrocode}
1314 %
1315 % \begin{macro}{\@@_aux_hook:}
1316 % If the \pkg{cite} package is loaded, then there is a hook to
1317 % reset the \file{aux} file after the citation. This means that moving
1318 % punctuation will still work under these circumstances. However, the
1319 % way \pkg{cite} sets things up is a little complicated. The link needs
1320 % to be made at the end of the \cs{document} macro.
1321 % \begin{macrocode}
1322 \AtBeginDocument
1323 {
1324 \@ifpackageloaded { cite }
1325 {
1326 \cs_set_protected:Npn \@@_mark_note_after_aux:n #1
1327 {
1328 \cs_set_eq:NN \@@_filesw: \if@filesw
1329 \@fileswfalse
1330 \cs_set:Npn \@@_aux_hook:
1331 {
1332 \cs_set_eq:NN \if@filesw \@@_filesw:
1333 \cs_set:Npn \@@_aux_hook: { }
1334 }
1335 \@@_cite:w {#1}
1336 }
1337 \cs_new:Npn \@@_aux_hook: { }
1338 \tl_gput_right:Nn \g_@@_document_hook_tl
1339 {
1340 \cs_if_exist:NF \@restore@auxhandle
1341 { \tl_new:N \@restore@auxhandle }
1342 \tl_put_right:Nn \@restore@auxhandle { \@@_aux_hook: }
1343 }
1344 }
1345 { }
1346 }
1347 % \end{macrocode}
1348 % \end{macro}
1349 %
1350 %\subsection{User functions}
1351 %
1352 % \begin{macro}{\bibnote}
1353 % \begin{macro}{\@@_bibnote:nn, \@@_bibnote:xn}
1354 % Creating a not from scratch is a multi-step operation. First, check
1355 % if a label was given by the user. If it was not, then one is created
1356 % by incrementing the automatic number and fully expanding
1357 % \cs{@@_note_name:}. The second phase is to create the note. The text
1358 % is dealt with first as this leaves the note-marking code at the end
1359 % of the function (needed if punctuation is to be moved).
1360 % \begin{macrocode}
1361 \NewDocumentCommand \bibnote { o +m }
1362 {
1363 \IfNoValueTF {#1}
1364 {
1365 \int_gincr:N \g_@@_note_int
1366 \@@_bibnote:xn { \@@_note_name: } {#2}
1367 }
1368 { \@@_bibnote:xn { \@@_insert_refsection: #1 } {#2} }
1369 }
1370 \cs_new_protected:Npn \@@_bibnote:nn #1#2
1371 {
1372 \notestobib_write_note:nn {#1} {#2}
1373 \@@_mark_note:n {#1}
1374 }
1375 \cs_generate_variant:Nn \@@_bibnote:nn { x }
1376 % \end{macrocode}
1377 % \end{macro}
1378 % \end{macro}
1379 %
1380 % \begin{macro}{\bibnotemark}
1381 % Simply marking a note has similar requirements, but as there is only
1382 % a single internal function to call the code is less complex.
1383 % \begin{macrocode}
1384 \NewDocumentCommand \bibnotemark { o }
1385 {
1386 \IfNoValueTF {#1}
1387 {
1388 \int_gincr:N \g_@@_note_int
1389 \@@_mark_note:x { \@@_note_name: }
1390 }
1391 { \@@_mark_note:x { \@@_insert_refsection: #1 } }
1392 }
1393 % \end{macrocode}
1394 % \end{macro}
1395 %
1396 % \begin{macro}{\bibnotetext}
1397 % As text for a note uses the same number as the preceding mark,
1398 % things are slightly less complex here. The basic \texttt{o} argument
1399 % type is used as this means that full expansion of the note name can
1400 % take place \enquote{early}.
1401 % \begin{macrocode}
1402 \NewDocumentCommand \bibnotetext { o +m }
1403 {
1404 \IfNoValueTF {#1}
1405 { \notestobib_write_note:xn { \@@_note_name: } {#2} }
1406 { \notestobib_write_note:xn { \@@_insert_refsection: #1 } {#2} }
1407 }
1408 % \end{macrocode}
1409 % \end{macro}
1410 %
1411 % \begin{macro}{\recordnotes}
1412 % A direct call to the internal function: no arguments are needed.
1413 % \begin{macrocode}
1414 \NewDocumentCommand \recordnotes { }
1415 { \@@_record_notes: }
1416 % \end{macrocode}
1417 % \end{macro}
1418 %
1419 % \begin{macro}{\bibnotesetup}
1420 % A user set up function.
1421 % \begin{macrocode}
1422 \NewDocumentCommand \bibnotesetup { m }
1423 { \keys_set:nn { notes2bib } {#1} }
1424 % \end{macrocode}
1425 % \end{macro}
1426 %
1427 % \begin{macro}{\printbibnotes}
1428 % A direct translation for the internal function.
1429 % \begin{macrocode}
1430 \NewDocumentCommand \printbibnotes { }
1431 { \@@_print_notes: }
1432 % \end{macrocode}
1433 % \end{macro}
1434 %
1435 % \begin{macro}{\citenote}
1436 % \begin{macro}{\flushnotestack}
1437 % \begin{macro}{\niibsetup}
1438 % A few functions which are depreciated in version two.
1439 % \begin{macrocode}
1440 \NewDocumentCommand \citenote { m }
1441 { \@@_mark_note:n {#1} }
1442 \cs_new_eq:NN \flushnotestack \recordnotes
1443 \cs_new_eq:NN \niibsetup \bibnotesetup
1444 % \end{macrocode}
1445 % \end{macro}
1446 % \end{macro}
1447 % \end{macro}
1448 %
1449 % \subsection{Auxiliary file functions}
1450 %
1451 % \pkg{notes2bib} needs to write information to the \file{aux} file
1452 % for carrying information between runs. Rather than give them cryptic
1453 % names, they have long design-level ones. They are also declared
1454 % as protected functions so that writing to the \file{aux} file is
1455 % easier.
1456 %
1457 % \begin{macro}{\NotesAfterCitations}
1458 % \begin{macro}{\NotesBeforeCitations}
1459 % The functions to pass information on out-of-order notes from one
1460 % run to another both add the information to the appropriate lists.
1461 % For notes before citations, there is also a need to put the
1462 % \cs{citation} calls into the \file{aux} file at the correct stage.
1463 % \begin{macrocode}
1464 \cs_new_protected:Npn \NotesAfterCitations #1
1465 { \clist_gput_right:Nn \g_@@_previous_after_clist {#1} }
1466 \cs_new_protected:Npn \NotesBeforeCitations #1
1467 {
1468 \clist_gput_right:Nn \g_@@_previous_after_clist {#1}
1469 \tl_gput_right:Nn \g_@@_document_hook_tl { \nocite {#1} }
1470 }
1471 % \end{macrocode}
1472 % \end{macro}
1473 % \end{macro}
1474 %
1475 % \begin{macro}{\TotalNotes}
1476 % This function allows the total number of bibliography notes to be
1477 % carried forward from one run to the next.
1478 % \begin{macrocode}
1479 \cs_new_protected:Npn \TotalNotes #1
1480 { \int_gset:Nn \g_@@_previous_notes_int {#1} }
1481 % \end{macrocode}
1482 % \end{macro}
1483 %
1484 % \subsection{Code at the start of the document}
1485 %
1486 % \begin{macro}{\g_@@_document_hook_tl}
1487 % \pkg{notes2bib} needs to be able to carry out a few tasks right at the
1488 % beginning of the document. To do that, a hook is added to the
1489 % \cs{document} macro, which can be treated as a token list variable
1490 % as it has no arguments.
1491 % \begin{macrocode}
1492 \tl_gput_right:Nn \document { \g_@@_document_hook_tl }
1493 \tl_new:N \g_@@_document_hook_tl
1494 % \end{macrocode}
1495 % \end{macro}
1496 %
1497 % \subsection{Code at end of the document}
1498 %
1499 % There are a few tasks which have to be carried out a the end of
1500 % the \LaTeX{} run, so that data is available for the next run.
1501 %
1502 % First, all of the notes need to be added to the auxiliary file.
1503 % This ensures that the comparisons made in the next step make sense.
1504 % \begin{macrocode}
1505 \AtEndDocument { \@@_record_notes: }
1506 % \end{macrocode}
1507 %
1508 % The list of out-of-order notes from the current run needs to match
1509 % that from the previous run. If not, then there is a need to re-run
1510 % \LaTeX{}.
1511 % \begin{macrocode}
1512 \AtEndDocument
1513 {
1514 \tl_if_eq:NNTF \g_@@_all_before_clist \g_@@_previous_before_clist
1515 {
1516 \tl_if_eq:NNF \g_@@_all_after_clist \g_@@_previous_after_clist
1517 { \msg_info:nn { notes2bib } { rerun } }
1518 }
1519 { \msg_info:nn { notes2bib } { rerun } }
1520 }
1521 \msg_new:nnn { notes2bib } { rerun }
1522 {
1523 To~get~notes~in~the~correct~order,~please~run: \\%
1524 \c_space_tl 1)~LaTeX \\
1525 \c_space_tl 2)~BibTeX \\
1526 \c_space_tl 3)~LaTeX
1527 }
1528 % \end{macrocode}
1529 %
1530 % \begin{macro}{\@@_write_note_file:}
1531 % \begin{macro}{\g_@@_file_iow}
1532 % The notes themselves are now written in one block: this avoids
1533 % using up a stream for any longer than necessary.
1534 % \begin{macrocode}
1535 \AtEndDocument
1536 {
1537 \if@filesw
1538 \exp_after:wN \@@_write_note_file:
1539 \fi:
1540 }
1541 \cs_new_protected:Npn \@@_write_note_file:
1542 {
1543 \tl_if_empty:NF \g_@@_notes_tl
1544 {
1545 \iow_open:Nn \g_@@_file_iow { \g_@@_filename_tl .bib }
1546 \iow_now:Nx \g_@@_file_iow { \c_@@_file_message_tl }
1547 \iow_now:Nx \g_@@_file_iow { \exp_not:V \g_@@_notes_tl }
1548 \iow_close:N \g_@@_file_iow
1549 }
1550 }
1551 \iow_new:N \g_@@_file_iow
1552 % \end{macrocode}
1553 % \end{macro}
1554 % \end{macro}
1555 %
1556 % The total number of bibliography notes from the current run is
1557 % recorded to the \file{aux} file. This will then be picked up in the
1558 % \begin{macrocode}
1559 \AtEndDocument
1560 {
1561 \int_compare:nNnT \g_@@_note_int > 0
1562 {
1563 \iow_now:Nx \@auxout
1564 { \TotalNotes { \int_to_arabic:n { \g_@@_note_int } } }
1565 }
1566 }
1567 % \end{macrocode}
1568 %
1569 % \subsection{Tidying up}
1570 %
1571 % \begin{macro}{\thanks}
1572 % The \cs{thanks} macro has to be replaced by one that uses the original
1573 % \cs{footnotemark} and \cs{footnotetext} under all circumstances. This
1574 % is the kernel definition modified: if an alternative version is in use
1575 % things may go wrong.
1576 % \begin{macrocode}
1577 \cs_set:Npn \thanks #1
1578 {
1579 \@@_footnotemark:w
1580 \protected@xdef \@thanks
1581 {
1582 \@thanks
1583 \protect \@@_footnotetext:w [ \the \c@footnote ] {#1}
1584 }
1585 }
1586 % \end{macrocode}
1587 % \end{macro}
1588 %
1589 % The final job is to set note placement: this is done here as various
1590 % parts of the module need to be in place for this to work correctly.
1591 % \begin{macrocode}
1592 \keys_set:nn { notes2bib } { placement = mixed }
1593 % \end{macrocode}
1594 %
1595 % Any load time options are processed.
1596 % \begin{macrocode}
1597 \ProcessKeysOptions { notes2bib }
1598 % \end{macrocode}
1599 %
1600 % \begin{macrocode}
1601 %</package>
1602 % \end{macrocode}
1603 %
1604 % \end{implementation}
1605 %
1606 % \PrintChanges
1607 % \PrintIndex