| 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 |