diff options
Diffstat (limited to 'info/laan/pwt/pwt.ref')
| -rw-r--r-- | info/laan/pwt/pwt.ref | 292 |
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 |