man pages section 1: User Commands

Exit Print View

Updated: July 2014

grefer (1)


grefer - preprocess bibliographic references for groff


grefer [ -benvCPRS ] [ -an ] [ -cfields ] [ -fn ]
[ -ifields ] [ -kfield ] [ -lm,n ] [ -pfilename ]
[ -sfields ] [ -tn ] [ -Bfield.macro ]
[ filename... ]

It is possible to have whitespace  between  a  command  line
option and its parameter.


User Commands                                           GREFER(1)

     grefer - preprocess bibliographic references for groff

     grefer [ -benvCPRS ] [ -an ] [ -cfields ] [ -fn ]
            [ -ifields ] [ -kfield ] [ -lm,n ] [ -pfilename ]
            [ -sfields ] [ -tn ] [ -Bfield.macro ]
            [ filename... ]

     It is possible to have whitespace  between  a  command  line
     option and its parameter.

     This  file documents the GNU version of refer, which is part
     of the groff document formatting system.  refer  copies  the
     contents  of filename... to the standard output, except that
     lines between .[ and .] are interpreted  as  citations,  and
     lines  between .R1 and .R2 are interpreted as commands about
     how citations are to be processed.

     Each citation specifies a reference.  The citation can spec-
     ify  a  reference that is contained in a bibliographic data-
     base by giving a set of keywords that  only  that  reference
     contains.   Alternatively it can specify a reference by sup-
     plying a database record in the citation.  A combination  of
     these alternatives is also possible.

     For  each  citation,  refer  can produce a mark in the text.
     This mark consists of some label which can be separated from
     the  text  and  from other labels in various ways.  For each
     reference it also outputs groff commands that can be used by
     a  macro  package  to produce a formatted reference for each
     citation.  The output of refer must therefore  be  processed
     using  a suitable macro package.  The -ms and -me macros are
     both suitable.  The commands to format a  citation's  refer-
     ence  can  be  output immediately after the citation, or the
     references may be accumulated, and the  commands  output  at
     some  later  point.  If the references are accumulated, then
     multiple citations of the same reference will produce a sin-
     gle formatted reference.

     The  interpretation of lines between .R1 and .R2 as commands
     is a new feature of GNU refer.  Documents making use of this
     feature  can still be processed by Unix refer just by adding
     the lines

          .de R1
          .ig R2
     to the beginning of the document.  This will cause troff  to
     ignore  everything  between .R1 and .R2.  The effect of some
     commands can also be achieved by options.  These options are

Groff Version 1.19.2 Last change: 6 May 2005                    1

User Commands                                           GREFER(1)

     supported  mainly  for compatibility with Unix refer.  It is
     usually more convenient to use commands.

     refer generates .lf lines so that filenames and line numbers
     in messages produced by commands that read refer output will
     be correct; it also interprets lines beginning with  .lf  so
     that  filenames  and  line  numbers  in the messages and .lf
     lines that it produces will be accurate even  if  the  input
     has been preprocessed by a command such as gsoelim(1).

     Most  options  are equivalent to commands (for a description
     of these commands see the Commands subsection):

     -b   no-label-in-text; no-label-in-reference

     -e   accumulate

     -n   no-default-database

     -C   compatible

     -P   move-punctuation

     -S   label "(A.n|Q) ', ' (D.y|D)"; bracket-label " (" ) "; "

     -an  reverse An

          capitalize fields

     -fn  label %n

          search-ignore fields

     -k   label L~%a

          label field~%a

     -l   label A.nD.y%a

     -lm  label A.n+mD.y%a

     -l,n label A.nD.y-n%a

          label A.n+mD.y-n%a

          database filename

Groff Version 1.19.2 Last change: 6 May 2005                    2

User Commands                                           GREFER(1)

          sort spec

     -tn  search-truncate n

     These  options are equivalent to the following commands with
     the addition that the filenames  specified  on  the  command
     line are processed as if they were arguments to the bibliog-
     raphy command instead of in the normal way:

     -B   annotate X AP; no-label-in-reference

          annotate field macro; no-label-in-reference

     The following options have no equivalent commands:

     -v   Print the version number.

     -R   Don't recognize lines beginning with .R1/.R2.

  Bibliographic databases
     The bibliographic database is  a  text  file  consisting  of
     records  separated  by one or more blank lines.  Within each
     record fields start with a % at the  beginning  of  a  line.
     Each field has a one character name that immediately follows
     the %.  It is best to use only upper and lower case  letters
     for  the  names  of fields.  The name of the field should be
     followed by exactly one space, and then by the  contents  of
     the  field.   Empty  fields  are  ignored.  The conventional
     meaning of each field is as follows:

     A    The name of an author.  If the name  contains  a  title
          such as Jr. at the end, it should be separated from the
          last name by a comma.  There  can  be  multiple  occur-
          rences  of  the A field.  The order is significant.  It
          is a good idea always to supply  an  A  field  or  a  Q

     B    For an article that is part of a book, the title of the

     C    The place (city) of publication.

     D    The date of publication.  The year should be  specified
          in  full.   If  the month is specified, the name rather
          than the number of the month should be used,  but  only
          the  first  three  letters  are required.  It is a good
          idea always to  supply  a  D  field;  if  the  date  is
          unknown,  a  value  such  as in press or unknown can be

Groff Version 1.19.2 Last change: 6 May 2005                    3

User Commands                                           GREFER(1)

     E    For an article that is part of a book, the name  of  an
          editor  of the book.  Where the work has editors and no
          authors, the names of the editors should be given as  A
          fields  and , (ed) or , (eds) should be appended to the
          last author.

     G    US Government ordering number.

     I    The publisher (issuer).

     J    For an article in a journal, the name of the journal.

     K    Keywords to be used for searching.

     L    Label.

     N    Journal issue number.

     O    Other information.  This is usually printed at the  end
          of the reference.

     P    Page number.  A range of pages can be specified as m-n.

     Q    The name of the author, if the author is not a  person.
          This will only be used if there are no A fields.  There
          can only be one Q field.

     R    Technical report number.

     S    Series name.

     T    Title.  For an article  in  a  book  or  journal,  this
          should be the title of the article.

     V    Volume number of the journal or book.

     X    Annotation.

     For  all  fields  except  A and E, if there is more than one
     occurrence of a particular field in a record, only the  last
     such field will be used.

     If accent strings are used, they should follow the character
     to be accented.  This means that the AM macro must  be  used
     with  the  -ms macros.  Accent strings should not be quoted:
     use one \ rather than two.

     The format of a citation is
          flags keywords

Groff Version 1.19.2 Last change: 6 May 2005                    4

User Commands                                           GREFER(1)


     The opening-text,  closing-text  and  flags  components  are
     optional.   Only  one  of the keywords and fields components
     need be specified.

     The keywords component  says  to  search  the  bibliographic
     databases  for  a  reference  that contains all the words in
     keywords.  It is an error if  more  than  one  reference  if

     The fields components specifies additional fields to replace
     or supplement those specified in the reference.  When refer-
     ences  are  being  accumulated and the keywords component is
     non-empty, then additional fields should be  specified  only
     on  the first occasion that a particular reference is cited,
     and will apply to all citations of that reference.

     The  opening-text  and  closing-text   component   specifies
     strings  to  be  used  to  bracket  the label instead of the
     strings specified in the bracket-label command.   If  either
     of  these  components is non-empty, the strings specified in
     the bracket-label command will not be used;  this  behaviour
     can  be  altered using the [ and ] flags.  Note that leading
     and trailing spaces are significant for these components.

     The flags component is a list of non-alphanumeric characters
     each  of  which  modifies  the  treatment of this particular
     citation.  Unix refer will treat these flags as part of  the
     keywords and so will ignore them since they are non-alphanu-
     meric.  The following flags are currently recognized:

     #    This says to use the label specified by the short-label
          command,  instead  of  that specified by the label com-
          mand.  If no short label has been specified, the normal
          label  will be used.  Typically the short label is used
          with author-date labels and consists of only  the  date
          and possibly a disambiguating letter; the # is supposed
          to be suggestive of a numeric type of label.

     [    Precede opening-text with the first string specified in
          the bracket-label command.

     ]    Follow closing-text with the second string specified in
          the bracket-label command.

     One advantages of using  the  [  and  ]  flags  rather  than
     including  the  brackets in opening-text and closing-text is
     that you can change the style of bracket used in  the  docu-
     ment  just  by  changing the bracket-label command.  Another
     advantage is that sorting and merging of citations will  not
     necessarily be inhibited if the flags are used.

Groff Version 1.19.2 Last change: 6 May 2005                    5

User Commands                                           GREFER(1)

     If  a  label  is  to  be  inserted into the text, it will be
     attached to the line preceding the .[ line.  If there is  no
     such line, then an extra line will be inserted before the .[
     line and a warning will be given.

     There is no special notation for making a citation to multi-
     ple  references.   Just use a sequence of citations, one for
     each reference.  Don't put anything between  the  citations.
     The  labels  for  all  the citations will be attached to the
     line preceding the first citation.  The labels may  also  be
     sorted  or  merged.   See  the  description  of the <> label
     expression, and of the sort-adjacent-labels and  abbreviate-
     label-ranges  command.   A  label  will not be merged if its
     citation has a non-empty opening-text or closing-text.  How-
     ever, the labels for a citation using the ] flag and without
     any closing-text immediately followed by  a  citation  using
     the  [  flag  and without any opening-text may be sorted and
     merged even though the first citation's opening-text or  the
     second  citation's  closing-text is non-empty.  (If you wish
     to prevent this just make the first citation's  closing-text

     Commands  are  contained between lines starting with .R1 and
     .R2.  Recognition of these lines can be prevented by the  -R
     option.   When a .R1 line is recognized any accumulated ref-
     erences are flushed out.  Neither .R1  nor  .R2  lines,  nor
     anything between them is output.

     Commands  are  separated  by newlines or ;s.  # 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 " extends to the next " that is not followed by another
     ".  If there is no such " the word extends to the end of the
     line.   Pairs  of " in a word beginning with " collapse to a
     single ".  Neither # nor ; are recognized inside "s.  A line
     can  be continued by ending it with \; this works everywhere
     except after a #.

     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 argu-

     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  let-
     ters; m and n are used for a non-negative numbers; string is
     used for an arbitrary string; filename is used for the  name
     of a file.

Groff Version 1.19.2 Last change: 6 May 2005                    6

User Commands                                           GREFER(1)

     abbreviate* fields string1 string2 string3 string4
                              Abbreviate   the   first  names  of
                              fields.  An initial letter will  be
                              separated from another initial let-
                              ter by string1, from the last  name
                              by  string2, and from anything else
                              (such as a 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  abbrevia-
                              tion.  Names are abbreviated before
                              sorting and before label  construc-

     abbreviate-label-ranges* string
                              Three  or more adjacent labels that
                              refer  to  consecutive   references
                              will be abbreviated to a label con-
                              sisting of the  first  label,  fol-
                              lowed  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   refer-
                              ences  will be written out whenever
                              a reference of the form


                              is  encountered,  after  all  input
                              files hve been processed, and when-
                              ever .R1 line is recognized.

     annotate* field string   field is an annotation; print it at
                              the end of the reference as a para-
                              graph preceded by the line


                              If macro is omitted it will default
                              to  AP; if field is also omitted it
                              will default to X.  Only one  field

Groff Version 1.19.2 Last change: 6 May 2005                    7

User Commands                                           GREFER(1)

                              can be an annotation.

     articles string...       string...  are  definite or indefi-
                              nite  articles,   and   should   be
                              ignored   at  the  beginning  of  T
                              fields  when  sorting.   Initially,
                              the,  a  and  an  are recognized as

     bibliography filename... Write out all the  references  con-
                              tained  in  the bibliographic data-
                              bases  filename...   This   command
                              should   come  last  in  a  .R1/.R2

     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  behav-
                              iour is

                                   bracket-label \*([. \*(.] ", "

     capitalize fields        Convert fields to  caps  and  small

     compatible*              Recognize  .R1  and  .R2  even when
                              followed by a character other  than
                              space or newline.

     database filename...     Search  the bibliographic databases
                              filename...  For each  filename  if
                              an   index  filename.i  created  by
                              gindxbib(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  con-
                              structing the label.  See the Label
                              expressions   subsection   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

Groff Version 1.19.2 Last change: 6 May 2005                    8

User Commands                                           GREFER(1)

                              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  let-
                              ter to the year part of the D field
                              in the reference.

     default-database*        The  default  database  should   be
                              searched.   This is the default be-
                              haviour, 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-data-
                              base command must be  given  before
                              then, in order to be effective.

     discard* fields          When  the reference is read, fields
                              should be discarded; no string def-
                              initions for fields will be output.
                              Initially, fields are XYZ.

     et-al* string m n        Control use of et al in the evalua-
                              tion  of  @  expressions  in  label
                              expressions.   If  the  number   of
                              authors  needed  to make the author
                              sequence unambiguous is u  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 behaviour

                                   et-al " et al" 2 3

     include filename         Include filename and interpret  the
                              contents as commands.

     join-authors string1 string2 string3
                              This  says  how  authors  should be
                              joined together.   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

Groff Version 1.19.2 Last change: 6 May 2005                    9

User Commands                                           GREFER(1)

                              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 ref-
                              erence's  label.    This   is   the
                              default  behaviour; so the negative
                              version of  this  command  is  more

     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 be-
                              haviour; so the negative version of
                              this command is more useful.

     label string             string   is   a   label  expression
                              describing how to label each refer-

     separate-label-second-parts string
                              When merging two-part labels, sepa-
                              rate 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.
                              It  is  usually a good idea to give
                              this command unless you  are  using
                              superscripted numbers as labels.

     reverse* string          Reverse  the fields whose names are
                              in string.  Each field name can  be
                              followed by a number which says how
                              many   such   fields   should    be
                              reversed.   If  no  number is given
                              for a field, all such  fields  will
                              be reversed.

     search-ignore* fields    While   searching   for   keys   in

Groff Version 1.19.2 Last change: 6 May 2005                   10

User Commands                                           GREFER(1)

                              databases  for   which   no   index
                              exists,   ignore  the  contents  of
                              fields.  Initially, fields XYZ  are

     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 contain-
                              ing just a date and possibly a dis-
                              ambiguating letter.

     sort* string             Sort    references   according   to
                              string.  References will  automati-
                              cally   be   accumulated.    string
                              should be a list  of  field  names,
                              each followed by a number, indicat-
                              ing 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  indi-
                              cate   the   references  should  be
                              sorted using the (tentative) label.
                              (The  Label  expressions subsection
                              describes the concept of  a  tenta-
                              tive label.)

     sort-adjacent-labels*    Sort  labels  that  are adjacent in
                              the text according to  their  posi-
                              tion  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  <> expres-
                              sion.  This  will  have  no  effect
                              unless    references    are   being

Groff Version 1.19.2 Last change: 6 May 2005                   11

User Commands                                           GREFER(1)


  Label expressions
     Label expressions can be evaluated both normally and  tenta-
     tively.  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 evalua-
     tion 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
          The  n-th  part of field.  If n is omitted, it defaults
          to 1.

          The characters in string literally.

     @    All the authors joined as specified by the join-authors
          command.  The whole of each author's name will be used.
          However, if the references are sorted by  author  (that
          is   the  sort  specification  starts  with  A+),  then
          authors' last names 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 intro-
          duce ambiguity.  The use of only the last name for  the
          i-th  author  of  some  reference  is  considered to be
          ambiguous if there is some other reference,  such  that
          the  first  i-1 authors of the references are the same,
          the i-th  authors  are  not  the  same,  but  the  i-th
          authors'  last  names  are  the same.  A proper initial
          subsequence of the sequence of authors for some  refer-
          ence is considered to be ambiguous if there is a refer-
          ence 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  remain-
          ing 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 subse-
          quence can be  used.   @  tentatively  evaluates  to  a
          canonical  representation  of  the  authors,  such that
          authors that compare equally for sorting  purpose  will
          have the same representation.


Groff Version 1.19.2 Last change: 6 May 2005                   12

User Commands                                           GREFER(1)

     %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.

          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.

          The first (+) or last (-) n upper or lower case letters
          or digits of expr.  Troff special characters  (such  as
          \('a)  count  as  a  single letter.  Accent strings are
          retained but do not count towards the total.

          expr converted to lowercase.

          expr converted to uppercase.

          expr converted to caps and small caps.

          expr reversed so that the last name is first.

          expr with first names abbreviated.   Note  that  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.

          The year part of expr.

          The part of expr before the year, or the whole of  expr
          if it does not contain a year.

          The  part of expr after the year, or an empty string if
          expr does not contain a year.

          The last name part of expr.

Groff Version 1.19.2 Last change: 6 May 2005                   13

User Commands                                           GREFER(1)

          expr1 except that if the last character of expr1  is  -
          then it will be replaced by expr2.

     expr1 expr2
          The concatenation of expr1 and expr2.

          If expr1 is non-empty then expr1 otherwise expr2.

          If  expr1  is  non-empty  then expr2 otherwise an empty

          If expr1 is non-empty then expr2 otherwise expr3.

          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.  Note that it is  permis-
          sible for the first part to be empty; this maybe desir-
          able for expressions used in the short-label command.

          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  refer-
     ence,  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
     number register [P is set to 1 if the  P  field  contains  a
     range  of pages.  The [T, [A and [O number registers are set
     to 1 according as the T, A and O fields end with one of  the
     characters  .?!.  The [E number 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  ref-
     erence.  If a reference contains a J field, it will be clas-
     sified as type 1, otherwise if it contains  a  B  field,  it
     will type 3, otherwise if it contains a G or R field it will

Groff Version 1.19.2 Last change: 6 May 2005                   14

User Commands                                           GREFER(1)

     be type 4, otherwise if  contains  a  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.

     /usr/dict/papers/Ind  Default database.

     file.i                Index files.

     REFER  If set, overrides the default database.

     See  attributes(5)  for  descriptions   of   the   following

     |Availability   | text/groff       |
     |Stability      | Uncommitted      |
     gindxbib(1), glookbib(1), lkbib(1)

     In  label  expressions,  <>  expressions  are ignored inside
     .char expressions.

     This  software  was   built   from   source   available   at    The  original
     community       source       was       downloaded       from

     Further  information about this software can be found on the
     open source community  website  at

Groff Version 1.19.2 Last change: 6 May 2005                   15