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
15 This file documents the GNU version of refer, which is part of the
16 groff document formatting system. refer copies the contents of file‐
17 name... to the standard output, except that lines between .[ and .] are
18 interpreted as citations, and lines between .R1 and .R2 are interpreted
19 as commands about how citations are to be processed.
20 Each citation specifies a reference. The citation can specify a refer‐
22 ence that is contained in a bibliographic database by giving a set of
23 keywords that only that reference contains. Alternatively it can spec‐
24 ify a reference by supplying a database record in the citation. A com‐
25 bination of these alternatives is also possible.
26 For each citation, refer can produce a mark in the text. This mark
28 consists of some label which can be separated from the text and from
29 other labels in various ways. For each reference it also outputs groff
30 commands that can be used by a macro package to produce a formatted
31 reference for each citation. The output of refer must therefore be
32 processed using a suitable macro package. The -ms and -me macros are
33 both suitable. The commands to format a citation's reference can be
34 output immediately after the citation, or the references may be accumu‐
35 lated, and the commands output at some later point. If the references
36 are accumulated, then multiple citations of the same reference will
37 produce a single formatted reference.
38 The interpretation of lines between .R1 and .R2 as commands is a new
40 feature of GNU refer. Documents making use of this feature can still
41 be processed by Unix refer just by adding the lines
42 .de R1
44 .ig R2
45 ..
46 to the beginning of the document. This will cause troff to ignore
47 everything between .R1 and .R2. The effect of some commands can also
48 be achieved by options. These options are supported mainly for compat‐
49 ibility with Unix refer. It is usually more convenient to use com‐
50 mands.
51 refer generates .lf lines so that filenames and line numbers in mes‐
53 sages produced by commands that read refer output will be correct; it
54 also interprets lines beginning with .lf so that filenames and line
55 numbers in the messages and .lf lines that it produces will be accurate
56 even if the input has been preprocessed by a command such as soelim(1).
57
59 It is possible to have whitespace between a command line option and its
60 parameter.
61 Most options are equivalent to commands (for a description of these
63 commands see the Commands subsection):
64 -b no-label-in-text; no-label-in-reference
66 -e accumulate
68 -n no-default-database
70 -C compatible
72 -P move-punctuation
74 -S label "(A.n|Q) ', ' (D.y|D)"; bracket-label " (" ) "; "
76 -an reverse An
78 -cfields
80 capitalize fields
81 -fn label %n
83 -ifields
85 search-ignore fields
86 -k label L~%a
88 -kfield
90 label field~%a
91 -l label A.nD.y%a
93 -lm label A.n+mD.y%a
95 -l,n label A.nD.y-n%a
97 -lm,n label A.n+mD.y-n%a
99 -pfilename
101 database filename
102 -sspec sort spec
104 -tn search-truncate n
106 These options are equivalent to the following commands with the addi‐
108 tion that the filenames specified on the command line are processed as
109 if they were arguments to the bibliography command instead of in the
110 normal way:
111 -B annotate X AP; no-label-in-reference
113 -Bfield.macro
115 annotate field macro; no-label-in-reference
116 The following options have no equivalent commands:
118 -v Print the version number.
120 -R Don't recognize lines beginning with .R1/.R2.
122
124 Bibliographic databases
125 The bibliographic database is a text file consisting of records sepa‐
126 rated by one or more blank lines. Within each record fields start with
127 a % at the beginning of a line. Each field has a one character name
128 that immediately follows the %. It is best to use only upper and lower
129 case letters for the names of fields. The name of the field should be
130 followed by exactly one space, and then by the contents of the field.
131 Empty fields are ignored. The conventional meaning of each field is as
132 follows:
133 %A The name of an author. If the name contains a title such as Jr.
135 at the end, it should be separated from the last name by a
136 comma. There can be multiple occurrences of the %A field. The
137 order is significant. It is a good idea always to supply an %A
138 field or a %Q field.
139 %B For an article that is part of a book, the title of the book.
141 %C The place (city) of publication.
143 %D The date of publication. The year should be specified in full.
145 If the month is specified, the name rather than the number of
146 the month should be used, but only the first three letters are
147 required. It is a good idea always to supply a %D field; if the
148 date is unknown, a value such as in press or unknown can be
149 used.
150 %E For an article that is part of a book, the name of an editor of
152 the book. Where the work has editors and no authors, the names
153 of the editors should be given as %A fields and , (ed) or
154 , (eds) should be appended to the last author.
155 %G US Government ordering number.
157 %I The publisher (issuer).
159 %J For an article in a journal, the name of the journal.
161 %K Keywords to be used for searching.
163 %L Label.
165 %N Journal issue number.
167 %O Other information. This is usually printed at the end of the
169 reference.
170 %P Page number. A range of pages can be specified as m-n.
172 %Q The name of the author, if the author is not a person. This
174 will only be used if there are no %A fields. There can only be
175 one %Q field.
176 %R Technical report number.
178 %S Series name.
180 %T Title. For an article in a book or journal, this should be the
182 title of the article.
183 %V Volume number of the journal or book.
185 %X Annotation.
187 For all fields except %A and %E, if there is more than one occurrence
189 of a particular field in a record, only the last such field will be
190 used.
191 If accent strings are used, they should follow the character to be
193 accented. This means that the AM macro must be used with the -ms
194 macros. Accent strings should not be quoted: use one \ rather than
195 two.
196 Citations
198 The format of a citation is
199 .[opening-text
200 flags keywords
201 fields
202 .]closing-text
203 The opening-text, closing-text and flags components are optional. Only
205 one of the keywords and fields components need be specified.
206 The keywords component says to search the bibliographic databases for a
208 reference that contains all the words in keywords. It is an error if
209 more than one reference if found.
210 The fields components specifies additional fields to replace or supple‐
212 ment those specified in the reference. When references are being accu‐
213 mulated and the keywords component is non-empty, then additional fields
214 should be specified only on the first occasion that a particular refer‐
215 ence is cited, and will apply to all citations of that reference.
216 The opening-text and closing-text component specifies strings to be
218 used to bracket the label instead of the strings specified in the
219 bracket-label command. If either of these components is non-empty, the
220 strings specified in the bracket-label command will not be used; this
221 behaviour can be altered using the [ and ] flags. Note that leading
222 and trailing spaces are significant for these components.
223 The flags component is a list of non-alphanumeric characters each of
225 which modifies the treatment of this particular citation. Unix refer
226 will treat these flags as part of the keywords and so will ignore them
227 since they are non-alphanumeric. The following flags are currently
228 recognized:
229 # This says to use the label specified by the short-label command,
231 instead of that specified by the label command. If no short
232 label has been specified, the normal label will be used. Typi‐
233 cally the short label is used with author-date labels and con‐
234 sists of only the date and possibly a disambiguating letter; the
235 # is supposed to be suggestive of a numeric type of label.
236 [ Precede opening-text with the first string specified in the
238 bracket-label command.
239 ] Follow closing-text with the second string specified in the
241 bracket-label command.
242 One advantages of using the [ and ] flags rather than including the
244 brackets in opening-text and closing-text is that you can change the
245 style of bracket used in the document just by changing the bracket-
246 label command. Another advantage is that sorting and merging of cita‐
247 tions will not necessarily be inhibited if the flags are used.
248 If a label is to be inserted into the text, it will be attached to the
250 line preceding the .[ line. If there is no such line, then an extra
251 line will be inserted before the .[ line and a warning will be given.
252 There is no special notation for making a citation to multiple refer‐
254 ences. Just use a sequence of citations, one for each reference.
255 Don't put anything between the citations. The labels for all the cita‐
256 tions will be attached to the line preceding the first citation. The
257 labels may also be sorted or merged. See the description of the <>
258 label expression, and of the sort-adjacent-labels and abbreviate-label-
259 ranges command. A label will not be merged if its citation has a non-
260 empty opening-text or closing-text. However, the labels for a citation
261 using the ] flag and without any closing-text immediately followed by a
262 citation using the [ flag and without any opening-text may be sorted
263 and merged even though the first citation's opening-text or the second
264 citation's closing-text is non-empty. (If you wish to prevent this
265 just make the first citation's closing-text \&.)
266 Commands
268 Commands are contained between lines starting with .R1 and .R2. Recog‐
269 nition of these lines can be prevented by the -R option. When a .R1
270 line is recognized any accumulated references are flushed out. Neither
271 .R1 nor .R2 lines, nor anything between them is output.
272 Commands are separated by newlines or ;s. # introduces a comment that
274 extends to the end of the line (but does not conceal the newline).
275 Each command is broken up into words. Words are separated by spaces or
276 tabs. A word that begins with " extends to the next " that is not fol‐
277 lowed by another ". If there is no such " the word extends to the end
278 of the line. Pairs of " in a word beginning with " collapse to a sin‐
279 gle ". Neither # nor ; are recognized inside "s. A line can be con‐
280 tinued by ending it with \; this works everywhere except after a #.
281 Each command name that is marked with * has an associated negative com‐
283 mand no-name that undoes the effect of name. For example, the no-sort
284 command specifies that references should not be sorted. The negative
285 commands take no arguments.
286 In the following description each argument must be a single word; field
288 is used for a single upper or lower case letter naming a field; fields
289 is used for a sequence of such letters; m and n are used for a non-neg‐
290 ative numbers; string is used for an arbitrary string; filename is used
291 for the name of a file.
292 abbreviate* fields string1 string2 string3 string4
294 Abbreviate the first names of fields. An ini‐
295 tial letter will be separated from another
296 initial letter by string1, from the last name
297 by string2, and from anything else (such as a
298 von or de) by string3. These default to a
299 period followed by a space. In a hyphenated
300 first name, the initial of the first part of
301 the name will be separated from the hyphen by
302 string4; this defaults to a period. No
303 attempt is made to handle any ambiguities that
304 might result from abbreviation. Names are
305 abbreviated before sorting and before label
306 construction.
307 abbreviate-label-ranges* string
309 Three or more adjacent labels that refer to
310 consecutive references will be abbreviated to
311 a label consisting of the first label, fol‐
312 lowed by string followed by the last label.
313 This is mainly useful with numeric labels. If
314 string is omitted it defaults to -.
315 accumulate* Accumulate references instead of writing out
317 each reference as it is encountered. Accumu‐
318 lated references will be written out whenever
319 a reference of the form
320 .[
322 $LIST$
323 .]
324 is encountered, after all input files have
326 been processed, and whenever .R1 line is rec‐
327 ognized.
328 annotate* field string field is an annotation; print it at the end of
330 the reference as a paragraph preceded by the
331 line
332 .string
334 If string is omitted it will default to AP; if
336 field is also omitted it will default to X.
337 Only one field can be an annotation.
338 articles string... string... are definite or indefinite articles,
340 and should be ignored at the beginning of T
341 fields when sorting. Initially, the, a and an
342 are recognized as articles.
343 bibliography filename... Write out all the references contained in the
345 bibliographic databases filename... This com‐
346 mand should come last in a .R1/.R2 block.
347 bracket-label string1 string2 string3
349 In the text, bracket each label with string1
350 and string2. An occurrence of string2 immedi‐
351 ately followed by string1 will be turned into
352 string3. The default behaviour is
353 bracket-label \*([. \*(.] ", "
355 capitalize fields Convert fields to caps and small caps.
357 compatible* Recognize .R1 and .R2 even when followed by a
359 character other than space or newline.
360 database filename... Search the bibliographic databases filename...
362 For each filename if an index filename.i cre‐
363 ated by indxbib(1) exists, then it will be
364 searched instead; each index can cover multi‐
365 ple databases.
366 date-as-label* string string is a label expression that specifies a
368 string with which to replace the D field after
369 constructing the label. See the Label expres‐
370 sions subsection for a description of label
371 expressions. This command is useful if you do
372 not want explicit labels in the reference
373 list, but instead want to handle any necessary
374 disambiguation by qualifying the date in some
375 way. The label used in the text would typi‐
376 cally be some combination of the author and
377 date. In most cases you should also use the
378 no-label-in-reference command. For example,
379 date-as-label D.+yD.y%a*D.-y
381 would attach a disambiguating letter to the
383 year part of the D field in the reference.
384 default-database* The default database should be searched. This
386 is the default behaviour, so the negative ver‐
387 sion of this command is more useful. refer
388 determines whether the default database should
389 be searched on the first occasion that it
390 needs to do a search. Thus a no-default-data‐
391 base command must be given before then, in
392 order to be effective.
393 discard* fields When the reference is read, fields should be
395 discarded; no string definitions for fields
396 will be output. Initially, fields are XYZ.
397 et-al* string m n Control use of et al in the evaluation of @
399 expressions in label expressions. If the num‐
400 ber of authors needed to make the author
401 sequence unambiguous is u and the total number
402 of authors is t then the last t-u authors will
403 be replaced by string provided that t-u is not
404 less than m and t is not less than n. The
405 default behaviour is
406 et-al " et al" 2 3
408 include filename Include filename and interpret the contents as
410 commands.
411 join-authors string1 string2 string3
413 This says how authors should be joined
414 together. When there are exactly two authors,
415 they will be joined with string1. When there
416 are more than two authors, all but the last
417 two will be joined with string2, and the last
418 two authors will be joined with string3. If
419 string3 is omitted, it will default to
420 string1; if string2 is also omitted it will
421 also default to string1. For example,
422 join-authors " and " ", " ", and "
424 will restore the default method for joining
426 authors.
427 label-in-reference* When outputting the reference, define the
429 string [F to be the reference's label. This
430 is the default behaviour; so the negative ver‐
431 sion of this command is more useful.
432 label-in-text* For each reference output a label in the text.
434 The label will be separated from the surround‐
435 ing text as described in the bracket-label
436 command. This is the default behaviour; so
437 the negative version of this command is more
438 useful.
439 label string string is a label expression describing how to
441 label each reference.
442 separate-label-second-parts string
444 When merging two-part labels, separate the
445 second part of the second label from the first
446 label with string. See the description of the
447 <> label expression.
448 move-punctuation* In the text, move any punctuation at the end
450 of line past the label. It is usually a good
451 idea to give this command unless you are using
452 superscripted numbers as labels.
453 reverse* string Reverse the fields whose names are in string.
455 Each field name can be followed by a number
456 which says how many such fields should be
457 reversed. If no number is given for a field,
458 all such fields will be reversed.
459 search-ignore* fields While searching for keys in databases for
461 which no index exists, ignore the contents of
462 fields. Initially, fields XYZ are ignored.
463 search-truncate* n Only require the first n characters of keys to
465 be given. In effect when searching for a
466 given key words in the database are truncated
467 to the maximum of n and the length of the key.
468 Initially n is 6.
469 short-label* string string is a label expression that specifies an
471 alternative (usually shorter) style of label.
472 This is used when the # flag is given in the
473 citation. When using author-date style
474 labels, the identity of the author or authors
475 is sometimes clear from the context, and so it
476 may be desirable to omit the author or authors
477 from the label. The short-label command will
478 typically be used to specify a label contain‐
479 ing just a date and possibly a disambiguating
480 letter.
481 sort* string Sort references according to string. Refer‐
483 ences will automatically be accumulated.
484 string should be a list of field names, each
485 followed by a number, indicating how many
486 fields with the name should be used for sort‐
487 ing. + can be used to indicate that all the
488 fields with the name should be used. Also .
489 can be used to indicate the references should
490 be sorted using the (tentative) label. (The
491 Label expressions subsection describes the
492 concept of a tentative label.)
493 sort-adjacent-labels* Sort labels that are adjacent in the text
495 according to their position in the reference
496 list. This command should usually be given if
497 the abbreviate-label-ranges command has been
498 given, or if the label expression contains a
499 <> expression. This will have no effect
500 unless references are being accumulated.
501 Label expressions
503 Label expressions can be evaluated both normally and tentatively. The
504 result of normal evaluation is used for output. The result of tenta‐
505 tive evaluation, called the tentative label, is used to gather the
506 information that normal evaluation needs to disambiguate the label.
507 Label expressions specified by the date-as-label and short-label com‐
508 mands are not evaluated tentatively. Normal and tentative evaluation
509 are the same for all types of expression other than @, *, and % expres‐
510 sions. The description below applies to normal evaluation, except
511 where otherwise specified.
512 field
514 field n
515 The n-th part of field. If n is omitted, it defaults to 1.
516 'string'
518 The characters in string literally.
519 @ All the authors joined as specified by the join-authors command.
521 The whole of each author's name will be used. However, if the
522 references are sorted by author (that is the sort specification
523 starts with A+), then authors last names will be used instead,
524 provided that this does not introduce ambiguity, and also an
525 initial subsequence of the authors may be used instead of all
526 the authors, again provided that this does not introduce ambigu‐
527 ity. The use of only the last name for the i-th author of some
528 reference is considered to be ambiguous if there is some other
529 reference, such that the first i-1 authors of the references are
530 the same, the i-th authors are not the same, but the i-th
531 authors last names are the same. A proper initial subsequence
532 of the sequence of authors for some reference is considered to
533 be ambiguous if there is a reference with some other sequence of
534 authors which also has that subsequence as a proper initial sub‐
535 sequence. When an initial subsequence of authors is used, the
536 remaining authors are replaced by the string specified by the
537 et-al command; this command may also specify additional require‐
538 ments that must be met before an initial subsequence can be
539 used. @ tentatively evaluates to a canonical representation of
540 the authors, such that authors that compare equally for sorting
541 purpose will have the same representation.
542 %n
544 %a
545 %A
546 %i
547 %I The serial number of the reference formatted according to the
548 character following the %. The serial number of a reference
549 is 1 plus the number of earlier references with same tentative
550 label as this reference. These expressions tentatively evaluate
551 to an empty string.
552 expr* If there is another reference with the same tentative label as
554 this reference, then expr, otherwise an empty string. It tenta‐
555 tively evaluates to an empty string.
556 expr+n
558 expr-n The first (+) or last (-) n upper or lower case letters or dig‐
559 its of expr. Troff special characters (such as \('a) count as a
560 single letter. Accent strings are retained but do not count
561 towards the total.
562 expr.l expr converted to lowercase.
564 expr.u expr converted to uppercase.
566 expr.c expr converted to caps and small caps.
568 expr.r expr reversed so that the last name is first.
570 expr.a expr with first names abbreviated. Note that fields specified
572 in the abbreviate command are abbreviated before any labels are
573 evaluated. Thus .a is useful only when you want a field to be
574 abbreviated in a label but not in a reference.
575 expr.y The year part of expr.
577 expr.+y
579 The part of expr before the year, or the whole of expr if it
580 does not contain a year.
581 expr.-y
583 The part of expr after the year, or an empty string if expr does
584 not contain a year.
585 expr.n The last name part of expr.
587 expr1~expr2
589 expr1 except that if the last character of expr1 is - then it
590 will be replaced by expr2.
591 expr1 expr2
593 The concatenation of expr1 and expr2.
594 expr1|expr2
596 If expr1 is non-empty then expr1 otherwise expr2.
597 expr1&expr2
599 If expr1 is non-empty then expr2 otherwise an empty string.
600 expr1?expr2:expr3
602 If expr1 is non-empty then expr2 otherwise expr3.
603 <expr> The label is in two parts, which are separated by expr. Two
605 adjacent two-part labels which have the same first part will be
606 merged by appending the second part of the second label onto the
607 first label separated by the string specified in the separate-
608 label-second-parts command (initially, a comma followed by a
609 space); the resulting label will also be a two-part label with
610 the same first part as before merging, and so additional labels
611 can be merged into it. Note that it is permissible for the
612 first part to be empty; this maybe desirable for expressions
613 used in the short-label command.
614 (expr) The same as expr. Used for grouping.
616 The above expressions are listed in order of precedence (highest
618 first); & and | have the same precedence.
619 Macro interface
621 Each reference starts with a call to the macro ]-. The string [F will
622 be defined to be the label for this reference, unless the no-label-in-
623 reference command has been given. There then follows a series of
624 string definitions, one for each field: string [X corresponds to field
625 X. The number register [P is set to 1 if the P field contains a range
626 of pages. The [T, [A and [O number registers are set to 1 according as
627 the T, A and O fields end with one of the characters .?!. The [E num‐
628 ber register will be set to 1 if the [E string contains more than one
629 name. The reference is followed by a call to the ][ macro. The first
630 argument to this macro gives a number representing the type of the ref‐
631 erence. If a reference contains a J field, it will be classified as
632 type 1, otherwise if it contains a B field, it will type 3, otherwise
633 if it contains a G or R field it will be type 4, otherwise if contains
634 a I field it will be type 2, otherwise it will be type 0. The second
635 argument is a symbolic name for the type: other, journal-article, book,
636 article-in-book or tech-report. Groups of references that have been
637 accumulated or are produced by the bibliography command are preceded by
638 a call to the ]< macro and followed by a call to the ]> macro.
639
641 /usr/dict/papers/Ind Default database.
642 file.i Index files.
644 refer uses temporary files. See the groff(1) man page for details
646 where such files are created.
647
649 REFER If set, overrides the default database.
650
652 indxbib(1), lookbib(1), lkbib(1)
653
655 In label expressions, <> expressions are ignored inside .char expres‐
656 sions.
657
659 Copyright © 1989-2014 Free Software Foundation, Inc.
660 Permission is granted to make and distribute verbatim copies of this
662 manual provided the copyright notice and this permission notice are
663 preserved on all copies.
664 Permission is granted to copy and distribute modified versions of this
666 manual under the conditions for verbatim copying, provided that the
667 entire resulting derived work is distributed under the terms of a per‐
668 mission notice identical to this one.
669 Permission is granted to copy and distribute translations of this man‐
671 ual into another language, under the above conditions for modified ver‐
672 sions, except that this permission notice may be included in transla‐
673 tions approved by the Free Software Foundation instead of in the origi‐
674 nal English.
675Groff Version 1.22.3 4 November 2014 REFER(1)