summaryrefslogtreecommitdiff
path: root/info/laan/pwt/pwt.ref
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 /info/laan/pwt/pwt.ref
Initial commit
Diffstat (limited to 'info/laan/pwt/pwt.ref')
-rw-r--r--info/laan/pwt/pwt.ref292
1 files changed, 292 insertions, 0 deletions
diff --git a/info/laan/pwt/pwt.ref b/info/laan/pwt/pwt.ref
new file mode 100644
index 0000000000..bbc786cc66
--- /dev/null
+++ b/info/laan/pwt/pwt.ref
@@ -0,0 +1,292 @@
+\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