1refer(1) General Commands Manual refer(1)
2
6 refer - process bibliographic references for groff
7
9 refer [-bCenPRS] [-a n] [-B field.macro] [-c fields] [-f n] [-i fields]
10 [-k field] [-l range-expression] [-p database-file] [-s fields]
11 [-t n] [file ...]
12 refer --help
14 refer -v
16 refer --version
17
19 The GNU implementation of refer is part of the groff(1) document for‐
20 matting system. refer is a troff(1) preprocessor that prepares bibilo‐
21 graphic citations by looking up keywords specified in a roff(7) input
22 document, obviating the need to type such annotations, and permitting
23 the citation style in formatted output to be altered independently and
24 systematically. It copies the contents of each file to the standard
25 output stream, except that it interprets lines between .[ and .] as ci‐
26 tations to be translated into groff input, and lines between .R1 and
27 .R2 as instructions regarding how citations are to be processed. Nor‐
28 mally, refer is not executed directly by the user, but invoked by spec‐
29 ifying the -R option to groff(1). If no file operands are given on the
30 command line, or if file is “-”, the standard input stream is read.
31 Each citation specifies a reference. The citation can specify a refer‐
33 ence that is contained in a bibliographic database by giving a set of
34 keywords that only that reference contains. Alternatively it can spec‐
35 ify a reference by supplying a database record in the citation. A com‐
36 bination of these alternatives is also possible.
37 For each citation, refer can produce a mark in the text. This mark
39 consists of some label which can be separated from the text and from
40 other labels in various ways. For each reference it also outputs
41 groff(7) language commands that can be used by a macro package to pro‐
42 duce a formatted reference for each citation. The output of refer must
43 therefore be processed using a suitable macro package, such as me, mm,
44 mom, or ms. The commands to format a citation's reference can be out‐
45 put immediately after the citation, or the references may be accumu‐
46 lated, and the commands output at some later point. If the references
47 are accumulated, then multiple citations of the same reference will
48 produce a single formatted reference.
49 The interpretation of lines between .R1 and .R2 as prepreocessor com‐
51 mands is a feature of GNU refer. Documents making use of this feature
52 can still be processed by AT&T refer just by adding the lines
53 .de R1
54 .ig R2
55 ..
56 to the beginning of the document. This will cause troff(1) to ignore
57 everything between .R1 and .R2. The effect of some commands can also
58 be achieved by options. These options are supported mainly for compat‐
59 ibility with AT&T refer. It is usually more convenient to use com‐
60 mands.
61 refer generates .lf requests so that file names and line numbers in
63 messages produced by commands that read refer output will be correct;
64 it also interprets lines beginning with .lf so that file names and line
65 numbers in the messages and .lf lines that it produces will be accurate
66 even if the input has been preprocessed by a command such as soelim(1).
67 Bibliographic databases
69 The bibliographic database is a text file consisting of records sepa‐
70 rated by one or more blank lines. Within each record fields start with
71 a % at the beginning of a line. Each field has a one character name
72 that immediately follows the %. It is best to use only upper and lower
73 case letters for the names of fields. The name of the field should be
74 followed by exactly one space, and then by the contents of the field.
75 Empty fields are ignored. The conventional meaning of each field is as
76 follows:
77 %A The name of an author. If the name contains a suffix such as
79 “Jr.”, it should be separated from the last name by a comma.
80 There can be multiple occurrences of the %A field. The order is
81 significant. It is a good idea always to supply an %A field or
82 a %Q field.
83 %B For an article that is part of a book, the title of the book.
85 %C The place (city) of publication.
87 %D The date of publication. The year should be specified in full.
89 If the month is specified, the name rather than the number of
90 the month should be used, but only the first three letters are
91 required. It is a good idea always to supply a %D field; if the
92 date is unknown, a value such as in press or unknown can be
93 used.
94 %E For an article that is part of a book, the name of an editor of
96 the book. Where the work has editors and no authors, the names
97 of the editors should be given as %A fields and “, (ed.)” or
98 “, (eds.)” should be appended to the last author.
99 %G U.S. government ordering number.
101 %I The publisher (issuer).
103 %J For an article in a journal, the name of the journal.
105 %K Keywords to be used for searching.
107 %L Label.
109 %N Journal issue number.
111 %O Other information. This is usually printed at the end of the
113 reference.
114 %P Page number. A range of pages can be specified as m-n.
116 %Q The name of the author, if the author is not a person. This
118 will only be used if there are no %A fields. There can only be
119 one %Q field.
120 %R Technical report number.
122 %S Series name.
124 %T Title. For an article in a book or journal, this should be the
126 title of the article.
127 %V Volume number of the journal or book.
129 %X Annotation.
131 For all fields except %A and %E, if there is more than one occurrence
133 of a particular field in a record, only the last such field will be
134 used.
135 If accent strings are used, they should follow the character to be ac‐
137 cented. This means that an ms document must call the .AM macro when it
138 initializes. Accent strings should not be quoted: use one \ rather
139 than two. Accent strings are an obsolescent feature of the me and ms
140 macro packages; modern documents should use groff special character es‐
141 cape sequences instead; see groff_char(7).
142 Citations
144 Citations have a characteristic format.
145 .[opening-text
146 flags keywords
147 fields
148 .]closing-text
149 The opening-text, closing-text, and flags components are optional.
151 Only one of the keywords and fields components need be specified.
152 The keywords component says to search the bibliographic databases for a
154 reference that contains all the words in keywords. It is an error if
155 more than one reference is found.
156 The fields components specifies additional fields to replace or supple‐
158 ment those specified in the reference. When references are being accu‐
159 mulated and the keywords component is non-empty, then additional fields
160 should be specified only on the first occasion that a particular refer‐
161 ence is cited, and will apply to all citations of that reference.
162 The opening-text and closing-text components specify strings to be used
164 to bracket the label instead of those in the bracket-label command. If
165 either of these components is non-empty, the strings specified in the
166 bracket-label command will not be used; this behavior can be altered
167 using the [ and ] flags. Leading and trailing spaces are significant
168 for these components.
169 The flags component is a list of non-alphanumeric characters each of
171 which modifies the treatment of this particular citation. AT&T refer
172 will treat these flags as part of the keywords and so will ignore them
173 since they are non-alphanumeric. The following flags are currently
174 recognized.
175 # Use the label specified by the short-label command, instead of
177 that specified by the label command. If no short label has been
178 specified, the normal label will be used. Typically the short
179 label is used with author-date labels and consists of only the
180 date and possibly a disambiguating letter; the “#” is supposed
181 to be suggestive of a numeric type of label.
182 [ Precede opening-text with the first string specified in the
184 bracket-label command.
185 ] Follow closing-text with the second string specified in the
187 bracket-label command.
188 An advantage of using the [ and ] flags rather than including the
190 brackets in opening-text and closing-text is that you can change the
191 style of bracket used in the document just by changing the
192 bracket-label command. Another is that sorting and merging of cita‐
193 tions will not necessarily be inhibited if the flags are used.
194 If a label is to be inserted into the text, it will be attached to the
196 line preceding the .[ line. If there is no such line, then an extra
197 line will be inserted before the .[ line and a warning will be given.
198 There is no special notation for making a citation to multiple refer‐
200 ences. Just use a sequence of citations, one for each reference.
201 Don't put anything between the citations. The labels for all the cita‐
202 tions will be attached to the line preceding the first citation. The
203 labels may also be sorted or merged. See the description of the <> la‐
204 bel expression, and of the sort-adjacent-labels and
205 abbreviate-label-ranges commands. A label will not be merged if its
206 citation has a non-empty opening-text or closing-text. However, the
207 labels for a citation using the ] flag and without any closing-text im‐
208 mediately followed by a citation using the [ flag and without any open‐
209 ing-text may be sorted and merged even though the first citation's
210 opening-text or the second citation's closing-text is non-empty. (If
211 you wish to prevent this, use the dummy character escape sequence \& as
212 the first citation's closing-text.)
213 Commands
215 Commands are contained between lines starting with .R1 and .R2. Recog‐
216 nition of these lines can be prevented by the -R option. When a .R1
217 line is recognized any accumulated references are flushed out. Neither
218 .R1 nor .R2 lines, nor anything between them, is output.
219 Commands are separated by newlines or semicolons. A number sign (#)
221 introduces a comment that extends to the end of the line, but does not
222 conceal the newline. Each command is broken up into words. Words are
223 separated by spaces or tabs. A word that begins with a (neutral) dou‐
224 ble quote (") extends to the next double quote that is not followed by
225 another double quote. If there is no such double quote, the word ex‐
226 tends to the end of the line. Pairs of double quotes in a word begin‐
227 ning with a double quote collapse to one double quote. Neither a num‐
228 ber sign nor a semicolon is recognized inside double quotes. A line
229 can be continued by ending it with a backslash “\”; this works every‐
230 where except after a number sign.
231 Each command name that is marked with * has an associated negative com‐
233 mand no-name that undoes the effect of name. For example, the no-sort
234 command specifies that references should not be sorted. The negative
235 commands take no arguments.
236 In the following description each argument must be a single word; field
238 is used for a single upper or lower case letter naming a field; fields
239 is used for a sequence of such letters; m and n are used for a non-neg‐
240 ative numbers; string is used for an arbitrary string; file is used for
241 the name of a file.
242 abbreviate* fields string1 string2 string3 string4
244 Abbreviate the first names of fields. An initial letter will be
245 separated from another initial letter by string1, from the last
246 name by string2, and from anything else (such as “von” or “de”)
247 by string3. These default to a period followed by a space. In
248 a hyphenated first name, the initial of the first part of the
249 name will be separated from the hyphen by string4; this defaults
250 to a period. No attempt is made to handle any ambiguities that
251 might result from abbreviation. Names are abbreviated before
252 sorting and before label construction.
253 abbreviate-label-ranges* string
255 Three or more adjacent labels that refer to consecutive refer‐
256 ences will be abbreviated to a label consisting of the first la‐
257 bel, followed by string, followed by the last label. This is
258 mainly useful with numeric labels. If string is omitted, it de‐
259 faults to “-”.
260 accumulate*
262 Accumulate references instead of writing out each reference as
263 it is encountered. Accumulated references will be written out
264 whenever a reference of the form
265 .[
266 $LIST$
267 .]
268 is encountered, after all input files have been processed, and
269 whenever a .R1 line is recognized.
270 annotate* field string
272 field is an annotation; print it at the end of the reference as
273 a paragraph preceded by the line
274 .string
276 If string is omitted, it will default to AP; if field is also
278 omitted it will default to X. Only one field can be an annota‐
279 tion.
280 articles string ...
282 Each string is a definite or indefinite article, and should be
283 ignored at the beginning of T fields when sorting. Initially,
284 “a”, “an”, and “the” are recognized as articles.
285 bibliography file ...
287 Write out all the references contained in each bibliographic
288 database file. This command should come last in an .R1/.R2
289 block.
290 bracket-label string1 string2 string3
292 In the text, bracket each label with string1 and string2. An
293 occurrence of string2 immediately followed by string1 will be
294 turned into string3. The default behavior is as follows.
295 bracket-label \*([. \*(.] ", "
296 capitalize fields
298 Convert fields to caps and small caps.
299 compatible*
301 Recognize .R1 and .R2 even when followed by a character other
302 than space or newline.
303 database file ...
305 Search each bibliographic database file. For each file, if an
306 index file.i created by indxbib(1) exists, then it will be
307 searched instead; each index can cover multiple databases.
308 date-as-label* string
310 string is a label expression that specifies a string with which
311 to replace the D field after constructing the label. See sub‐
312 section “Label expressions” below for a description of label ex‐
313 pressions. This command is useful if you do not want explicit
314 labels in the reference list, but instead want to handle any
315 necessary disambiguation by qualifying the date in some way.
316 The label used in the text would typically be some combination
317 of the author and date. In most cases you should also use the
318 no-label-in-reference command. For example,
319 date-as-label D.+yD.y%a*D.-y
320 would attach a disambiguating letter to the year part of the D
321 field in the reference.
322 default-database*
324 The default database should be searched. This is the default
325 behavior, so the negative version of this command is more use‐
326 ful. refer determines whether the default database should be
327 searched on the first occasion that it needs to do a search.
328 Thus a no-default-database command must be given before then, in
329 order to be effective.
330 discard* fields
332 When the reference is read, fields should be discarded; no
333 string definitions for fields will be output. Initially, fields
334 are XYZ.
335 et-al* string m n
337 Control use of et al. in the evaluation of @ expressions in la‐
338 bel expressions. If the number of authors needed to make the
339 author sequence unambiguous is u and the total number of authors
340 is t then the last t-u authors will be replaced by string pro‐
341 vided that t-u is not less than m and t is not less than n. The
342 default behavior is as follows.
343 et-al " et al" 2 3
344 Note the absence of a dot from the end of the abbreviation,
345 which is arguably not correct. (Et al[.] is short for et alli,
346 as etc. is short for et cetera.)
347 include file
349 Include file and interpret the contents as commands.
350 join-authors string1 string2 string3
352 Join multiple authors together with strings. When there are ex‐
353 actly two authors, they will be joined with string1. When there
354 are more than two authors, all but the last two will be joined
355 with string2, and the last two authors will be joined with
356 string3. If string3 is omitted, it will default to string1; if
357 string2 is also omitted it will also default to string1. For
358 example,
359 join-authors " and " ", " ", and "
360 will restore the default method for joining authors.
361 label-in-reference*
363 When outputting the reference, define the string [F to be the
364 reference's label. This is the default behavior, so the nega‐
365 tive version of this command is more useful.
366 label-in-text*
368 For each reference output a label in the text. The label will
369 be separated from the surrounding text as described in the
370 bracket-label command. This is the default behavior, so the
371 negative version of this command is more useful.
372 label string
374 string is a label expression describing how to label each refer‐
375 ence.
376 separate-label-second-parts string
378 When merging two-part labels, separate the second part of the
379 second label from the first label with string. See the descrip‐
380 tion of the <> label expression.
381 move-punctuation*
383 In the text, move any punctuation at the end of line past the
384 label. It is usually a good idea to give this command unless
385 you are using superscripted numbers as labels.
386 reverse* string
388 Reverse the fields whose names are in string. Each field name
389 can be followed by a number which says how many such fields
390 should be reversed. If no number is given for a field, all such
391 fields will be reversed.
392 search-ignore* fields
394 While searching for keys in databases for which no index exists,
395 ignore the contents of fields. Initially, fields XYZ are ig‐
396 nored.
397 search-truncate* n
399 Only require the first n characters of keys to be given. In ef‐
400 fect when searching for a given key words in the database are
401 truncated to the maximum of n and the length of the key. Ini‐
402 tially, n is 6.
403 short-label* string
405 string is a label expression that specifies an alternative (usu‐
406 ally shorter) style of label. This is used when the # flag is
407 given in the citation. When using author-date style labels, the
408 identity of the author or authors is sometimes clear from the
409 context, and so it may be desirable to omit the author or au‐
410 thors from the label. The short-label command will typically be
411 used to specify a label containing just a date and possibly a
412 disambiguating letter.
413 sort* string
415 Sort references according to string. References will automati‐
416 cally be accumulated. string should be a list of field names,
417 each followed by a number, indicating how many fields with the
418 name should be used for sorting. “+” can be used to indicate
419 that all the fields with the name should be used. Also . can be
420 used to indicate the references should be sorted using the (ten‐
421 tative) label. (Subsection “Label expressions” below describes
422 the concept of a tentative label.)
423 sort-adjacent-labels*
425 Sort labels that are adjacent in the text according to their po‐
426 sition in the reference list. This command should usually be
427 given if the abbreviate-label-ranges command has been given, or
428 if the label expression contains a <> expression. This will
429 have no effect unless references are being accumulated.
430 Label expressions
432 Label expressions can be evaluated both normally and tentatively. The
433 result of normal evaluation is used for output. The result of tenta‐
434 tive evaluation, called the tentative label, is used to gather the in‐
435 formation that normal evaluation needs to disambiguate the label. La‐
436 bel expressions specified by the date-as-label and short-label commands
437 are not evaluated tentatively. Normal and tentative evaluation are the
438 same for all types of expression other than @, *, and % expressions.
439 The description below applies to normal evaluation, except where other‐
440 wise specified.
441 field
443 field n
444 The n-th part of field. If n is omitted, it defaults to 1.
445 'string'
447 The characters in string literally.
448 @ All the authors joined as specified by the join-authors command.
450 The whole of each author's name will be used. However, if the
451 references are sorted by author (that is, the sort specification
452 starts with “A+”), then authors' last names will be used in‐
453 stead, provided that this does not introduce ambiguity, and also
454 an initial subsequence of the authors may be used instead of all
455 the authors, again provided that this does not introduce ambigu‐
456 ity. The use of only the last name for the i-th author of some
457 reference is considered to be ambiguous if there is some other
458 reference, such that the first i-1 authors of the references are
459 the same, the i-th authors are not the same, but the i-th au‐
460 thors last names are the same. A proper initial subsequence of
461 the sequence of authors for some reference is considered to be
462 ambiguous if there is a reference with some other sequence of
463 authors which also has that subsequence as a proper initial sub‐
464 sequence. When an initial subsequence of authors is used, the
465 remaining authors are replaced by the string specified by the
466 et-al command; this command may also specify additional require‐
467 ments that must be met before an initial subsequence can be
468 used. @ tentatively evaluates to a canonical representation of
469 the authors, such that authors that compare equally for sorting
470 purpose will have the same representation.
471 %n
473 %a
474 %A
475 %i
476 %I The serial number of the reference formatted according to the
477 character following the %. The serial number of a reference
478 is 1 plus the number of earlier references with same tentative
479 label as this reference. These expressions tentatively evaluate
480 to an empty string.
481 expr* If there is another reference with the same tentative label as
483 this reference, then expr, otherwise an empty string. It tenta‐
484 tively evaluates to an empty string.
485 expr+n
487 expr-n The first (+) or last (-) n upper or lower case letters or dig‐
488 its of expr. roff special characters (such as \('a) count as a
489 single letter. Accent strings are retained but do not count to‐
490 wards the total.
491 expr.l expr converted to lowercase.
493 expr.u expr converted to uppercase.
495 expr.c expr converted to caps and small caps.
497 expr.r expr reversed so that the last name is first.
499 expr.a expr with first names abbreviated. Fields specified in the
501 abbreviate command are abbreviated before any labels are evalu‐
502 ated. Thus .a is useful only when you want a field to be abbre‐
503 viated in a label but not in a reference.
504 expr.y The year part of expr.
506 expr.+y
508 The part of expr before the year, or the whole of expr if it
509 does not contain a year.
510 expr.-y
512 The part of expr after the year, or an empty string if expr does
513 not contain a year.
514 expr.n The last name part of expr.
516 expr1~expr2
518 expr1 except that if the last character of expr1 is - then it
519 will be replaced by expr2.
520 expr1 expr2
522 The concatenation of expr1 and expr2.
523 expr1|expr2
525 If expr1 is non-empty then expr1 otherwise expr2.
526 expr1&expr2
528 If expr1 is non-empty then expr2 otherwise an empty string.
529 expr1?expr2:expr3
531 If expr1 is non-empty then expr2 otherwise expr3.
532 <expr> The label is in two parts, which are separated by expr. Two ad‐
534 jacent two-part labels which have the same first part will be
535 merged by appending the second part of the second label onto the
536 first label separated by the string specified in the
537 separate-label-second-parts command (initially, a comma followed
538 by a space); the resulting label will also be a two-part label
539 with the same first part as before merging, and so additional
540 labels can be merged into it. It is permissible for the first
541 part to be empty; this may be desirable for expressions used in
542 the short-label command.
543 (expr) The same as expr. Used for grouping.
545 The above expressions are listed in order of precedence (highest
547 first); & and | have the same precedence.
548 Macro interface
550 Each reference starts with a call to the macro ]-. The string [F will
551 be defined to be the label for this reference, unless the
552 no-label-in-reference command has been given. There then follows a se‐
553 ries of string definitions, one for each field: string [X corresponds
554 to field X. The register [P is set to 1 if the P field contains a
555 range of pages. The [T, [A and [O registers are set to 1 according as
556 the T, A and O fields end with any of .?! (an end-of-sentence charac‐
557 ter). The [E register will be set to 1 if the [E string contains more
558 than one name. The reference is followed by a call to the ][ macro.
559 The first argument to this macro gives a number representing the type
560 of the reference. If a reference contains a J field, it will be clas‐
561 sified as type 1, otherwise if it contains a B field, it will be
562 type 3, otherwise if it contains a G or R field it will be type 4, oth‐
563 erwise if it contains an I field it will be type 2, otherwise it will
564 be type 0. The second argument is a symbolic name for the type: other,
565 journal-article, book, article-in-book, or tech-report. Groups of ref‐
566 erences that have been accumulated or are produced by the bibliography
567 command are preceded by a call to the ]< macro and followed by a call
568 to the ]> macro.
569
571 --help displays a usage message, while -v and --version show version
572 information; all exit afterward.
573 -R Don't recognize lines beginning with .R1/.R2.
575 Other options are equivalent to refer commands.
577 -a n reverse An
579 -b no-label-in-text; no-label-in-reference
581 -B See below.
583 -c fields capitalize fields
585 -C compatible
587 -e accumulate
589 -f n label %n
591 -i fields search-ignore fields
593 -k label L~%a
595 -k field label field~%a
597 -l label A.nD.y%a
599 -l m label A.n+mD.y%a
601 -l ,n label A.nD.y-n%a
603 -l m,n label A.n+mD.y-n%a
605 -n no-default-database
607 -p db-file database db-file
609 -P move-punctuation
611 -s spec sort spec
613 -S label "(A.n|Q) ', ' (D.y|D)"; bracket-label " (" ) "; "
615 -t n search-truncate n
617 The B option has command equivalents with the addition that the file
619 names specified on the command line are processed as if they were argu‐
620 ments to the bibliography command instead of in the normal way.
621 -B annotate X AP; no-label-in-reference
623 -B field.macro annotate field macro; no-label-in-reference
625
627 REFER If set, overrides the default database.
628
630 /usr/dict/papers/Ind
631 Default database.
632 file.i Index files.
634 /usr/share/groff/1.23.0/tmac/refer.tmac
636 defines macros and strings facilitating integration with macro
637 packages that wish to support refer.
638 refer uses temporary files. See the groff(1) man page for details of
640 where such files are created.
641
643 In label expressions, <> expressions are ignored inside .char expres‐
644 sions.
645
647 We can illustrate the operation of refer with a sample bibliographic
648 database containing one entry and a simple roff document to cite that
649 entry.
650 $ cat > my-db-file
652 %A Daniel P.\& Friedman
653 %A Matthias Felleisen
654 %C Cambridge, Massachusetts
655 %D 1996
656 %I The MIT Press
657 %T The Little Schemer, Fourth Edition
658 $ refer -p my-db-file
659 Read the book
660 .[
661 friedman
662 .]
663 on your summer vacation.
664 <Control+D>
665 .lf 1 -
666 Read the book\*([.1\*(.]
667 .ds [F 1
668 .]-
669 .ds [A Daniel P. Friedman and Matthias Felleisen
670 .ds [C Cambridge, Massachusetts
671 .ds [D 1996
672 .ds [I The MIT Press
673 .ds [T The Little Schemer, Fourth Edition
674 .nr [T 0
675 .nr [A 0
676 .][ 2 book
677 .lf 5 -
678 on your summer vacation.
679 The foregoing shows us that refer (a) produces a label “1”; (b) brack‐
681 ets that label with interpolations of the “[.” and “.]” strings; (c)
682 calls a macro “]-”; (d) defines strings and registers containing the
683 label and bibliographic data for the reference; (e) calls a macro “][”;
684 and (f) uses the lf request to restore the line numbers of the original
685 input. As discussed in subsection “Macro interface” above, it is up to
686 the document or a macro package to employ and format this information
687 usefully. Let us see how we might turn groff_ms(7) to this task.
688 $ REFER=my-db-file groff -R -ms
690 .LP
691 Read the book
692 .[
693 friedman
694 .]
695 on your summer vacation.
696 Commentary is available.\*{*\*}
697 .FS \*{*\*}
698 Space reserved for penetrating insight.
699 .FE
700 ms's automatic footnote numbering mechanism is not aware of refer's la‐
702 bel numbering, so we have manually specified a (superscripted) symbolic
703 footnote for our non-bibliographic aside.
704
706 “Some Applications of Inverted Indexes on the Unix System”, by M. E.
707 Lesk, 1978, AT&T Bell Laboratories Computing Science Technical Report
708 No. 69.
709 indxbib(1), lookbib(1), lkbib(1)
711groff 1.23.0 2 November 2023 refer(1)