path: root/macros/latex/contrib/listbib/listbib.dtx

% \iffalse meta-comment
% %%----------------------------------------------------------------------------
%
%% File: listbib.dtx Copyright (C) 2000 Volker Kuhlmann
%%       (based on biblist.sty version 1.4 copyright 1991 Joachim Schrod)
%% All rights are reserved.
%%
%
%<*dtx>
        \NeedsTeXFormat{LaTeX2e}[1999/06/01]
        \ProvidesFile{listbib.dtx}
%</dtx>
%<package|maindoc>\NeedsTeXFormat{LaTeX2e}[1998/06/01]
%<package>\ProvidesPackage{listbib}
%<driver> \ProvidesFile{listbib.drv}
%<maindoc>\ProvidesFile{listbib.tex}
%
% \fi
%         \ProvidesFile{listbib.dtx}
       [2000/08/28 v2.2 list contents of bibtex files (VK)]
%
%%
%% \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         \~}
%%
%
% \iffalse
%<*driver>

\NeedsTeXFormat{LaTeX2e}[1999/06/01]
\documentclass{ltxdoc}
%%\IfFileExists{ltxdoc.cfg}{}{\OnlyDescription\RecordChanges\CodelineIndex}

 %\OnlyDescription                  % uncomment to suppress code line listing
 \RecordChanges                    % uncomment for a change history
 %\CodelineIndex\EnableCrossrefs    % uncomment for command index
\GetFileInfo{listbib.dtx}

\usepackage{listbib}

\begin{document}
\DocInput{listbib.dtx}
%%\IfFileExists{ltxdoc.cfg}{}{\PrintChanges\PrintIndex}
 \PrintChanges                     % uncomment for a change history
 %\PrintIndex                       % uncomment for command index
\end{document}

%</driver>
% \fi
%
%
% \GetFileInfo{listbib.dtx}
% \CheckSum{259}
%
% %^^A This command extracts all index entries:
% %^^A sed < listbib.idx -e 's,indexentry{,,' -e 's,=.*$,,'
%
% \date{\filedate}
% \title{The \textsf{listbib} Package\thanks
%        {This file has version number \fileversion,
%         last modified \filedate.}}
% \author{Volker Kuhlmann\thanks{%^^A
%         Email:\ \url{v.kuhlmann@elec.canterbury.ac.nz}.
%   	  For a postal address refer to the license section.}}
%
%
% \let\package\textsf
% \let\env\textsf
% \let\url\texttt
% \newcommand\optmeta[1]{[\meta{#1}]}
% \providecommand\MF{\textsc{meta-font}}
% \providecommand\fixendverbatim{\vspace{-\bigskipamount}}
% \renewenvironment{quote}{%
%   \list{}{\leftmargin=0.5\leftmargin\rightmargin\leftmargin}\item\relax
%   }{%
%   \endlist
%   }
% \makeatletter
% \providecommand\DescribeWord[1]{%
%   \leavevmode\@bsphack
%   \marginpar{\raggedleft\PrintDescribeEnv{#1}}%^^A
%   \@bsphack\index{#1\actualchar{\protect\ttfamily#1}\encapchar usage}\@esphack
%   \@esphack\ignorespaces
%   }
% \makeatother
%
% %^^A We need listbib for the examples and do therefore include it. But it
% %^^A sets the headline (see below ;-). So we just reset it again to the
% %^^A value it had before. Well, it's a kind of a kludge, but it works...
% \pagestyle{plain}
%
% %^^A The examples will consist of framed pseudo-output. We'll need a
% %^^A variable for the width of these examples.
% \newdimen\examplewidth
%
%
% \changes{v2.2}{2000/08/28}
%   {Enhancements to the listbib shell script.
%    Example listbib.cfg.
%    Support for entry fields `URL' and `totalpages' (custom-bib uses them).}
%
% \changes{v2.1}{2000/03/17}
%   {Fixed bug in \cs{@citex}.
%    Removed silly \cs{listbibpreamble}.
%    listbib.cfg.
%    No longer adding \emph{.bib} to filenames in header.
%    Adding period after annote in listbib.bst.
%    Inherited fields are now not printed!
%    Shell script listbib.}
%
% \changes{v2.0}{2000/03/13}
%   {Renamed listbib from biblist version 1.4 by Volker Kuhlmann.
%    Complete revamp: for \LaTeXe, docstrip, etc.
%    Released under GPL.}
%
% \changes{1.4}{1992/01/13}
%   {Last version by Joachim Schrod, TU Darmstadt, Darmstadt, Germany.
%    \mbox{\$Date: 1992/01/13 16:35:56\$}
%    Added examples, repaired headline.
%    Called \cs{reset@font} where appropriate.
%    October 91 version of LaTeX was delayed until December 91. Readers
%    might be disturbed if there is the notion of a nonexistant version.
%   }
%
% \changes{1.3}{1991/10/14  14:10:21  schrod}
%   {mentioned that this option is supported.
%   moved local guide section to separate file.}
%
% \changes{1.2}{1991/10/10  16:13:31  schrod}
%   {changed email address.
%   mentioned LaTeX 2.09 $<$Oct 91${}$ (just announced).}
%
% \changes{1.1}{1991/04/13  15:03:08  schrod}
%   {Initial revision.}
%
%
% \maketitle
%
% \begin{abstract}
% This package typesets a listing of a (possibly large) \BibTeX{} input
% file. With old implementations of texmf the string space could easily be
% exceeded when trying to typeset large bibliographic databases.  Contemporary
% implementations are usually big and have much higher limits. However,
% \package{listbib} works with arbitrarily large \BibTeX\ database files.
%
% In addition to that, \package{listbib} tries to show the full content of a
% \BibTeX\ file without alterations introduced by the bibliographic style used.
% The entry fields ISBN, ISSN, annote, library, totalpages and URL are added to
% the standard ones.
% \end{abstract}
%
% \tableofcontents
%
%
% \section{License}
%
% This package is copyright \textcopyright\ 2000 by:
%
% \begin{quote}
%   Volker Kuhlmann,
%   c/o University of Canterbury,
%   ELEC Dept, Creyke Road,
%   Christchurch, New Zealand\\
%   E-Mail: \url{v.kuhlmann@elec.canterbury.ac.nz}
% \end{quote}
%
%     This program is free software; you can redistribute it and/or modify
%     it under the terms of the GNU General Public License as published by
%     the Free Software Foundation; either version 2 of the License, or
%     (at your option) any later version.
%
% To obtain a copy of the license, write to the
% Free Software Foundation, Inc.,
% 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA,
% or browse \url{http://www.fsf.org/}.
%
%
% \section{History}
%
% This package is derived from |biblist|, version 1.4, 1992/01/13 by Joachim
% Schrod. J.\ Schrod's association with the university of Darmstadt seems to no
% longer exist. biblist is available from CTAN and is under the GNU general
% public license, version 1 or later.
% 
% \package{listbib} is the successor and will only work with \LaTeXe. 
% It uses the docstrip format for literate programming.
% The bibliography style was regenerated from btxbst.doc (unsrt), and
% then enhanced to be suitable for listbib. The fully commented |.bst| file is
% in the distribution (extension |.doc|).
%
% This documentation has little left of the original |biblist| documentation.
%
%
% \section{User manual}
%
% \subsection{Introduction}
%
% This package facilitates printing of large \BibTeX\ files. With  such
% large files --- especially if the cite keys are long --- the needed string
% space is often exceeded. Often a Big\TeX{} is available which pushes the
% limits further out, but with this package any \TeX{} will do it. Printing
% complete \BibTeX\ files as they are is useful for record-keeping.
%
% \DescribeEnv{thebibliography}
% The |\nocite{*}| command and |thebibliography| environment from \LaTeX\
% are used to do the work. The |thebibliography| environment is modified
% and eliminates huge |.aux| files and a second \LaTeX-run, although
% cross-references used in the bibliography entries themselves may still
% require a second \LaTeX-run.
%
% \DescribeMacro{\bibliography}
% A minimal \LaTeX-document must be prepared which uses the article class,
% loads the \package{listbib} package, and specifies the bibliography to be
% printed with the |\bibliography| command. Other packages can be loaded as
% well, for example to set margins or language-specific definitions.
%
% \DescribeMacro{\raggedbottom}
% Other classes can perhaps be used, but \package{listbib} works on the
% assumption that |\raggedbottom| is in effect, which is why it probably
% won't work too well with |twocolumn| or |multicol|. A page break within
% an entry is not allowed and the flexibility at the page bottom is needed.
%
% \DescribeMacro{\nocite}
% \DescribeMacro{\bibliographystyle}
% Unlike with normal \LaTeX\ documents, use of |\bibliographystyle| is not
% required, although it is not prohibited. The default is the listbib.bst
% bibliography style. It is also not necessary to use |\nocite{*}| as that is
% the default. However |\nocite| can be used to select certain entries only to
% be printed.
% 
% A ``bug'' you may encounter is that |\cite| tags within \BibTeX{} entries will
% not be processed. Instead the cite key itself will be printed. Note that this
% is not a bug, this is a feature! You have to use |\nocite| for \emph{all}
% entries that shall be included in the listing. If you do not give any
% |\nocite| tag at all, a listing with all entries is created.
% 
% \DescribeMacro{\BibTeX}
% As a bonus, \package{listbib} defines the control sequence |\BibTeX| if it
% is not already defined. The definition is copied from |btxdoc.tex|.
% 
%
% \subsection{Additional \BibTeX\ Entry Fields}
%
% In addition to the entry fields known by the standard \BibTeX\ styles,
% \package{listbib} recognises these fields: |ISBN|, |ISSN|, |annote|,
% |library|, |URL|, and |totalpages|.
% 
% The use of |ISBN| and |ISSN| should be obvious.
% 
% The |annote| field can be used for annotations or comments regarding this
% particular entry. The standard \BibTeX\ styles do not make use of this
% feature, however other styles might. With \package{listbib} it is useful to
% store a short summary of the contents of this entry. As for |note|, the
% first word should be capitalised. Punctuation at the end of the field 
% is added by the style if appropriate.
% 
% The |library| field is not meant to be printed in final documents, and is
% supplied to store e.g.\ the library location of a book. Useful for database
% listings only.
% 
% The |URL| field can be used to store a URL belonging to this bibliography
% entry. It is also becoming more popular to have bibliography entries which
% entirely consist of a URL. URLs are typeset as |\url{|\meta{URL}|}|, it is
% recommended to use package \package{url} with documents referencing
% bibliography entries which contain a URL. As an additional safeguard, the
% listbib \BibTeX-style defines |\url| to exand to \meta{URL} if it is not
% already defined. This field is supported by \package{custom-bib}.
% 
% The |totalpages| field is meant to store the total number of pages of the
% work. This field is supported by \package{custom-bib}.
%
% All 13 entry types take the |library|, |annote|, |totalpages| and |URL|
% fields. They take the fields |ISBN| and |ISSN| as well, with these exceptions:
% |article| only takes |ISSN|, and |unpublished| takes neither |ISBN| nor |ISSN|.
%
%
% \subsection{Formatting of the entries in the resulting listing}
%
% \begin{description}
% \item[\tt cite key]
%   \leavevmode \null \dotfill \quad {\sf\small (Library info)}\break
% Author(s)/Editor(s).\\
% {\em Title.}\\
% Publication info.\\
% Notes.\\
% \null \qquad {\footnotesize Pages: 123 \ensuremath{\bullet}
%                 URL: \texttt{http://my.url/file}}\\
% \null \qquad {\footnotesize Annotation}
% \end{description}
%
% I.e., an open format is used. Although this needs more space I think the
% enhanced legibility pays back.
%
% Note that you will not get the `Library info' and the `Annotation' in the
% above format if you use a bibliography style other than |listbib| which
% does not supply this information with the assumed markup. The parenthesis
% around the library info are produced by this style option, not by \BibTeX.
%
%
% \subsection{Example}
%
% Suppose, there is a file |typography.bib| with references on typography.
% %
% \begin{quote}
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \begin{verbatim}
% % typography.bib                                13 Jan 92
% % References on Typography, Typesetting, and Book Design
% %
%
% % make sure it's at least defined:
% @preamble{"\providecommand\MF{\textsc{meta-font}}"}
%
% @book{typo:tschichold:selected,
%   author = {Jan Tschichold},
%   title = {Ausgew\"ahlte Aufs\"atze \"uber Fragen der Gestalt des
%         Buches und der Typographie},
%   publisher = {Birkh\"auser},
%   address = {Basel},
%   year = 1975,
%   isbn = {3-7643-1946-1},
%   note = {A second, unchanged, edition appeared in~1987.},
%   library = {},
%   annote = {A collection of his ``classic'' papers. The best book on
%         typographic principles read so far. A definitive `\emph{must
%         read}' for everyone interested in typography, book design,
%         or typesetting.}
% }
%
% @article{typo:blostein:music,
%   author = {Dorothea Blostein},
%   title = {Justification of Printed Music},
%   journal = cacm,
%   volume = 34,
%   number = 3,
%   month = mar,
%   year = 1991,
%   pages = {88--99},
%   annote = {Presents problems and solutions of the task to create a
%         correct spacing while setting notes. The proposed method also
%         takes the temporal relationship of notes into account.
%         Handles two-dimensional layout, e.g., staffs and texts.}
% }
%
% @book{typo:sta:zapf,
%   title = {Herrman Zapf and his Design Philosophy},
%   publisher = {Society of Typographic Arts},
%   address = {Chicago},
%   year = 1987,
%   isbn = {0-941447-00-6},
%   note = {},
%   library = {Lib MQ .B77},
%   annote = {A valuable book. A chapter on his work around \MF{} is
%         included. Was among the most beautiful books of the year.}
% }
% \end{verbatim}\fixendverbatim
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \end{quote}
%
% Furthermore assume that the bibliography style |listbib| is
% available. Then the \LaTeX{} file
%
% \begin{verbatim}
%     \documentclass{article}
%     \usepackage{listbib}
%     \begin{document}
%     \bibliography{typography}
%     \end{document}
% \end{verbatim}\fixendverbatim
%
% may be used to create a listing with all entries. You have to run
% \LaTeX{}, \BibTeX{}, and \LaTeX{}. (Careful readers will note that
% there will be a \BibTeX{} warning about a missing author or editor in
% the Zapf entry.) You do {\it not\/} need to run \LaTeX{} twice after
% the \BibTeX{} run. The result looks like this:
% %
% \begingroup
%   \examplewidth=\linewidth
%   \advance\examplewidth by -2\fboxrule
%   \advance\examplewidth by -2\fboxsep
%   ~\par\noindent\fbox{\begin{minipage}{\examplewidth}
%   \section*{References}
%
%   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%   %
%   %^^A We must fake a little bit to include it here. \bibitem gobbles the
%   %^^A next character since it thinks it's a line end. (This might be a
%   %^^A problem for itself, but untill now all bibliography styles put
%   %^^A \bibitem on an own line.) We must supply a token which might be
%   %^^A eaten by \bibitem. Best to use a \relax for this.
%   %
%   \begin{thebibliography}{1}
%
%   \bibitem{typo:tschichold:selected}\relax
%   Jan Tschichold.
%   \newblock {\it Ausgew\"ahlte Aufs\"atze \"uber Fragen der Gestalt des
%     Buches und der Typographie}.
%   \newblock Birkh\"auser, Basel, 1975. ISBN~3-7643-1946-1.
%   \newblock A second, unchanged, edition appeared in~1987.
%   \newblock
%   \annote A collection of his ``classic'' papers. The best book on
%     typographic principles read so far. A definitive `{\it must\/}' for
%     everyone interested in typography, book design, or typesetting.
%   \endannote.
%
%   \bibitem{typo:blostein:music}\relax
%   Dorothea Blostein.
%   \newblock Justification of Printed Music.
%   \newblock {\it Communications of the ACM}, 34(3):88--99, March 1991.
%   \newblock
%   \annote Presents problems and solutions of the task to create a correct
%     spacing while setting notes. The proposed method also takes the
%     temporal relationship of notes into account. Handles two-dimensional
%     layout, e.g., staffs and texts.
%   \endannote.
%
%   \bibitem{typo:sta:zapf}\relax
%   \library{Lib MQ .B77}
%   {\it Herrman Zapf and his Design Philosophy}.
%   \newblock Society of Typographic Arts, Chicago, 1987. ISBN~0-941447-00-6.
%   \newblock
%   \annote A valuable book. A chapter on his work around \MF{} is included.
%     Was among the most beautiful books of the year.
%   \endannote.
%
%   \end{thebibliography}
%   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%   \end{minipage}}
% \endgroup
%
% \bigskip
%
% To use a bibliography style other than |listbib|, specify it in the usual way
% with |\bibliographystyle|. For example, |unsrt| gives:
% %
% \begingroup
%   \examplewidth=\linewidth
%   \advance\examplewidth by -2\fboxrule
%   \advance\examplewidth by -2\fboxsep
%   ~\par\noindent\fbox{\begin{minipage}{\examplewidth}
%   \section*{References}
%   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%   %^^A Here the same reason for inserting \relax'es as in the previous
%   %^^A example applies.
%   \begin{thebibliography}{1}
%
%   \bibitem{typo:tschichold:selected}\relax
%   Jan Tschichold.
%   \newblock {\em Ausgew\"ahlte Aufs\"atze \"uber Fragen der Gestalt des
%     Buches und der Typographie}.
%   \newblock Birkh\"auser, Basel, 1975.
%   \newblock A second, unchanged, edition appeared in~1987.
%
%   \bibitem{typo:blostein:music}\relax
%   Dorothea Blostein.
%   \newblock Justification of printed music.
%   \newblock {\em Communications of the ACM}, 34(3):88--99, March 1991.
%
%   \bibitem{typo:sta:zapf}\relax
%   {\em Herrman Zapf and his Design Philosophy}.
%   \newblock Society of Typographic Arts, Chicago, 1987.
%
%   \end{thebibliography}
%   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%   \end{minipage}}
% \endgroup
%
% \bigskip
%
% Of course, the ISBN/ISSN numbers, annotations, and library information is
% missing, since |unsrt| does not extract them from the database. (Careful
% readers will notice another difference: The |listbib| bibliography style does
% not lower-case titles as the standard styles do.)
% 
% 
% \subsection{Site Configuration File}
% 
% The \package{listbib} package will input a site configuration file
% \DescribeWord{listbib.cfg}
% |listbib.cfg| if it exists. This is a good place for changing margins or the
% document title, etc. The configuration file is |\input| at the end of the
% \package{listbib} package.
% Here is an example:
% \begin{quote}
% \begin{verbatim}
%   %% listbib.cfg     VK 30 Jul 2000
% 
%   % Date format: 99 Month 9999
%   \newcommand\monthname{%
%     \ifcase \month \or
%       January\or February\or March\or April\or May\or June\or
%       July\or August\or September\or October\or November\or December\fi
%   }
%   \def\today{%
%     \number\day \space \monthname \space \number\year
%   }
% 
%   % Latin-1 input
%   % (There is currently no way to do this from within a .bib file.)
%   \usepackage[latin1]{inputenc}
% \end{verbatim}\fixendverbatim
% \end{quote}
% 
% 
% \subsection{Inheriting Field Entries}
% 
% As \BibTeX\ currently works, missing fields in all entries which
% crossreference another entry are inherited from the crossreferenced entry. To
% illustrate, in this .bib file
% 
% \begin{quote}
% \begin{verbatim}
%   @incollection{chapter,
%       crossref="book",
%       author="..", title=".."
%   }
%   @book{book,
%       editor="..", booktitle="..", note=".."
%   }
% \end{verbatim}\fixendverbatim
% \end{quote}
% 
% the chapter entry inherits the |note| field from the |book| entry. The same is
% true for all other fields which can possibly be inherited. \BibTeX\ does not
% make the information of whether a field was inherited available in the style
% file, so the inheritence can not be detected directly.
% 
% \package{listbib} implements a workaround for this which can detect inherited
% fields. A field is assumed to be inherited by a crossreferencing entry  if its
% value is identical to that of the crossreferenced entry. This assumption fails
% when the field values are in fact identical. Please let me know of any cases
% where that is a problem, and I will try and fix it or make a sepaarte style
% which does not try to detect inherited fields. A quick fix might be to add
% something like a |{}| at the end of the field.
% 
% Currently inheritance is detected for the fields |note|, |annote|, |ISBN|,
% |ISSN|, |library|, |totalpages| and |URL|. Inherited fields are not printed in
% the listing.
% 
% 
% \subsection{The listbib.tex Main Document Frame}
% 
% \DescribeMacro{\listbibs}
% The shortest way to to typeset a bibliography is to put something like this
% into a \meta{file}|.tex| and to run it through \LaTeX, \BibTeX, and (possibly
% more than once) \LaTeX\ again:
%     \begin{quote}
%     |\newcommand||\listbibs||{|\meta{bibliographies}|}|\\
%     |\AtBeginDocument{|\meta{preamblematerial}|}|\\
%     |\input||{||listbib||}|
%     \end{quote}
% For \meta{bibliographies} list everything to be printed. Any \BibTeX\
% files containing string definitions must also be specified (first).
%
% \DescribeMacro{\AtBeginDocument}
% The use of |\AtBeginDocument| is completely optional. If used,
% \meta{preamblematerial} will be inserted into the preamble of
% |listbib.tex|.
% 
% |listbib.tex| also loads the packages
%   \DescribeWord{vmargin}
%   \DescribeWord{url}
% \package{vmargin} and \package{url} if
% it can find them. \package{vmargin} sets up the page margins, and
% \package{url} provides a |\url| command for typesetting urls.
% 
% A configuration file \meta{file}|.cfg| will be loaded within the preamble of
% |listbib.tex|, if it exists.
% 
% This short document selects a document font size of 10pt, and double-sided
% printing. Unfortunately it is not possible to override that in any of the two
% configuration files.
% 
% 
% \subsection{The listbib Shell Script}
%
% The |listbib| program can be used to quickly generate a listing of the
% bibliographies given on the command line. The program is a Unix shell script;
% sorry if you don't use Unix. You may still be able to port it, send me a copy
% if you do.
% 
% Here is its usage:
% \begin{verbatim}
%   Usage: listbib [OPTIONS] [BIBFILE[.bib] ..] BIBFILE_N[.bib]
%   Version VK 1.2.3, 28 Aug 2000
% 
%   Options:
%     -h|--help              shows help
%     -o|--output FILE       generates FILE.dvi / FILE.ps (default listedbibs)
%     -O|--same              as -o, but generate FILE.dvi and BIBFILE_N.ps
%     -p|--ps|--postscript   generate PostScript as well as dvi
%     -d|--deltemp           delete all generated files but .dvi
%     -P|--psonly            generate only PostScript (delete all generated files
%                              but .ps)
%     --                     stop option processing; only .bib files remain
% \end{verbatim}\fixendverbatim
% A temporary .tex file is created which makes use of |listbib.tex|. latex,
% bibtex, and possibly dvips are run on the .tex file to create the listing of
% all .bib files specified. The .bib extension can be left out. Remember to
% specify any .bib first which define any strings needed later.
% 
% By default, the name of the .tex file is |listedbibs.tex|, this can be changed
% with the |-o| option. Don't specify an extension here.
% 
% To generate PostScript as well, use the |-p| option. This currently only
% supports dvips. I can change that if there is demand. The |-d| option will
% delete all temporary files when |listbib| is finished, and only leave the dvi
% file. |-P| will create a PostScript file and then delete all others.
%
% To only generate a mybib.ps from mybib.bib, use |-P -O|.
% 
% An error is displayed if the .tex file to be created already exists and is not
% one generated by listbib.
%
%
% \subsection{To Do and Bugs}
% 
% Inheritance is currently only checked for the fields |note|, |annote|, |ISBN|,
% |ISSN|, |library|, |totalpages| and |URL|. Printing of these fields is
% suppressed for all entry types if inherited. Should printing of other
% inherited fields be suppressed as well? I am less inclined to suppress
% |volume|, and I am not sure about |year|, |month|, etc. Please let me know
% what you think.
% 
% As a future enhancement one could place a word from the starting and the
% finishing entry on each page into the page header, like it is in a dictionary.
% 
% Some kind of section title above each .bib file would be useful.
%
%
% \DoNotIndex{\ ,\.,\_}%^^A  DOES NOT WORK!!
% \DoNotIndex{\@M,\@checkAnnote,\@citex,\@evenhead,\@for,\@gobble}
% \DoNotIndex{\@highpenalty,\@m,\@ne,\@oddhead,\@tempdima,\@totalleftmargin}
% \DoNotIndex{\AddBibliographystyle,\AddNocite,\IfFileExists}
% \DoNotIndex{\InputIfFileExists,\advance,\afterassignment,\annote,\begin}
% \DoNotIndex{\begingroup,\bib,\break,\catcode,\chardef,\check,\csname,\def}
% \DoNotIndex{\do,\documentclass,\dotfill,\edef,\else,\end,\endannote}
% \DoNotIndex{\endcsname,\enddescription,\endgraf,\endgroup,\endinput}
% \DoNotIndex{\endthebibliography,\escapechar,\expandafter,\f@size,\fbox}
% \DoNotIndex{\fboxsep,\fi,\fontsize,\footnotesize,\futurelet,\hbox,\hfil}
% \DoNotIndex{\if@tempswa,\ifx,\ignorespaces,\interlinepenalty,\item,\jobname}
% \DoNotIndex{\kern,\lb,\leavevmode,\leftmargin,\leftmark,\let,\linewidth}
% \DoNotIndex{\lower,\mark,\markboth,\newblock,\newline,\next,\null,\obeylines}
% \DoNotIndex{\parsep,\parshape,\penalty,\prepare,\providecommand,\quad,\relax}
% \DoNotIndex{\reset@font,\rightmark,\rightskip,\rm,\section,\selectfont}
% \DoNotIndex{\setmarginsrb,\sfcode,\small,\string,\textrm,\textsc,\textsf}
% \DoNotIndex{\texttt,\today,\tt,\typeout,\uscode,\usepackage,\vmargin,\vskip}
% \DoNotIndex{\z@,\z@skip}
% \DoNotIndex{\thebibliography,\ttfamily}
%
% \StopEventually{}
%
%
%
% \section{Implementation}
%
%
% \subsection{Main Document for Quick Use}
%
% %^^A NOTE: "latex listbib.ins" does not extract module <maindoc> if it
% %^^A       is after module <package> !!
%
% The intended usage is this:
%     \begin{quote}
%     |\newcommand||\listbibs||{|\meta{bibliographies}|}|\\
%     |\input||{||listbib||}|
%     \end{quote}
%
%    \begin{macrocode}
%<*maindoc>
%    \end{macrocode}
%
%    \begin{macrocode}
\documentclass[10pt,twoside]{article}
%    \end{macrocode}
%
% Set document margins if package \package{vmargin} is installed. Load package
% \package{url} if available; this package provides an excellent |\url| command
% which can be used in bibliography entries.
%
%    \begin{macrocode}
%% Packages
\IfFileExists{vmargin.sty}{% use if available
    \usepackage{vmargin}%
    \setmarginsrb{25mm}{12mm}{22mm}{8mm}{10pt}{8mm}{}{10mm}}{}
\IfFileExists{url.sty}{\usepackage{url}}{} % load if installed
%    \end{macrocode}
%
%    \begin{macrocode}
%% Layout
\fboxsep	0.8pt	% normally 3pt
%    \end{macrocode}
%
% And yes, we want \package{listbib}\ldots
%
%    \begin{macrocode}
%% Package listbib
\usepackage{listbib}
%    \end{macrocode}
%
% Further document setting can be placed into a per-job configuration file,
% which will be loaded if found.
% 
%    \begin{macrocode}
%% Load per-job configuration file if it exists
\InputIfFileExists{\jobname.cfg}{\typeout
    {*** listbib: per-job configuration file \jobname.cfg found. ***}}{}
%    \end{macrocode}
%
% ^^A Or, simple settings can be inserted with this command.
% ^^A This is stupid. Use |\AtBeginDocument|!
%    \begin{macrocode}
%\csname listbibpreamble\endcsname  % call it if it is defined
%    \end{macrocode}
%
% \begin{macro}{\listbibs}
% Main document part. The bibliographies to typeset are taken from |\listbibs|.
%
%    \begin{macrocode}
%% Main
\begin{document}
\bibliography{\listbibs}
\end{document}
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
%</maindoc>
%    \end{macrocode}
%
%
% \subsection{Preliminary}
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
% The main work is to supply the environment |thebibliography|; in
% fact, we implement it as a |description| environment. The environment
% has an unused argument. In addition we have to supply a correct
% definition for the |\bibitem| command which takes the cite key as its
% argument. Of course, this will result in an |\item|. After the
% |\bibitem| a |\library| tag may follow, with one parameter followed
% by a period. Then comes the reference, the (optional) annotation is
% a block of its own, enclosed in |\annote| and |\endannote|. After
% |\endannote| comes a period which should be discarded. (This should
% be done in the \BibTeX{} style, but nevertheless\dots)
%
% Before we start we declare some shorthands for category codes.
% By declaring the underscore~`(|_|)' as letter we can use it in our
% macros. (I agree with {\sc D.~Knuth} that
% |\identifier_several_words_long| is more readable than
% |\IdentifierSeveralWordsLong| and in every case better than
% |\p@@@s|.) As this is a \LaTeX{} style option the at sign is a letter
% anyhow; so we can use the ``private'' Plain and \LaTeX{} macros; and
% with the underscore we can make our own macros more readable.  But as
% we have to restore this category code at the end of this macro file
% we store its former value in the control sequence |\uscode|. This
% method is better than using a group because not all macros have to
% be defined global this way.
%
%    \begin{macrocode}
\chardef\uscode=\catcode`\_
\catcode`\_=11
%    \end{macrocode}
%
%
% \subsection{The Bibliography}
%
% \begin{environment}{thebibliography}
% Within an entry we use a ragged right margin. To break within an
% entry is always difficult and is made easier in this way. After all,
% the open format we use gives a ragged impression anyhow. Within an
% entry we dissallow page breaks and we do not treat periods as full
% stops.
%
%    \begin{macrocode}
\def\thebibliography#1{%
    \description
        \rightskip \z@ plus 2em
        \interlinepenalty\@M
        \sfcode`\.=\@m
    }
\let\endthebibliography=\enddescription
%    \end{macrocode}
% \end{environment}
%
% |\bibitem| should look for the next token: If a library info
% exists it must go in the same line, otherwise a line break must be
% issued.
%
% \begin{macro}{\@lbibitem}
% \begin{macro}{\@bibitem}
% But |\bibitem| itself is not of interest, it looks only for the
% optional argument. We have to redefine |\@bibitem|. If a
% bibliography style like |alpha| is used, |\bibitem| will be supplied with
% an optional argument. We ignore this optional argument.
%
% After the argument(s) of |\bibitem| a line end occurs in any case. The
% optional |\library| tag will follow on the next line. This means we
% first have to gobble the line end char |^^M|, and have to check the
% next token afterwards. If this next token is |\library| we will do
% nothing since |\library| will itself end the line. Otherwise we do a
% line break. Experiments have shown that the dotted line at the start
% of every entry helps with finding the different entries.
%
%    \begin{macrocode}
\def\@lbibitem[#1]{\@bibitem}
\def\@bibitem#1{%
    \item[\texttt{\lb_sanitize{#1}}]\leavevmode
    \null \dotfill
    \begingroup
        \obeylines
        \afterassignment\prepare_check_library
        \let\next               % gobble following ^^M
    }
\def\prepare_check_library{%
        \futurelet\next\check_library
    }
\def\check_library{%
        \ifx \next\library \else \break \fi
    \endgroup
    }
\def\lb_sanitize#1{{\escapechar=-1
    \expandafter\string\csname#1\endcsname}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
%
% \subsection{Library}
%
% \begin{macro}{\library}
% We assume that the library info and the cite key will fit into
% one line. If this is not true, a two line solution would have to be set up.
%
% We add |\@highpenalty| instead of |\@M| after the library part to avoid 
% an underfull hbox warning and an empty line if both author and editor are
% empty (in which case there is a |\newblock| immediately following the 
% |\library{..}|. Alternativelly, we could implement more |\futurelet|
% trickery.
%
%    \begin{macrocode}
\def\library#1{%
    \quad\textsf{\small (#1)}\penalty -\@highpenalty
    }
%    \end{macrocode}
% \end{macro}
%
%
% \subsection{Annotation}
%
% \begin{macro}{\newblock}
% A reference is divided into blocks starting with |\newblock|.
% Each block shall start a new line. We use |\newline| for this. A
% special block is the one with an annotation in it. Since we want to
% indent this block once more we must change the parshape. But then we
% have to finish the paragraph first. The annotation block starts with
% |\annote| and may be easily recognized in this way.
%
%    \begin{macrocode}
\def\newblock{%
    \futurelet\next\@checkAnnote
    }
\def\@checkAnnote{%
    \ifx \next\annote \else \newline \fi
    }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\annote}
% The annotation is a paragraph on its own and indented by |\leftmargin|.
% Since it is not a paragraph in the logical sense we do not insert
% vertical glue (i.e., |\parskip|) at the top. The annotation is typeset
% in a smaller size. We assume that it consists of full sentences which
% might be made up in a proper way. Therefore we don't use a ragged
% margin here.
%
% The change of |\parshape| has to be reset after the group --- these
% changes are not local.
%
%    \begin{macrocode}
\def\annote{%
    \endgraf
    \vskip -\parsep
    \begingroup
        \reset@font\footnotesize
        \rightskip\z@skip
        \advance\linewidth -\leftmargin
        \advance\@totalleftmargin \leftmargin
        \parshape \@ne \@totalleftmargin \linewidth
    }
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\endannote}
% The period in the definition is used to gobble the period placed by \BibTeX.
%    \begin{macrocode}
\def\endannote.{%
        \endgraf
    \endgroup
    \parshape \@ne \@totalleftmargin \linewidth
    }
%    \end{macrocode}
% \end{macro}
%
%
% \subsection{Citation Key}
%
% \begin{macro}{\@citex}
% In our documents |\cite| will print the cite key in typewriter with a framed
% box around. In fact, |\cite| expands to |\@citex|, which has an optional
% argument. The flag |\if@tempswa| shows if this optional argument is there.
% |\texttt{..}| will alter |\if@tempswa|. So might |\fbox| and |\ttfamily| in
% the future. |\fbox| does not work inside |\if|, and |\lb_sanitize|
% does not work inside a |\def|, so we save the flag in |\@cxt|.
%
% ^^A > \cite=macro:
% ^^A ->\protect \cite  .
% ^^A > \cite =\long macro:
% ^^A ->\@ifnextchar [{\@tempswatrue \@citex }{\@tempswafalse \@citex []}.
%
%    \begin{macrocode}
\def\@citex[#1]#2{\if@tempswa\def\@cxt{y}\else\let\@cxt\relax\fi
    \fbox{{\ttfamily\lb_sanitize{#2}}%
          \if y\@cxt , \ttfamily\lb_sanitize{#1}\fi}}
%    \end{macrocode}
% \end{macro}
%
%
% \subsection{Defaults for $\backslash$nocite and $\backslash$bibliographystyle}
%
% \begin{macro}{\@@nocite}
% \begin{macro}{\@@bibliographystyle}
% \begin{macro}{\@@bibliography}
% First the original definitions of the to-be-redefined control sequences are
% saved. We define two macros which will issue the default given above.
% These macros are not private, but protected; a knowing user may redefine the
% `default bibliography style' in this way.
%
%    \begin{macrocode}
\let\@@nocite=\nocite
\let\@@bibliographystyle=\bibliographystyle
\let\@@bibliography=\bibliography
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% ^^A\DescribeMacro{\nocite}
% ^^A\DescribeMacro{\bibliographystyle}
% \begin{macro}{\nocite}
% \begin{macro}{\bibliographystyle}
% If |\nocite| or |\bibliographystyle| is issued, the default
% tags are discarded, the original meaning is restored, and the control
% sequence is reissued again.
%
%    \begin{macrocode}
\def\AddNocite{\nocite{*}}
\def\AddBibliographystyle{\bibliographystyle{listbib}}
\def\nocite{%
    \let\AddNocite\relax
    \let\nocite\@@nocite
    \nocite
    }
\def\bibliographystyle{%
    \let\AddBibliographystyle\relax
    \let\bibliographystyle\@@bibliographystyle
    \bibliographystyle
    }
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% 
% \subsection{Bibliographies and Title}
% 
% \begin{macro}{\bibliography}
% The |\bibliography| command will first issue the missing default
% tags, will produce a heading afterwards, will setup the headline, and
% will create the bibliography itself.
%    \begin{macrocode}
\def\bibliography#1{%
    \AddNocite
    \AddBibliographystyle
    \section*{\refname}%
    \mark_for_headline{#1}%
    \@@bibliography{#1}%
    }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\refname}
% The section heading text comes from |\refname|, which we give a new default.
% ^^A using "\ " after "\BibTeX" causes the space command to be indexed,
% ^^A even if it is listed with \DoNotIndex{}.
%    \begin{macrocode}
\def\refname{\BibTeX{} Database Listing}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\BibTeX}
% Provide |\BibTeX| if it has not yet been defined.
% This definition is taken from btxdoc.tex (compared with \LaTeX's definition
% of |\TeX|, this one has the ``E'' not touch the ``T'' and ``X''.
% Unfortunately the standard computer modern fonts do not supply a small caps
% bold, so we expect a NFSS warning when |\BibTeX| appears in the bold-faced
% section heading. That is, unless we do some trickery\ldots
%
%    \begin{macrocode}
\providecommand\BibTeX{%
    \textrm{B\kern-.05em%
        {\@tempdima\f@size pt\fontsize{0.83333\@tempdima}\z@\selectfont
         I\kern-.025em B}%
        \kern-.08em T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}%
    }
\providecommand\BibTeX{% one of the 2...
    \textrm{B\kern-.05em\textsc{i\kern-.025em b}%
        \kern-.08em T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}%
    }
%    \end{macrocode}
% \end{macro}
%
%
% \subsection{Page header}
%
% The page header shows the database names given with the
% |\bibliography| command and the current date.
% We do not issue a warning if no file name is given; this will be
% done by |\@@bibliography|. When a file name exists a comma and a
% space will be prepended at the very beginning of |\bib_list|. The
% comma is removed after the loop. When there was no file name
% |\bib_list| will expand to an empty list, the |\relax| serves as a
% catch-argument for |\@gobble|.
% 
% A |.bib| is no longer added to each bibliography filename to make the line
% shorter. If there are too many names the header won't fit on the page. This
% should be fixed somehow.
%
% ^^A    \@for \bib_file :=#1\do {\edef\bib_list{\bib_list, \bib_file.bib}}%
%    \begin{macrocode}
\def\mark_for_headline#1{%
    \def\bib_list{}%
    \@for \bib_file :=#1\do {\edef\bib_list{\bib_list, \bib_file}}%
    \edef\bib_list{\expandafter\@gobble\bib_list \relax}%
    \markboth{{\reset@font\ttfamily\bib_list}}{{\reset@font\ttfamily\bib_list}}%
    }
\def\@oddhead{\reset@font\rmfamily \hfil \leftmark \quad (\today)}
\def\@evenhead{\reset@font\rmfamily (\today)\quad \ignorespaces
    \rightmark \hfil}
%    \end{macrocode}
%
%
% \subsection{Site Configuration File}
%
% Further document settings can be placed into a site configuration file,
% \DescribeWord{listbib.cfg}
% which will be loaded if found. This is a good place to put some
% default margin settings, for example.
% 
%    \begin{macrocode}
\InputIfFileExists{listbib.cfg}{\typeout
    {*** listbib: site configuration file listbib.cfg found. ***}}{}
%    \end{macrocode}
%
%
% \subsection{Finish}
%
% We must restore our catcode and are finished.
%
%    \begin{macrocode}
\catcode`\_=\uscode
\endinput
%    \end{macrocode}
%
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
%
% \Finale
%
% \iffalse
% %% EOF listbib.dtx
% %%----------------------------------------------------------------------------
% \fi