From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- macros/latex/contrib/usebib/usebib.dtx | 403 +++++++++++++++++++++++++++++++++ 1 file changed, 403 insertions(+) create mode 100644 macros/latex/contrib/usebib/usebib.dtx (limited to 'macros/latex/contrib/usebib/usebib.dtx') diff --git a/macros/latex/contrib/usebib/usebib.dtx b/macros/latex/contrib/usebib/usebib.dtx new file mode 100644 index 0000000000..4909210f1f --- /dev/null +++ b/macros/latex/contrib/usebib/usebib.dtx @@ -0,0 +1,403 @@ +% \iffalse meta-comment +% +% Copyright (C) 2012 by Enrico Gregorio +% +% ------------------------------------------------------- +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either +% version 1.3c of this license or (at your option) any +% later version. The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3 or later is part of all distributions +% of LaTeX version 2005/12/01 or later. +% +% This work has the LPPL maintenance status `maintained'. +% +% The Current Maintainer of this work is Enrico Gregorio. +% +% This work consists of the files +% usebib.dtx +% usebib.ins +% and the derived file usebib.sty. +% +% \fi +% +% \iffalse +%<*driver> +\ProvidesFile{usebib.dtx} +% +%\NeedsTeXFormat{LaTeX2e}[2008/04/05] +%\ProvidesPackage{usebib} +%<*package> + [2012/04/13 v1.0a Reusing bib files] +% +% +%<*driver> +\documentclass{ltxdoc} +\providecommand{\BibTeX}{\textsc{Bib}\!\TeX} +\EnableCrossrefs +\CodelineIndex +\RecordChanges +\begin{document} + \DocInput{usebib.dtx} + \PrintChanges + \PrintIndex +\end{document} +% +% \fi +% +% \CheckSum{128} +% +% \CharacterTable +% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z +% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z +% Digits \0\1\2\3\4\5\6\7\8\9 +% Exclamation \! Double quote \" Hash (number) \# +% Dollar \$ Percent \% Ampersand \& +% Acute accent \' Left paren \( Right paren \) +% Asterisk \* Plus \+ Comma \, +% Minus \- Point \. Solidus \/ +% Colon \: Semicolon \; Less than \< +% Equals \= Greater than \> Question mark \? +% Commercial at \@ Left bracket \[ Backslash \\ +% Right bracket \] Circumflex \^ Underscore \_ +% Grave accent \` Left brace \{ Vertical bar \| +% Right brace \} Tilde \~} +% +% +% \changes{v1.0a}{2012/04/13}{Corrected macro names in the doc} +% \changes{v1.0}{2012/03/17}{Initial version} +% +% \GetFileInfo{usebib.dtx} +% +% \DoNotIndex{\newcommand,\newenvironment,\!,\@empty,\@gobble,\@gobbletwo} +% \DoNotIndex{\@ifpackageloaded,\@ifpackagewith,\@ifundefined,\@namedef} +% \DoNotIndex{\@nil,\@onlypreamble,\@tempa,\@tempb,\@tempswafalse,\def} +% \DoNotIndex{\@tempswatrue,\^,\-,\active,\begingroup,\catcode,\@car,\@cdr} +% \DoNotIndex{\edef,\else,\endgroup,\endinput,\expandafter,\fi,\if} +% \DoNotIndex{\if@tempswa,\ifcase,\ifnum,\ifx,\lccode,\let,\lowercase} +% \DoNotIndex{\MessageBreak,\next,\number,\numexpr,\or,\PackageError} +% \DoNotIndex{\PackageWarning,\PackageWarningNoLine,\strip@prefix,\@@end} +% \DoNotIndex{\relax,\space,\string,\DeclareOption,\ProcessOptions} +% \DoNotIndex{\meaning,\ifdefined,\csname,\chardef,\endcsname,\protect} +% \DoNotIndex{\input,\RequirePackage,\global,\ifcsname,\makeatother} +% \DoNotIndex{\@makeother,\the,\toks@} +% +% \title{The \textsf{usebib} package\thanks{This document +% corresponds to \textsf{newunicodechar}~\fileversion, dated \filedate.}} +% \author{Enrico Gregorio \\ \texttt{Enrico dot Gregorio at univr dot it}} +% +% \maketitle +% +% \section{Introduction} +% +% With \textsf{biblatex} it's possible to use any element of a +% bibliographic item in a document. With packages such as +% \textsf{natbib} or simply with the native \BibTeX{} support one +% can't refer directly to the title of a cited article or book without +% directly typing it in. +% +% This package allows this by reading in a special environment a +% |.bib| file. It should be considered no more than a devious usage of +% a |.bib| file, to be honest. But it works. +% +% \section{Usage} +% +% The package \emph{must} be loaded after \textsf{hyperref}, but it +% doesn't require it. It depends only on \textsf{url} and +% \textsf{keyval}, which should be present on every \TeX{} +% distribution. +% +% \subsection{Preamble commands} +% +% \DescribeMacro{\bibinput} +% The main command is |\bibinput|, which accepts the name of a |.bib| +% file (\emph{without} the extension) and may be repeated any number +% of times to read all the necessary files.\footnote{Making it +% dependent on the \texttt{\string\bibliography} command would be too +% difficult.} The command should appear only in the preamble. +% +% \DescribeMacro{\newbibfield} +% With the macro |\newbibfield|, to be issued \emph{before} +% |\bibinput|, it's possible to declare new known fields, for example +%\begin{verbatim} +% \newbibfield{annotation} +%\end{verbatim} +% and say in the document |\usebibentry{xyz}{annotation}|. It's also +% possible to say |\newbibfield{author}|, but as author names are +% input in a very peculiar way, the result would be at least +% questionable in the vast majority of cases. This command should +% appear before |\bibinput|. +% +% \DescribeMacro{\newbibignore} +% The entry types |@preamble| and |@string| are ignored by default. If +% some other type should also, it's possible to say +% \begin{flushleft} +% |\newbibignore{|\meta{type}|}| +% \end{flushleft} +% so that, for example, |\newbibignore{misc}| will ignore all |@misc| +% entry types. This command should appear before |\bibinput|. +% +% \subsection{Document commands} +% +% \DescribeMacro{\usebibentry} +% The main document command is |\usebibentry| which requires two +% arguments, the bibliography key and the field name: +% \begin{flushleft} +% |\usebibentry{|\meta{key}|}{|\meta{field}|}| +% \end{flushleft} +% The \meta{key} is what's used in the argument to |\cite| (or +% variations thereof) and \meta{field} can be |title|, |year|, |note| +% or |isbn|, but it's possible to augment the list of known +% fields. So, in order to get in the document the referenced item's +% title one can say +%\begin{verbatim} +% In the book ``\usebibentry{newton1687}{title}''~\cite{newton1687}, +% published in~\usebibentry{newton1687}{year}, Newton +% describes the Law of Universal Gravitation +%\end{verbatim} +% to get the text +% \begin{quote} +% In the book ``Philosophiae Naturalis Principia Mathematica''~[3], +% published in 1687, Newton describes the Law of Universal Gravitation +% \end{quote} +% assuming that in the |.bib| file that has been read with |\bibinput| +% there's an entry such as +%\begin{verbatim} +% @book{newton1687, +% author={Newton, Isaac}, +% title={Philosophiae Naturalis Principia Mathematica}, +% publisher={Royal Society}, +% address={London}, +% year={1687}, +% url={http://royalsociety.org}, +% } +%\end{verbatim} +% Unknown keys and missing values trigger errors: so +% |\usebibentry{newton1687}{isbn}| would result in the error +%\begin{verbatim} +% Undefined key `newton1687' or empty value for `isbn' +%\end{verbatim} +% Unsupported fields will be ignored and print nothing. +% +% \DescribeMacro{\usebibentryurl} +% If the |.bib| entry has a |url| field, its value can be obtained +% with +% \begin{flushleft} +% |\usebibentryurl{|\meta{key}|}| +% \end{flushleft} +% \begin{trivlist}\footnotesize\item +% When \textsf{hyperref} is not loaded, this is equivalent to calling +% \verb+\url|+\meta{url}\verb+|+. In case the URL contains the +% character \verb+|+, this call will produce wrong results and +% one can specify a different delimiter +% \begin{flushleft} +% |\usebibentry[!]{|\meta{key}|}| +% \end{flushleft} +% where, of course, the optional argument is a character not appearing +% in the URL. This optional argument is not needed when +% \textsf{hyperref} is loaded and, if present, it's ignored. +% \end{trivlist} +% +% \section{Limitations} +% +% The field delimiters in the |.bib| files \emph{must} be braces, as +% must also the entry delimiters. \BibTeX{} allows double quotes in +% for delimiting fields and parentheses for the entry. So, while +%\begin{verbatim} +% @book(newton1687, +% author="Newton, Isaac", +% title="Philosophiae Naturalis Principia Mathematica", +% publisher="Royal Society", +% address="London", +% year=1687, +% url="http://royalsociety.org", +% ) +%\end{verbatim} +% would be accepted by \BibTeX{}, it won't be by +% \textsf{usebib}. Supporting this is out of question, since we parse +% entries as a key-value list. Strictly speaking, double quotes won't +% give errors, as long as no comma is in the fields, but will be part +% of the replacement text anyways. Numeric field values can, of +% course, be input without field delimiters. +% +% Another limitation is in the fact that field names should always be +% lowercase; supporting mixed case for these is beyond the limits of a +% small package like this. Sorry. +% +% Note also that all the bibliographic data are loaded in memory, so +% large |.bib| files could exceed \TeX{} capacity. +% +% Don't ever try typing |\usebibentry{foo}{url}|: you've been +% warned. There's |\usebibentryurl{foo}| for this. +% +% Finally, the package requires $\varepsilon$-\TeX, which shouldn't be +% a problem, nowadays. +% +% \StopEventually{} +% +% \section{Implementation} +% +% After the usual presentation, we check first of all that the +% typesetting engine is sufficiently recent to include +% $\varepsilon$-\TeX{} extensions. +% \begin{macrocode} +\@ifundefined{eTeXversion} + {\PackageError{usebib}{LaTeX engine too old, aborting} + {Please upgrade your TeX system}\@@end}{} +% \end{macrocode} +% We start by loading the required packages. +% \begin{macrocode} +\RequirePackage{url} +\RequirePackage{keyval} +% \end{macrocode} +% +% When we read a |.bib| file the |@| character is made active. Its +% action is to read what follows up to the next open brace, using it +% as the value of the |currenttype| key. This is necessary for +% ignoring the entry types |@preamble| and |@string| which would mess +% up everything. +% +% Now we define the known fields as keys for \textsf{keyval} and the +% two auxiliary keys. The |\define@reuse@key| macro is just syntactic +% sugar. +% \begin{macrocode} +\define@key{usebib}{currenttype}{\def\@tempa{#1}} +\define@key{usebib}{currententry}{\def\reuse@current{#1}} +\def\define@reuse@key#1{% + \define@key{usebib}{#1}{\global\@namedef{reuse@\reuse@current @#1}{##1}}} +\define@reuse@key{title} +\define@reuse@key{isbn} +\define@reuse@key{url} +\define@reuse@key{year} +\define@reuse@key{note} +% \end{macrocode} +% +% \begin{macro}{\reuse@find} +% The first macro to be used when looking at an entry, later we'll +% define the active |@| to be this macro: it takes as argument the +% entry's type and does, for instance, +% |\setkeys{usebib}{currenttype=BOOK}|, but inside a |\lowercase| so +% that the type will be normalized. Then it checks whether +% |\reuse@type@book| is defined, which it isn't, so |\reuse@extract| +% will be expanded; since we later define |\reuse@type@preamble| and +% |\reuse@type@string|, such entries will be ignored because of +% |\@gobble|. The expansion of |\reuse@extract| is done in a group +% where |@| has category code~12 and also the percent character, +% because it can be in some URL (and has not a special meaning in +% \BibTeX{} entries). +% \begin{macrocode} +\def\reuse@find#1#{% + \lowercase{\setkeys{usebib}{currenttype=#1}}% + \ifcsname reuse@type@\@tempa\endcsname + \expandafter\@gobble + \else + \begingroup\@makeother\%\makeatother + \expandafter\reuse@extract + \fi} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\reuse@extract} +% The entire entry is the argument to |\reuse@extract|; since it has a +% fixed form, we feed the citation key as the value of |currententry| +% and then read all the fields as key-value pairs. The effect of +% |currententry=xyz| is to define |\reuse@current| to |xyz|; so a +% subsequent |year=2012| will do the equivalent of +%\begin{verbatim} +% \gdef\reuse@xyz@year{2012} +%\end{verbatim} +% and similarly for the other known fields. The group opened by +% |\reuse@find| is then closed. +% \begin{macrocode} +\def\reuse@extract#1{\setkeys{usebib}{currententry=#1}\endgroup} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\reuse@type@preamble} +% \begin{macro}{\reuse@type@preamble} +% \begin{macro}{\newbibignore} +% Here we define the two entry types to ignore and the user level +% command to augment the list of ignored fields. +% \begin{macrocode} +\let\reuse@type@preamble\@empty +\let\reuse@type@string\@empty +\def\newbibignore#1{\expandafter\let\csname reuse@type@#1\endcsname\@empty} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\reuse@error} +% A macro for issuing an error message. +% \begin{macrocode} +\def\reuse@error#1#2{% + \PackageError{usebib} + {Undefined key `#1' or empty value for `#2'} + {The key you used is wrong or the value to `#2' has not been set}} +% \end{macrocode} +% \end{macro} +% +% Next we define the other four user level macros. +% \begin{macro}{\newbibfield} +% |\newbibfield{type}| defines a new key. +% \begin{macrocode} +\newcommand\newbibfield[1]{\define@reuse@key{#1}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\usebibentry} +% \begin{macro}{\usebibentryurl} +% \begin{macro}{\reuse@usebibentryurl} +% Both |\usebibentry| and |\usebibentryurl| check whether the +% corresponding inner macro is defined. The latter then expands a +% special inner version that's defined in different ways depending +% whether \textsf{hyperref} has been loaded or not. If it is, a simple +% |\scantokens| hands the job to the |\url| macro, which is cleverly +% defined for accepting special characters; otherwise we need to be +% sure that the URL is properly delimited. +% \begin{macrocode} +\def\usebibentry#1#2{\@ifundefined{reuse@#1@#2} + {\reuse@error{#1}{#2}} + {\@nameuse{reuse@#1@#2}}} +\newcommand{\usebibentryurl}[2][|]{\@ifundefined{reuse@#2@url} + {\reuse@error{#2}{url}} + {\reuse@usebibentryurl{#1}{#2}}} +\@ifpackageloaded{hyperref}{\@tempswatrue}{\@tempswafalse} +\if@tempswa + \def\reuse@usebibentryurl#1#2{% + \scantokens{\url{\csname reuse@#2@url\endcsname}\endinput}} +\else + \def\reuse@usebibentryurl#1#2{% + \toks@=\expandafter\expandafter\expandafter + {\csname reuse@#2@url\endcsname}% + \scantokens\expandafter{% + \expandafter\url\expandafter#1\the\toks@#1\endinput}} +\fi +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\bibinput} +% The macro that starts the reading of a |.bib| file. We start a group +% where end-of-line characters are treated like spaces and where the +% error messages of \textsf{keyval} and \textsf{xkeyval} about +% undefined keys are disabled. Then we define the active |@| to be +% |\reuse@find| and input the |.bib| file, closing the group at the +% end. +% \begin{macrocode} +\newcommand{\bibinput}[1]{% + \begingroup + \catcode`\^^M=10 + \let\KV@err=\@gobble + \let\KV@errx=\@gobble + \let\XKV@err=\@gobble + \begingroup\lccode`\~=`\@ + \lowercase{\endgroup\let~}\reuse@find + \catcode`\@=\active \input{#1.bib}\endgroup} +% \end{macrocode} +% \end{macro} +% \Finale +\endinput -- cgit v1.2.3