diff options
Diffstat (limited to 'Master/texmf-dist/doc')
| -rw-r--r-- | Master/texmf-dist/doc/generic/librarian/README | 7 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/generic/librarian/README.TEXLIVE | 6 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/generic/librarian/authoryear.tex | 2 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/generic/librarian/librarian-doc.pdf | bin | 0 -> 153869 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/generic/librarian/librarian-doc.tex | 1271 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/generic/librarian/librarian.bib | 39 |
6 files changed, 1318 insertions, 7 deletions
diff --git a/Master/texmf-dist/doc/generic/librarian/README b/Master/texmf-dist/doc/generic/librarian/README index d8cfd07864b..45841bd9465 100644 --- a/Master/texmf-dist/doc/generic/librarian/README +++ b/Master/texmf-dist/doc/generic/librarian/README @@ -9,7 +9,14 @@ for all formats. Relevant information can be found in librarian-doc.pdf. The files in this distribution are: + +DOC: librarian-doc.pdf -> The documentation. +librarian-doc.tex -> The source. +librarian.bib -> A bib file for the examples in + the documentation. + +TEX: librarian.tex -> The crux of the biscuit (directly \input in plain TeX). t-librarian.tex -> A third-party file for use with ConTeXt. diff --git a/Master/texmf-dist/doc/generic/librarian/README.TEXLIVE b/Master/texmf-dist/doc/generic/librarian/README.TEXLIVE deleted file mode 100644 index 63d055e00f5..00000000000 --- a/Master/texmf-dist/doc/generic/librarian/README.TEXLIVE +++ /dev/null @@ -1,6 +0,0 @@ -The following files have been removed in the TeX Live installation of -the current package, typically due to duplication, lack of space, or -missing source code. You can find these files on CTAN. If questions or -concerns, email tex-live@tug.org. - - librarian-doc.pdf diff --git a/Master/texmf-dist/doc/generic/librarian/authoryear.tex b/Master/texmf-dist/doc/generic/librarian/authoryear.tex index ff782dd42a6..1bd0c7b2f50 100644 --- a/Master/texmf-dist/doc/generic/librarian/authoryear.tex +++ b/Master/texmf-dist/doc/generic/librarian/authoryear.tex @@ -233,7 +233,7 @@ , Master's thesis% \TypesetField{organization}\addcomma{}{}% } -\createtype{mastersthesis}{% +\createtype{phdthesis}{% \booktitle{title}% , PhD dissertation% \TypesetField{organization}\addcomma{}{}% diff --git a/Master/texmf-dist/doc/generic/librarian/librarian-doc.pdf b/Master/texmf-dist/doc/generic/librarian/librarian-doc.pdf Binary files differnew file mode 100644 index 00000000000..2e3d0e84c8b --- /dev/null +++ b/Master/texmf-dist/doc/generic/librarian/librarian-doc.pdf diff --git a/Master/texmf-dist/doc/generic/librarian/librarian-doc.tex b/Master/texmf-dist/doc/generic/librarian/librarian-doc.tex new file mode 100644 index 00000000000..1beb373e016 --- /dev/null +++ b/Master/texmf-dist/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/Master/texmf-dist/doc/generic/librarian/librarian.bib b/Master/texmf-dist/doc/generic/librarian/librarian.bib new file mode 100644 index 00000000000..f58b10be47d --- /dev/null +++ b/Master/texmf-dist/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 |