1REFER(1) General Commands Manual REFER(1)
2
6 refer - preprocess bibliographic references for groff
7
9 refer [ -benvCPRS ] [ -an ] [ -cfields ] [ -fn ] [ -ifields ]
10 [ -kfield ] [ -lm,n ] [ -pfilename ] [ -sfields ] [ -tn ]
11 [ -Bfield.macro ] [ filename... ]
12
14 This file documents the GNU version of refer, which is part of the
15 groff document formatting system. refer copies the contents of file‐
16 name... to the standard output, except that lines between .[ and .] are
17 interpreted as citations, and lines between .R1 and .R2 are interpreted
18 as commands about how citations are to be processed.
19 Each citation specifies a reference. The citation can specify a refer‐
21 ence that is contained in a bibliographic database by giving a set of
22 keywords that only that reference contains. Alternatively it can spec‐
23 ify a reference by supplying a database record in the citation. A com‐
24 bination of these alternatives is also possible.
25 For each citation, refer can produce a mark in the text. This mark
27 consists of some label which can be separated from the text and from
28 other labels in various ways. For each reference it also outputs groff
29 commands that can be used by a macro package to produce a formatted
30 reference for each citation. The output of refer must therefore be
31 processed using a suitable macro package. The -ms and -me macros are
32 both suitable. The commands to format a citation's reference can be
33 output immediately after the citation, or the references may be accumu‐
34 lated, and the commands output at some later point. If the references
35 are accumulated, then multiple citations of the same reference will
36 produce a single formatted reference.
37 The interpretation of lines between .R1 and .R2 as commands is a new
39 feature of GNU refer. Documents making use of this feature can still
40 be processed by Unix refer just by adding the lines
41 .de R1
43 .ig R2
44 ..
45 to the beginning of the document. This will cause troff to ignore
46 everything between .R1 and .R2. The effect of some commands can also
47 be achieved by options. These options are supported mainly for compat‐
48 ibility with Unix refer. It is usually more convenient to use com‐
49 mands.
50 refer generates .lf lines so that filenames and line numbers in mes‐
52 sages produced by commands that read refer output will be correct; it
53 also interprets lines beginning with .lf so that filenames and line
54 numbers in the messages and .lf lines that it produces will be accurate
55 even if the input has been preprocessed by a command such as soelim(1).
56
58 It is possible to have whitespace between a command line option and its
59 parameter.
60 Most options are equivalent to commands (for a description of these
62 commands see the Commands subsection):
63 -b no-label-in-text; no-label-in-reference
65 -e accumulate
67 -n no-default-database
69 -C compatible
71 -P move-punctuation
73 -S label "(A.n|Q) ', ' (D.y|D)"; bracket-label " (" ) "; "
75 -an reverse An
77 -cfields
79 capitalize fields
80 -fn label %n
82 -ifields
84 search-ignore fields
85 -k label L~%a
87 -kfield
89 label field~%a
90 -l label A.nD.y%a
92 -lm label A.n+mD.y%a
94 -l,n label A.nD.y-n%a
96 -lm,n label A.n+mD.y-n%a
98 -pfilename
100 database filename
101 -sspec sort spec
103 -tn search-truncate n
105 These options are equivalent to the following commands with the addi‐
107 tion that the filenames specified on the command line are processed as
108 if they were arguments to the bibliography command instead of in the
109 normal way:
110 -B annotate X AP; no-label-in-reference
112 -Bfield.macro
114 annotate field macro; no-label-in-reference
115 The following options have no equivalent commands:
117 -v Print the version number.
119 -R Don't recognize lines beginning with .R1/.R2.
121
123 Bibliographic databases
124 The bibliographic database is a text file consisting of records sepa‐
125 rated by one or more blank lines. Within each record fields start with
126 a % at the beginning of a line. Each field has a one character name
127 that immediately follows the %. It is best to use only upper and lower
128 case letters for the names of fields. The name of the field should be
129 followed by exactly one space, and then by the contents of the field.
130 Empty fields are ignored. The conventional meaning of each field is as
131 follows:
132 A The name of an author. If the name contains a title such as Jr.
134 at the end, it should be separated from the last name by a
135 comma. There can be multiple occurrences of the A field. The
136 order is significant. It is a good idea always to supply an A
137 field or a Q field.
138 B For an article that is part of a book, the title of the book.
140 C The place (city) of publication.
142 D The date of publication. The year should be specified in full.
144 If the month is specified, the name rather than the number of
145 the month should be used, but only the first three letters are
146 required. It is a good idea always to supply a D field; if the
147 date is unknown, a value such as in press or unknown can be
148 used.
149 E For an article that is part of a book, the name of an editor of
151 the book. Where the work has editors and no authors, the names
152 of the editors should be given as A fields and , (ed) or , (eds)
153 should be appended to the last author.
154 G US Government ordering number.
156 I The publisher (issuer).
158 J For an article in a journal, the name of the journal.
160 K Keywords to be used for searching.
162 L Label.
164 N Journal issue number.
166 O Other information. This is usually printed at the end of the
168 reference.
169 P Page number. A range of pages can be specified as m-n.
171 Q The name of the author, if the author is not a person. This
173 will only be used if there are no A fields. There can only be
174 one Q field.
175 R Technical report number.
177 S Series name.
179 T Title. For an article in a book or journal, this should be the
181 title of the article.
182 V Volume number of the journal or book.
184 X Annotation.
186 For all fields except A and E, if there is more than one occurrence of
188 a particular field in a record, only the last such field will be used.
189 If accent strings are used, they should follow the character to be
191 accented. This means that the AM macro must be used with the -ms
192 macros. Accent strings should not be quoted: use one \ rather than
193 two.
194 Citations
196 The format of a citation is
197 .[opening-text
198 flags keywords
199 fields
200 .]closing-text
201 The opening-text, closing-text and flags components are optional. Only
203 one of the keywords and fields components need be specified.
204 The keywords component says to search the bibliographic databases for a
206 reference that contains all the words in keywords. It is an error if
207 more than one reference if found.
208 The fields components specifies additional fields to replace or supple‐
210 ment those specified in the reference. When references are being accu‐
211 mulated and the keywords component is non-empty, then additional fields
212 should be specified only on the first occasion that a particular refer‐
213 ence is cited, and will apply to all citations of that reference.
214 The opening-text and closing-text component specifies strings to be
216 used to bracket the label instead of the strings specified in the
217 bracket-label command. If either of these components is non-empty, the
218 strings specified in the bracket-label command will not be used; this
219 behaviour can be altered using the [ and ] flags. Note that leading
220 and trailing spaces are significant for these components.
221 The flags component is a list of non-alphanumeric characters each of
223 which modifies the treatment of this particular citation. Unix refer
224 will treat these flags as part of the keywords and so will ignore them
225 since they are non-alphanumeric. The following flags are currently
226 recognized:
227 # This says to use the label specified by the short-label command,
229 instead of that specified by the label command. If no short
230 label has been specified, the normal label will be used. Typi‐
231 cally the short label is used with author-date labels and con‐
232 sists of only the date and possibly a disambiguating letter; the
233 # is supposed to be suggestive of a numeric type of label.
234 [ Precede opening-text with the first string specified in the
236 bracket-label command.
237 ] Follow closing-text with the second string specified in the
239 bracket-label command.
240 One advantages of using the [ and ] flags rather than including the
242 brackets in opening-text and closing-text is that you can change the
243 style of bracket used in the document just by changing the bracket-
244 label command. Another advantage is that sorting and merging of cita‐
245 tions will not necessarily be inhibited if the flags are used.
246 If a label is to be inserted into the text, it will be attached to the
248 line preceding the .[ line. If there is no such line, then an extra
249 line will be inserted before the .[ line and a warning will be given.
250 There is no special notation for making a citation to multiple refer‐
252 ences. Just use a sequence of citations, one for each reference.
253 Don't put anything between the citations. The labels for all the cita‐
254 tions will be attached to the line preceding the first citation. The
255 labels may also be sorted or merged. See the description of the <>
256 label expression, and of the sort-adjacent-labels and abbreviate-label-
257 ranges command. A label will not be merged if its citation has a non-
258 empty opening-text or closing-text. However, the labels for a citation
259 using the ] flag and without any closing-text immediately followed by a
260 citation using the [ flag and without any opening-text may be sorted
261 and merged even though the first citation's opening-text or the second
262 citation's closing-text is non-empty. (If you wish to prevent this
263 just make the first citation's closing-text \&.)
264 Commands
266 Commands are contained between lines starting with .R1 and .R2. Recog‐
267 nition of these lines can be prevented by the -R option. When a .R1
268 line is recognized any accumulated references are flushed out. Neither
269 .R1 nor .R2 lines, nor anything between them is output.
270 Commands are separated by newlines or ;s. # introduces a comment that
272 extends to the end of the line (but does not conceal the newline).
273 Each command is broken up into words. Words are separated by spaces or
274 tabs. A word that begins with " extends to the next " that is not fol‐
275 lowed by another ". If there is no such " the word extends to the end
276 of the line. Pairs of " in a word beginning with " collapse to a sin‐
277 gle ". Neither # nor ; are recognized inside "s. A line can be con‐
278 tinued by ending it with \; this works everywhere except after a #.
279 Each command name that is marked with * has an associated negative com‐
281 mand no-name that undoes the effect of name. For example, the no-sort
282 command specifies that references should not be sorted. The negative
283 commands take no arguments.
284 In the following description each argument must be a single word; field
286 is used for a single upper or lower case letter naming a field; fields
287 is used for a sequence of such letters; m and n are used for a non-neg‐
288 ative numbers; string is used for an arbitrary string; filename is used
289 for the name of a file.
290 abbreviate* fields string1 string2 string3 string4
292 Abbreviate the first names of fields. An ini‐
293 tial letter will be separated from another
294 initial letter by string1, from the last name
295 by string2, and from anything else (such as a
296 von or de) by string3. These default to a
297 period followed by a space. In a hyphenated
298 first name, the initial of the first part of
299 the name will be separated from the hyphen by
300 string4; this defaults to a period. No
301 attempt is made to handle any ambiguities that
302 might result from abbreviation. Names are
303 abbreviated before sorting and before label
304 construction.
305 abbreviate-label-ranges* string
307 Three or more adjacent labels that refer to
308 consecutive references will be abbreviated to
309 a label consisting of the first label, fol‐
310 lowed by string followed by the last label.
311 This is mainly useful with numeric labels. If
312 string is omitted it defaults to -.
313 accumulate* Accumulate references instead of writing out
315 each reference as it is encountered. Accumu‐
316 lated references will be written out whenever
317 a reference of the form
318 .[
320 $LIST$
321 .]
322 is encountered, after all input files have
324 been processed, and whenever .R1 line is rec‐
325 ognized.
326 annotate* field string field is an annotation; print it at the end of
328 the reference as a paragraph preceded by the
329 line
330 .string
332 If string is omitted it will default to AP; if
334 field is also omitted it will default to X.
335 Only one field can be an annotation.
336 articles string... string... are definite or indefinite articles,
338 and should be ignored at the beginning of T
339 fields when sorting. Initially, the, a and an
340 are recognized as articles.
341 bibliography filename... Write out all the references contained in the
343 bibliographic databases filename... This com‐
344 mand should come last in a .R1/.R2 block.
345 bracket-label string1 string2 string3
347 In the text, bracket each label with string1
348 and string2. An occurrence of string2 immedi‐
349 ately followed by string1 will be turned into
350 string3. The default behaviour is
351 bracket-label \*([. \*(.] ", "
353 capitalize fields Convert fields to caps and small caps.
355 compatible* Recognize .R1 and .R2 even when followed by a
357 character other than space or newline.
358 database filename... Search the bibliographic databases filename...
360 For each filename if an index filename.i cre‐
361 ated by indxbib(1) exists, then it will be
362 searched instead; each index can cover multi‐
363 ple databases.
364 date-as-label* string string is a label expression that specifies a
366 string with which to replace the D field after
367 constructing the label. See the Label expres‐
368 sions subsection for a description of label
369 expressions. This command is useful if you do
370 not want explicit labels in the reference
371 list, but instead want to handle any necessary
372 disambiguation by qualifying the date in some
373 way. The label used in the text would typi‐
374 cally be some combination of the author and
375 date. In most cases you should also use the
376 no-label-in-reference command. For example,
377 date-as-label D.+yD.y%a*D.-y
379 would attach a disambiguating letter to the
381 year part of the D field in the reference.
382 default-database* The default database should be searched. This
384 is the default behaviour, so the negative ver‐
385 sion of this command is more useful. refer
386 determines whether the default database should
387 be searched on the first occasion that it
388 needs to do a search. Thus a no-default-data‐
389 base command must be given before then, in
390 order to be effective.
391 discard* fields When the reference is read, fields should be
393 discarded; no string definitions for fields
394 will be output. Initially, fields are XYZ.
395 et-al* string m n Control use of et al in the evaluation of @
397 expressions in label expressions. If the num‐
398 ber of authors needed to make the author
399 sequence unambiguous is u and the total number
400 of authors is t then the last t-u authors will
401 be replaced by string provided that t-u is not
402 less than m and t is not less than n. The
403 default behaviour is
404 et-al " et al" 2 3
406 include filename Include filename and interpret the contents as
408 commands.
409 join-authors string1 string2 string3
411 This says how authors should be joined
412 together. When there are exactly two authors,
413 they will be joined with string1. When there
414 are more than two authors, all but the last
415 two will be joined with string2, and the last
416 two authors will be joined with string3. If
417 string3 is omitted, it will default to
418 string1; if string2 is also omitted it will
419 also default to string1. For example,
420 join-authors " and " ", " ", and "
422 will restore the default method for joining
424 authors.
425 label-in-reference* When outputting the reference, define the
427 string [F to be the reference's label. This
428 is the default behaviour; so the negative ver‐
429 sion of this command is more useful.
430 label-in-text* For each reference output a label in the text.
432 The label will be separated from the surround‐
433 ing text as described in the bracket-label
434 command. This is the default behaviour; so
435 the negative version of this command is more
436 useful.
437 label string string is a label expression describing how to
439 label each reference.
440 separate-label-second-parts string
442 When merging two-part labels, separate the
443 second part of the second label from the first
444 label with string. See the description of the
445 <> label expression.
446 move-punctuation* In the text, move any punctuation at the end
448 of line past the label. It is usually a good
449 idea to give this command unless you are using
450 superscripted numbers as labels.
451 reverse* string Reverse the fields whose names are in string.
453 Each field name can be followed by a number
454 which says how many such fields should be
455 reversed. If no number is given for a field,
456 all such fields will be reversed.
457 search-ignore* fields While searching for keys in databases for
459 which no index exists, ignore the contents of
460 fields. Initially, fields XYZ are ignored.
461 search-truncate* n Only require the first n characters of keys to
463 be given. In effect when searching for a
464 given key words in the database are truncated
465 to the maximum of n and the length of the key.
466 Initially n is 6.
467 short-label* string string is a label expression that specifies an
469 alternative (usually shorter) style of label.
470 This is used when the # flag is given in the
471 citation. When using author-date style
472 labels, the identity of the author or authors
473 is sometimes clear from the context, and so it
474 may be desirable to omit the author or authors
475 from the label. The short-label command will
476 typically be used to specify a label contain‐
477 ing just a date and possibly a disambiguating
478 letter.
479 sort* string Sort references according to string. Refer‐
481 ences will automatically be accumulated.
482 string should be a list of field names, each
483 followed by a number, indicating how many
484 fields with the name should be used for sort‐
485 ing. + can be used to indicate that all the
486 fields with the name should be used. Also .
487 can be used to indicate the references should
488 be sorted using the (tentative) label. (The
489 Label expressions subsection describes the
490 concept of a tentative label.)
491 sort-adjacent-labels* Sort labels that are adjacent in the text
493 according to their position in the reference
494 list. This command should usually be given if
495 the abbreviate-label-ranges command has been
496 given, or if the label expression contains a
497 <> expression. This will have no effect
498 unless references are being accumulated.
499 Label expressions
501 Label expressions can be evaluated both normally and tentatively. The
502 result of normal evaluation is used for output. The result of tenta‐
503 tive evaluation, called the tentative label, is used to gather the
504 information that normal evaluation needs to disambiguate the label.
505 Label expressions specified by the date-as-label and short-label com‐
506 mands are not evaluated tentatively. Normal and tentative evaluation
507 are the same for all types of expression other than @, *, and % expres‐
508 sions. The description below applies to normal evaluation, except
509 where otherwise specified.
510 field
512 field n
513 The n-th part of field. If n is omitted, it defaults to 1.
514 'string'
516 The characters in string literally.
517 @ All the authors joined as specified by the join-authors command.
519 The whole of each author's name will be used. However, if the
520 references are sorted by author (that is the sort specification
521 starts with A+), then authors' last names will be used instead,
522 provided that this does not introduce ambiguity, and also an
523 initial subsequence of the authors may be used instead of all
524 the authors, again provided that this does not introduce ambigu‐
525 ity. The use of only the last name for the i-th author of some
526 reference is considered to be ambiguous if there is some other
527 reference, such that the first i-1 authors of the references are
528 the same, the i-th authors are not the same, but the i-th
529 authors' last names are the same. A proper initial subsequence
530 of the sequence of authors for some reference is considered to
531 be ambiguous if there is a reference with some other sequence of
532 authors which also has that subsequence as a proper initial sub‐
533 sequence. When an initial subsequence of authors is used, the
534 remaining authors are replaced by the string specified by the
535 et-al command; this command may also specify additional require‐
536 ments that must be met before an initial subsequence can be
537 used. @ tentatively evaluates to a canonical representation of
538 the authors, such that authors that compare equally for sorting
539 purpose will have the same representation.
540 %n
542 %a
543 %A
544 %i
545 %I The serial number of the reference formatted according to the
546 character following the %. The serial number of a reference
547 is 1 plus the number of earlier references with same tentative
548 label as this reference. These expressions tentatively evaluate
549 to an empty string.
550 expr* If there is another reference with the same tentative label as
552 this reference, then expr, otherwise an empty string. It tenta‐
553 tively evaluates to an empty string.
554 expr+n
556 expr-n The first (+) or last (-) n upper or lower case letters or dig‐
557 its of expr. Troff special characters (such as \('a) count as a
558 single letter. Accent strings are retained but do not count
559 towards the total.
560 expr.l expr converted to lowercase.
562 expr.u expr converted to uppercase.
564 expr.c expr converted to caps and small caps.
566 expr.r expr reversed so that the last name is first.
568 expr.a expr with first names abbreviated. Note that fields specified
570 in the abbreviate command are abbreviated before any labels are
571 evaluated. Thus .a is useful only when you want a field to be
572 abbreviated in a label but not in a reference.
573 expr.y The year part of expr.
575 expr.+y
577 The part of expr before the year, or the whole of expr if it
578 does not contain a year.
579 expr.-y
581 The part of expr after the year, or an empty string if expr does
582 not contain a year.
583 expr.n The last name part of expr.
585 expr1~expr2
587 expr1 except that if the last character of expr1 is - then it
588 will be replaced by expr2.
589 expr1 expr2
591 The concatenation of expr1 and expr2.
592 expr1|expr2
594 If expr1 is non-empty then expr1 otherwise expr2.
595 expr1&expr2
597 If expr1 is non-empty then expr2 otherwise an empty string.
598 expr1?expr2:expr3
600 If expr1 is non-empty then expr2 otherwise expr3.
601 <expr> The label is in two parts, which are separated by expr. Two
603 adjacent two-part labels which have the same first part will be
604 merged by appending the second part of the second label onto the
605 first label separated by the string specified in the separate-
606 label-second-parts command (initially, a comma followed by a
607 space); the resulting label will also be a two-part label with
608 the same first part as before merging, and so additional labels
609 can be merged into it. Note that it is permissible for the
610 first part to be empty; this maybe desirable for expressions
611 used in the short-label command.
612 (expr) The same as expr. Used for grouping.
614 The above expressions are listed in order of precedence (highest
616 first); & and | have the same precedence.
617 Macro interface
619 Each reference starts with a call to the macro ]-. The string [F will
620 be defined to be the label for this reference, unless the no-label-in-
621 reference command has been given. There then follows a series of
622 string definitions, one for each field: string [X corresponds to field
623 X. The number register [P is set to 1 if the P field contains a range
624 of pages. The [T, [A and [O number registers are set to 1 according as
625 the T, A and O fields end with one of the characters .?!. The [E num‐
626 ber register will be set to 1 if the [E string contains more than one
627 name. The reference is followed by a call to the ][ macro. The first
628 argument to this macro gives a number representing the type of the ref‐
629 erence. If a reference contains a J field, it will be classified as
630 type 1, otherwise if it contains a B field, it will type 3, otherwise
631 if it contains a G or R field it will be type 4, otherwise if contains
632 a I field it will be type 2, otherwise it will be type 0. The second
633 argument is a symbolic name for the type: other, journal-article, book,
634 article-in-book or tech-report. Groups of references that have been
635 accumulated or are produced by the bibliography command are preceded by
636 a call to the ]< macro and followed by a call to the ]> macro.
637
639 /usr/dict/papers/Ind Default database.
640 file.i Index files.
642 refer uses temporary files. See the groff(1) man page for details
644 where such files are created.
645
647 REFER If set, overrides the default database.
648
650 indxbib(1), lookbib(1), lkbib(1)
651
653 In label expressions, <> expressions are ignored inside .char expres‐
654 sions.
655Groff Version 1.22.2 7 February 2013 REFER(1)