path: root/info/laan/pwt/pwt.ref

\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 |<author name(s)>| |<year>|. ^^{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 |<n>|.

\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\<name><extension>
{<name part> (<date part>):
 <title part>
 <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