\input blue.tex \loadindexmacros \report \bluechapter Coping with References \beginsummary \bluetex{} makes use of the database of references lit.dat. The references have to be specified by name. Prior to the formatting of the script the specified references are set and kept in a box. This box is pasted up on command. The layout of the references has been inspired upon AMS and can be customized at a lower level. \endsummary Most if not all of your references should be part of your\ftn{And hopefully of your publisher as well.} database of literature. This starting point makes things simpler and definitely facilitates reuse. \bluetex{} makes use of lit.dat, a database of references, organized as a list. ^^{database,\ lit.dat} The names of the list elements\Dash primary keys in database jargon\Dash identify the entries. Each list entry consists of a list element tag, a name, and the (marked up) bibliography item proper. The structure of the marked up of the bibliography item proper is modest and prompted by my use: author name, year of publication, and rest part, next to some adopted conventions. In the field I'm working I know the publication by heart, once I know the name of the author(s) and the year of publication. For my own use I don't need further tagging. \bluehead Using references With \bluetex{} the use comes down to specifying the names of the references in the preliminary part of the script, via ^^|\beginreferences|%^^|\endreferences|^^|\references| \begincenterblock \cs{beginreferences} $\cs{}\langle\,name_1\rangle\dots% \cs{}\langle\,name_n\rangle\qquad% \hbox{or}\qquad% \cs{references}\{\cs{}\langle\,name_1\rangle\dots% \cs{}\langle\,name_n\rangle\}$ \cs{endreferences} \endcenterblock and paste up the references via ^|\pasteupreferences|, at your place of choice. \exercise What is the effect of |\references{}|? \answer Via this empty specification we can typeset what has been supplied in \cs{thisreferences}. Agreed, a little unusual. Placement within context can be handled via the token variables ^|\prereferences| and ^|\postreferences|. Default \cs{prereferences} takes care of the heading via \displaycenterline{|\prereferences{\head{\the\referencesname}}|.} The token variables ^|\thisreferences| and ^|\everyreferences| can be used for customization. \thissubhead{\runintrue} \bluesubhead Cross-referencing\par can always be done via the convention of || ||. ^^{cross-referencing} This approach facilitates reading, at least for me, at the expense of a little more space in print than the system of numbers. The latter system is possible with \bluetex. Once the references have been set by \cs{references}, each name is redefined by its sequence number. After $\cs{references}\{\dots\cs{}\langle\,name_n\rangle\dots\}$ then $\cs{}\langle\,name_n\rangle$ denotes the number ||. \thissubhead{\runintrue} \bluesubhead Robustness\par is there too. Most likely users will now and then mistype a name supplied in \cs{references}. \bluetex{} reacts very elegantly to this. First, it continues, it does not stop. A message is provided in the log file, and as reference an error message is printed by |\pasteupreferences|. \bluehead Adding a reference to the database lit.dat ^^{add\ a\ reference} The structure of the bibliography items in lit.dat is modest, a list of elements and each element starting with the list element tag, \cs{lst}, and a name. ^^{entry\ for\ lit.dat} \begincenterverbatim \lst\ { (): <rest> } !endcenterverbatim This syntax leaves freedom and flexibility, although the essentials\Dash name, date, title\ftn{I consider it important to delineate the main fields, however.} \Dash have prescribed positions. The number of authors does not matter, nor is it prescribed how the author names should be specified. That is up to you. The representation of the date is free too, leaving room for things like `in progress' or `priv. comm.' I don't like to prescribe structurally the title in more detail. The rest part is not further prescribed either, because of the great variety of sources---publishers, books, journal series, proceedings, theses, technical reports, and the like. At the end of the rest part I added, within parentheses, annotations, now and then.\ftn{There is usually too much formatting in a bibliography for my taste. Why discriminate between a title of a book and an article? Given the context that is clear enough. Especially, when for a book the ISBN (or ISSN) number is provided. And why so much (superfluous) punctuation? For me there should be as little punctuation as is functionally needed to separate the elements within the entry.} For the name I chose to use lowercase letters only: the (first) name followed by the initials. For the |<extension>| I chose extra letter(s). The latter are there to tell the difference between more than one publication per author, and to allow insertions, when one stumbles on some early work of an author. As an example of an entry, I'm pleased to take \TB.\ftn{In practice I hardly use this one, because in \cs{prereferences} I supply the note `I assume \TB{} to be omni-present.'} \blueexample lit.dat entry \begincenterverbatim \lst\knuthded {Knuth D.E (1984): \TB. \AW. ISBN 0-201-13448-9. \annotation{Soft cover edition of book A in the series Computers and Typesetting.} } !endcenterverbatim The list of references is ordered alphabetically on |<name><extension>|. Prepare your bibliography and insert the items in your personalized version of lit.dat, and that is it. \exercise How can we format the complete lit.dat database, with each entry preceded with numbers enclosed in square brackets? \answer Recognize that the file consists of triples. BLUe's format provides \cs{setdatabase} for this purpose. That macros comes down to the following. \beginverbatim \input blue.tex \onecol \prenum{[\thinspace}\postnum{\thinspace]} \def\lst#1{\nitem} \input lit.dat \smallbreak \bye !endverbatim An older fifo-oriented solution reads as follows. \beginverbatim \newcount\bcnt \def\prt{\medskip\noindent\advance\bcnt1 \llap{[\number\bcnt]\quad}} \def\fifo#1#2#3{\ifx#1\ofif\ofif\fi \prt#3\fifo} %a blank line \fifo\lst\<name1>{...} \lst\<name2>{...} ... \lst\<namen>{...} \ofif\relax\relax \bye !endverbatim Note the difference. ^^{list\ of\ database} \exercise How can we get a list of names of the references in the database? \answer \bluetex{} contains a macro \cs{contentsdatabase} that writes the list of names of a lit, pic, or address database to the file contentslit, contentspic, or contentsaddress.\\ Let us assume that we wish the list of names in a toks variable \cs{namelst}. To facilitate processing of \cs{namelst} \cs{lst} has been inserted before each name in the list. \beginverbatim \newtoks\namelst \def\lst#1#2{\namelst\ea{\the\namelst\lst#1}} \input lit.dat %and to verify the contents \baselineskip12pt plus2pt minus1pt \lineskip1pt plus 1pt minus1pt \def\lst#1{{\tt\string#1}\endgraf} \the\namelst !endverbatim \exercise When a reference has been added to lit.dat a simple check for verifying that the file can still be processed is the following. What would you expect as outcome? \begincenterverbatim \input blue.tex \references\zusek \zusek \bye !endcenterverbatim \answer The number 1. Once the reference has been found, it will be used, and the name will be overwritten by its sequence number. %end answer \bluesubhead Check for data integrity After a reference has been added one can check whether the file can be scanned by \TeX{} via making a table of contents as follows. \begincenterverbatim \input blue.tex \contentsdatabase{lit} \bye !endcenterverbatim This script produces no pages of output (that is OK). The file contentslit will be created, though. If you have a file with references of your own, say abc.dat, provide also \cs{newwrite} \cs{tocabc}. \bluehead Customization Each entry is typeset by \cs{ls} which is activated by ^|\lsams| in \cs{references}. The default formatting has been inspired upon AMS. \bluesubhead How to provide your way of formatting? To illustrate how a user can specify his own convention \bluetex{} contains the template \begincenterverbatim \def\lsstraight{\let\ls\nitem} !endcenterverbatim \blueexample Formatting references your way Provide your variant of \cs{lsstraight} and supply ^^{formatting\ references} \begincenterverbatim \thisreferences{\let\lsams\lsstraight}. !endcenterverbatim \bluehead Searching the lit.dat database by pattern ^^{search\ of\ database} BLUe's format provides a \cs{search} macro with as argument a search pattern. The purpose is to search the database file provided in the toks variable \cs{searchfile}, for this search pattern. The result of the search is the list of names of which the replacement texts contain the search pattern. This list of names is delivered in the toks var \cs{namelist}, and for the time being they are also written to the log file. \blueexample Search for references of {\oldstyle1973} in lit.dat In order to justify my use of the word database in relation to \TeX, I provided the search macro to browse the databases lit.dat and address.dat. Below the input and result have been given of the search of lit.dat for the pattern {\oldstyle1973}. The result is contained in the toks variable \cs{namelst}. The names are also written to the log file to give you a check for whether the right names have been selected. \begindemo \input blue.tex \searchfile{lit} \search{1973} \bye !yields \cs{lst}\cs{knuthdec} \cs{lst}\cs{schumacherefa} \cs{lst}\cs{wirthna} \enddemo Remarks. A search pattern should not contain a period. The search is case sensitive. \endinput