[net.sources] Yet another refer macro substitute

rggoebel (10/31/82)

I too have found the macros and document types a bit weak. What follows is
breif documentation (with macro definition file embedded) that can be 
formatted with -MS macros.  I attempted to keep the "%" key names compatible
with the standard refer choices. As the documentation says, there are few
required fields, and the macros will do their best when fields are missing.
If anyone is interested, I am (slowly) constructing macros for various other
formats, e.g., CACM, TOG, AI, etc.

These macros have no name, and are really intended as alternatives to the
standard MS ones, rather than replacements. Comments cheerfully accepted.
============================================================================

.\"		Documentation for Refer macros (October 28, 1082)
.\"		R. Goebel
.\"		Department of Computer Science
.\"		University of Waterloo
.\"		Waterloo, Ontario
.\"		Canada N2L 3G1   (519) 885-1211 x3512
.\"		UUCP: watmath!rggoebel
.\"		------------------------------------------------
.\"
.\"		To produce hard copies:
.\"
.\"		versatec: vtroff -ms /u/rggoebel/pub/doc/refer.rt
.\"		imagen:   itroff -ms /u/rggoebel/pub/doc/refer.rt
.\"		printer:  nroff -ms -Tlpr /u/rggoebel/pub/doc/refer.rt
.\"             ________________________________________________
.\"
.\"		Refer macros default format
.\"		R. Goebel, September 26, 1982
.\"		Documentation: /u/rggoebel/pub/doc/refer
.\"             ________________________________________________
.\"
.\"		reference format selection macro
.\"		notice default format
.de ][
.ie "\\*([l"book" .[0
.el .ie "\\*([l"journal-article" .[1
.el .ie "\\*([l"proceedings-article" .[2
.el .ie "\\*([l"book-article" .[3
.el .ie "\\*([l"edited-book" .[4
.el .ie "\\*([l"edited-proceedings" .[5
.el .ie "\\*([l"technical-report" .[6
.el .ie "\\*([l"manuscript" .[7
.el .ie "\\*([l"dissertation" .[8
.el .ie "\\*([l"edited-journal" .[9
.el .[d
..
.\"		format in-text citation
.de rF
.ne 4
.ti -5
[\\*([F]
.br
..
.\"		punctuation definition
.ds >. .
.ds <. \&
.ds >, ,
.ds <, \&
.ds >; ;
.ds <; \&
.ds >: :
.ds <: \&
.\"		in-text citation brackets
.ds [. " [
.ds .] ]
.\"		reference list initialization macro
.de ]<
.ft R
.ls 1
.in 5
.sp 2
.na
..
.\"		reference list termination macro
.de ]>
.ft P
.ad
.in 0
.sp 2
..
.\"		string definition reset macro
.de ]-
.rm [V [P [A [T [N [C [B [O [R [I [E [D [L [J [S [M [l [e [n [c
..
.de [0		\" book format
.rF
\\*([A (\\*([D),
\\f2\\*([T\\f1\c
.if !"\\*([n"" , edition \\*([n\c
.if !"\\*([S"" , \\*([S\c
.if !"\\*([V"" , vol.\ \\*([V\c
, \\*([I\c
.if !"\\*([C"" , \\*([C\c
.ie "\\*([O"" \&.
.el \& [\\*([O].
..
.de [1		\" journal-article format
.rF
\\*([A (\\*([D),
\\*([T,
\\f2\\*([J\\f1\c
.if !"\\*([V"" \& \\f3\\*([V\\f1\c
.if !"\\*([N"" (\\*([N)\c
.if !"\\*([M"" , \\*([M\c
.if !"\\*([I"" , \\*([I\c
.if !"\\*([C"" , \\*([C\c
.if !"\\*([P"" , \\*([P\c
.ie "\\*([O"" \&.
.el \& [\\*([O].
..
.de [2		\"proceedings-article format
.rF
\\*([A (\\*([D),
\\*([T,
\\f2\\*([J\\f1\c
.if !"\\*([V"" \& \\f3\\*([V\\f1\c
.if !"\\*([M"" , \\*([M\c
.if !"\\*([I"" , \\*([I\c
.if !"\\*([C"" , \\*([C\c
.if !"\\*([E"" \{\
, \\*([E
.ie !"\\*([e"" (eds.)\c
.el (ed.)\c
.\}
.if !"\\*([P"" , \\*([P\c
.ie "\\*([O"" \&.
.el \& [\\*([O].
..
.de [3		\" book-article format
.rF
\\*([A (\\*([D),
\\*([T,
\\f2\\*([B\\f1\c
.if !"\\*([n"" , edition \\*([n\c
.if !"\\*([S"" , \\*([S\c
.if !"\\*([V"" , vol.\ \\*([V\c
.if !"\\*([E"" \{\
, \\*([E
.ie !"\\*([e"" (eds.)\c
.el (ed.)\c\}
, \\*([I\c
.if !"\\*([C"" , \\*([C\c
.if !"\\*([P"" , \\*([P\c
.ie "\\*([O"" \&.
.el \& [\\*([O].
..
.de [4		\" edited-book format
.rF
\\*([A (\\*([D,
.ie "\\*([e"" ed.),
.el eds.),
\\f2\\*([T\\f1\c
.if !"\\*([n"" , edition \\*([n\c
.if !"\\*([S"" , \\*([S\c
.if !"\\*([V"" , vol.\ \\*([V\c
, \\*([I\c
.if !"\\*([C"" , \\*([C\c
.ie "\\*([O"" \&.
.el \& [\\*([O].
..
.de [5		\" edited-proceedings format
.rF
.ie "\\*([e"" \\*([A (\\*([D, ed.),
.el \\*([A (\\*([D, eds.),
\\f2\\*([J\\f1\c
.if !"\\*([V"" \& \\f3\\*([V\\f1\c
.if !"\\*([M"" , \\*([M\c
.if !"\\*([I"" , \\*([I\c
.if !"\\*([C"" , \\*([C\c
.ie "\\*([O"" \&.
.el \& [\\*([O].
..
.de [6		\" technical-report format
.rF
\\*([A (\\*([D),
\\*([T\c
.if !"\\*([R"" , \\*([R\c
.if !"\\*([S"" , \\*([S\c
.if !"\\*([I"" , \\*([I\c
.if !"\\*([C"" , \\*([C\c
.if !"\\*([M"" , \\*([M\c
.if !"\\*([P"" , \\*(P pages\c
.ie "\\*([O"" \&.
.el \& [\\*([O].
..
.de [7		\" manuscript format
.rF
\\*([A (\\*([D),
\\*([T\c
.if !"\\*([S"" , \\*([S\c
.if !"\\*([I"" , \\*([I\c
.if !"\\*([C"" , \\*([C\c
.if !"\\*([M"" , \\*([M\c
.if !"\\*([P"" , \\*([P pages\c
.ie "\\*([O"" \&.
.el \& [\\*([O].
..
.de [8		\" dissertation format
.rF
\\*([A (\\*([D),
\\*([T\c
.if !"\\*([Q"" , \\*([Q dissertation\c
.if !"\\*([S"" , \\*([S\c
.if !"\\*([I"" , \\*([I\c
.if !"\\*([C"" , \\*([C\c
.if !"\\*([M"" , \\*([M\c
.if !"\\*([P"" , \\*([P pages\c
.ie "\\*([O"" \&.
.el \& [\\*([O].
..
.de [9		\" edited-journal
.rF
\\*([A (\\*([D,
.ie "\\*([e"" ed.),
.el eds.),
\\*([T,
\\f2\\*([J\\f1\c
.if !"\\*([V"" \& \\f3\\*([V\\f1\c
.if !"\\*([N"" (\\*([N)\c
.if !"\\*([M"" , \\*([M\c
.if !"\\*([I"" , \\*([I\c
.if !"\\*([C"" , \\*([C\c
.ie "\\*([O"" \&.
.el \& [\\*([O].
..
.de [d		\" default format
.rF
\\*([A (\\*([D),
\\*([T\c
.if !"\\*([J"" , \\f2\\*([J\\f1\c
.if !"\\*([B"" , \\f2\\*([B\\f1\c
.if !"\\*([S"" , \\*([S\c
.if !"\\*([V"" , vol.\ \\*([V\c
.if !"\\*([N"" , no.\ \\*([N\c
.if !"\\*([E"" \{\
, \\*([E
.ie !"\\*([e"" (eds.)\c
.el (ed.)\c\}
.if !"\\*([I"" , \\*([I\c
.if !"\\*([C"" , \\*([C\c
.if !"\\*([M"" , \\*([M\c
.if !"\\*([P"" , \\*([P\c
.ie "\\*([O"" \&.
.el \& [\\*([O].
..
.ds nt N\s-2ROFF/\s+2T\s-2ROFF\s+2
.ds rf R\s-2EFER\s+2
.RP
.TL
Reference Formatting Macros
.AU
Randy Goebel
.AI
Computer Science Department
University of Waterloo
Waterloo, Ontario
Canada N2L 3G1
.AB
This brief document describes the use of a set of \*(nt macros
for formatting bibliographic entries maintained with the inverted index
utilities described by Lesk\*(<.\*([.Lesk79a\*(.]\*(>.
The macros extend the set of "%" keys used by Lesk's suite of
programs to provide for a bit more flexibility
in defining and formatting various kinds of bibliographic citations.
It is important to realize that extending the "%" key fields for each
bibliographic entry is, in part, a response to the many bugs of the \*(rf
software.
The macros are written to be independent of any existing macro package
(e.g., MS or ME), and can be used alone or together with other macro
packages.
.AE
.SH
Introduction
.PP
The UNIX suite of programs for maintaining and using bibliographic
data is extremely useful\*(<,\*([.Lesk79a\*(.]\*(>,
but suffers from at least two difficulties:
1) the \*(rf program attempts to make inferences about what
kind of bibliographic entry is being cited (e.g., book article,
proceedings article, etc.) but its inferences are frequently wrong.
Its inferences are communicated as integer arguments
to the formatting macros and can thus be ignored.
The macros described herein provide an alternative when 
those inferences are ignored;
2) the \*(rf program fails to communicate more detailed bibliographic
data to the standard formatting macros,
e.g., multiple editors should be flagged as "(eds.)" not "(ed.)".
The macros herein were designed to overcome several such difficulties.
.PP
Many of \*(rf's difficulties result from a lack of communication
between the bibliographic data base entry and the formatting macros.
Rather than rewrite \*(rf, the approach taken here is to provide
extra information in each bibliographic entry by extra "%" key fields,
and then have the macro definitions use those fields to produce a more
"accurate" formatting of the citation.
.SH
Document formats
.PP
Instead of relying on \*(rf
to make the correct inference about the kind of document cited, these macros
.B require
that a "%l" entry be associated with each bibliographic data base
entry. The value of the "%l" field fixes the document type once and for all,
and is used to determine the final format of any citation of that document.
.PP
Current document types supported are:
.DS
book
journal-article
proceedings-article
book-article
edited-book
edited-proceedings
technical-report
manuscript
dissertation
edited-journal
.DE
.PP
The formatting macros use the "%l" field to determine how 
a reference is to be formatted.
If the "%l" field is missing or is not one of the
document types named above, the macros will use a default format.
Consider the following example bibliographic entry:
.DS
%A F. Foo
%A B. Bar
%D 1982
%e 2
%J Artificial Insemination
%T Special issue on bull-breeding
%V 11
%N 4
%l edited-journal
.DE
The above document is formatted as follows:
.LP
.in +5
.na
.ds [F Foo82a
.]-
.ds [A Foo, F.
.as [A " and Bar, B.
.ds [D 1982
.ds [e 2
.ds [J Artificial Insemination
.ds [T Special issue on bull-breeding
.ds [V 11
.ds [N 4
.ds [l edited-journal
.nr [T 0
.nr [A 1
.nr [O 0
.][ 1
.in -5
.ad
.LP
If the "%e" field is included and is not null, then the formatting
macros will produce "F. Foo and B. Bar (1982, eds.)" instead of
"F. Foo and B. Bar (1982, ed.)"
As with all bibliographic entries, the order of fields is
not important.
.SH
Document formatting details
.PP
The University of Chicago Manual of Style was used as a basic guideline
for the preparation of these macros\*(<.\*([.Chicago69a\*(.]\*(>.
Among other things, this means that \*(rf's in-text citation style using
footnotes is
.B not
used; as indicated by the Chicago Manual of Style, citations
in the Natural Sciences normally use the (<author><year>) style of in-text
citation.
The footnote style can be provided by changing the string definitions
for the in-text citation brackets (see below), but the reference listing
will be produced in the same way.
.PP
The use of each field for each document type is given below. 
An asterisk beside a field name indicates a required field.
Note that very few fields are required; the macro for each
format will do its best to provide reasonable output with the
information provided.
.LP
.DS L
.B book
.sp
%A <author(s)>*
%D <year>*
%T <title>*
%V <volume> (appears as "vol. <volume>")
%S <series> (include series number if it exists)
%n <edition> (appears as "edition <edition>")
%I <publisher>*
%C <city of publication>
%O <optional> (appears within square brackets "[<optional>]")
%l book*
.DE
.LP
.DS L
.B journal-article
.sp
%A <author(s)>*
%D <year>*
%T <title>*
%J <journal>*
%V <volume>
%N <number>
%M <month>
%I <publisher>
%C <city of publication>
%P <pages>
%O <optional> (appears within square brackets "[<optional>]")
%l journal-article*
.DE
.LP
.DS L
.B proceedings-article
.sp
%A <author(s)>*
%D <year>*
%T <title>*
%J <proceedings title>*
%V <volume>
%M <month>
%I <institution> (e.g., name of university, corporation, etc.)
%C <city of conference>
%E <editor(s)> (multiple editors must be given in one field)
%e <editor(s) flag> (non-null flag produces "(eds.)" otherwise "(ed.)")
%O <optional> (appears within square brackets "[<optional>]")
%l proceedings-article*
.DE
.LP
.DS L
.B book-article
.sp
%A <author(s)>*
%D <year>*
%T <title>*
%B <book title>*
%n <edition> (appears as "edition <edition>")
%V <volume> (appears as "vol. <volume>")
%S <series> (include series number if it exists)
%E <editor(s)> (multiple editors must be given in one field)
%e <editor(s) flag> (non-null flag produces "(eds.)" otherwise "(ed.)")
%I <publisher>*
%C <city of publication>
%P <pages>
%O <optional> (appears within square brackets "[<optional>]")
%l book-article*
.DE
.LP
.DS L
.B edited-book
.sp
%A <editor(s)>* (note that multiple entries can appear here)
%e <editor(s) flag> (non-null flag produces "(eds.)" otherwise "(ed.)")
%D <year>*
%T <title>*
%n <edition> (appears as "edition <edition>")
%V <volume> (appears as "vol. <volume>")
%S <series> (include series number if it exists)
%I <publisher>*
%C <city of publication>
%O <optional> (appears enclosed within square brackets "[<optional>]")
%l edited-book*
.DE
.LP
.DS L
.B edited-proceedings
.sp
%A <editor(s)>* (note that multiple entries can appear here)
%e <editor(s) flag> (non-null flag produces "(eds.)" otherwise "(ed.)")
%D <year>*
%J <proceedings title>*
%V <volume>
%M <month>
%I <institution> (e.g., name of university, corporation, etc.)
%C <city of conference>
%O <optional> (appears within square brackets "[<optional>]")
%l edited-proceedings*
.DE
.LP
.DS L
.B technical-report
.sp
%A <author(s)>*
%D <year>*
%T <title>*
%R <report number>
%S <subdivision>  (e.g., Computer Science Department, Systems Lab, etc.)
%I <institution> (e.g., name of university, corporation, etc.)
%C <city>
%M <month>
%P <page count> (note that this is page count, not page range)
%O <optional> (appears enclosed within square brackets "[<optional>]")
%l technical-report*
.DE
.LP
.DS L
.B manuscript
.sp
%A <author(s)>*
%D <year>*
%T <title>*
%S <subdivision> (e.g., Computer Science Department, Systems Lab, etc.)
%I <institution> (e.g., name of university, corporation, etc.)
%C <city>
%M <month>
%P <page count> (note that this is page count, not page range)
%O <optional> (appears enclosed within square brackets "[<optional>]")
%l manuscript*
.DE
.LP
.DS L
.B dissertation
.sp
%A <author>*
%D <year>*
%T <title>*
%Q <level> (e.g., Ph.D., M.Math., D.Sc., etc.)
%S <subdivision> (e.g., Computer Science Department, Systems Lab, etc.)
%I <institution> (e.g., name of university, corporation, etc.)
%C <city>
%M <month>
%P <page count> (note that this is page count, not page range)
%O <optional> (appears enclosed within square brackets "[<optional>]")
%l dissertation*
.DE
.LP
.DS L
.B edited-journal
.sp
%A <editor(s)>* (note that multiple entries can appear here)
%e <editor(s) flag> (non-null flag produces "(eds.)" otherwise "(ed.)")
%D <year>*
%T <title>* (e.g., special issue title)
%J <journal>*
%V <volume>
%N <number>
%M <month>
%I <publisher>
%C <city of publication>
%O <optional> (appears enclosed within square brackets "[<optional>]")
%l edited-journal*
.DE
.SH
User options
.PP
As with the standard set of \*(rf macros, the user can redefine a few
macros and strings to customize his in-text citation format and 
reference listing.
The following macro definition is used at the beginning of each reference
in the reference list:
.LP
.DS
\\.de rF 
\\.ne 4
\\.ti -5
[\\\\\\\\*([F]
\\.br
\\..
.DE
.LP
The "rF" macro works in conjunction with the following two macros, called
at the beginning and end (respectively) of the collected list of references:
.LP
.DS
\\.de ]<
\\.ft R
\\.ls 1
\\.in 5
\\.sp 2
\\.na
\\..

\\.de ]>
\\.ft P
\\.ad
\\.in 0
\\.sp 2
\\..
.DE
.LP
In the reference list, the indenting of each reference can be 
changed by replacing the definitions of the above macros.
.PP
The \*(rf software constructs an \*(nt string "[F" to be used as
the in-text citation for each document cited. 
The contents of this string is controlled by \*(rf command line
parameters\*(<,\*([.Lesk79a\*(.]\*(>,
and can be adjusted by the user.
The in-text citation brackets are defined as
.LP
.DS
\\.ds [. " [
\\.ds .] ]
.DE
The first definition is expanded before the in-text citation is formatted,
and the latter definition is expanded just after.
Thus, the default in-text citation is a blank, a left square bracket,
the string value of "[F" followed by a right square bracket.
These bracketing strings can be redefined by the user,
e.g., to produce in-text citations as footnotes.
.PP
The following string definitions control the positioning
of punctuation:
.LP
.DS
\\.ds >. .
\\.ds <. \&
\\.ds >, ,
\\.ds <, \&
\\.ds >; ;
\\.ds <; \&
\\.ds >: :
\\.ds <: \&
.DE
The above definitions will position all punctuation after the in-text
citation.
.SH
References
.LP
.]<
.\"Chicago.U.o-1969-1
.ds [F Chicago69a
.]-
.ds [A University of Chicago
.ds [D 1969
.ds [T A Manual of Style
.ds [n 12
.ds [I University of Chicago Press
.ds [l book
.ds [C Chicago, Illinois
.nr [T 0
.nr [A 0
.nr [O 0
.][ 2 book
.\"Lesk.M.E.-1979-2
.ds [F Lesk79a
.]-
.ds [A M.E. Lesk
.ds [D 1979
.ds [l book-article
.ds [T Some applications of inverted indexes on the UNIX system
.ds [B UNIX Programmers Manual
.ds [V 2A
.ds [n 7
.nr [T 0
.nr [A 0
.nr [O 0
.][ 3 article-in-book
.]>