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 It is possible to have whitespace between a command line option and its
14 parameter.
15
17 This file documents the GNU version of refer, which is part of the
18 groff document formatting system. refer copies the contents of file‐
19 name... to the standard output, except that lines between .[ and .]
20 are interpreted as citations, and lines between .R1 and .R2 are inter‐
21 preted as commands about how citations are to be processed.
22 Each citation specifies a reference. The citation can specify a refer‐
24 ence that is contained in a bibliographic database by giving a set of
25 keywords that only that reference contains. Alternatively it can spec‐
26 ify a reference by supplying a database record in the citation. A com‐
27 bination of these alternatives is also possible.
28 For each citation, refer can produce a mark in the text. This mark
30 consists of some label which can be separated from the text and from
31 other labels in various ways. For each reference it also outputs groff
32 commands that can be used by a macro package to produce a formatted
33 reference for each citation. The output of refer must therefore be
34 processed using a suitable macro package. The -ms and -me macros are
35 both suitable. The commands to format a citation's reference can be
36 output immediately after the citation, or the references may be accumu‐
37 lated, and the commands output at some later point. If the references
38 are accumulated, then multiple citations of the same reference will
39 produce a single formatted reference.
40 The interpretation of lines between .R1 and .R2 as commands is a new
42 feature of GNU refer. Documents making use of this feature can still
43 be processed by Unix refer just by adding the lines
44 .de R1
46 .ig R2
47 ..
48 to the beginning of the document. This will cause troff to ignore
49 everything between .R1 and .R2. The effect of some commands can also
50 be achieved by options. These options are supported mainly for compat‐
51 ibility with Unix refer. It is usually more convenient to use com‐
52 mands.
53 refer generates .lf lines so that filenames and line numbers in mes‐
55 sages produced by commands that read refer output will be correct; it
56 also interprets lines beginning with .lf so that filenames and line
57 numbers in the messages and .lf lines that it produces will be accurate
58 even if the input has been preprocessed by a command such as soelim(1).
59
61 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 hve been
324 processed, and whenever .R1 line is recog‐
325 nized.
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 macro 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 arti‐
338 cles, and should be ignored at the beginning
339 of T fields when sorting. Initially, the, a
340 and an are recognized as articles.
341 bibliography filename... Write out all the references contained in the
343 bibliographic databases filename...
344 bracket-label string1 string2 string3
346 In the text, bracket each label with string1
347 and string2. An occurrence of string2 immedi‐
348 ately followed by string1 will be turned into
349 string3. The default behaviour is
350 bracket-label \*([. \*(.] ", "
352 capitalize fields Convert fields to caps and small caps.
354 compatible* Recognize .R1 and .R2 even when followed by a
356 character other than space or newline.
357 database filename... Search the bibliographic databases filename...
359 For each filename if an index filename.i cre‐
360 ated by indxbib(1) exists, then it will be
361 searched instead; each index can cover multi‐
362 ple databases.
363 date-as-label* string string is a label expression that specifies a
365 string with which to replace the D field after
366 constructing the label. See the Label expres‐
367 sions subsection for a description of label
368 expressions. This command is useful if you do
369 not want explicit labels in the reference
370 list, but instead want to handle any necessary
371 disambiguation by qualifying the date in some
372 way. The label used in the text would typi‐
373 cally be some combination of the author and
374 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
380 year part of the D field in the reference.
381 default-database* The default database should be searched. This
383 is the default behaviour, so the negative ver‐
384 sion of this command is more useful. refer
385 determines whether the default database should
386 be searched on the first occasion that it
387 needs to do a search. Thus a no-default-data‐
388 base command must be given before then, in
389 order to be effective.
390 discard* fields When the reference is read, fields should be
392 discarded; no string definitions for fields
393 will be output. Initially, fields are XYZ.
394 et-al* string m n Control use of et al in the evaluation of @
396 expressions in label expressions. If the num‐
397 ber of authors needed to make the author
398 sequence unambiguous is u and the total number
399 of authors is t then the last t-u authors will
400 be replaced by string provided that t-u is not
401 less than m and t is not less than n. The
402 default behaviour is
403 et-al " et al" 2 3
405 include filename Include filename and interpret the contents as
407 commands.
408 join-authors string1 string2 string3
410 This says how authors should be joined
411 together. When there are exactly two authors,
412 they will be joined with string1. When there
413 are more than two authors, all but the last
414 two will be joined with string2, and the last
415 two authors will be joined with string3. If
416 string3 is omitted, it will default to
417 string1; if string2 is also omitted it will
418 also default to string1. For example,
419 join-authors " and " ", " ", and "
421 will restore the default method for joining
423 authors.
424 label-in-reference* When outputting the reference, define the
426 string [F to be the reference's label. This
427 is the default behaviour; so the negative ver‐
428 sion of this command is more useful.
429 label-in-text* For each reference output a label in the text.
431 The label will be separated from the surround‐
432 ing text as described in the bracket-label
433 command. This is the default behaviour; so
434 the negative version of this command is more
435 useful.
436 label string string is a label expression describing how to
438 label each reference.
439 separate-label-second-parts string
441 When merging two-part labels, separate the
442 second part of the second label from the first
443 label with string. See the description of the
444 <> label expression.
445 move-punctuation* In the text, move any punctuation at the end
447 of line past the label. It is usually a good
448 idea to give this command unless you are using
449 superscripted numbers as labels.
450 reverse* string Reverse the fields whose names are in string.
452 Each field name can be followed by a number
453 which says how many such fields should be
454 reversed. If no number is given for a field,
455 all such fields will be reversed.
456 search-ignore* fields While searching for keys in databases for
458 which no index exists, ignore the contents of
459 fields. Initially, fields XYZ are ignored.
460 search-truncate* n Only require the first n characters of keys to
462 be given. In effect when searching for a
463 given key words in the database are truncated
464 to the maximum of n and the length of the key.
465 Initially n is 6.
466 short-label* string string is a label expression that specifies an
468 alternative (usually shorter) style of label.
469 This is used when the # flag is given in the
470 citation. When using author-date style
471 labels, the identity of the author or authors
472 is sometimes clear from the context, and so it
473 may be desirable to omit the author or authors
474 from the label. The short-label command will
475 typically be used to specify a label contain‐
476 ing just a date and possibly a disambiguating
477 letter.
478 sort* string Sort references according to string. Refer‐
480 ences will automatically be accumulated.
481 string should be a list of field names, each
482 followed by a number, indicating how many
483 fields with the name should be used for sort‐
484 ing. + can be used to indicate that all the
485 fields with the name should be used. Also .
486 can be used to indicate the references should
487 be sorted using the (tentative) label. (The
488 Label expressions subsection describes the
489 concept of a tentative label.)
490 sort-adjacent-labels* Sort labels that are adjacent in the text
492 according to their position in the reference
493 list. This command should usually be given if
494 the abbreviate-label-ranges command has been
495 given, or if the label expression contains a
496 <> expression. This will have no effect
497 unless references are being accumulated.
498 Label expressions
500 Label expressions can be evaluated both normally and tentatively. The
501 result of normal evaluation is used for output. The result of tenta‐
502 tive evaluation, called the tentative label, is used to gather the
503 information that normal evaluation needs to disambiguate the label.
504 Label expressions specified by the date-as-label and short-label com‐
505 mands are not evaluated tentatively. Normal and tentative evaluation
506 are the same for all types of expression other than @, *, and % expres‐
507 sions. The description below applies to normal evaluation, except
508 where otherwise specified.
509 field
511 field n
512 The n-th part of field. If n is omitted, it defaults to 1.
513 'string'
515 The characters in string literally.
516 @ All the authors joined as specified by the join-authors command.
518 The whole of each author's name will be used. However, if the
519 references are sorted by author (that is the sort specification
520 starts with A+), then authors' last names will be used instead,
521 provided that this does not introduce ambiguity, and also an
522 initial subsequence of the authors may be used instead of all
523 the authors, again provided that this does not introduce ambigu‐
524 ity. The use of only the last name for the i-th author of some
525 reference is considered to be ambiguous if there is some other
526 reference, such that the first i-1 authors of the references are
527 the same, the i-th authors are not the same, but the i-th
528 authors' last names are the same. A proper initial subsequence
529 of the sequence of authors for some reference is considered to
530 be ambiguous if there is a reference with some other sequence of
531 authors which also has that subsequence as a proper initial sub‐
532 sequence. When an initial subsequence of authors is used, the
533 remaining authors are replaced by the string specified by the
534 et-al command; this command may also specify additional require‐
535 ments that must be met before an initial subsequence can be
536 used. @ tentatively evaluates to a canonical representation of
537 the authors, such that authors that compare equally for sorting
538 purpose will have the same representation.
539 %n
541 %a
542 %A
543 %i
544 %I The serial number of the reference formatted according to the
545 character following the %. The serial number of a reference is
546 1 plus the number of earlier references with same tentative
547 label as this reference. These expressions tentatively evaluate
548 to an empty string.
549 expr* If there is another reference with the same tentative label as
551 this reference, then expr, otherwise an empty string. It tenta‐
552 tively evaluates to an empty string.
553 expr+n
555 expr-n The first (+) or last (-) n upper or lower case letters or dig‐
556 its of expr. Troff special characters (such as \('a) count as a
557 single letter. Accent strings are retained but do not count
558 towards the total.
559 expr.l expr converted to lowercase.
561 expr.u expr converted to uppercase.
563 expr.c expr converted to caps and small caps.
565 expr.r expr reversed so that the last name is first.
567 expr.a expr with first names abbreviated. Note that fields specified
569 in the abbreviate command are abbreviated before any labels are
570 evaluated. Thus .a is useful only when you want a field to be
571 abbreviated in a label but not in a reference.
572 expr.y The year part of expr.
574 expr.+y
576 The part of expr before the year, or the whole of expr if it
577 does not contain a year.
578 expr.-y
580 The part of expr after the year, or an empty string if expr does
581 not contain a year.
582 expr.n The last name part of expr.
584 expr1~expr2
586 expr1 except that if the last character of expr1 is - then it
587 will be replaced by expr2.
588 expr1 expr2
590 The concatenation of expr1 and expr2.
591 expr1|expr2
593 If expr1 is non-empty then expr1 otherwise expr2.
594 expr1&expr2
596 If expr1 is non-empty then expr2 otherwise an empty string.
597 expr1?expr2:expr3
599 If expr1 is non-empty then expr2 otherwise expr3.
600 <expr> The label is in two parts, which are separated by expr. Two
602 adjacent two-part labels which have the same first part will be
603 merged by appending the second part of the second label onto the
604 first label separated by the string specified in the separate-
605 label-second-parts command (initially, a comma followed by a
606 space); the resulting label will also be a two-part label with
607 the same first part as before merging, and so additional labels
608 can be merged into it. Note that it is permissible for the
609 first part to be empty; this maybe desirable for expressions
610 used in the short-label command.
611 (expr) The same as expr. Used for grouping.
613 The above expressions are listed in order of precedence (highest
615 first); & and | have the same precedence.
616 Macro interface
618 Each reference starts with a call to the macro ]-. The string [F will
619 be defined to be the label for this reference, unless the no-label-in-
620 reference command has been given. There then follows a series of
621 string definitions, one for each field: string [X corresponds to field
622 X. The number register [P is set to 1 if the P field contains a range
623 of pages. The [T, [A and [O number registers are set to 1 according as
624 the T, A and O fields end with one of the characters .?!. The [E num‐
625 ber register will be set to 1 if the [E string contains more than one
626 name. The reference is followed by a call to the ][ macro. The first
627 argument to this macro gives a number representing the type of the ref‐
628 erence. If a reference contains a J field, it will be classified as
629 type 1, otherwise if it contains a B field, it will type 3, otherwise
630 if it contains a G or R field it will be type 4, otherwise if contains
631 a I field it will be type 2, otherwise it will be type 0. The second
632 argument is a symbolic name for the type: other, journal-article, book,
633 article-in-book or tech-report. Groups of references that have been
634 accumulated or are produced by the bibliography command are preceded by
635 a call to the ]< macro and followed by a call to the ]> macro.
636
638 /usr/dict/papers/Ind Default database.
639 file.i Index files.
641
643 indxbib(1), lookbib(1), lkbib(1)
644
646 In label expressions, <> expressions are ignored inside .char expres‐
647 sions.
648Groff Version 1.18.1.4 27 June 2001 REFER(1)