Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2012 by Enrico Gregorio
4 % <Enrico dot Gregorio at univr dot it>
5 % -------------------------------------------------------
6 %
7 % This work may be distributed and/or modified under the
8 % conditions of the LaTeX Project Public License, either
9 % version 1.3c of this license or (at your option) any
10 % later version. The latest version of this license is in
11 % http://www.latex-project.org/lppl.txt
12 % and version 1.3 or later is part of all distributions
13 % of LaTeX version 2005/12/01 or later.
14 %
15 % This work has the LPPL maintenance status `maintained'.
16 %
17 % The Current Maintainer of this work is Enrico Gregorio.
18 %
19 % This work consists of the files
20 % usebib.dtx
21 % usebib.ins
22 % and the derived file usebib.sty.
23 %
24 % \fi
25 %
26 % \iffalse
27 %<*driver>
28 \ProvidesFile{usebib.dtx}
29 %</driver>
30 %<package>\NeedsTeXFormat{LaTeX2e}[2008/04/05]
31 %<package>\ProvidesPackage{usebib}
32 %<*package>
33 [2012/04/13 v1.0a Reusing bib files]
34 %</package>
35 %
36 %<*driver>
37 \documentclass{ltxdoc}
38 \providecommand{\BibTeX}{\textsc{Bib}\!\TeX}
39 \EnableCrossrefs
40 \CodelineIndex
41 \RecordChanges
42 \begin{document}
43 \DocInput{usebib.dtx}
44 \PrintChanges
45 \PrintIndex
46 \end{document}
47 %</driver>
48 % \fi
49 %
50 % \CheckSum{128}
51 %
52 % \CharacterTable
53 % {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
54 % 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
55 % Digits \0\1\2\3\4\5\6\7\8\9
56 % Exclamation \! Double quote \" Hash (number) \#
57 % Dollar \$ Percent \% Ampersand \&
58 % Acute accent \' Left paren \( Right paren \)
59 % Asterisk \* Plus \+ Comma \,
60 % Minus \- Point \. Solidus \/
61 % Colon \: Semicolon \; Less than \<
62 % Equals \= Greater than \> Question mark \?
63 % Commercial at \@ Left bracket \[ Backslash \\
64 % Right bracket \] Circumflex \^ Underscore \_
65 % Grave accent \` Left brace \{ Vertical bar \|
66 % Right brace \} Tilde \~}
67 %
68 %
69 % \changes{v1.0a}{2012/04/13}{Corrected macro names in the doc}
70 % \changes{v1.0}{2012/03/17}{Initial version}
71 %
72 % \GetFileInfo{usebib.dtx}
73 %
74 % \DoNotIndex{\newcommand,\newenvironment,\!,\@empty,\@gobble,\@gobbletwo}
75 % \DoNotIndex{\@ifpackageloaded,\@ifpackagewith,\@ifundefined,\@namedef}
76 % \DoNotIndex{\@nil,\@onlypreamble,\@tempa,\@tempb,\@tempswafalse,\def}
77 % \DoNotIndex{\@tempswatrue,\^,\-,\active,\begingroup,\catcode,\@car,\@cdr}
78 % \DoNotIndex{\edef,\else,\endgroup,\endinput,\expandafter,\fi,\if}
79 % \DoNotIndex{\if@tempswa,\ifcase,\ifnum,\ifx,\lccode,\let,\lowercase}
80 % \DoNotIndex{\MessageBreak,\next,\number,\numexpr,\or,\PackageError}
81 % \DoNotIndex{\PackageWarning,\PackageWarningNoLine,\strip@prefix,\@@end}
82 % \DoNotIndex{\relax,\space,\string,\DeclareOption,\ProcessOptions}
83 % \DoNotIndex{\meaning,\ifdefined,\csname,\chardef,\endcsname,\protect}
84 % \DoNotIndex{\input,\RequirePackage,\global,\ifcsname,\makeatother}
85 % \DoNotIndex{\@makeother,\the,\toks@}
86 %
87 % \title{The \textsf{usebib} package\thanks{This document
88 % corresponds to \textsf{newunicodechar}~\fileversion, dated \filedate.}}
89 % \author{Enrico Gregorio \\ \texttt{Enrico dot Gregorio at univr dot it}}
90 %
91 % \maketitle
92 %
93 % \section{Introduction}
94 %
95 % With \textsf{biblatex} it's possible to use any element of a
96 % bibliographic item in a document. With packages such as
97 % \textsf{natbib} or simply with the native \BibTeX{} support one
98 % can't refer directly to the title of a cited article or book without
99 % directly typing it in.
100 %
101 % This package allows this by reading in a special environment a
102 % |.bib| file. It should be considered no more than a devious usage of
103 % a |.bib| file, to be honest. But it works.
104 %
105 % \section{Usage}
106 %
107 % The package \emph{must} be loaded after \textsf{hyperref}, but it
108 % doesn't require it. It depends only on \textsf{url} and
109 % \textsf{keyval}, which should be present on every \TeX{}
110 % distribution.
111 %
112 % \subsection{Preamble commands}
113 %
114 % \DescribeMacro{\bibinput}
115 % The main command is |\bibinput|, which accepts the name of a |.bib|
116 % file (\emph{without} the extension) and may be repeated any number
117 % of times to read all the necessary files.\footnote{Making it
118 % dependent on the \texttt{\string\bibliography} command would be too
119 % difficult.} The command should appear only in the preamble.
120 %
121 % \DescribeMacro{\newbibfield}
122 % With the macro |\newbibfield|, to be issued \emph{before}
123 % |\bibinput|, it's possible to declare new known fields, for example
124 %\begin{verbatim}
125 % \newbibfield{annotation}
126 %\end{verbatim}
127 % and say in the document |\usebibentry{xyz}{annotation}|. It's also
128 % possible to say |\newbibfield{author}|, but as author names are
129 % input in a very peculiar way, the result would be at least
130 % questionable in the vast majority of cases. This command should
131 % appear before |\bibinput|.
132 %
133 % \DescribeMacro{\newbibignore}
134 % The entry types |@preamble| and |@string| are ignored by default. If
135 % some other type should also, it's possible to say
136 % \begin{flushleft}
137 % |\newbibignore{|\meta{type}|}|
138 % \end{flushleft}
139 % so that, for example, |\newbibignore{misc}| will ignore all |@misc|
140 % entry types. This command should appear before |\bibinput|.
141 %
142 % \subsection{Document commands}
143 %
144 % \DescribeMacro{\usebibentry}
145 % The main document command is |\usebibentry| which requires two
146 % arguments, the bibliography key and the field name:
147 % \begin{flushleft}
148 % |\usebibentry{|\meta{key}|}{|\meta{field}|}|
149 % \end{flushleft}
150 % The \meta{key} is what's used in the argument to |\cite| (or
151 % variations thereof) and \meta{field} can be |title|, |year|, |note|
152 % or |isbn|, but it's possible to augment the list of known
153 % fields. So, in order to get in the document the referenced item's
154 % title one can say
155 %\begin{verbatim}
156 % In the book ``\usebibentry{newton1687}{title}''~\cite{newton1687},
157 % published in~\usebibentry{newton1687}{year}, Newton
158 % describes the Law of Universal Gravitation
159 %\end{verbatim}
160 % to get the text
161 % \begin{quote}
162 % In the book ``Philosophiae Naturalis Principia Mathematica''~[3],
163 % published in 1687, Newton describes the Law of Universal Gravitation
164 % \end{quote}
165 % assuming that in the |.bib| file that has been read with |\bibinput|
166 % there's an entry such as
167 %\begin{verbatim}
168 % @book{newton1687,
169 % author={Newton, Isaac},
170 % title={Philosophiae Naturalis Principia Mathematica},
171 % publisher={Royal Society},
172 % address={London},
173 % year={1687},
174 % url={http://royalsociety.org},
175 % }
176 %\end{verbatim}
177 % Unknown keys and missing values trigger errors: so
178 % |\usebibentry{newton1687}{isbn}| would result in the error
179 %\begin{verbatim}
180 % Undefined key `newton1687' or empty value for `isbn'
181 %\end{verbatim}
182 % Unsupported fields will be ignored and print nothing.
183 %
184 % \DescribeMacro{\usebibentryurl}
185 % If the |.bib| entry has a |url| field, its value can be obtained
186 % with
187 % \begin{flushleft}
188 % |\usebibentryurl{|\meta{key}|}|
189 % \end{flushleft}
190 % \begin{trivlist}\footnotesize\item
191 % When \textsf{hyperref} is not loaded, this is equivalent to calling
192 % \verb+\url|+\meta{url}\verb+|+. In case the URL contains the
193 % character \verb+|+, this call will produce wrong results and
194 % one can specify a different delimiter
195 % \begin{flushleft}
196 % |\usebibentry[!]{|\meta{key}|}|
197 % \end{flushleft}
198 % where, of course, the optional argument is a character not appearing
199 % in the URL. This optional argument is not needed when
200 % \textsf{hyperref} is loaded and, if present, it's ignored.
201 % \end{trivlist}
202 %
203 % \section{Limitations}
204 %
205 % The field delimiters in the |.bib| files \emph{must} be braces, as
206 % must also the entry delimiters. \BibTeX{} allows double quotes in
207 % for delimiting fields and parentheses for the entry. So, while
208 %\begin{verbatim}
209 % @book(newton1687,
210 % author="Newton, Isaac",
211 % title="Philosophiae Naturalis Principia Mathematica",
212 % publisher="Royal Society",
213 % address="London",
214 % year=1687,
215 % url="http://royalsociety.org",
216 % )
217 %\end{verbatim}
218 % would be accepted by \BibTeX{}, it won't be by
219 % \textsf{usebib}. Supporting this is out of question, since we parse
220 % entries as a key-value list. Strictly speaking, double quotes won't
221 % give errors, as long as no comma is in the fields, but will be part
222 % of the replacement text anyways. Numeric field values can, of
223 % course, be input without field delimiters.
224 %
225 % Another limitation is in the fact that field names should always be
226 % lowercase; supporting mixed case for these is beyond the limits of a
227 % small package like this. Sorry.
228 %
229 % Note also that all the bibliographic data are loaded in memory, so
230 % large |.bib| files could exceed \TeX{} capacity.
231 %
232 % Don't ever try typing |\usebibentry{foo}{url}|: you've been
233 % warned. There's |\usebibentryurl{foo}| for this.
234 %
235 % Finally, the package requires $\varepsilon$-\TeX, which shouldn't be
236 % a problem, nowadays.
237 %
238 % \StopEventually{}
239 %
240 % \section{Implementation}
241 %
242 % After the usual presentation, we check first of all that the
243 % typesetting engine is sufficiently recent to include
244 % $\varepsilon$-\TeX{} extensions.
245 % \begin{macrocode}
246 \@ifundefined{eTeXversion}
247 {\PackageError{usebib}{LaTeX engine too old, aborting}
248 {Please upgrade your TeX system}\@@end}{}
249 % \end{macrocode}
250 % We start by loading the required packages.
251 % \begin{macrocode}
252 \RequirePackage{url}
253 \RequirePackage{keyval}
254 % \end{macrocode}
255 %
256 % When we read a |.bib| file the |@| character is made active. Its
257 % action is to read what follows up to the next open brace, using it
258 % as the value of the |currenttype| key. This is necessary for
259 % ignoring the entry types |@preamble| and |@string| which would mess
260 % up everything.
261 %
262 % Now we define the known fields as keys for \textsf{keyval} and the
263 % two auxiliary keys. The |\define@reuse@key| macro is just syntactic
264 % sugar.
265 % \begin{macrocode}
266 \define@key{usebib}{currenttype}{\def\@tempa{#1}}
267 \define@key{usebib}{currententry}{\def\reuse@current{#1}}
268 \def\define@reuse@key#1{%
269 \define@key{usebib}{#1}{\global\@namedef{reuse@\reuse@current @#1}{##1}}}
270 \define@reuse@key{title}
271 \define@reuse@key{isbn}
272 \define@reuse@key{url}
273 \define@reuse@key{year}
274 \define@reuse@key{note}
275 % \end{macrocode}
276 %
277 % \begin{macro}{\reuse@find}
278 % The first macro to be used when looking at an entry, later we'll
279 % define the active |@| to be this macro: it takes as argument the
280 % entry's type and does, for instance,
281 % |\setkeys{usebib}{currenttype=BOOK}|, but inside a |\lowercase| so
282 % that the type will be normalized. Then it checks whether
283 % |\reuse@type@book| is defined, which it isn't, so |\reuse@extract|
284 % will be expanded; since we later define |\reuse@type@preamble| and
285 % |\reuse@type@string|, such entries will be ignored because of
286 % |\@gobble|. The expansion of |\reuse@extract| is done in a group
287 % where |@| has category code~12 and also the percent character,
288 % because it can be in some URL (and has not a special meaning in
289 % \BibTeX{} entries).
290 % \begin{macrocode}
291 \def\reuse@find#1#{%
292 \lowercase{\setkeys{usebib}{currenttype=#1}}%
293 \ifcsname reuse@type@\@tempa\endcsname
294 \expandafter\@gobble
295 \else
296 \begingroup\@makeother\%\makeatother
297 \expandafter\reuse@extract
298 \fi}
299 % \end{macrocode}
300 % \end{macro}
301 %
302 % \begin{macro}{\reuse@extract}
303 % The entire entry is the argument to |\reuse@extract|; since it has a
304 % fixed form, we feed the citation key as the value of |currententry|
305 % and then read all the fields as key-value pairs. The effect of
306 % |currententry=xyz| is to define |\reuse@current| to |xyz|; so a
307 % subsequent |year=2012| will do the equivalent of
308 %\begin{verbatim}
309 % \gdef\reuse@xyz@year{2012}
310 %\end{verbatim}
311 % and similarly for the other known fields. The group opened by
312 % |\reuse@find| is then closed.
313 % \begin{macrocode}
314 \def\reuse@extract#1{\setkeys{usebib}{currententry=#1}\endgroup}
315 % \end{macrocode}
316 % \end{macro}
317 %
318 % \begin{macro}{\reuse@type@preamble}
319 % \begin{macro}{\reuse@type@preamble}
320 % \begin{macro}{\newbibignore}
321 % Here we define the two entry types to ignore and the user level
322 % command to augment the list of ignored fields.
323 % \begin{macrocode}
324 \let\reuse@type@preamble\@empty
325 \let\reuse@type@string\@empty
326 \def\newbibignore#1{\expandafter\let\csname reuse@type@#1\endcsname\@empty}
327 % \end{macrocode}
328 % \end{macro}
329 % \end{macro}
330 % \end{macro}
331 %
332 % \begin{macro}{\reuse@error}
333 % A macro for issuing an error message.
334 % \begin{macrocode}
335 \def\reuse@error#1#2{%
336 \PackageError{usebib}
337 {Undefined key `#1' or empty value for `#2'}
338 {The key you used is wrong or the value to `#2' has not been set}}
339 % \end{macrocode}
340 % \end{macro}
341 %
342 % Next we define the other four user level macros.
343 % \begin{macro}{\newbibfield}
344 % |\newbibfield{type}| defines a new key.
345 % \begin{macrocode}
346 \newcommand\newbibfield[1]{\define@reuse@key{#1}}
347 % \end{macrocode}
348 % \end{macro}
349 %
350 % \begin{macro}{\usebibentry}
351 % \begin{macro}{\usebibentryurl}
352 % \begin{macro}{\reuse@usebibentryurl}
353 % Both |\usebibentry| and |\usebibentryurl| check whether the
354 % corresponding inner macro is defined. The latter then expands a
355 % special inner version that's defined in different ways depending
356 % whether \textsf{hyperref} has been loaded or not. If it is, a simple
357 % |\scantokens| hands the job to the |\url| macro, which is cleverly
358 % defined for accepting special characters; otherwise we need to be
359 % sure that the URL is properly delimited.
360 % \begin{macrocode}
361 \def\usebibentry#1#2{\@ifundefined{reuse@#1@#2}
362 {\reuse@error{#1}{#2}}
363 {\@nameuse{reuse@#1@#2}}}
364 \newcommand{\usebibentryurl}[2][|]{\@ifundefined{reuse@#2@url}
365 {\reuse@error{#2}{url}}
366 {\reuse@usebibentryurl{#1}{#2}}}
367 \@ifpackageloaded{hyperref}{\@tempswatrue}{\@tempswafalse}
368 \if@tempswa
369 \def\reuse@usebibentryurl#1#2{%
370 \scantokens{\url{\csname reuse@#2@url\endcsname}\endinput}}
371 \else
372 \def\reuse@usebibentryurl#1#2{%
373 \toks@=\expandafter\expandafter\expandafter
374 {\csname reuse@#2@url\endcsname}%
375 \scantokens\expandafter{%
376 \expandafter\url\expandafter#1\the\toks@#1\endinput}}
377 \fi
378 % \end{macrocode}
379 % \end{macro}
380 % \end{macro}
381 % \end{macro}
382 %
383 % \begin{macro}{\bibinput}
384 % The macro that starts the reading of a |.bib| file. We start a group
385 % where end-of-line characters are treated like spaces and where the
386 % error messages of \textsf{keyval} and \textsf{xkeyval} about
387 % undefined keys are disabled. Then we define the active |@| to be
388 % |\reuse@find| and input the |.bib| file, closing the group at the
389 % end.
390 % \begin{macrocode}
391 \newcommand{\bibinput}[1]{%
392 \begingroup
393 \catcode`\^^M=10
394 \let\KV@err=\@gobble
395 \let\KV@errx=\@gobble
396 \let\XKV@err=\@gobble
397 \begingroup\lccode`\~=`\@
398 \lowercase{\endgroup\let~}\reuse@find
399 \catcode`\@=\active \input{#1.bib}\endgroup}
400 % \end{macrocode}
401 % \end{macro}
402 % \Finale
403 \endinput