# refer

## Name



           refer - process bibliographic references for _groff_
    


## Synopsis



           **refer**[**-bCenPRS**] [**-a** _n_] [**-B** _field_**.**_macro_] [**-c** _fields_] [**-f** _n_]
                 [**-i** _fields_] [**-k** _field_] [**-l** _range-expression_] [**-p** _database-_
                 _file_] [**-s** _fields_] [**-t** _n_] [_file_ ...]
    
           **refer --help**
    
           **refer -v**
    
           **refer --version**
    


## Description



           The GNU implementation of _refer_ is part of the _groff_(1) document
           formatting system.  _refer_ is a _troff_(1) preprocessor that prepares
           bibliographic citations by looking up keywords specified in a
           _roff_(7) input document, obviating the need to type such
           annotations, and permitting the citation style in formatted output
           to be altered independently and systematically.  It copies the
           contents of each _file_ to the standard output stream, except that
           it interprets lines between **.[** and **.]** as _citations_ to be
           translated into _groff_ input, and lines between **.R1** and **.R2** as
           instructions regarding how citations are to be processed.  _refer_
           interprets and generates _roff_ **lf** requests so that file names and
           line numbers in messages produced by commands that read its output
           correctly describe the source document.  Normally, _refer_ is not
           executed directly by the user, but invoked by specifying the **-R**
           option to _groff_(1).  If no _file_ operands are present, or if _file_
           is “**-** ”, _refer_ reads the standard input stream.
    
           A citation identifies a work by reference to a _bibliographic_
           _record_ detailing it.  Select a work from a database of records by
           listing keywords that uniquely identify its entry.  Alternatively,
           a document can specify a record for the work at the point its
           citation occurs.  A document can use either or both strategies as
           desired.
    
           For each citation, _refer_ produces a _mark_ in the text, like a
           superscripted footnote number or “[Lesk1978a]”.  A mark consists
           of a _label_ between _brackets._  The mark can be separated from
           surrounding text and from other labels in various ways.  _refer_
           produces _roff_ language requests usable by a document or a macro
           package such as _me_ , _mm_ , _mom_ , or _ms_ to produce a formatted
           reference for each citation.  A citation's reference can be output
           immediately after it occurs (as with footnotes), or references may
           _accumulate_ , with corresponding output appearing later in the
           document (as with endnotes).  When references accumulate, multiple
           citations of the same reference produce a single formatted entry.
    
           Interpretation of lines between **.R1** and **.R2** tokens as preprocessor
           commands is a GNU _refer_ extension.  Documents employing this
           feature can still be processed by AT&T _refer_ by adding the lines
                  .de R1
                  .ig R2
                  ..
           to the beginning of the document.  The foregoing input causes
           _troff_ to ignore everything between **.R1** and **.R2**.  The effects of
           some _refer_ commands can be achieved by command-line options; these
           are supported for compatibility with AT&T _refer_.  It is usually
           more convenient to use commands.
    
       **Bibliographic records**
           A bibliographic record describes a referenced work in sufficient
           detail that it may be cited to accepted standards of scholarly and
           professional clarity.  The record format permits annotation and
           extension that a document may use or ignore.  A record is a plain
           text sequence of _fields,_ one per line, each consisting of a
           percent sign **%** , an alphanumeric character classifying it, one
           space, and its contents.  If a field's contents are empty, the
           field is ignored.
    
           Frequently, such records are organized into a _bibliographic_
           _database,_ with each entry separated by blank lines or file
           boundaries.  This practice relieves documents of the need to
           maintain bibliographic data themselves.  The programs _lookbib_(1)
           and _lkbib_(1) consult a bibliographic database, and _indxbib_(1)
           indexes one to speed retrieval from it, reducing document
           processing time.  Use of these tools is optional.
    
           The conventional uses of the bibliographic field entries are as
           follows.  Within a record, fields other than **%A** and **%E** replace
           previous occurrences thereof.  The ordering of multiple **%A** and **%E**
           fields is significant.
    
           **%A** names an author.  If the name contains a suffix such as
                  “Jr.” or “III”, it should be separated from the surname by
                  a comma.  We recommend always supplying an **%A** field or a **%Q**
                  field.
    
           **%B** records the title of the book within which a cited article
                  is collected.  See **%J** and **%T**.
    
           **%C** names the city or other place of publication.
    
           **%D** indicates the date of publication.  Specify the year in
                  full.  If the month is specified, use its name rather than
                  its number; only the first three letters are required.  We
                  recommend always supplying a **%D** field; if the date is
                  unknown, use “**in press** ” or “**unknown** ” as its contents.
    
           **%E** names an editor of the book within which a cited article is
                  collected.  Where a work has editors but no authors, name
                  the editors in **%A** fields and append “**, (ed.)** ” or “**, (eds.)** ”
                  to the last of these.
    
           **%G** records the U.S. government ordering number, ISBN, DOI, or
                  other unique identifier.
    
           **%I** names the publisher (issuer).
    
           **%J** records the name of the journal within which a cited
                  article is collected.  See **%B** and **%T**.
    
           **%K** lists keywords intended to aid searches.
    
           **%L** is a label; typically unused in database entries, it can
                  override the label format otherwise determined.
    
           **%N** records the issue number of the journal within which a
                  cited article is collected.
    
           **%O** presents additional (“other”) information, typically placed
                  at the end of the reference.
    
           **%P** lists the page numbers of a cited work that is part of a
                  larger collection.  Specify a range with _m_**-**_n_.
    
           **%Q** names an institutional author when no **%A** fields are
                  present.  Only one **%Q** field is permitted.
    
           **%R** is an identifier for a report, thesis, memorandum, or other
                  unpublished work.
    
           **%S** records the title of a series to which the cited work
                  belongs.
    
           **%T** is the work's title.  See **%B** and **%J**.
    
           **%V** is the volume number of the journal or book containing the
                  cited work.
    
           **%X** is an annotation.  By convention, it is not formatted in
                  the citing document.
    
           If the obsolescent “accent strings” feature of the _ms_ or _me_ macro
           packages is used, such strings should follow the character to be
           accented; an _ms_ document must call the **AM** macro before using them.
           Do not quote accent strings: use one **\** rather than two.  See
           _groff_char_(7) for a modern approach to the problem of diacritics.
    
       **Citations**
           Citations have a characteristic format.
                  **.[**_opening-text_
                  _flags keyword_ ...
                  _field_
                  ...
                  **.]**_closing-text_
    
           _opening-text_ , _closing-text_ , and _flags_ are optional, and only one
           _keyword_ or _field_ need be specified.  If keywords are present,
           _refer_ searches the bibliographic database(s) for a unique
           reference matching them.  Multiple matches are an error; add more
           keywords to disambiguate the reference.  In the absence of
           keywords, _fields_ constitute the bibliographic record.  Otherwise,
           _fields_ specify additional data to replace or supplement those in
           the reference.  When references are accumulating and keywords are
           present, specify additional _fields_ at most on the first citation
           of a particular reference; they apply to all further citations
           thereof.
    
           _opening-text_ and _closing-text_ are _roff_ input used to bracket the
           label, overriding the **bracket-label** command.  Leading and trailing
           spaces are significant.  If either of these is non-empty, the
           corresponding argument to the **bracket-label** command is not used;
           alter this behavior with the **[** and **]**_flags._
    
           _flags_ is a list of non-alphanumeric characters each of which
           modifies the treatment of the particular citation.  AT&T _refer_
           ignores them since they are non-alphanumeric.  They direct GNU
           _refer_ as follows.
    
           **#** Use the label specified by the **short-label** command, if any.
                  _refer_ otherwise uses the normal label.  Typically, a short
                  label implements author-date citation styles consisting of
                  a name, a year, and a disambiguating letter if necessary.
                  “**#** ” is meant to suggest such a (quasi-)numeric label.
    
           **[** Precede _opening-text_ with the first argument given to the
                  **bracket-label** command.
    
           **]** Follow _closing-text_ with the second argument given to the
                  **bracket-label** command.
    
           An advantage of the **[** and **]** flags over use of _opening-text_ and
           _closing-text_ is that you can update the document's bracketing
           style in one place using the **bracket-label** command.  Another is
           that sorting and merging of citations is not necessarily inhibited
           if the flags are used.
    
           _refer_ appends any label resulting from a citation to the _roff_
           input line preceding the **.[** token.  If there is no such line,
           _refer_ issues a warning diagnostic.
    
           There is no special notation for citing multiple references in
           series.  Use a sequence of citations, one for each reference, with
           nothing between them.  _refer_ attaches all of their labels to the
           line preceding the first.  These labels may be sorted or merged.
           See the description of the **< > **label expression, and of the
           **sort-adjacent-labels** and **abbreviate-label-ranges** commands.  A
           label is not merged if its citation has a non-empty _opening-text_
           or _closing-text_.  However, the labels for two adjacent citations,
           the former using the **]** flag and without any _closing-text,_ and the
           latter using the **[** flag and without any _opening-text,_ may be
           sorted and merged even if the former's _opening-text_ or the
           latter's _closing-text_ is non-empty.  (To prevent these operations,
           use the dummy character escape sequence **\ & **as the former's
           _closing-text_.)
    
       **Commands**
           Commands are contained between lines starting with **.R1** and **.R2**.
           The **-R** option prevents recognition of these lines.  When _refer_
           encounters a **.R1** line, it flushes any accumulated references.
           Neither **.R1** nor **.R2** lines, nor anything between them, is output.
    
           Commands are separated by newlines or semicolons.  A number sign
           (**#**) introduces a comment that extends to the end of the line, but
           does not conceal the newline.  Each command is broken up into
           words.  Words are separated by spaces or tabs.  A word that begins
           with a (neutral) double quote (**"**) extends to the next double quote
           that is not followed by another double quote.  If there is no such
           double quote, the word extends to the end of the line.  Pairs of
           double quotes in a word beginning with a double quote collapse to
           one double quote.  Neither a number sign nor a semicolon is
           recognized inside double quotes.  A line can be continued by
           ending it with a backslash “**\** ”; this works everywhere except after
           a number sign.
    
           Each command _name_ that is marked with * has an associated negative
           command **no-**_name_ that undoes the effect of _name_.  For example, the
           **no-sort** command specifies that references should not be sorted.
           The negative commands take no arguments.
    
           In the following description each argument must be a single word;
           _field_ is used for a single upper or lower case letter naming a
           field; _fields_ is used for a sequence of such letters; _m_ and _n_ are
           used for a non-negative numbers; _string_ is used for an arbitrary
           string; _file_ is used for the name of a file.
    
           **abbreviate** * _fields string1 string2 string3 string4_
                  Abbreviate the first names of _fields_.  An initial letter
                  will be separated from another initial letter by _string1_ ,
                  from the surname by _string2_ , and from anything else (such
                  as “von” or “de”) by _string3_.  These default to a period
                  followed by a space.  In a hyphenated first name, the
                  initial of the first part of the name will be separated
                  from the hyphen by _string4_ ; this defaults to a period.  No
                  attempt is made to handle any ambiguities that might result
                  from abbreviation.  Names are abbreviated before sorting
                  and before label construction.
    
           **abbreviate-label-ranges** * _string_
                  Three or more adjacent labels that refer to consecutive
                  references will be abbreviated to a label consisting of the
                  first label, followed by _string_ , followed by the last
                  label.  This is mainly useful with numeric labels.  If
                  _string_ is omitted, it defaults to “**-** ”.
    
           **accumulate** *
                  Accumulate references instead of writing out each reference
                  as it is encountered.  Accumulated references will be
                  written out whenever a reference of the form
                         **.[**
                         **$LIST$**
                         **.]**
                  is encountered, after all input files have been processed,
                  and whenever a **.R1** line is recognized.
    
           **annotate** * _field string_
                  _field_ is an annotation; print it at the end of the
                  reference as a paragraph preceded by the line
    
                         **.**_string_
    
                  If _string_ is omitted, it will default to **AP** ; if _field_ is
                  also omitted it will default to **X**.  Only one field can be
                  an annotation.
    
           **articles** _string_ ...
                  Each _string_ is a definite or indefinite article, and should
                  be ignored at the beginning of **T** fields when sorting.
                  Initially, “a”, “an”, and “the” are recognized as articles.
    
           **bibliography** _file_ ...
                  Write out all the references contained in each
                  bibliographic database _file_.  This command should come last
                  in an **.R1** /**.R2** block.
    
           **bracket-label** _string1 string2 string3_
                  In the text, bracket each label with _string1_ and _string2_.
                  An occurrence of _string2_ immediately followed by _string1_
                  will be turned into _string3_.  The default behavior is as
                  follows.
                         bracket-label \*([. \*(.] ", "
    
           **capitalize** _fields_
                  Convert _fields_ to caps and small caps.
    
           **compatible** *
                  Recognize **.R1** and **.R2** even when followed by a character
                  other than space or newline.
    
           **database** _file_ ...
                  Search each bibliographic database _file_.  For each _file_ , if
                  an index file _.i_ created by _indxbib_(1) exists, then it will
                  be searched instead; each index can cover multiple
                  databases.
    
           **date-as-label** * _string_
                  _string_ is a label expression that specifies a string with
                  which to replace the **D** field after constructing the label.
                  See subsection “Label expressions” below for a description
                  of label expressions.  This command is useful if you do not
                  want explicit labels in the reference list, but instead
                  want to handle any necessary disambiguation by qualifying
                  the date in some way.  The label used in the text would
                  typically be some combination of the author and date.  In
                  most cases you should also use the **no-label-in-reference**
                  command.  For example,
                         date-as-label D.+yD.y%a*D.-y
                  would attach a disambiguating letter to the year part of
                  the **D** field in the reference.
    
           **default-database** *
                  The default database should be searched.  This is the
                  default behavior, so the negative version of this command
                  is more useful.  _refer_ determines whether the default
                  database should be searched on the first occasion that it
                  needs to do a search.  Thus a **no-default-database** command
                  must be given before then, in order to be effective.
    
           **discard** * _fields_
                  When the reference is read, _fields_ should be discarded; no
                  string definitions for _fields_ will be output.  Initially,
                  _fields_ are **XYZ**.
    
           **et-al** * _string m n_
                  Configure use of “**et al** ” in the evaluation of **@** expressions
                  in label expressions.  If _u_ is the number of authors needed
                  to make the author sequence unambiguous and the total
                  number of authors is _t,_ then the last _t_ -_u_ authors will be
                  replaced by _string_ provided that _t_ -_u_ is not less than _m_ and
                  _t_ is not less than _n_.  The default behavior is as follows.
                         et-al " et al" 2 3
                  Note the absence of a dot from the end of the abbreviation,
                  which is arguably not correct.  (_Et al_[.]  is short for _et_
                  _alli_ , as _etc._ is short for _et cetera_.)
    
           **include** _file_
                  Include _file_ and interpret the contents as commands.
    
           **join-authors** _string1 string2 string3_
                  Join multiple authors together with _string_ s.  When there
                  are exactly two authors, they will be joined with _string1_.
                  When there are more than two authors, all but the last two
                  will be joined with _string2_ , and the last two authors will
                  be joined with _string3_.  If _string3_ is omitted, it will
                  default to _string1_ ; if _string2_ is also omitted it will also
                  default to _string1_.  For example,
                         join-authors " and " ", " ", and "
                  will restore the default method for joining authors.
    
           **label-in-reference** *
                  When outputting the reference, define the string **[F** to be
                  the reference's label.  This is the default behavior, so
                  the negative version of this command is more useful.
    
           **label-in-text** *
                  For each reference output a label in the text.  The label
                  will be separated from the surrounding text as described in
                  the **bracket-label** command.  This is the default behavior,
                  so the negative version of this command is more useful.
    
           **label** _string_
                  _string_ is a label expression describing how to label each
                  reference.
    
           **separate-label-second-parts** _string_
                  When merging two-part labels, separate the second part of
                  the second label from the first label with _string_.  See the
                  description of the **< > **label expression.
    
           **move-punctuation** *
                  In the text, move any punctuation at the end of line past
                  the label.  We recommend employing this command unless you
                  are using superscripted numbers as labels.
    
           **reverse** * _string_
                  Reverse the fields whose names are in _string_.  An optional
                  integer after a field name limits the number of such fields
                  to the given count; no integer means no limit.
    
           **search-ignore** * _fields_
                  While searching for keys in databases for which no index
                  exists, ignore the contents of _fields_.  Initially, fields
                  **XYZ** are ignored.
    
           **search-truncate** * _n_
                  Only require the first _n_ characters of keys to be given.
                  In effect when searching for a given key words in the
                  database are truncated to the maximum of _n_ and the length
                  of the key.  Initially, _n_ is 6.
    
           **short-label** * _string_
                  _string_ is a label expression that specifies an alternative
                  (usually shorter) style of label.  This is used when the **#**
                  flag is given in the citation.  When using author-date
                  style labels, the identity of the author or authors is
                  sometimes clear from the context, and so it may be
                  desirable to omit the author or authors from the label.
                  The **short-label** command will typically be used to specify a
                  label containing just a date and possibly a disambiguating
                  letter.
    
           **sort** * _string_
                  Sort references according to _string_.  References will
                  automatically be accumulated.  _string_ should be a list of
                  field names, each followed by a number, indicating how many
                  fields with the name should be used for sorting.  “**+** ” can
                  be used to indicate that all the fields with the name
                  should be used.  Also **.** can be used to indicate the
                  references should be sorted using the (tentative) label.
                  (Subsection “Label expressions” below describes the concept
                  of a tentative label.)
    
           **sort-adjacent-labels** *
                  Sort labels that are adjacent in the text according to
                  their position in the reference list.  This command should
                  usually be given if the **abbreviate-label-ranges** command has
                  been given, or if the label expression contains a **< >**
                  expression.  This has no effect unless references are being
                  accumulated.
    
       **Label expressions**
           Label expressions can be evaluated both normally and tentatively.
           The result of normal evaluation is used for output.  The result of
           tentative evaluation, called the _tentative label_ , is used to
           gather the information that normal evaluation needs to
           disambiguate the label.  Label expressions specified by the
           **date-as-label** and **short-label** commands are not evaluated
           tentatively.  Normal and tentative evaluation are the same for all
           types of expression other than **@** , ***** , and **%** expressions.  The
           description below applies to normal evaluation, except where
           otherwise specified.
    
           _field_ [_n_]
                  is the _n_ th part of _field_.  If _n_ is omitted, it defaults
                  to 1.
    
           **'**_string_**'**
                  The characters in _string_ literally.
    
           **@** All authors joined as specified by the **join-authors**
                  command.  The whole of each author's name is used.
                  However, if the references are sorted by author (that is,
                  the sort specification starts with “**A+** ”), then authors'
                  surnames will be used instead, provided that this does not
                  introduce ambiguity, and also an initial subsequence of the
                  authors may be used instead of all the authors, again
                  provided that this does not introduce ambiguity.  Given any
                  two referenced works with _n_ authors, the use of only the
                  surname for the _n_ th author of a reference is regarded as
                  ambiguous if the other reference shares the first _n_ -1
                  authors, the _n_ th authors of each reference are not
                  identical, but the _n_ th authors' surnames _are_ the same.  A
                  proper initial subsequence of the sequence of authors for
                  some reference is considered to be ambiguous if there is a
                  reference with some other sequence of authors which also
                  has that subsequence as a proper initial subsequence.  When
                  an initial subsequence of authors is used, the remaining
                  authors are replaced by the string specified by the **et-al**
                  command; this command may also specify additional
                  requirements that must be met before an initial subsequence
                  can be used.  **@** tentatively evaluates to a canonical
                  representation of the authors, such that authors that
                  compare equally for sorting purposes have the same
                  representation.
    
           **%**_n_
           **%a**
           **%A**
           **%i**
           **%I** The serial number of the reference formatted according to
                  the character following the **%**.  The serial number of a
                  reference is 1 plus the number of earlier references with
                  same tentative label as this reference.  These expressions
                  tentatively evaluate to an empty string.
    
           _expr_***** If there is another reference with the same tentative label
                  as this reference, then _expr_ , otherwise an empty string.
                  It tentatively evaluates to an empty string.
    
           _expr_**+**_n_
           _expr_**-**_n_ The first (**+**) or last (**-**) _n_ upper or lower case letters or
                  digits of _expr_.  _roff_ special characters (such as **\('a**)
                  count as a single letter.  Accent strings are retained but
                  do not count toward the total.
    
           _expr_**.l** _expr_ converted to lowercase.
    
           _expr_**.u** _expr_ converted to uppercase.
    
           _expr_**.c** _expr_ converted to caps and small caps.
    
           _expr_**.r** _expr_ reversed so that the surname is first.
    
           _expr_**.a** _expr_ with first names abbreviated.  Fields specified in the
                  **abbreviate** command are abbreviated before any labels are
                  evaluated.  Thus **.a** is useful only when you want a field to
                  be abbreviated in a label but not in a reference.
    
           _expr_**.y** The year part of _expr_.
    
           _expr_**.+y**
                  The part of _expr_ before the year, or the whole of _expr_ if
                  it does not contain a year.
    
           _expr_**.-y**
                  The part of _expr_ after the year, or an empty string if _expr_
                  does not contain a year.
    
           _expr_**.n** The surname part of _expr_.
    
           _expr1_**~**_expr2_
                  _expr1_ except that if the last character of _expr1_ is **-** then
                  it will be replaced by _expr2_.
    
           _expr1 expr2_
                  The catenation of _expr1_ and _expr2_.
    
           _expr1_**|**_expr2_
                  If _expr1_ is non-empty then _expr1_ otherwise _expr2_.
    
           _expr1_**&**_expr2_
                  If _expr1_ is non-empty then _expr2_ otherwise an empty string.
    
           _expr1_**?**_expr2_**:**_expr3_
                  If _expr1_ is non-empty then _expr2_ otherwise _expr3_.
    
           **<**_expr_**> **The label is in two parts, which are separated by _expr_.
                  Two adjacent two-part labels which have the same first part
                  will be merged by appending the second part of the second
                  label onto the first label separated by the string
                  specified in the **separate-label-second-parts** command
                  (initially, a comma followed by a space); the resulting
                  label will also be a two-part label with the same first
                  part as before merging, and so additional labels can be
                  merged into it.  It is permissible for the first part to be
                  empty; this may be desirable for expressions used in the
                  **short-label** command.
    
           **(**_expr_**)** The same as _expr_.  Used for grouping.
    
           The above expressions are listed in order of precedence (highest
           first); **& **and **|** have the same precedence.
    
       **Macro interface**
           Each reference starts with a call to the macro **]-**.  The string **[F**
           will be defined to be the label for this reference, unless the
           **no-label-in-reference** command has been given.  There then follows
           a series of string definitions, one for each field: string **[**_X_
           corresponds to field _X_.  The register **[P** is set to 1 if the **P**
           field contains a range of pages.  The **[T** , **[A** and **[O** registers are
           set to 1 according as the **T** , **A** and **O** fields end with any of **.?!**
           (an end-of-sentence character).  The **[E** register will be set to 1
           if the **[E** string contains more than one name.  The reference is
           followed by a call to the **][** macro.  The first argument to this
           macro gives a number representing the type of the reference.  If a
           reference contains a **J** field, it will be classified as type 1,
           otherwise if it contains a **B** field, it will be type 3, otherwise
           if it contains a **G** or **R** field it will be type 4, otherwise if it
           contains an **I** field it will be type 2, otherwise it will be
           type 0.  The second argument is a symbolic name for the type:
           **other** , **journal-article** , **book** , **article-in-book** , or **tech-report**.
           Groups of references that have been accumulated or are produced by
           the **bibliography** command are preceded by a call to the **] < **macro
           and followed by a call to the **] > **macro.
    


## Options



           **--help** displays a usage message, while **-v** and **--version** show
           version information; all exit afterward.
    
           **-R** Don't recognize lines beginning with **.R1** /**.R2**.
    
           Other options are equivalent to _refer_ commands.
    
           **-a** _n_   **reverse A** _n_
    
           **-b     no-label-in-text; no-label-in-reference**
    
           **-B** See below.
    
           **-c** _fields_
                  **capitalize** _fields_
    
           **-C     compatible**
    
           **-e     accumulate**
    
           **-f** _n_   **label %**_n_
    
           **-i** _fields_
                  **search-ignore** _fields_
    
           **-k     label L~%a**
    
           **-k** _field_
                  **label** _field_**~%a**
    
           **-l     label A.nD.y%a**
    
           **-l** _m_   **label A.n+**_m_**D.y%a**
    
           **-l ,**_n_  **label A.nD.y-**_n_**%a**
    
           **-l** _m_**,**_n_ **label A.n+**_m_**D.y-**_n_**%a**
    
           **-n     no-default-database**
    
           **-p** _db-file_
                  **database** _db-file_
    
           **-P     move-punctuation**
    
           **-s** _spec_
                  **sort** _spec_
    
           **-S     label "(A.n|Q) ', ' (D.y|D)"; bracket-label " (" ) "; "**
    
           **-t** _n_   **search-truncate** _n_
    
           The **B** option has command equivalents with the addition that the
           file names specified on the command line are processed as if they
           were arguments to the **bibliography** command instead of in the
           normal way.
    
           **-B     annotate X AP; no-label-in-reference**
    
           **-B** _field_**.**_macro_
                  **annotate** _field macro_**; no-label-in-reference**
    


## Exit status



           _refer_ exits with status **0** on successful operation, status **2** if the
           program cannot interpret its command-line arguments, and status **1**
           if it encounters an error during operation.
    


## Environment



           _REFER_  Assign this variable a file name to override the default
                  database.
    


## Files



           _/usr/dict/papers/Ind_
                  Default database.
    
           file _.i_ Index files.
    
           _/usr/local/share/groff/1.23.0/tmac/refer.tmac_
                  defines macros and strings facilitating integration with
                  macro packages that wish to support _refer_.
    
           _refer_ uses temporary files.  See the _groff_(1) man page for details
           of where such files are created.
    


## Bugs



           In label expressions, **< > **expressions are ignored inside **.**_char_
           expressions.
    


## Examples



           We can illustrate the operation of _refer_ with a sample
           bibliographic database containing one entry and a simple _roff_
           document to cite that entry.
    
                  $ **cat > my-db-file**
                  **%A Daniel P.\ & Friedman**
                  **%A Matthias Felleisen**
                  **%C Cambridge, Massachusetts**
                  **%D 1996**
                  **%I The MIT Press**
                  **%T The Little Schemer, Fourth Edition**
                  $ **refer -p my-db-file**
                  **Read the book**
                  **.[**
                  **friedman**
                  **.]**
                  **on your summer vacation.**
                  _< Control+D>_
                  .lf 1 -
                  Read the book\*([.1\*(.]
                  .ds [F 1
                  .]-
                  .ds [A Daniel P. Friedman and Matthias Felleisen
                  .ds [C Cambridge, Massachusetts
                  .ds [D 1996
                  .ds [I The MIT Press
                  .ds [T The Little Schemer, Fourth Edition
                  .nr [T 0
                  .nr [A 0
                  .][ 2 book
                  .lf 5 -
                  on your summer vacation.
    
           The foregoing shows us that _refer_ (a) produces a label “1”; (b)
           brackets that label with interpolations of the “**[.** ”  and “**.]** ”
           strings; (c) calls a macro “**]-** ”; (d) defines strings and registers
           containing the label and bibliographic data for the reference; (e)
           calls a macro “**][** ”; and (f) uses the **lf** request to restore the
           line numbers of the input.  As noted in subsection “Macro
           interface” above, it is the document's responsibility to employ
           and format the information usefully.  Let us see how we might turn
           _groff_ms_(7) to this task.
    
                  $ **REFER=my-db-file groff -R -ms**
                  **.LP**
                  **Read the book**
                  **.[**
                  **friedman**
                  **.]**
                  **on your summer vacation.**
                  **Commentary is available.\*{*\*}**
                  **.FS \*{*\*}**
                  **Space reserved for penetrating insight.**
                  **.FE**
    
           _ms_ 's automatic footnote numbering mechanism is not aware of
           _refer_ 's label numbering, so we have manually specified a
           (superscripted) symbolic footnote for our non-bibliographic aside.
    


## See also



           “Refer — A Bibliography System”, by Bill Tuthill, 1983, Computing
           Services, University of California, Berkeley.
    
           “Some Applications of Inverted Indexes on the Unix System”, by M.
           E. Lesk, 1978, AT&T Bell Laboratories Computing Science Technical
           Report No. 69.
    
           _indxbib_(1), _lookbib_(1), _lkbib_(1)
    


* * *