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