summaryrefslogtreecommitdiff
path: root/macros/generic/librarian/doc
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/generic/librarian/doc
Initial commit
Diffstat (limited to 'macros/generic/librarian/doc')
l---------macros/generic/librarian/doc/generic/librarian/README1
-rw-r--r--macros/generic/librarian/doc/generic/librarian/librarian-doc.pdfbin0 -> 153869 bytes
-rw-r--r--macros/generic/librarian/doc/generic/librarian/librarian-doc.tex1271
-rw-r--r--macros/generic/librarian/doc/generic/librarian/librarian.bib39
4 files changed, 1311 insertions, 0 deletions
diff --git a/macros/generic/librarian/doc/generic/librarian/README b/macros/generic/librarian/doc/generic/librarian/README
new file mode 120000
index 0000000000..443793f937
--- /dev/null
+++ b/macros/generic/librarian/doc/generic/librarian/README
@@ -0,0 +1 @@
+../../../README \ No newline at end of file
diff --git a/macros/generic/librarian/doc/generic/librarian/librarian-doc.pdf b/macros/generic/librarian/doc/generic/librarian/librarian-doc.pdf
new file mode 100644
index 0000000000..2e3d0e84c8
--- /dev/null
+++ b/macros/generic/librarian/doc/generic/librarian/librarian-doc.pdf
Binary files differ
diff --git a/macros/generic/librarian/doc/generic/librarian/librarian-doc.tex b/macros/generic/librarian/doc/generic/librarian/librarian-doc.tex
new file mode 100644
index 0000000000..1beb373e01
--- /dev/null
+++ b/macros/generic/librarian/doc/generic/librarian/librarian-doc.tex
@@ -0,0 +1,1271 @@
+% This is the source of the documentation for the librarian package.
+% Proper compilation requires: luatex (v.0.51 or later), a recent
+% version of luaotfload, not to mention the Adobe Garamond Pro font,
+% which however might be replaced by URW's Garamond. The required format
+% is plain TeX in its modified luatex version.
+% Three compilations are needed to get examples right.
+%
+% Author: Paul Isambert.
+% E-mail: zappathustra AT free DOT fr
+% Comments and suggestions are welcome.
+% Date: April 2010.
+
+
+%%%%%%%%%%%%%%%%%
+%%%%% FONTS %%%%%
+%%%%%%%%%%%%%%%%%
+
+\input luaotfload.sty
+\pdfadjustspacing=2
+\directlua{%
+% From otfl-font-dum.lua
+ local byte = string.byte
+ fonts.expansions.setups['threepercent'] = {
+
+ stretch = 3, shrink = 3, step = .5, factor = 1,
+
+ [byte('A')] = 0.5, [byte('B')] = 0.7, [byte('C')] = 0.7, [byte('D')] = 0.5, [byte('E')] = 0.7,
+ [byte('F')] = 0.7, [byte('G')] = 0.5, [byte('H')] = 0.7, [byte('K')] = 0.7, [byte('M')] = 0.7,
+ [byte('N')] = 0.7, [byte('O')] = 0.5, [byte('P')] = 0.7, [byte('Q')] = 0.5, [byte('R')] = 0.7,
+ [byte('S')] = 0.7, [byte('U')] = 0.7, [byte('W')] = 0.7, [byte('Z')] = 0.7,
+ [byte('a')] = 0.7, [byte('b')] = 0.7, [byte('c')] = 0.7, [byte('d')] = 0.7, [byte('e')] = 0.7,
+ [byte('g')] = 0.7, [byte('h')] = 0.7, [byte('k')] = 0.7, [byte('m')] = 0.7, [byte('n')] = 0.7,
+ [byte('o')] = 0.7, [byte('p')] = 0.7, [byte('q')] = 0.7, [byte('s')] = 0.7, [byte('u')] = 0.7,
+ [byte('w')] = 0.7, [byte('z')] = 0.7, [byte('2')] = 0.7, [byte('3')] = 0.7, [byte('6')] = 0.7,
+ [byte('8')] = 0.7, [byte('9')] = 0.7,
+ }
+ }
+
+\def\currentstyle{rm}
+\def\currentweight{rg}
+\def\currentcase{lc}
+\def\makecurrentfont{%
+ \csname\currentfont @\currentstyle @\currentweight @\currentcase\endcsname
+ }
+
+\def\fontfeatures{+trep;+onum;+tlig;+liga;expansion=threepercent}
+\def\mainfont{%
+ \def\currentfont{Garamond}%
+ \csname\currentfont @\currentstyle @\currentweight @\currentcase\endcsname
+ }
+\expandafter\font\csname Garamond@rm@rg@lc\endcsname="AGaramondPro-Regular.otf:\fontfeatures" at 10pt
+\expandafter\font\csname Garamond@rm@bf@lc\endcsname="AGaramondPro-Bold.otf:\fontfeatures" at 10pt
+\expandafter\font\csname Garamond@rm@rg@sc\endcsname="AGaramondPro-Regular.otf:+smcp;\fontfeatures" at 10pt
+\expandafter\font\csname Garamond@rm@bf@sc\endcsname="AGaramondPro-Bold.otf:+smcp;\fontfeatures" at 10pt
+\expandafter\font\csname Garamond@it@rg@lc\endcsname="AGaramondPro-Italic.otf:\fontfeatures" at 10pt
+\expandafter\font\csname Garamond@it@bf@lc\endcsname="AGaramondPro-BoldItalic.otf:\fontfeatures" at 10pt
+\expandafter\font\csname Garamond@it@rg@sc\endcsname="AGaramondPro-Italic.otf:+smcp;\fontfeatures" at 10pt
+\expandafter\font\csname Garamond@it@bf@sc\endcsname="AGaramondPro-BoldItalic.otf:+smcp;\fontfeatures" at 10pt
+\mainfont
+
+\font\titlefont="AGaramondPro-Italic.otf:\fontfeatures" at 20pt
+
+\def\codefont{%
+ \def\currentfont{Inconsolata}%
+ \csname\currentfont @\currentstyle @\currentweight @\currentcase\endcsname
+ }
+\expandafter\font\csname Inconsolata@rm@rg@lc\endcsname="Inconsolata.Otf:\fontfeatures;-trep" at 8.5pt
+\expandafter\font\csname Inconsolata@rm@bf@lc\endcsname="Inconsolata.Otf:\fontfeatures;-trep" at 8.5pt
+%\expandafter\font\csname Inconsolata@rm@rg@sc\endcsname="Inconsolata.Otf:+smcp;\fontfeatures;-trep" at 8.5pt
+%\expandafter\font\csname Inconsolata@rm@bf@sc\endcsname="Inconsolata.Otf:+smcp;\fontfeatures;-trep" at 8.5pt
+\expandafter\font\csname Inconsolata@it@rg@lc\endcsname="Inconsolata.Otf:slant=.2;\fontfeatures;-trep" at 8.5pt
+\expandafter\font\csname Inconsolata@it@bf@lc\endcsname="Inconsolata.Otf:slant=.2;\fontfeatures;-trep" at 8.5pt
+%\expandafter\font\csname Inconsolata@it@rg@sc\endcsname="Inconsolata.Otf:slant=.2;+smcp;\fontfeatures;-trep" at 8.5pt
+%\expandafter\font\csname Inconsolata@it@bf@sc\endcsname="Inconsolata.Otf:slant=.2;+smcp;\fontfeatures;-trep" at 8.5pt
+
+\def\it{%
+ \def\currentstyle{it}%
+ \makecurrentfont
+ }
+\def\bf{%
+ \def\currentweight{bf}%
+ \makecurrentfont
+ }
+\def\sc{%
+ \def\currentcase{sc}%
+ \makecurrentfont
+ }
+\def\rm{%
+ \def\currentstyle{rm}%
+ \makecurrentfont
+ }
+\def\textit#1{{\it#1}}
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%
+%%%%% PAGE LAYOUT %%%%%
+%%%%%%%%%%%%%%%%%%%%%%%
+
+\baselineskip=12pt
+\topskip=\baselineskip
+\vsize=41\baselineskip
+\hsize=21pc
+\parfillskip=.5\hsize plus 1fil minus .4\hsize
+\pdfpagewidth=3\hsize
+\pdfpageheight=\pdfpagewidth
+\pdfhorigin=\dimexpr((\pdfpagewidth-2\hsize-1em)/2)
+\pdfvorigin=\pdfhorigin
+\parskip0pt \parindent0pt
+\frenchspacing
+
+\newbox\leftside
+\newif\ifleftside \leftsidetrue
+\output{%
+ \ifleftside
+ \global\setbox\leftside=\box255
+ \global\leftsidefalse
+ \else
+ \global\leftsidetrue
+ \shipout\hbox{%
+ \box\leftside\kern1em\box255
+ }%
+ \advancepageno
+ \fi
+ }
+
+
+
+%%%%%%%%%%%%%%%%%%%%
+%%%%% SECTIONS %%%%%
+%%%%%%%%%%%%%%%%%%%%
+
+\def\title#1{%
+ \hbox to \hsize{%
+ \vbox to 2\baselineskip{%
+ \vfill
+ \hbox{\titlefont\inred{#1}}%
+ \vfill
+ }%
+ \hfil
+ \vbox{%
+ \setbox0=\hbox{\texttt{zappathustra@free.fr}}%
+ \hbox to\wd0{\hfil\textit{Paul Isambert}}%
+ \box0}%
+ }%
+ }
+\newcount\sectioncount
+\def\onelineskip{\vskip\baselineskip}
+\def\makebookmarks{%
+ \def\lib{librarian}%
+ \def\TeX{TeX}}%
+\def\section#1{%
+ \onelineskip
+ \advance\sectioncount1
+ \subsectioncount=0
+ \expandafter\gdef\csname\the\sectioncount sub\endcsname{0}%
+ \xdef\makebookmarks{%
+ \unexpanded\expandafter{\makebookmarks
+ \pdfoutline goto name}{section\the\sectioncount}%
+ count -\unexpanded\expandafter{\csname\the\sectioncount sub\endcsname{#1}}%
+ }%
+ \pdfdest name{section\the\sectioncount} xyz\penalty10000
+ \noindent
+ {%
+ \parfillskip0pt plus 1fil
+ \hfil\inred{\sc#1}\par}\penalty10000
+ \everypar\expandafter{%
+ \expandafter\parindent\the\parindent
+ \everypar={}}%
+ \parindent=0pt
+ }
+\newcount\subsectioncount
+\newif\iflefttitle
+\def\subsection#1{%
+ \advance\subsectioncount1
+ \expandafter\xdef\csname\the\sectioncount sub\endcsname{%
+ \the\numexpr(1+\csname\the\sectioncount sub\endcsname)}%
+ \xdef\makebookmarks{%
+ \unexpanded\expandafter{\makebookmarks
+ \pdfoutline goto name}{section\the\sectioncount.\the\subsectioncount}%
+ \unexpanded{{#1}}%
+ }%
+ \onelineskip
+ \pdfdest name{section\the\sectioncount.\the\subsectioncount} xyz\penalty10000
+ \noindent
+ {%
+ \penalty0
+ \ifdim\pagetotal<\dimexpr(\pagegoal-\baselineskip)\relax
+ \ifleftside \lefttitletrue
+ \else \lefttitlefalse \fi
+ \else
+ \ifleftside \lefttitlefalse
+ \else \lefttitletrue \fi
+ \fi
+ \iflefttitle
+ \parfillskip0pt plus 1fil
+ \inred{\hbox to0pt{\hss\char"E09D\kern1em}\textit{#1}}
+ \else
+ \parfillskip0pt
+ \inred{\textit{#1}\hfill\hbox to0pt{\kern1em \char"E09D\hss}}
+ \fi
+ \par\penalty10000
+ }%
+ }
+
+
+
+%%%%%%%%%%%%%%%%%%%%
+%%%%% VERBATIM %%%%%
+%%%%%%%%%%%%%%%%%%%%
+
+\def\do#1{\catcode`#1=12}
+\def\verbatim{%
+ \bgroup
+ \parfillskip0pt plus 1fill
+ \onelineskip
+ \obeylines \dospecials
+ \def\par{\leavevmode\endgraf}%
+ \parindent=0pt
+ \codefont \getcode
+ }%
+\bgroup
+\catcode`\|=0
+\catcode`\\=12
+|long|gdef|getcode#1\endverbatim{#1|egroup|onelineskip}%
+|egroup
+\newbox\cmdbox
+\def\command#1{%
+ \bgroup
+ \codefont
+ \string#1%
+ \egroup
+ }
+\def\cmd#1{%
+ \inred{\command{#1}}%
+ }
+\def\tcmd#1{%
+ \command{#1}%
+ }
+\def\cmddef{%
+ \onelineskip\subcmddef
+ }
+\def\subcmddef#1{%
+ \noindent{\bf\cmd{#1}\parfillskip0pt plus 1fil \par}%
+ \penalty10000\noindent\ignorespaces
+ }
+\def\arg#1{%
+ \bgroup
+ \codefont
+ \textit{\lower.08em\hbox{\char"003C}#1\lower.08em\hbox{\char"003E}}%
+ \egroup
+ }
+\def\marg#1{%
+ \char"007B\arg{#1}\char"007D
+ }
+\def\targ#1{%
+ \texttt{\char"007B #1\char"007D}%
+ }
+\def\field#1{\texttt{\inred{#1}}}
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%
+%%%%% SOME MACROS %%%%%
+%%%%%%%%%%%%%%%%%%%%%%%
+
+\def\texttt#1{{\codefont#1}}
+\def\inred{\incolor{.7 0 .1}}
+\long\def\incolor#1#2{%
+ \pdfliteral{#1 rg}%
+ #2%
+ \pdfliteral{0 0 0 rg}%
+ }
+\def\lib{\textit{librarian}}
+\def\LaTeX{La\TeX} \def\ConTeXt{Con\TeX t}
+\long\def\citation#1\endcitation{%
+ \onelineskip
+ \bgroup
+ \advance\leftskip2em \rightskip\leftskip
+ \incolor{.1 0 .5}{#1}\par
+ \egroup
+ \onelineskip
+}
+
+
+\pdfinfo{%
+ /Title (librarian-doc.pdf)
+ /Author (Paul Isambert)
+ }
+\pdfcatalog{%
+ /PageMode /UseOutlines
+ }
+
+\input librarian
+\title{Librarian}
+
+\section{Introduction}
+
+\textit{Librarian} is a set of macros that handles bibliographic
+references without Bib\TeX. It reads bibliographic files, extracts
+information about entries, and sorts lists of entries according to
+that informa\-tion and the user's specifications. \TeX\ code can then
+be written to typeset citations and bibliographies or more generally
+to write the equivalent of \texttt{bst} files, and absolutely
+no knowledge of the Bib\TeX\ language is needed, nor is Bib\TeX\ itself.
+
+The package is low-level in the sense that it doesn't do much more
+than what's said above and offers little syntactic sugar to typeset
+bibliographies. It is meant to make as few meaningful decisions as
+possible, where `meaningful decisions' means operations that influence
+the output or what the user can do. The way \lib\ extracts information
+is immaterial (barring efficiency, of course) to the typesetting of
+a bibliography, which depends strictly on the user's knowledge in
+\TeX\ programming. On the contrary, predefined styles, for instance,
+would be easier indeed but also more limited.
+
+Besides, \lib\ is format-independent, relying on plain \TeX's usual
+allocation macros only (which are similar in other formats, as far
+as I can tell). Thus, a well-written bibliographic style should
+work equally well in all formats; by `well written' I mean that it does
+not use any format-specific commands, and at worst defines aliases
+to those commands at the beginning of the file.
+
+The first part of this document is a reference manual where \lib\
+is explained thoroughly. The second part spells out a pair of
+examples of bibliographic styles; the second example gives details
+on the important parts of the file \texttt{authoryear.tex}, which
+is distributed with the package and can be used as is.
+
+
+
+
+
+\section{Reference manual}
+
+\subsection{How to load \lib}
+
+In plain, the package is loaded in the good old way:
+
+\verbatim
+\input librarian
+\endverbatim
+
+\noindent In La\TeX\ you must use the associated style file:
+
+\verbatim
+\usepackage{librarian}
+\endverbatim
+
+\noindent And in Con\TeX t you must load \lib\ with the
+third-party file:
+
+\verbatim
+\usemodule[librarian]
+\endverbatim
+
+\subsection{Commands}
+
+\cmddef{\Cite\marg{entry key}\marg{list}\marg{code1}\marg{code2}}
+This adds \arg{entry key} to \arg{list} (if the latter doesn't exist,
+it is created on the fly), unless it has already been added previously. If \arg{entry key}
+has already been read in the bibliography (most likely in a previous
+compilation), \cmd\EntryKey\ is set to \arg{entry key} and \arg{code1} is
+executed. Otherwise, \lib\ will read the bibliographic files to retrieve information
+about \arg{entrykey}, and for the moment \arg{code2} is executed (without
+redefining \tcmd\EntryKey). With complex bibliographic styles, this command is
+better embedded in macros.
+
+\cmddef{\BibFile\marg{list of files}}
+The \arg{list of files} is a comma-sepa\-rated list of bibliographic
+files in which \lib\ will dig information about the requested entries.
+The \texttt{.bib} extension is implicit, but you can give another
+one, as in \tcmd{\BibFiles\targ{mybib,myotherbib.tex}}. The information
+is passed to the next compilation thanks to an external file called
+\texttt{\arg{jobname}.lbr} (the culprit to delete if things seem wrong to you).
+If there remains no requested entry then the
+files aren't read. \tcmd\BibFile\ can occur several times in a document,
+but on each call, only those entries that have been \tcmd\Cite'd before
+will be searched for in the bibliographic files, because calls
+to \tcmd\Cite\ aren't passed from one compilation to the next. Most
+complex bibliographic styles generally require three compilations to
+get everything right.
+
+%%%% Pour la page suivante:
+\advance\vsize-\baselineskip
+%%%% Clumsy but I had no time to implement
+%%%% my own widow-killer here...
+
+\cmddef{\SortingOrder\marg{list of fields}\marg{name parts}}
+This sets the order in which lists will be sorted. The fields in
+\arg{list of fields} are the ones you find in Bib\TeX\ entries,
+plus the ones \lib\ adds to entries (like \texttt{name}), and they should
+be separated by commas. Any field can be prefixed with `\texttt{-}',
+which indicates that when it comes to this field entries will be
+sorted in reverse order. The sorting works as follows: when comparing
+two entries, \lib\ compares their values for the first field; if they
+are the same, it tries the second field, and so on. If \arg{list of fields}
+is exhausted, the entries are sorted according to the order of citation
+in the document relative to the list that's being scanned (i.e. the value
+of \tcmd\EntryNumber). The \arg{name parts}
+are concatenated letters, with `\texttt{f}' denoting first name, `\texttt{l}'
+denoting last name, `\texttt{v}' referring to the von part and `\texttt{j}'
+referring to the junior part; it sets how names are compared, and although
+there seems to be only two meaningful orders (\texttt{vlfj} and \texttt{lfvj}),
+differing in how the von part is taken into account, you can do whatever you
+want. Thus, \tcmd{\SortingOrder\targ{name,year,title}\targ{vlfj}} sorts entries in
+the `author year' style, with titles differentiating entries by the same
+author(s) written the same year, and with the von part taking precedence in
+the last name. Instead, \tcmd{\SortingOrder\targ{name,-year}\targ{lfvj}}
+will produce a bibliography sorted by names, with most recent references first,
+and similar references sorted according to their order in the document, while
+the von part doesn't matter in last names (and thus Ludwig van Beethoven is
+sorted before Franz Schubert). In any case, \arg{name parts} have nothing
+to do with how names are typeset in the bibliography. (In these examples,
+\texttt{name} is used instead of \texttt{author} or \texttt{editor} on purpose.
+See below about the \texttt{name} field.) By default, \lib\ doesn't sort entries.
+
+\cmddef{\SortList\marg{list}}
+This sorts \arg{list} according to the latest value of \tcmd\SortingOrder.
+Thus different lists can be sorted with different orders. If \tcmd\SortList\
+is called before \tcmd\BibFile, then new entries will be sorted on the
+next compilation only. From one compilation to the next, \lib\ retains
+the previous sorted entries and sorts only new entries, and entries that
+are equal according to \tcmd\SortingOrder\ (because their relative order
+may have changed). This saves time (especially in Lua\TeX\ where the many
+calls to \tcmd\directlua\ are quite time-consuming). However, if the value
+of \tcmd\SortingOrder\ when \tcmd\SortList\ is called has changed from the
+previous compilation, all entries are sorted again.
+
+\cmddef{\ReadList\marg{list}}
+This loops over entries in \arg{list}, and for each it stores its key
+in \cmd\EntryKey\ and calls \cmd\MakeReference, which by default does nothing,
+and should be redefined to typeset the entry. For each entry you can use
+the \cmd\ifequalentry\ conditional, which is true if the current entry
+is part of a set of entries that are equal with regard to \tcmd\SortingOrder\
+and are thus distinguished by citation order only, and false otherwise.
+If the list is unsorted (i.e. \tcmd\SortingOrder\ is empty), then \tcmd\ifequalentry\
+is always false, even though all entries are equal.
+
+
+
+\cmddef{\SortDef\marg{command}\marg{definition}}
+This defines \arg{command} as \arg{defi\-nition} at sorting time.
+Indeed, macros shouldn't hinder sorting. However, \tcmd\TeX\ won't
+be read as `TeX' and \textit{\TeX book} won't be sorted after
+\textit{Tao Te Ching} but rather after \textit{Typographic Investigations},
+because macros separate letters. So
+\tcmd{\SortDef\tcmd\TeX\targ{tex}} is the proper way to get good sorting
+(everything is sorted in lowercase, so no need to use `\texttt{TeX}').
+\tcmd\SortDef\ can't define with parameter text, but a macro can
+be defined to another one taking arguments, although it is generally
+unnecessary: all braces are removed at sorting time. It is probably
+very important to redefine accents (\lib\ doesn't), e.g. \tcmd{\SortDef\string\'\targ{}}
+is vital if you want to see B\char"00E9 zier between Bernoulli and Boole.
+
+\cmddef{\WriteInfo\marg{arg}}
+\subcmddef{\WriteImmediateInfo\marg{arg}}
+Since \lib\ reads and rewrites an external file on each compilation,
+you can use it too. This writes \arg{arg} to that file, so that it is
+made available for the next compilation; \arg{arg} is expanded as in
+any \tcmd\write\ statement. \tcmd\WriteInfo\ writes at output time,
+whereas \tcmd\WriteImmediateInfo\ writes immediately.
+
+\cmddef\Preamble
+This holds everything that has been encountered in \texttt{@preamble}
+entries when reading bibliographies. It isn't passed from one compilation
+to the next.
+
+%%%% Pour la page suivante:
+\advance\vsize\baselineskip
+\cmddef{\CreateField\marg{field}}
+If a field is unknown to \lib\ (there is no restriction in bibliographic entries),
+\lib\ complains when asked to retrieve it with the commands below. This command
+just enables it to work with unknown fields. By default, \lib\ knows the common
+Bib\TeX\ fields and its own, of course.
+
+\cmddef{\AbbreviateFirstname}
+This turns first names into initials, e.g. \textit{John} into \textit{J.} and
+\textit{Jean-Luc} into \textit{J.-L.} In order to get \textit{Ch.} from
+\textit{Charles}, the name in the bibliographic file should be
+`\texttt{\char`\{Ch\char`\}arles}', which is already the case for Bib\TeX.
+Note that \lib\ sorts full names and thus \textit{J(ohn) Doe} and \textit{J(ack) Doe}
+are different in this respect, even though they'll be indistinguishable in your
+bibliography.
+
+
+
+
+
+
+\onelineskip
+The following macros all come in pairs made of \tcmd\Command\ and \tcmd\CommandFor,
+where \tcmd\Command\ is \tcmd\CommandFor\ with \arg{entry key} set to \tcmd\EntryKey.
+All along, I refer to bibliographic entries, naturally, and \textit{field\/} and \textit{value\/}
+are to be understood in that context (see the next two sections for details).
+
+\cmddef{\RetrieveField\marg{field}}
+\subcmddef{\RetrieveFieldFor\marg{field}\marg{entry key}}
+This produces the value of \arg{field} for \arg{entry key}. The command
+uses \tcmd\lowercase, so you should use it with care, and basically avoid it
+unless for typesetting fields. The following command should be preferred
+if anything must be manipulated.
+
+\cmddef{\RetrieveFieldIn\marg{field}\marg{command}}
+\subcmddef{\RetrieveFieldInFor\marg{field}\marg{entry key}\marg{command}}
+This one defines \arg{command} as the value of \arg{field} for \arg{entry key}.
+If \arg{field} doesn't exist in \arg{entry key}, or else if \arg{entry key}
+doesn't exist, then \arg{command} is defined as an empty command and
+is equivalent to \tcmd\empty\ if the latter is defined as
+\tcmd\def\tcmd\empty\texttt{\char`\{\char`\}}. Quite convenient for testing.
+
+\cmddef{\EntryNumber\marg{list}}
+\subcmddef{\EntryNumberFor\marg{entry key}\marg{list}}
+This returns \textit{n} if \arg{entry key} is the \textit{n}th entry
+in \arg{list}, i.e. if it is the \textit{n}th entry to be cited for the
+first time in \arg{list}.
+
+\cmddef{\EntryNumberIn\marg{list}\marg{command}}
+\subcmddef{\EntryNumberInFor\marg{entry key}\marg{list}\marg{command}}
+This defines \arg{command} as \textit{n}, where \textit{n} is defined
+as above. (Beware that \arg{command} is a macro whose expansion produces
+a number, not an integer denotation.) This is safer than the previous command
+for the same reason as with \tcmd\RetrieveFieldFor, and is emptily defined
+under the same circumstances.
+
+\cmddef{\ReadName\marg{code}}
+\subcmddef{\ReadNameFor\marg{entry key}\marg{code}}
+For each person in the \texttt{name} field for \arg{entry key}, this stores the first name
+in \cmd\Firstname\ (abbreviated if \tcmd\AbbreviateFirstname\ was called),
+the last name in \cmd\Lastname, the von part in
+\cmd\Von\ and the junior part in \cmd\Junior. There is also a
+number \cmd\NameCount, which holds the place of the person in the
+\texttt{name} field (i.e. the first author has \tcmd\NameCount\texttt{=1}).
+Finally, \arg{code} is called with those values. There are aliases
+\cmd\ReadNames\ and \cmd\ReadNamesFor. \cmd\ReadAuthor, \cmd\ReadAuthorFor,
+\cmd\ReadEditor\ and \cmd\ReadEditorFor, and the versions with plural as well,
+are defined equivalently for the \texttt{author} and
+\texttt{editor} fields respectively. You can still use \tcmd{\RetrieveField
+\targ{author}}, for instance, but those fields aren't designed
+for typesetting in their basic form, hence this command.
+
+\cmddef{\TypesetField\marg{field}\marg{command}\marg{code}}
+\subcmddef{\TypesetFieldFor\marg{field}\marg{entry key}\marg{command}\marg{code}}
+If \arg{field} isn't empty in \arg{entry key}, \arg{command} is
+executed with the value of \arg{field} as its argument. So
+\arg{command} should be a macro that takes one (and only one) argument.
+If \arg{field} is empty, \arg{code} is executed instead.
+
+
+
+
+
+
+
+
+\subsection{Fields}
+Beside the fields that are found in bibliographic entries, \lib\ adds
+some of its own, which can be convenient for dealing with references.
+Here they are.
+
+The \field{entrytype} field contains the type of the entry as recorded
+in \texttt{bib} files at the beginning of each entry after the
+\texttt{@} sign. Thus
+
+\verbatim
+@Book{Coover2002,
+ ...
+}
+\endverbatim
+
+\noindent has `\texttt{book}' as the value for \texttt{entrytype}. Note
+that lowercase is always used, whatever the actual case in the \texttt{bib} file.
+The number of authors in the \texttt{author} field is the value of the \field{authornumber}
+field, each author being distinguished from the next by the customary `\texttt{and}'.
+An equivalent field, \field{editornumber}, does the same for \texttt{editor}.
+Most importantly, the \field{name} field holds the same value as \texttt{author}
+if there is such a field in the entry, or the value of \texttt{editor}
+it it exists and there is no \texttt{author}. Thus edited books can be
+cited along with normal books. That's why \texttt{name} appeared in
+\tcmd\SortingOrder\ above: if it had been \texttt{author}, then collective
+works wouldn't have been sorted correctly. Along with \texttt{name},
+\field{namenumber} holds the value either of \texttt{authornumber} or
+of \texttt{editornumber}, according to the same rule. Finally, \field{nametype}
+takes one out of two values: \texttt{author} or \texttt{editor}. It
+takes the former if the \texttt{name} field is set to the value of the \texttt{author}
+field, and the latter if it is set to the value of the \texttt{editor} field.
+Thus, when referencing collective works in a bibliography, you can add
+`(ed.)' for instance after the value of \texttt{name} if \texttt{nametype}
+is \texttt{editor}.
+
+
+
+
+\subsection{A crash course in bibliographic entries (and how \lib\ reads them)}
+This section is not necessary to the understanding of \lib\ but it can be
+useful if in trouble. Suppose you have the following entry:
+
+\verbatim
+@Book{Coover2002,
+ author = {Coover, Robert},
+ title = {The Adventures of Lucky Pierre},
+ subtitle = {Director's Cut},
+ publisher = "Grove Press",
+ Address = {New York},
+ year = 2002,
+}
+\endverbatim
+
+\noindent Then \lib\ stores all the fields for the `\texttt{coover2002}' entry key.
+This key is in lowercase, and thus you can't distinguish two entries by case only
+(this is how Bib\TeX\ works). This doesn't mean that you can't use
+\tcmd{\Cite\targ{Coover2002}\targ{list}}: \lib\ does the necessary conversion.
+The \texttt{entrytype} field is set to `\texttt{book}', in lowercase once again, and
+this time you must be careful: `\texttt{book}' is a value, and since you'll probably
+test it to know how the reference should be typeset in the bibliography, you
+shouldn't compare it to, say, `\texttt{Book}', of course. And to finish with
+lowercase, `\texttt{New York}' is the value of the \texttt{address} field,
+not \texttt{Address}, but once again \lib\ does the conversion so you can call
+\tcmd{\RetrieveField\targ{Address}\targ{cooVEr2002}}. Finally, the \texttt{subtitle}
+field is no customary field, but you can use it. Up to there, \lib\ works
+exactly like Bib\TeX.
+
+But there are differences too. For one thing, \lib\ has no restriction on the type
+of the entry, so you could have:
+
+\verbatim
+@novel{Coover2002,
+ author = {Coover, Robert},
+ title = {The Adventures of Lucky Pierre},
+ subtitle = {Director's Cut},
+ publisher = "Grove Press",
+ Address = {New York},
+ year = 2002,
+}
+\endverbatim
+
+\noindent That's perfectly fine with \lib, although not with Bib\TeX.
+There are no restrictions on fields either, and unlike Bib\TeX\ fields
+aren't labelled as required or optional or ignored; in a bibliographic
+style you can issue an error message if a field is missing, but \lib\
+won't do it for you. And there are
+annoying differences too. They occur in the way \lib\ reads the values of
+fields. Here's how it works: if the first character (disregarding space) after
+the `\texttt{=}' sign is a~\texttt{\string{}, then everything up to the next
+balanced~\texttt{\string}} is taken as the value, and everything up to the comma
+is discarded. (The last value of the entry may have no comma, but \lib\ adds one
+before reading the entry.) If the first character is a~\texttt{\string"}, then
+everything up to the next~\texttt{\string"}, with balanced braces, is taken
+as the value, and everything up to the comma is discarded once again. Finally,
+if the first character is none of the above, then \lib\ takes everything up
+to the next comma as the value (while balancing braces, of course). The latter
+case differs from Bib\TeX. Normally, only numerical values (like the value of
+\texttt{year} in our example) can be given as such, unless strings are used.
+But \lib\ is totally unable to understand strings. The following
+
+\verbatim
+@string{ny = "New York"}
+@Book{Coover2002,
+ author = {Coover, Robert},
+ title = {The Adventures of Lucky Pierre},
+ subtitle = {Director's Cut},
+ publisher = "Grove Press",
+ Address = ny,
+ year = 2002,
+}
+\endverbatim
+
+\noindent would yield `\texttt{New York}' as the value of \texttt{address} in
+Bib\TeX, whereas with \lib\ it gives `\texttt{ny}' (and the \texttt{@string}
+entry is simply ignored). In a situation as simple as the present one, you can
+make do with macros in you document, i.e. a macro which when fed with `\texttt{ny}'
+returns `\texttt{New York}' (problems arise if `\texttt{ny}' is the \textit{real}
+value of a field, though), but it becomes more serious when you concatenate strings
+with the \texttt{\string#} operator. No way to hide the truth: \lib\ will get
+everything wrong. So if you're heavy on strings, better stick to Bib\TeX.
+
+
+
+
+
+
+\section{Examples}
+Although \lib\ doesn't use many commands, it might be hard to understand them
+from scratch. This section details a pair of example styles so you can get
+familiar with how things work. The first example is stripped to the minimum
+just to learn the basic use of \lib's macros.
+The second example is an \textit{Author~(Year)} style
+with some refinements, dealing in particular with entries that have the same
+author and the same year and should thus be distinguished by a suffix, and it
+also shows how to handle cross-references. This style is thoroughly defined
+in the file \texttt{authoryear.tex}, distributed with \lib.
+
+Remember, though, that what you can do in \lib\ is what you can do in \TeX.
+There's nothing arcane in \lib, and what you can achieve depends really
+on your skill in \TeX. So don't feel limited; for instance, suppose you
+want to make a list of your publications like:
+
+\citation
+{\it2010}\par
+`My fascinating paper', {\it Journal of Science}, volume 55 (22), 210--224.\par
+{\it The book I finally wrote}, Good Publishing House: City\-ville.\par
+{\it2009}\par
+`A talk on something', presented at...
+\endcitation
+
+\noindent That is, you want the year to be set above the entries, not
+repeated each time: then, for each entry, retrieve its \texttt{year}
+in a macro, and on the next one, compare with the current year. If it
+has changed, print the new value. (Of course entries should be sorted
+by date, otherwise it doesn't make sense.)
+
+Another example: \lib\ doesn't abbreviate journal titles. But if you think
+in \TeX, it is easily solved: just create a function from a journal title
+to its abbreviation (if any), and call it on the value of the \texttt{journal}
+field... and so on and so forth...
+
+
+
+\subsection{A simple unsorted list with numerical references, which gets sorted later}
+Our first example simply doesn't sort entries, and they are cited with
+the number they get when they appear. To make things a little funnier,
+though, we'll have a case of multiple bibliographies, e.g. one bibliography
+per chapter. In each chapter we set \tcmd\currentchapter, and \tcmd\cite\
+is as follows:
+
+\verbatim
+\def\cite#1{%
+ \Cite{#1}{\currentchapter}%
+ {[\EntryNumber{\currentchapter}]}{[??]}%
+ }
+...
+\def\currentchapter{chapter1}
+\endverbatim
+
+\noindent And at the end of the chapter we'll have:
+
+\verbatim
+\ReadList{\currentchapter}
+\endverbatim
+
+\noindent whereas the \tcmd\BibFile\ command will appear
+at the end of the book. What \tcmd\cite\ does is: store
+the entry in the list associated with the chapter, print
+`[??]' if there's no information associated with that entry (probably
+because it hasn't been read in the bibliographic file yet) and
+`[n]' instead, where \textit{n} is its number in that list, e.g.
+`[3]' if that's the third entry in that chapter.
+
+When \tcmd\ReadList\ is called, we need to have \tcmd\MakeReference\
+ready, so here it is:
+
+\verbatim
+\def\empty{}
+\def\MakeReference{%
+ \par \noindent
+ \llap{[\EntryNumber{\currentchapter}]~}%
+ \RetrieveFieldIn{namenumber}\tempcount
+ \ifx\tempcount\empty
+ \def\tempcount{0}%
+ \fi
+ \ReadName\makerefname.
+ \RetrieveField{title}.
+ \RetrieveField{year}.\par
+ }
+\endverbatim
+
+This produces `[n]' in the left margin (with plain \TeX's \tcmd\llap\
+macro), and prints the name, the title, the year, separated by dots
+and a space. To put it simply, that's an utterly boring citation style,
+which doesn't take the entry type into account. The thing about \tcmd\tempcount\
+is: we'll need it in \tcmd\ReadName\ with \tcmd\makerefname\ to check
+whether we're at the last author. So we need it as a number; however,
+on the first compilation, since \tcmd\BibFile\ appears after \tcmd\ReadList,
+entries have no \texttt{namenumber} field, and thus \tcmd\tempcount\ is
+empty... which is a very bad idea in an \tcmd\ifnum\ test. In that case
+we set it to 0. Now here how names are typeset:
+
+\verbatim
+\def\space{ }
+\def\makerefname{%
+ \ifnum\NameCount>1
+ \ifnum\NameCount=\tempcount\relax \space and \else , \fi
+ \fi
+ \Firstname
+ \unless\ifx\Von\empty \Von\space \fi
+ \space\Lastname
+ \unless\ifx\Junior\empty , \Junior \fi
+ }
+\endverbatim
+
+\noindent We check for the existence of the von and junior parts and
+put them conditionally. Names are separated by a comma except the last
+one which takes `and' instead. Note the crucial \tcmd\relax\ after
+\tcmd\tempcount: the latter is a macro expanding to a number, and it
+would gobble the next \tcmd\space\ if \tcmd\relax\ wasn't there.
+I could have swapped \tcmd\NameCount\ and \tcmd\tempcount, since the
+former is a real integer denotation, but we would have missed this
+fascinating conversation.
+
+Now we're done with that style. Suppose however we want sorted entries.
+For instance:
+
+\verbatim
+\SortingOrder{name,year,title}{lfvj}
+\endverbatim
+
+Now, citing entries with the citation number isn't very convenient.
+Instead, we want a number associated with the entry in the sorted
+list. We need a new count, and on each chapter it should be reset to
+0. For instance:
+
+\verbatim
+\newcount\entrycount
+...
+\def\currentchapter{chapter24}
+\entrycount=0
+\endverbatim
+
+\noindent Next, we redefine \tcmd\cite\ as follows:
+
+\verbatim
+\def\cite#1{%
+ \Cite{#1}{\currentchapter}%
+ {[\csname\EntryKey @\currentchapter\endcsname]}%
+ {[??]}%
+ }
+\endverbatim
+
+\noindent Now \tcmd\cite\ calls a command associated with the key
+(note that \tcmd\EntryKey\ is useless, we could have used \texttt{\#1}
+directly) and the chapter, which holds the number we want. The latter
+was set in \tcmd\MakeCitation, redefined as:
+
+\verbatim
+\def\MakeReference{%
+ \par \noindent
+ \advance\entrycount1
+ \WriteImmediateInfo{%
+ \noexpand\expandafter\def
+ \noexpand\csname\EntryKey @\currentchapter
+ \noexpand\endcsname{\the\entrycount}%
+ }%
+ \llap{[\the\entrycount]~}%
+% ... same as before
+ }
+\endverbatim
+
+\noindent This means: on each entry, advance \tcmd\entrycount\ and
+store its value as the expansion of the command seen above, thanks
+to \tcmd\WriteImmediateInfo. The rather clumsy code in the latter
+just means that the following will be written to the external file:
+
+\verbatim
+\expandafter\def\csname coover2002@chapter24\endcsname{13}
+\endverbatim
+
+And of course, it is the value of \tcmd\entrycount\ that we put into the left margin.
+Note that this style takes three compilations to get everything right:
+in the first one, a new entry can't be sorted, because \tcmd\SortList\
+appears before \tcmd\BibFile. In the second compilation, the entry is
+sorted and its number is written to the external file. In the last one,
+that number is read and used when the entry is cited. Here's the style
+it produces:
+
+
+%\input unsorted
+%\Cite{Wallace2004}{\currentchapter}{}{} \Cite{Wallace1996}{\currentchapter}{}{}
+%\citation
+%Wallace's last book \cite{Wallace2004} was published eight years after his cult
+%novel \cite{Wallace1996}.\par
+%...\par
+%\SortList{\currentchapter}
+%\ReadList{\currentchapter}
+%\endcitation
+
+\Cite{Wallace2004}{empty}{}{} \Cite{Wallace1996}{empty}{}{}
+\citation
+Wallace's last book [2] was published eight years after his cult
+novel [1].\par
+...\par
+\quitvmode\llap{[1]~}David Foster Wallace. \RetrieveFieldFor{title}{Wallace1996}. \RetrieveFieldFor{year}{Wallace1996}.\par
+\quitvmode\llap{[2]~}David Foster Wallace. \RetrieveFieldFor{title}{Wallace2004}. \RetrieveFieldFor{year}{Wallace2004}.\par
+\endcitation
+
+
+
+
+
+\subsection{An Author (Year) style, with similar entries and cross-references}
+The basic idea here is to have a command \tcmd{\cite\targ{entry key}}
+that produces an \textit{Author~(Year)} citation in the main document
+(rather \textit{Name~(Year)}, but whatever). References are thus sorted
+according to names and then year, and if two entries are equal with
+regard to these fields, they should be sorted according to their relative
+order of appearance in the document and distinguished with a suffixes,
+e.g. `Wallace~(2003a)' and `Wallace~(2003b)'. To do so we'll use \tcmd\ifequalentry\
+and \tcmd\WriteImmediateInfo.
+
+However, such a simple \tcmd\cite\ is definitely not very fun. So let's
+make it harder: it will take any number of entry keys and separate them
+with commas (e.g. `Wallace~(1996), Coover~(2002)') unless the \texttt{name}
+field is identical, in which case it won't be repeated and the year
+will be put between the same parentheses as the previous entry
+(e.g. `Wallace~(1996, 2003)'). So \tcmd\cite\ actually calls a
+recursive macro (\tcmd\readcite) on its argument. Here's how it goes.
+(Since \lib\ requires e\TeX, we can use it too; if you don't know anything
+about it, the only important thing is that you can prefix a conditional
+with \tcmd\unless\ to reverse its evaluation; i.e.
+\tcmd{\unless\tcmd\ifwhatever\ A\tcmd\else\ B\tcmd\fi} is the same as
+\tcmd{\ifwhatever\ B\tcmd\else\ A\tcmd\fi}. It's useful to write
+\tcmd{\unless\tcmd\ifwhatever} instead of \tcmd{\ifwhatever\tcmd\else}
+when you're interested in the false condition only.)
+
+\verbatim
+\def\terminator{\terminator} \def\empty{}
+\def\cite#1{%
+ \def\prevauthor{}%
+ \readcite#1,\terminator,%
+ }
+\def\readcite#1,{%
+ \def\temp{#1}%
+ \ifx\temp\terminator
+ )%
+ \let\tail\relax
+ \else
+ \let\tail\readcite
+ \unless\ifx\temp\empty
+ \Cite{#1}{main}\makecitation{}%
+ \fi
+ \fi\tail
+ }
+\endverbatim
+
+\noindent Since we don't know what the next entry will be, if any,
+the final parenthesis is typeset when \tcmd\readcite\ meets the
+terminator. (We take care of empty entries in case one writes
+`\tcmd{\cite\targ{entry1,entry2,}}' by mistake, which becomes
+`\texttt{entry1,entry2,,\string\terminator,}' for \tcmd\readcite.)
+Note that in \texttt{authoryear.tex}, `(' and `)' are actually
+replaced by macros (\tcmd\leftcitemark\ and \tcmd\rightcitemark)
+that are defined as parentheses; it simply makes the switch to
+another style easier.
+
+All entries are added to the \texttt{main} list, and at the end
+of the document we'll have to write:
+
+\verbatim
+% Perhaps some \SortDef's?
+\BibFile{myfiles}
+\SortingOrder{name,year}{lfvj}
+\SortList{main}
+\ReadList{main}
+\endverbatim
+
+But back to citation. \tcmd\readcite\ calls \tcmd\makecitation\
+in case there are fields for the entry. Here it is. If the current
+author is the same as in the previous entry (recorded in
+\tcmd\prevauthor), then we just add a command and a space
+to the previous date:
+
+\verbatim
+\def\makecitation{%
+ \RetrieveFieldIn{name}\temp
+ \ifx\temp\prevauthor ,
+\endverbatim
+
+\noindent On the other hand, if authors differ (unless the previous
+one is empty, which means we're on the first citation), we close
+the parenthesis (always added by the next entry to the previous
+one, remember?), adds a comma and a space to separate entries,
+and typeset the name with \tcmd\ReadName\ (which will make
+use of \tcmd\tempcount). We also typeset an opening parenthesis
+preceded by a hard space to welcome the upcoming year.
+
+\verbatim
+ \else
+ \unless\ifx\prevauthor\empty ),\fi
+ \RetrieveFieldIn{namenumber}\tempcount
+ \ReadName\makecitename~(%
+ \fi
+\endverbatim
+
+\noindent And in any case we set \tcmd\prevauthor\ to the
+current value of \texttt{name}, typeset the year and
+add the suffix associated with that entry if it exists
+(it is created when we use \tcmd\ReadList), somehow like
+the entry number in the previous example.
+
+\verbatim
+ \RetrieveFieldIn{name}\prevauthor
+ \RetrieveField{year}\csname\EntryKey @suffix\endcsname
+ }
+\endverbatim
+
+Now here's how names are typeset: they are separated by
+commas, except the last one which is separated by \textit{and}
+(e.g. `Jackson, Jameson and Johnson~(1980)'). Besides, if there
+are more than 3 authors, only the first one is typeset,
+followed by \textit{et alii}. The number 3 is of course
+totally arbitrary. Finally, each name is typeset as
+\texttt{\string\Von\string~\string\Lastname} with the \tcmd\Von\
+part optional, of course (maybe that makes too many hard
+spaces, though). Remember that \tcmd\tempcount\ holds the value of
+the \texttt{namenumber} field and that \tcmd\NameCount\ is
+the place of the author under investigation in the entire field.
+Hence, if they are more authors than allowed:
+
+\verbatim
+\chardef\namelimit=3
+\def\makecitename{%
+ \ifnum\tempcount>\namelimit
+ \ifnum\NameCount=1
+ \unless\ifx\Von\empty \Von~\fi
+ \Lastname\space {\italics{et alii}}%
+ \fi
+\endverbatim
+
+\noindent Otherwise we typeset all names preceded by
+different markers: nothing for the first author, \textit{and}
+for the last one, and commas in between.
+
+\verbatim
+ \else
+ \unless\ifnum\NameCount=1
+ \ifnum\NameCount=\tempcount\relax \space and
+ \else , \fi
+ \fi
+ \unless\ifx\Von\empty \Von~\fi
+ \Lastname
+ \fi
+ }
+\endverbatim
+
+\noindent And we're done with the \tcmd\cite\ command. We could
+add variation, e.g. \tcmd\citeauthor\ to typeset the \texttt{name}
+field, \tcmd\citeyear\ for the date, remove parentheses when needed,
+etc., but basically we've done the hardest part. The \tcmd\makecitename\
+macro shown here is slightly simpler than the real one in
+\texttt{authoryear.tex}. The latter first checks whether \tcmd\Lastname\
+is `\texttt{others}', in which case it typesets the \textit{et alii}
+phrase (a basic feature of Bib\TeX).
+
+Now we have to define \tcmd\MakeCitation. It begins with \tcmd\ReadName\
+called with \tcmd\makerefname\ as in the previous example. Even though
+\tcmd\makrefname\ is slightly different (the first author is typeset
+as \textit{von Last, Jr, First} whereas the other authors remain in the
+\textit{First von Last, Jr} style), I won't show it here,
+because there's nothing much to learn.
+
+\verbatim
+\def\MakeReference{%
+ \par\noindent
+ \RetrieveFieldIn{namenumber}\tempcount
+ \ReadName\makerefname
+\endverbatim
+
+\noindent In \tcmd\MakeReference\ still, we add a usual marker for collective
+works (\tcmd\editor\ is simply defined as `\texttt{editor}' elsewhere).
+
+\verbatim
+ \RetrieveFieldIn{nametype}\temp
+ \ifx\temp\editor
+ \RetrieveFieldIn{namenumber}\temp
+ \ifnum\temp>1 \space (eds.)\else \space (ed.)\fi
+ \fi
+\endverbatim
+
+\noindent Then we typeset the date between parentheses with a suffix,
+which will be set by \tcmd\comparentries\ (and actually probably empty).
+This suffix is meant to distinguish entries that are equal according to
+\tcmd\SortingOrder.
+
+\verbatim
+ \space (\RetrieveField{year}%
+ \csname\EntryKey @suffix\endcsname)
+ \compareentries
+\endverbatim
+
+\noindent Typesetting the rest of the entry depends on the entry type,
+which is fed to \tcmd\typesetref. At the end of the entry we call
+\tcmd\conditionalstop, a stop that appears if and only if there was no
+stop before (see \texttt{authoryear.tex} for details).
+
+
+\verbatim
+ \RetrieveFieldIn{entrytype}\temp
+ \typesetref\temp \conditionalstop
+ }
+\endverbatim
+
+The \tcmd\comparentries\ macro tests whether we are in equal entries
+relative to sorting and if so gives them a suffix.
+
+\verbatim
+\newcount\sameentrycount
+\def\compareentries{%
+ \ifequalentry
+ \advance\sameentrycount1
+ \WriteImmediateInfo{%
+ \noexpand\expandafter\def
+ \noexpand\csname\EntryKey @suffix\noexpand\endcsname
+ {\toletter}}%
+ \else \sameentrycount=0 \fi
+ }
+\endverbatim
+
+\noindent The \tcmd\toletter\ macro turns \tcmd\sameentrycount\
+into a letter and is quite uninteresting, so it isn't shown here.
+Note that this version of \tcmd\compareentries\ works because
+the first argument of \tcmd\SortOrder\ is set to `\texttt{name,year}',
+and hence two references written the same year by the same author
+are equal according to \lib, which can set the \tcmd\ifequelentry\
+conditional to the requested value. However, if \tcmd\SortOrder\
+was `\texttt{name,year,title}', then not only would the same two
+entries be sorted according to their titles,
+but most importantly they wouldn't be equal at all as far as \lib\
+is concerned (unless they have identical titles, of course),
+although in this bibliographic style they should be
+seen as such. In that case, \tcmd\compareentries\ should be more
+refined and store each entry's \texttt{name} and \texttt{year} fields
+in a macro to be compared to the next one.
+
+But we were calling \tcmd\typesetref\ on the \texttt{entrytype} field.
+It launches a macro which typesets the rest of the entry according
+to its type, and \tcmd\createtype\ is meant to define such a macro:
+
+\verbatim
+\def\typesetref#1{%
+ \ifcsname#1@entrytype\endcsname
+ \csname#1@entrytype\endcsname
+ \else
+ \errmessage{Unknown entry type: `#1'}%
+ \fi
+ }
+\def\createtype#1{%
+ \expandafter\def\csname#1@entrytype\endcsname
+ }
+\endverbatim
+
+Before creating entries, here are some useful macros to be used with
+\tcmd\TypesetField. Indeed, to typeset references properly, punctuation
+should be added if and only if the corresponding field exists.
+
+\verbatim
+\def\booktitle#1{\setbooktitle{\RetrieveField{#1}}}
+\def\setbooktitle#1{\italics{#1}}
+\def\articletitle#1{\setarticletitle{\RetrieveField{#1}}}
+\def\setarticletitle#1{`#1'}
+\def\addcomma#1{, #1}
+\def\addjournal#1{\addcomma{{\setbooktitle{#1}}}}
+\def\addcolon#1{: #1}
+\def\addpar#1{(#1)}
+\def\addbook#1{, in \setbooktitle{#1}}
+\def\addeditor#1{%
+ \RetrieveFieldIn{editornumber}\tempcount
+ , edited by \ReadEditor\makeedname}
+\endverbatim
+
+\noindent The \tcmd\italics\ macro in \tcmd\setbooktitle\ should
+be set to whatever you use to typeset italics. Now, we can create
+entries:
+
+\verbatim
+\createtype{book}{%
+ \booktitle{title}%
+ \TypesetField{publisher}\addcomma{}%
+ \TypesetField{address}\addcolon{}%
+ }
+\createtype{article}{%
+ \articletitle{title}%
+ \TypesetField{journal}\addjournal{}%
+ \TypesetField{volume}\addcomma{}%
+ \TypesetField{number}\addpar{}%
+ \TypesetField{pages}\addcomma{}%
+ }
+\createtype{incollection}{%
+ \articletitle{title}%
+ \TypesetField{crossref}\crossref{%
+ \TypesetField{booktitle}\addbook{}%
+ \TypesetField{editor}\addeditor{}%
+ \TypesetField{pages}\addcomma{}%
+ \TypesetField{publisher}\addcomma{}%
+ \TypesetField{address}\addcolon{}%
+ }%
+ }
+\endverbatim
+
+\noindent ... and many more! That's the basic job of a bibliographic
+style. Note that we make good use of \tcmd\TypesetField, but not with
+the \texttt{title} field, because it is very unlikely to be missing.
+Now, give a look at the \texttt{incollection} entry; once the title
+is typeset, it reads as follows: call the \tcmd\crossref\ macro on the
+value of the \texttt{crossref} field if it has any, otherwise, typeset
+the information about the book. And \tcmd\crossref\ is:
+
+\verbatim
+\def\crossref#1{%
+ , in \cite{#1}%
+ \WriteImmediateInfo{\noexpand\Cite{#1}{main}{}{}}%
+ }
+\endverbatim
+
+\noindent Since the value of the \texttt{crossref} field is an entry key,
+we simply \tcmd\cite\ that entry. However, this is not enough; \tcmd\SortList\
+can deal with entries if and only if they are cited before it is called; on the
+other hand, \tcmd\ReadList, where the cross-reference happens, must appear after
+\tcmd\SortList. That's why we pass a \tcmd\Cite\ command to the next compilation;
+note that the third argument does nothing.
+
+Thus, supposing the reference `\texttt{Gaddis1994}' has a \texttt{crossref} field to `\texttt{Gass2000}',
+\tcmd{\cite\targ{Gaddis1994}} in a document will produce the following in the
+bibliography:
+
+\input authoryear
+\Cite{Gaddis1994}{main}{}{}
+\citation
+\SortList{main}
+\ReadList{main}
+\endcitation
+
+What if we don't want to see the `\texttt{Gass2000}' reference in the bibliography
+and instead want something like this:
+
+\citation
+\def\EntryKey{gaddis1994}
+\RetrieveFieldIn{namenumber}\tempcount
+\ReadName\makerefname~(\RetrieveField{year})
+`\RetrieveField{title}', in
+\def\EntryKey{gass2000}
+\RetrieveFieldIn{namenumber}\tempcount
+\booktitle{title}, edited by \ReadName\makeedname,
+\RetrieveField{publisher}: \RetrieveField{address},
+\RetrieveField{year}.
+\endcitation
+
+\noindent Then \tcmd\crossref\ should be something like this:
+
+\verbatim
+\def\crossref#1{%
+ \bgroup
+ \lowercase{\def\EntryKey{#1}}%
+ \TypesetField{title}\addbook{}%
+ \TypesetField{editor}\addeditor{}%
+ \TypesetField{pages}\addcomma{}%
+ \TypesetField{publisher}\addcomma{}%
+ \TypesetField{address}\addcolon{}%
+ \TypesetField{year}\addcomma{}%
+ \egroup
+ \WriteImmediateInfo{\noexpand\Cite{#1}{crossref}{}{}}%
+ }
+\endverbatim
+
+\noindent That is: we apply the same macros to a different entry
+by redefining \tcmd\EntryKey\ temporarily (hence the group). Note
+that this redefinition must happen in \tcmd\lowercase, because there
+we're away from \lib's handling of entry keys. Note also that we
+still \tcmd\Cite\ the entry in the external file, because the citation
+is necessary to retrieve fields in the bibliographic files; however
+the entry is added to a secondary list `\texttt{crossref}' that we'll never
+sort nor read.
+
+\vskip 0pt plus 1filll
+\parfillskip0pt
+\noindent\hfill {\it Typeset with Lua\TeX\ v.0.6}\par
+\noindent\hfill {\it in Garamond Pro (Robert Slimbach)}\par
+\noindent\hfill {\it and Inconsolata (Raph Levien)}\par
+
+\makebookmarks
+
+\BibFile{librarian}
+\bye
diff --git a/macros/generic/librarian/doc/generic/librarian/librarian.bib b/macros/generic/librarian/doc/generic/librarian/librarian.bib
new file mode 100644
index 0000000000..f58b10be47
--- /dev/null
+++ b/macros/generic/librarian/doc/generic/librarian/librarian.bib
@@ -0,0 +1,39 @@
+@Book{Coover2002,
+ author = {Coover, Robert},
+ title = {The Adventures of Lucky Pierre},
+ subtitle = {Director's Cut},
+ publisher = "Grove Press",
+ Address = {New York},
+ year = 2002,
+}
+
+@book{Wallace1996,
+ author = {David Foster Wallace},
+ title = {Infinite Jest},
+ publisher = "Little, Brown",
+ address = "New York",
+ year = 1996,
+}
+
+@shortstories{Wallace2004,
+ author = {David Foster Wallace},
+ title = {Oblivion},
+ publisher = "Little, Brown",
+ address = "New York",
+ year = 2004,
+}
+
+@incollection{Gaddis1994,
+ author = {Gaddis, William},
+ title = {Old Foes with New Faces},
+ year = 1994,
+ crossref = {Gass2000},
+}
+
+@book{Gass2000,
+ editor = {Gass, William H. and Lorin Cuoco},
+ title = {The Writer and Religion},
+ publisher = {Southern Illinois University Press},
+ address = {Carbondale},
+ year = 2000,
+} \ No newline at end of file