1REFER(1)                    General Commands Manual                   REFER(1)
2
3
4

NAME

6       refer - preprocess bibliographic references for groff
7

SYNOPSIS

9       refer [-benCPRS] [-a n] [-c fields] [-f n] [-i fields] [-k field]
10             [-l m,n] [-p filename] [-s fields] [-t n] -B field.macro [file
11             ...]
12
13       refer --help
14
15       refer -v
16       refer --version
17

DESCRIPTION

19       This  file  documents  the  GNU  version of refer, which is part of the
20       groff document formatting system.  refer copies the contents  of  file‐
21       name... to the standard output, except that lines between .[ and .] are
22       interpreted as citations, and lines between .R1 and .R2 are interpreted
23       as commands about how citations are to be processed.
24
25       Each citation specifies a reference.  The citation can specify a refer‐
26       ence that is contained in a bibliographic database by giving a  set  of
27       keywords that only that reference contains.  Alternatively it can spec‐
28       ify a reference by supplying a database record in the citation.  A com‐
29       bination of these alternatives is also possible.
30
31       For  each  citation,  refer  can produce a mark in the text.  This mark
32       consists of some label which can be separated from the  text  and  from
33       other labels in various ways.  For each reference it also outputs groff
34       commands that can be used by a macro package  to  produce  a  formatted
35       reference  for  each  citation.   The output of refer must therefore be
36       processed using a suitable macro package.  The -ms and -me  macros  are
37       both  suitable.   The  commands to format a citation's reference can be
38       output immediately after the citation, or the references may be accumu‐
39       lated,  and the commands output at some later point.  If the references
40       are accumulated, then multiple citations of  the  same  reference  will
41       produce a single formatted reference.
42
43       The  interpretation  of  lines between .R1 and .R2 as commands is a new
44       feature of GNU refer.  Documents making use of this feature  can  still
45       be processed by Unix refer just by adding the lines
46
47              .de R1
48              .ig R2
49              ..
50       to  the beginning of the document.  This will cause troff to ignore ev‐
51       erything between .R1 and .R2.  The effect of some commands can also  be
52       achieved  by  options.  These options are supported mainly for compati‐
53       bility with Unix refer.  It is usually more convenient to use commands.
54
55       refer generates .lf lines so that filenames and line  numbers  in  mes‐
56       sages  produced  by commands that read refer output will be correct; it
57       also interprets lines beginning with .lf so  that  filenames  and  line
58       numbers in the messages and .lf lines that it produces will be accurate
59       even if the input has been preprocessed by a command such as soelim(1).
60

OPTIONS

62       Whitespace is permitted between a command-line option and its argument.
63
64       Most options are equivalent to commands (for  a  description  of  these
65       commands, see subsection “Commands” below).
66
67       -b     no-label-in-text; no-label-in-reference
68
69       -e     accumulate
70
71       -n     no-default-database
72
73       -C     compatible
74
75       -P     move-punctuation
76
77       -S     label "(A.n|Q) ', ' (D.y|D)"; bracket-label " (" ) "; "
78
79       -an    reverse An
80
81       -cfields
82              capitalize fields
83
84       -fn    label %n
85
86       -ifields
87              search-ignore fields
88
89       -k     label L~%a
90
91       -kfield
92              label field~%a
93
94       -l     label A.nD.y%a
95
96       -lm    label A.n+mD.y%a
97
98       -l,n   label A.nD.y-n%a
99
100       -lm,n  label A.n+mD.y-n%a
101
102       -pfilename
103              database filename
104
105       -sspec sort spec
106
107       -tn    search-truncate n
108
109       These  options  are equivalent to the following commands with the addi‐
110       tion that the filenames specified on the command line are processed  as
111       if  they  were  arguments to the bibliography command instead of in the
112       normal way:
113
114       -B     annotate X AP; no-label-in-reference
115
116       -Bfield.macro
117              annotate field macro; no-label-in-reference
118
119       The following options have no equivalent commands:
120
121       -v     Print the version number.
122
123       -R     Don't recognize lines beginning with .R1/.R2.
124

USAGE

126   Bibliographic databases
127       The bibliographic database is a text file consisting of  records  sepa‐
128       rated by one or more blank lines.  Within each record fields start with
129       a % at the beginning of a line.  Each field has a  one  character  name
130       that immediately follows the %.  It is best to use only upper and lower
131       case letters for the names of fields.  The name of the field should  be
132       followed  by  exactly one space, and then by the contents of the field.
133       Empty fields are ignored.  The conventional meaning of each field is as
134       follows:
135
136       %A     The name of an author.  If the name contains a title such as Jr.
137              at the end, it should be separated  from  the  last  name  by  a
138              comma.   There can be multiple occurrences of the %A field.  The
139              order is significant.  It is a good idea always to supply an  %A
140              field or a %Q field.
141
142       %B     For an article that is part of a book, the title of the book.
143
144       %C     The place (city) of publication.
145
146       %D     The  date of publication.  The year should be specified in full.
147              If the month is specified, the name rather than  the  number  of
148              the  month  should be used, but only the first three letters are
149              required.  It is a good idea always to supply a %D field; if the
150              date  is  unknown,  a  value  such as in press or unknown can be
151              used.
152
153       %E     For an article that is part of a book, the name of an editor  of
154              the  book.  Where the work has editors and no authors, the names
155              of the editors should be  given  as  %A  fields  and  , (ed)  or
156              , (eds) should be appended to the last author.
157
158       %G     US Government ordering number.
159
160       %I     The publisher (issuer).
161
162       %J     For an article in a journal, the name of the journal.
163
164       %K     Keywords to be used for searching.
165
166       %L     Label.
167
168       %N     Journal issue number.
169
170       %O     Other  information.   This  is usually printed at the end of the
171              reference.
172
173       %P     Page number.  A range of pages can be specified as m-n.
174
175       %Q     The name of the author, if the author is  not  a  person.   This
176              will  only be used if there are no %A fields.  There can only be
177              one %Q field.
178
179       %R     Technical report number.
180
181       %S     Series name.
182
183       %T     Title.  For an article in a book or journal, this should be  the
184              title of the article.
185
186       %V     Volume number of the journal or book.
187
188       %X     Annotation.
189
190       For  all  fields except %A and %E, if there is more than one occurrence
191       of a particular field in a record, only the last  such  field  will  be
192       used.
193
194       If  accent strings are used, they should follow the character to be ac‐
195       cented.  This means that the AM macro must be used with the -ms macros.
196       Accent strings should not be quoted: use one \ rather than two.
197
198   Citations
199       The format of a citation is
200              .[opening-text
201              flags keywords
202              fields
203              .]closing-text
204
205       The  opening-text,  closing-text,  and  flags  components are optional.
206       Only one of the keywords and fields components need be specified.
207
208       The keywords component says to search the bibliographic databases for a
209       reference  that  contains all the words in keywords.  It is an error if
210       more than one reference if found.
211
212       The fields components specifies additional fields to replace or supple‐
213       ment those specified in the reference.  When references are being accu‐
214       mulated and the keywords component is non-empty, then additional fields
215       should be specified only on the first occasion that a particular refer‐
216       ence is cited, and will apply to all citations of that reference.
217
218       The opening-text and closing-text component  specifies  strings  to  be
219       used  to  bracket  the  label  instead  of the strings specified in the
220       bracket-label command.  If either of these components is non-empty, the
221       strings  specified  in the bracket-label command will not be used; this
222       behaviour can be altered using the [ and ] flags.   Note  that  leading
223       and trailing spaces are significant for these components.
224
225       The  flags  component  is a list of non-alphanumeric characters each of
226       which modifies the treatment of this particular citation.   Unix  refer
227       will  treat these flags as part of the keywords and so will ignore them
228       since they are non-alphanumeric.  The  following  flags  are  currently
229       recognized:
230
231       #      This says to use the label specified by the short-label command,
232              instead of that specified by the label command.  If no short la‐
233              bel  has  been  specified, the normal label will be used.  Typi‐
234              cally the short label is used with author-date labels  and  con‐
235              sists of only the date and possibly a disambiguating letter; the
236              # is supposed to be suggestive of a numeric type of label.
237
238       [      Precede opening-text with the  first  string  specified  in  the
239              bracket-label command.
240
241       ]      Follow  closing-text  with  the  second  string specified in the
242              bracket-label command.
243
244       One advantages of using the [ and ] flags  rather  than  including  the
245       brackets  in  opening-text  and closing-text is that you can change the
246       style of bracket used in the document just by changing the  bracket-la‐
247       bel  command.   Another  advantage is that sorting and merging of cita‐
248       tions will not necessarily be inhibited if the flags are used.
249
250       If a label is to be inserted into the text, it will be attached to  the
251       line  preceding  the  .[ line.  If there is no such line, then an extra
252       line will be inserted before the .[ line and a warning will be given.
253
254       There is no special notation for making a citation to  multiple  refer‐
255       ences.   Just  use  a  sequence  of  citations, one for each reference.
256       Don't put anything between the citations.  The labels for all the cita‐
257       tions  will  be attached to the line preceding the first citation.  The
258       labels may also be sorted or merged.  See the description of the <> la‐
259       bel  expression,  and of the sort-adjacent-labels and abbreviate-label-
260       ranges command.  A label will not be merged if its citation has a  non-
261       empty opening-text or closing-text.  However, the labels for a citation
262       using the ] flag and without any closing-text immediately followed by a
263       citation  using  the  [ flag and without any opening-text may be sorted
264       and merged even though the first citation's opening-text or the  second
265       citation's  closing-text  is  non-empty.   (If you wish to prevent this
266       just make the first citation's closing-text \&.)
267
268   Commands
269       Commands are contained between lines starting with .R1 and .R2.  Recog‐
270       nition  of  these  lines can be prevented by the -R option.  When a .R1
271       line is recognized any accumulated references are flushed out.  Neither
272       .R1 nor .R2 lines, nor anything between them is output.
273
274       Commands  are separated by newlines or ;s.  # introduces a comment that
275       extends to the end of the line (but  does  not  conceal  the  newline).
276       Each command is broken up into words.  Words are separated by spaces or
277       tabs.  A word that begins with " extends to the next " that is not fol‐
278       lowed  by another ".  If there is no such " the word extends to the end
279       of the line.  Pairs of " in a word beginning with " collapse to a  sin‐
280       gle  ".   Neither # nor ; are recognized inside "s.  A line can be con‐
281       tinued by ending it with \; this works everywhere except after a #.
282
283       Each command name that is marked with * has an associated negative com‐
284       mand  no-name that undoes the effect of name.  For example, the no-sort
285       command specifies that references should not be sorted.   The  negative
286       commands take no arguments.
287
288       In the following description each argument must be a single word; field
289       is used for a single upper or lower case letter naming a field;  fields
290       is used for a sequence of such letters; m and n are used for a non-neg‐
291       ative numbers; string is used for an arbitrary string; filename is used
292       for the name of a file.
293
294       abbreviate* fields string1 string2 string3 string4
295              Abbreviate the first names of fields.  An initial letter will be
296              separated from another initial letter by string1, from the  last
297              name by string2, and from anything else (such as a von or de) by
298              string3.  These default to a period followed by a space.   In  a
299              hyphenated first name, the initial of the first part of the name
300              will be separated from the hyphen by string4; this defaults to a
301              period.  No attempt is made to handle any ambiguities that might
302              result from abbreviation.  Names are abbreviated before  sorting
303              and before label construction.
304
305       abbreviate-label-ranges* string
306              Three  or  more adjacent labels that refer to consecutive refer‐
307              ences will be abbreviated to a label consisting of the first la‐
308              bel,  followed  by  string  followed by the last label.  This is
309              mainly useful with numeric labels.  If string is omitted it  de‐
310              faults to -.
311
312       accumulate*
313              Accumulate  references  instead of writing out each reference as
314              it is encountered.  Accumulated references will be  written  out
315              whenever a reference of the form
316
317                     .[
318                     $LIST$
319                     .]
320
321              is  encountered,  after all input files have been processed, and
322              whenever .R1 line is recognized.
323
324       annotate* field string
325              field is an annotation; print it at the end of the reference  as
326              a paragraph preceded by the line
327
328                     .string
329
330              If  string  is  omitted  it will default to AP; if field is also
331              omitted it will default to X.  Only one field can be an  annota‐
332              tion.
333
334       articles string...
335              string... are definite or indefinite articles, and should be ig‐
336              nored at the beginning of T  fields  when  sorting.   Initially,
337              the, a and an are recognized as articles.
338
339       bibliography filename...
340              Write  out  all  the  references  contained in the bibliographic
341              databases filename...   This  command  should  come  last  in  a
342              .R1/.R2 block.
343
344       bracket-label string1 string2 string3
345              In  the  text,  bracket each label with string1 and string2.  An
346              occurrence of string2 immediately followed by  string1  will  be
347              turned into string3.  The default behaviour is
348
349                     bracket-label \*([. \*(.] ", "
350
351       capitalize fields
352              Convert fields to caps and small caps.
353
354       compatible*
355              Recognize  .R1  and  .R2 even when followed by a character other
356              than space or newline.
357
358       database filename...
359              Search the bibliographic databases filename...  For  each  file‐
360              name  if  an index filename.i created by indxbib(1) exists, then
361              it will be searched instead; each index can cover multiple data‐
362              bases.
363
364       date-as-label* string
365              string  is a label expression that specifies a string with which
366              to replace the D field after constructing the label.   See  sub‐
367              section “Label expressions” below for a description of label ex‐
368              pressions.  This command is useful if you do not  want  explicit
369              labels  in  the  reference  list, but instead want to handle any
370              necessary disambiguation by qualifying the  date  in  some  way.
371              The  label  used in the text would typically be some combination
372              of the author and date.  In most cases you should also  use  the
373              no-label-in-reference command.  For example,
374
375                     date-as-label D.+yD.y%a*D.-y
376
377              would  attach  a disambiguating letter to the year part of the D
378              field in the reference.
379
380       default-database*
381              The default database should be searched.  This  is  the  default
382              behaviour,  so the negative version of this command is more use‐
383              ful.  refer determines whether the default  database  should  be
384              searched  on  the  first  occasion that it needs to do a search.
385              Thus a no-default-database command must be given before then, in
386              order to be effective.
387
388       discard* fields
389              When  the  reference  is  read,  fields  should be discarded; no
390              string definitions for fields will be output.  Initially, fields
391              are XYZ.
392
393       et-al* string m n
394              Control use of et al in the evaluation of @ expressions in label
395              expressions.  If the number of authors needed to make the author
396              sequence  unambiguous  is u and the total number of authors is t
397              then the last t-u authors will be replaced  by  string  provided
398              that  t-u  is not less than m and t is not less than n.  The de‐
399              fault behaviour is
400
401                     et-al " et al" 2 3
402
403       include filename
404              Include filename and interpret the contents as commands.
405
406       join-authors string1 string2 string3
407              This says how authors should be joined together.  When there are
408              exactly  two  authors,  they  will be joined with string1.  When
409              there are more than two authors, all but the last  two  will  be
410              joined  with  string2,  and  the last two authors will be joined
411              with string3.   If  string3  is  omitted,  it  will  default  to
412              string1;  if  string2  is  also  omitted it will also default to
413              string1.  For example,
414
415                     join-authors " and " ", " ", and "
416
417              will restore the default method for joining authors.
418
419       label-in-reference*
420              When outputting the reference, define the string [F  to  be  the
421              reference's  label.  This is the default behaviour; so the nega‐
422              tive version of this command is more useful.
423
424       label-in-text*
425              For each reference output a label in the text.  The  label  will
426              be  separated  from  the  surrounding  text  as described in the
427              bracket-label command.  This is the default  behaviour;  so  the
428              negative version of this command is more useful.
429
430       label string
431              string is a label expression describing how to label each refer‐
432              ence.
433
434       separate-label-second-parts string
435              When merging two-part labels, separate the second  part  of  the
436              second label from the first label with string.  See the descrip‐
437              tion of the <> label expression.
438
439       move-punctuation*
440              In the text, move any punctuation at the end of  line  past  the
441              label.   It  is  usually a good idea to give this command unless
442              you are using superscripted numbers as labels.
443
444       reverse* string
445              Reverse the fields whose names are in string.  Each  field  name
446              can  be  followed  by  a  number which says how many such fields
447              should be reversed.  If no number is given for a field, all such
448              fields will be reversed.
449
450       search-ignore* fields
451              While searching for keys in databases for which no index exists,
452              ignore the contents of fields.  Initially, fields  XYZ  are  ig‐
453              nored.
454
455       search-truncate* n
456              Only require the first n characters of keys to be given.  In ef‐
457              fect when searching for a given key words in  the  database  are
458              truncated  to  the maximum of n and the length of the key.  Ini‐
459              tially n is 6.
460
461       short-label* string
462              string is a label expression that specifies an alternative (usu‐
463              ally  shorter)  style of label.  This is used when the # flag is
464              given in the citation.  When using author-date style labels, the
465              identity  of  the  author or authors is sometimes clear from the
466              context, and so it may be desirable to omit the  author  or  au‐
467              thors from the label.  The short-label command will typically be
468              used to specify a label containing just a date  and  possibly  a
469              disambiguating letter.
470
471       sort* string
472              Sort  references according to string.  References will automati‐
473              cally be accumulated.  string should be a list of  field  names,
474              each  followed  by a number, indicating how many fields with the
475              name should be used for sorting.  + can be used to indicate that
476              all the fields with the name should be used.  Also . can be used
477              to indicate the references should be sorted  using  the  (tenta‐
478              tive)  label.   (Subsection  “Label expressions” below describes
479              the concept of a tentative label.)
480
481       sort-adjacent-labels*
482              Sort labels that are adjacent in the text according to their po‐
483              sition  in  the  reference list.  This command should usually be
484              given if the abbreviate-label-ranges command has been given,  or
485              if  the  label  expression  contains a <> expression.  This will
486              have no effect unless references are being accumulated.
487
488   Label expressions
489       Label expressions can be evaluated both normally and tentatively.   The
490       result  of  normal evaluation is used for output.  The result of tenta‐
491       tive evaluation, called the tentative label, is used to gather the  in‐
492       formation  that normal evaluation needs to disambiguate the label.  La‐
493       bel expressions specified by the date-as-label and short-label commands
494       are not evaluated tentatively.  Normal and tentative evaluation are the
495       same for all types of expression other than @, *,  and  %  expressions.
496       The description below applies to normal evaluation, except where other‐
497       wise specified.
498
499       field
500       field n
501              The n-th part of field.  If n is omitted, it defaults to 1.
502
503       'string'
504              The characters in string literally.
505
506       @      All the authors joined as specified by the join-authors command.
507              The  whole  of each author's name will be used.  However, if the
508              references are sorted by author (that is the sort  specification
509              starts  with  A+), then authors last names will be used instead,
510              provided that this does not introduce  ambiguity,  and  also  an
511              initial  subsequence  of  the authors may be used instead of all
512              the authors, again provided that this does not introduce ambigu‐
513              ity.   The use of only the last name for the i-th author of some
514              reference is considered to be ambiguous if there is  some  other
515              reference, such that the first i-1 authors of the references are
516              the same, the i-th authors are not the same, but  the  i-th  au‐
517              thors  last names are the same.  A proper initial subsequence of
518              the sequence of authors for some reference is considered  to  be
519              ambiguous  if  there  is a reference with some other sequence of
520              authors which also has that subsequence as a proper initial sub‐
521              sequence.   When  an initial subsequence of authors is used, the
522              remaining authors are replaced by the string  specified  by  the
523              et-al command; this command may also specify additional require‐
524              ments that must be met before  an  initial  subsequence  can  be
525              used.   @ tentatively evaluates to a canonical representation of
526              the authors, such that authors that compare equally for  sorting
527              purpose will have the same representation.
528
529       %n
530       %a
531       %A
532       %i
533       %I     The  serial  number  of the reference formatted according to the
534              character following the %.  The serial  number  of  a  reference
535              is 1  plus  the number of earlier references with same tentative
536              label as this reference.  These expressions tentatively evaluate
537              to an empty string.
538
539       expr*  If  there  is another reference with the same tentative label as
540              this reference, then expr, otherwise an empty string.  It tenta‐
541              tively evaluates to an empty string.
542
543       expr+n
544       expr-n The  first (+) or last (-) n upper or lower case letters or dig‐
545              its of expr.  Troff special characters (such as \('a) count as a
546              single letter.  Accent strings are retained but do not count to‐
547              wards the total.
548
549       expr.l expr converted to lowercase.
550
551       expr.u expr converted to uppercase.
552
553       expr.c expr converted to caps and small caps.
554
555       expr.r expr reversed so that the last name is first.
556
557       expr.a expr with first names abbreviated.  Note that  fields  specified
558              in  the abbreviate command are abbreviated before any labels are
559              evaluated.  Thus .a is useful only when you want a field  to  be
560              abbreviated in a label but not in a reference.
561
562       expr.y The year part of expr.
563
564       expr.+y
565              The  part  of  expr  before the year, or the whole of expr if it
566              does not contain a year.
567
568       expr.-y
569              The part of expr after the year, or an empty string if expr does
570              not contain a year.
571
572       expr.n The last name part of expr.
573
574       expr1~expr2
575              expr1  except  that  if the last character of expr1 is - then it
576              will be replaced by expr2.
577
578       expr1 expr2
579              The concatenation of expr1 and expr2.
580
581       expr1|expr2
582              If expr1 is non-empty then expr1 otherwise expr2.
583
584       expr1&expr2
585              If expr1 is non-empty then expr2 otherwise an empty string.
586
587       expr1?expr2:expr3
588              If expr1 is non-empty then expr2 otherwise expr3.
589
590       <expr> The label is in two parts, which are separated by expr.  Two ad‐
591              jacent  two-part  labels  which have the same first part will be
592              merged by appending the second part of the second label onto the
593              first  label  separated by the string specified in the separate-
594              label-second-parts command (initially, a  comma  followed  by  a
595              space);  the  resulting label will also be a two-part label with
596              the same first part as before merging, and so additional  labels
597              can  be  merged  into  it.   Note that it is permissible for the
598              first part to be empty; this  maybe  desirable  for  expressions
599              used in the short-label command.
600
601       (expr) The same as expr.  Used for grouping.
602
603       The  above  expressions  are  listed  in  order  of precedence (highest
604       first); & and | have the same precedence.
605
606   Macro interface
607       Each reference starts with a call to the macro ]-.  The string [F  will
608       be  defined to be the label for this reference, unless the no-label-in-
609       reference command has been given.   There  then  follows  a  series  of
610       string  definitions, one for each field: string [X corresponds to field
611       X.  The number register [P is set to 1 if the P field contains a  range
612       of pages.  The [T, [A and [O number registers are set to 1 according as
613       the T, A and O fields end with one of the characters .?!.  The [E  num‐
614       ber  register  will be set to 1 if the [E string contains more than one
615       name.  The reference is followed by a call to the ][ macro.  The  first
616       argument to this macro gives a number representing the type of the ref‐
617       erence.  If a reference contains a J field, it will  be  classified  as
618       type 1,  otherwise  if it contains a B field, it will type 3, otherwise
619       if it contains a G or R field it will be type 4, otherwise if  it  con‐
620       tains  an  I field it will be type 2, otherwise it will be type 0.  The
621       second argument is a symbolic name for the type:  other,  journal-arti‐
622       cle,  book,  article-in-book or tech-report.  Groups of references that
623       have been accumulated or are produced by the bibliography  command  are
624       preceded  by  a  call  to the ]< macro and followed by a call to the ]>
625       macro.
626

FILES

628       /usr/dict/papers/Ind
629              Default database.
630
631       file.i Index files.
632
633       refer uses temporary files.  See the  groff(1)  man  page  for  details
634       where such files are created.
635

ENVIRONMENT

637       REFER  If set, overrides the default database.
638

SEE ALSO

640       indxbib(1), lookbib(1), lkbib(1)
641

BUGS

643       In  label  expressions, <> expressions are ignored inside .char expres‐
644       sions.
645
646
647
648groff 1.22.4                    19 January 2023                       REFER(1)
Impressum