Debian Codegraph @

upstream/debian-trixie/man1/refer.1

raw
1 .TH \%refer 1 "3 June 2025" "groff 1.23.0"
2 .SH Name
3 \%refer \- process bibliographic references for
4 .I groff
5 .
6 .
7 .\" ====================================================================
8 .\" Legal Terms
9 .\" ====================================================================
10 .\"
11 .\" Copyright (C) 1989-2021 Free Software Foundation, Inc.
12 .\"
13 .\" Permission is granted to make and distribute verbatim copies of this
14 .\" manual provided the copyright notice and this permission notice are
15 .\" preserved on all copies.
16 .\"
17 .\" Permission is granted to copy and distribute modified versions of
18 .\" this manual under the conditions for verbatim copying, provided that
19 .\" the entire resulting derived work is distributed under the terms of
20 .\" a permission notice identical to this one.
21 .\"
22 .\" Permission is granted to copy and distribute translations of this
23 .\" manual into another language, under the above conditions for
24 .\" modified versions, except that this permission notice may be
25 .\" included in translations approved by the Free Software Foundation
26 .\" instead of in the original English.
27 .
28 .
29 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
30 .do nr *groff_refer_1_man_C \n[.cp]
31 .cp 0
32 .
33 .\" Define fallback for groff 1.23's MR macro if the system lacks it.
34 .nr do-fallback 0
35 .if !\n(.f .nr do-fallback 1 \" mandoc
36 .if \n(.g .if !d MR .nr do-fallback 1 \" older groff
37 .if !\n(.g .nr do-fallback 1 \" non-groff *roff
38 .if \n[do-fallback] \{\
39 . de MR
40 . ie \\n(.$=1 \
41 . I \%\\$1
42 . el \
43 . IR \%\\$1 (\\$2)\\$3
44 . .
45 .\}
46 .rr do-fallback
47 .
48 .
49 .\" ====================================================================
50 .SH Synopsis
51 .\" ====================================================================
52 .
53 .SY \%refer
54 .RB [ \-bCenPRS ]
55 .RB [ \-a\~\c
56 .IR n ]
57 .RB [ \-B
58 .IB field . macro\c
59 ]
60 .RB [ \-c\~\c
61 .IR fields ]
62 .RB [ \-f\~\c
63 .IR n ]
64 .RB [ \-i\~\c
65 .IR fields ]
66 .RB [ \-k\~\c
67 .IR field ]
68 .RB [ \-l\~\c
69 .IR range-expression ]
70 .RB [ \-p\~\c
71 .IR database-file ]
72 .RB [ \-s\~\c
73 .IR fields ]
74 .RB [ \-t\~\c
75 .IR n ]
76 .RI [ file\~ .\|.\|.]
77 .YS
78 .
79 .
80 .SY \%refer
81 .B \-\-help
82 .YS
83 .
84 .
85 .SY \%refer
86 .B \-v
87 .
88 .SY \%refer
89 .B \-\-version
90 .YS
91 .
92 .
93 .\" ====================================================================
94 .SH Description
95 .\" ====================================================================
96 .
97 The GNU implementation of
98 .I \%refer \" generic
99 is part of the
100 .MR groff 1
101 document formatting system.
102 .
103 .I \%refer
104 is a
105 .MR \%troff 1
106 preprocessor that prepares bibilographic citations by looking up
107 keywords specified in a
108 .MR roff 7
109 input document,
110 obviating the need to type such annotations,
111 and permitting the citation style in formatted output to be altered
112 independently and systematically.
113 .
114 It copies the contents of each
115 .I file
116 to the standard output stream,
117 except that it interprets lines between
118 .B .[
119 and
120 .B .]\&
121 as citations to be translated into
122 .I groff
123 input,
124 and lines between
125 .B .R1
126 and
127 .B .R2
128 as instructions regarding how citations are to be processed.
129 .
130 Normally,
131 .I \%refer
132 is not executed directly by the user,
133 but invoked by specifying the
134 .B \-R
135 option to
136 .MR groff 1 .
137 .
138 If no
139 .I file
140 operands are given on the command line,
141 or if
142 .I file
143 is
144 .RB \[lq] \- \[rq],
145 the standard input stream is read.
146 .
147 .
148 .LP
149 Each citation specifies a reference.
150 .
151 The citation can specify a reference that is contained in a
152 bibliographic database by giving a set of keywords that only that
153 reference contains.
154 .
155 Alternatively it can specify a reference by supplying a database record
156 in the citation.
157 .
158 A combination of these alternatives is also possible.
159 .
160 .
161 .LP
162 For each citation,
163 .I \%refer
164 can produce a mark in the text.
165 .
166 This mark consists of some label which can be separated from the text
167 and from other labels in various ways.
168 .
169 For each reference it also outputs
170 .MR groff 7
171 language commands that can be used by a macro package to produce a
172 formatted reference for each citation.
173 .
174 The output of
175 .I \%refer
176 must therefore be processed using a suitable macro package,
177 such as
178 .\" .IR man ,
179 .IR me ,
180 .IR mm ,
181 .IR mom ,
182 or
183 .IR ms .
184 .
185 The commands to format a citation's reference can be output immediately
186 after the citation,
187 or the references may be accumulated,
188 and the commands output at some later point.
189 .
190 If the references are accumulated,
191 then multiple citations of the same reference will produce a single
192 formatted reference.
193 .
194 .
195 .LP
196 The interpretation of lines between
197 .B .R1
198 and
199 .B .R2
200 as prepreocessor commands is a feature of GNU
201 .IR \%refer . \" GNU
202 .
203 Documents making use of this feature can still be processed by AT&T
204 .I \%refer \" AT&T
205 just by adding the lines
206 .
207 .RS
208 .EX
209 \&.de R1
210 \&.ig R2
211 \&..
212 .EE
213 .RE
214 .
215 to the beginning of the document.
216 .
217 This will cause
218 .MR \%troff 1
219 to ignore everything between
220 .B .R1
221 and
222 .BR .R2 .
223 .
224 The effect of some commands can also be achieved by options.
225 .
226 These options are supported mainly for compatibility with AT&T
227 .IR \%refer . \" AT&T
228 .
229 It is usually more convenient to use commands.
230 .
231 .
232 .LP
233 .I \%refer
234 generates
235 .B .lf
236 requests so that file names and line numbers in messages produced by
237 commands that read
238 .I \%refer
239 output will be correct;
240 it also interprets lines beginning with
241 .B .lf
242 so that file names and line numbers in the messages and
243 .B .lf
244 lines that it produces will be accurate even if the input has been
245 preprocessed by a command such as
246 .MR \%soelim 1 .
247 .
248 .
249 .\" ====================================================================
250 .SS "Bibliographic databases"
251 .\" ====================================================================
252 .
253 The bibliographic database is a text file consisting of records
254 separated by one or more blank lines.
255 .
256 Within each record fields start with a
257 .B %
258 at the beginning of a line.
259 .
260 Each field has a one character name that immediately follows the
261 .BR % .
262 It is best to use only upper and lower case letters for the names
263 of fields.
264 .
265 The name of the field should be followed by exactly one space,
266 and then by the contents of the field.
267 .
268 Empty fields are ignored.
269 .
270 The conventional meaning of each field is as follows:
271 .
272 .
273 .TP
274 .B %A
275 The name of an author.
276 .
277 If the name contains a suffix such as \[lq]Jr.\&\[rq],
278 it should be separated from the last name by a comma.
279 .
280 There can be multiple occurrences of the
281 .B %A
282 field.
283 .
284 The order is significant.
285 .
286 It is a good idea always to supply an
287 .B %A
288 field or a
289 .B %Q
290 field.
291 .
292 .
293 .TP
294 .B %B
295 For an article that is part of a book,
296 the title of the book.
297 .
298 .
299 .TP
300 .B %C
301 The place (city) of publication.
302 .
303 .
304 .TP
305 .B %D
306 The date of publication.
307 .
308 The year should be specified in full.
309 .
310 If the month is specified,
311 the name rather than the number of the month should be used,
312 but only the first three letters are required.
313 .
314 It is a good idea always to supply a
315 .B %D
316 field;
317 if the date is unknown,
318 a value such as
319 .B in press
320 or
321 .B unknown
322 can be used.
323 .
324 .
325 .TP
326 .B %E
327 For an article that is part of a book,
328 the name of an editor of the book.
329 .
330 Where the work has editors and no authors,
331 the names of the editors should be given as
332 .B %A
333 fields and
334 .RB \[lq] ,\~(ed.)\& \[rq]
335 or
336 .RB \[lq] ,\~(eds.)\& \[rq]
337 should be appended to the last author.
338 .
339 .
340 .TP
341 .B %G
342 U.S. government ordering number.
343 .
344 .
345 .TP
346 .B %I
347 The publisher (issuer).
348 .
349 .
350 .TP
351 .B %J
352 For an article in a journal,
353 the name of the journal.
354 .
355 .
356 .TP
357 .B %K
358 Keywords to be used for searching.
359 .
360 .
361 .TP
362 .B %L
363 Label.
364 .
365 .
366 .TP
367 .B %N
368 Journal issue number.
369 .
370 .
371 .TP
372 .B %O
373 Other information.
374 .
375 This is usually printed at the end of the reference.
376 .
377 .
378 .TP
379 .B %P
380 Page number.
381 .
382 A range of pages can be specified as
383 .IB m \- \c
384 .IR n .
385 .
386 .
387 .TP
388 .B %Q
389 The name of the author,
390 if the author is not a person.
391 .
392 This will only be used if there are no
393 .B %A
394 fields.
395 .
396 There can only be one
397 .B %Q
398 field.
399 .
400 .
401 .TP
402 .B %R
403 Technical report number.
404 .
405 .
406 .TP
407 .B %S
408 Series name.
409 .
410 .
411 .TP
412 .B %T
413 Title.
414 .
415 For an article in a book or journal,
416 this should be the title of the article.
417 .
418 .
419 .TP
420 .B %V
421 Volume number of the journal or book.
422 .
423 .
424 .TP
425 .B %X
426 Annotation.
427 .
428 .
429 .LP
430 For all fields except
431 .B %A
432 and
433 .BR %E ,
434 if there is more than one occurrence of a particular field in a record,
435 only the last such field will be used.
436 .
437 .
438 .P
439 If accent strings are used,
440 they should follow the character to be accented.
441 .
442 This means that an
443 .I ms
444 document must call the
445 .B .AM
446 macro when it initializes.
447 .
448 Accent strings should not be quoted:
449 use one
450 .B \e
451 rather than two.
452 .
453 Accent strings are an obsolescent feature of the
454 .I me
455 and
456 .I ms
457 macro packages;
458 modern documents should use
459 .I groff
460 special character escape sequences instead;
461 see
462 .MR groff_char 7 .
463 .
464 .
465 .\" ====================================================================
466 .SS Citations
467 .\" ====================================================================
468 .
469 Citations have a characteristic format.
470 .
471 .RS
472 .EX
473 .BI .[ opening-text
474 .I flags keywords
475 .I fields
476 .BI .] closing-text
477 .EE
478 .RE
479 .
480 .
481 .LP
482 The
483 .IR opening-text ,
484 .IR closing-text ,
485 and
486 .I flags
487 components are optional.
488 .
489 Only one of the
490 .I keywords
491 and
492 .I fields
493 components need be specified.
494 .
495 .
496 .LP
497 The
498 .I keywords
499 component says to search the bibliographic databases for a reference
500 that contains all the words in
501 .IR keywords .
502 .
503 It is an error if more than one reference is found.
504 .
505 .
506 .LP
507 The
508 .I fields
509 components specifies additional fields to replace or supplement those
510 specified in the reference.
511 .
512 When references are being accumulated and the
513 .I keywords
514 component is non-empty,
515 then additional fields should be specified only on the first occasion
516 that a particular reference is cited,
517 and will apply to all citations of that reference.
518 .
519 .
520 .br
521 .ne 2v
522 .LP
523 The
524 .I opening-text
525 and
526 .I closing-text
527 components specify strings to be used to bracket the label instead of
528 those in the
529 .B \%bracket\-label
530 command.
531 .
532 If either of these components is non-empty,
533 the strings specified in the
534 .B \%bracket\-label
535 command will not be used;
536 this behavior can be altered using the
537 .B [
538 and
539 .B ]
540 flags.
541 .
542 Leading and trailing spaces are significant for these components.
543 .
544 .
545 .LP
546 The
547 .I flags
548 component is a list of non-alphanumeric characters each of which
549 modifies the treatment of this particular citation.
550 .
551 AT&T
552 .I \%refer \" AT&T
553 will treat these flags as part of the keywords and so will ignore them
554 since they are non-alphanumeric.
555 .
556 The following flags are currently recognized.
557 .
558 .
559 .TP
560 .B #
561 Use the label specified by the
562 .B \%short\-label
563 command,
564 instead of that specified by the
565 .B \%label
566 command.
567 .
568 If no short label has been specified,
569 the normal label will be used.
570 .
571 Typically the short label is used with author-date labels and consists
572 of only the date and possibly a disambiguating letter;
573 the
574 .RB \[lq] # \[rq]
575 is supposed to be suggestive of a numeric type of label.
576 .
577 .
578 .TP
579 .B [
580 Precede
581 .I opening-text
582 with the first string specified in the
583 .B \%bracket\-label
584 command.
585 .
586 .
587 .TP
588 .B ]
589 Follow
590 .I closing-text
591 with the second string specified in the
592 .B \%bracket\-label
593 command.
594 .
595 .
596 .LP
597 An advantage of using the
598 .B [
599 and
600 .B ]
601 flags rather than including the brackets in
602 .I opening-text
603 and
604 .I closing-text
605 is that
606 .
607 you can change the style of bracket used in the document just by
608 changing the
609 .B \%bracket\-label
610 command.
611 .
612 Another is that sorting and merging of citations will not necessarily be
613 inhibited if the flags are used.
614 .
615 .
616 .LP
617 If a label is to be inserted into the text,
618 it will be attached to the line preceding the
619 .B .[
620 line.
621 .
622 If there is no such line,
623 then an extra line will be inserted before the
624 .B .[
625 line and a warning will be given.
626 .
627 .
628 .LP
629 There is no special notation for making a citation to multiple
630 references.
631 .
632 Just use a sequence of citations,
633 one for each reference.
634 .
635 Don't put anything between the citations.
636 .
637 The labels for all the citations will be attached to the line preceding
638 the first citation.
639 .
640 The labels may also be sorted or merged.
641 .
642 See the description of the
643 .B <>
644 label expression,
645 and of the
646 .B \%sort\-adjacent\-labels
647 and
648 .B \%abbreviate\-label\-ranges
649 commands.
650 .
651 A label will not be merged if its citation has a non-empty
652 .I opening-text
653 or
654 .IR closing-text .
655 .
656 However,
657 the labels for a citation using the
658 .B ]
659 flag and without any
660 .I closing-text
661 immediately followed by a citation using the
662 .B [
663 flag and without any
664 .I opening-text
665 may be sorted and merged
666 even though the first citation's
667 .I opening-text
668 or the second citation's
669 .I closing-text
670 is non-empty.
671 .
672 (If you wish to prevent this,
673 use the dummy character escape sequence
674 .B \[rs]&
675 as the first citation's
676 .IR closing-text .)
677 .
678 .
679 .\" ====================================================================
680 .SS Commands
681 .\" ====================================================================
682 .
683 Commands are contained between lines starting with
684 .B .R1
685 and
686 .BR .R2 .
687 .
688 Recognition of these lines can be prevented by the
689 .B \-R
690 option.
691 .
692 When a
693 .B .R1
694 line is recognized any accumulated references are flushed out.
695 .
696 Neither
697 .B .R1
698 nor
699 .B .R2
700 lines,
701 nor anything between them,
702 is output.
703 .
704 .
705 .P
706 Commands are separated by newlines or semicolons.
707 .
708 A number sign
709 .RB ( # )
710 introduces a comment that extends to the end of the line,
711 but does not conceal the newline.
712 .
713 Each command is broken up into words.
714 .
715 Words are separated by spaces or tabs.
716 .
717 A word that begins with a (neutral) double quote
718 .RB ( \[dq] )
719 extends to the next double quote that is not followed by another double
720 quote.
721 .
722 If there is no such double quote,
723 the word extends to the end of the line.
724 .
725 Pairs of double quotes in a word beginning with a double quote collapse
726 to one double quote.
727 .
728 Neither a number sign nor a semicolon is recognized inside double
729 quotes.
730 .
731 A line can be continued by ending it with a backslash
732 .RB \[lq] \[rs] \[rq];
733 this works everywhere except after a number sign.
734 .
735 .
736 .LP
737 .ds n \fR*\fP\"
738 Each command
739 .I name
740 that is marked with \*n has an associated negative command
741 .BI no\- name
742 that undoes the effect of
743 .IR name .
744 .
745 For example,
746 the
747 .B no\-sort
748 command specifies that references should not be sorted.
749 .
750 The negative commands take no arguments.
751 .
752 .
753 .LP
754 In the following description each argument must be a single word;
755 .I field
756 is used for a single upper or lower case letter naming a field;
757 .I fields
758 is used for a sequence of such letters;
759 .I m
760 and
761 .I n
762 are used for a non-negative numbers;
763 .I string
764 is used for an arbitrary string;
765 .I file
766 is used for the name of a file.
767 .
768 .
769 .TP
770 .BI abbreviate\*n\~ fields\~string1\~string2\~string3\~string4
771 Abbreviate the first names of
772 .IR fields .
773 .
774 An initial letter will be separated from another initial letter by
775 .IR string1 ,
776 from the last name by
777 .IR string2 ,
778 and from anything else
779 (such as \[lq]von\[rq] or \[lq]de\[rq])
780 by
781 .IR string3 .
782 .
783 These default to a period followed by a space.
784 .
785 In a hyphenated first name,
786 the initial of the first part of the name will be separated from the
787 hyphen by
788 .IR string4 ;
789 this defaults to a period.
790 .
791 No attempt is made to handle any ambiguities that might
792 result from abbreviation.
793 .
794 Names are abbreviated before sorting and before label construction.
795 .
796 .
797 .TP
798 .BI abbreviate\-label\-ranges\*n\~ string
799 .
800 Three or more adjacent labels that refer to consecutive references
801 will be abbreviated to a label consisting of the first label,
802 followed by
803 .IR string ,
804 followed by the last label.
805 .
806 This is mainly useful with numeric labels.
807 .
808 If
809 .I string
810 is omitted,
811 it defaults to
812 .RB \[lq] \- \[rq].
813 .
814 .
815 .TP
816 .B accumulate\*n
817 Accumulate references instead of writing out each reference
818 as it is encountered.
819 .
820 Accumulated references will be written out whenever a reference
821 of the form
822 .
823 .RS
824 .RS
825 .EX
826 .B .[
827 .B $LIST$
828 .B .]
829 .EE
830 .RE
831 .
832 is encountered,
833 after all input files have been processed,
834 and whenever a
835 .B .R1
836 line is recognized.
837 .RE
838 .
839 .
840 .TP
841 .BI annotate\*n\~ "field string"
842 .I field
843 is an annotation;
844 print it at the end of the reference as a paragraph preceded by the line
845 .
846 .RS
847 .IP
848 .BI . string
849 .
850 .
851 .LP
852 If
853 .I string
854 is omitted,
855 it will default to
856 .BR AP ;
857 if
858 .I field
859 is also omitted it will default to
860 .BR X .
861 .
862 Only one field can be an annotation.
863 .RE
864 .
865 .
866 .TP
867 .BI articles\~ string\~\c
868 \&.\|.\|.
869 Each
870 .I string
871 is a definite or indefinite article,
872 and should be ignored at the beginning of
873 .B T
874 fields when sorting.
875 .
876 Initially,
877 \[lq]a\[rq],
878 \[lq]an\[rq],
879 and
880 \[lq]the\[rq] are recognized as articles.
881 .
882 .
883 .TP
884 .BI bibliography\~ file\~\c
885 \&.\|.\|.
886 .
887 Write out all the references contained in each bibliographic database
888 .IR file .
889 .
890 This command should come last in an
891 .BR .R1 / .R2
892 block.
893 .
894 .
895 .TP
896 .BI bracket\-label\~ "string1 string2 string3"
897 In the text,
898 bracket each label with
899 .I string1
900 and
901 .IR string2 .
902 .
903 An occurrence of
904 .I string2
905 immediately followed by
906 .I string1
907 will be turned into
908 .IR string3 .
909 .
910 The default behavior is as follows.
911 .
912 .RS \" RS twice to get inboard of the tagged paragraph indentation.
913 .RS
914 .EX
915 .B bracket\-label \e*([. \e*(.] \[dq], \[dq]
916 .EE
917 .RE
918 .RE
919 .
920 .
921 .TP
922 .BI capitalize\~ fields
923 Convert
924 .I fields
925 to caps and small caps.
926 .
927 .
928 .TP
929 .B compatible\*n
930 Recognize
931 .B .R1
932 and
933 .B .R2
934 even when followed by a character other than space or newline.
935 .
936 .
937 .TP
938 .BI database\~ file\~\c
939 \&.\|.\|.
940 Search each bibliographic database
941 .IR file .
942 .
943 For each
944 .IR file ,
945 if an index
946 .RI file \%.i
947 created by
948 .MR \%indxbib 1
949 exists,
950 then it will be searched instead;
951 each index can cover multiple databases.
952 .
953 .
954 .TP
955 .BI date\-as\-label\*n\~ string
956 .I string
957 is a label expression that specifies a string with which to replace the
958 .B D
959 field after constructing the label.
960 .
961 See subsection \[lq]Label expressions\[rq] below for a description of
962 label expressions.
963 .
964 This command is useful if you do not want explicit labels in the
965 reference list,
966 but instead want to handle any necessary disambiguation by qualifying
967 the date in some way.
968 .
969 The label used in the text would typically be some combination of the
970 author and date.
971 .
972 In most cases you should also use the
973 .B \%no\-label\-in\-reference
974 command.
975 .
976 For example,
977 .
978 .RS \" RS twice to get inboard of the tagged paragraph indentation.
979 .RS
980 .EX
981 .B date\-as\-label D.+yD.y%a*D.\-y
982 .EE
983 .RE
984 .
985 would attach a disambiguating letter to the year part of the
986 .B D
987 field in the reference.
988 .RE
989 .
990 .
991 .TP
992 .B default\-database\*n
993 The default database should be searched.
994 .
995 This is the default behavior,
996 so the negative version of this command is more useful.
997 .
998 .I \%refer
999 determines whether the default database should be searched
1000 on the first occasion that it needs to do a search.
1001 .
1002 Thus a
1003 .B \%no\-default\-database
1004 command must be given before then,
1005 in order to be effective.
1006 .
1007 .
1008 .TP
1009 .BI discard\*n\~ fields
1010 When the reference is read,
1011 .I fields
1012 should be discarded;
1013 no string definitions for
1014 .I fields
1015 will be output.
1016 .
1017 Initially,
1018 .I fields
1019 are
1020 .BR XYZ .
1021 .
1022 .
1023 .TP
1024 .BI et\-al\*n\~ "string m n"
1025 Control use of
1026 .B et al.\&
1027 in the evaluation of
1028 .B @
1029 expressions in label expressions.
1030 .
1031 If the number of authors needed to make the author sequence unambiguous
1032 is
1033 .I u
1034 and the total number of authors is
1035 .I t
1036 then the last
1037 .IR t \|\-\| u
1038 authors will be replaced by
1039 .I string
1040 provided that
1041 .IR t \|\-\| u
1042 is not less than
1043 .I m
1044 and
1045 .I t
1046 is not less than
1047 .IR n .
1048 .
1049 The default behavior is as follows.
1050 .
1051 .RS \" RS twice to get inboard of the tagged paragraph indentation.
1052 .RS
1053 .EX
1054 .B et\-al \[dq] et al\[dq] 2 3
1055 .EE
1056 .RE
1057 .
1058 Note the absence of a dot from the end of the abbreviation,
1059 which is arguably not correct.
1060 .
1061 .RI ( "Et al" [.]
1062 is short for
1063 .IR "et alli" ,
1064 as
1065 .I etc.\&
1066 is short for
1067 .IR "et cetera".)
1068 .RE
1069 .
1070 .
1071 .TP
1072 .BI include\~ file
1073 Include
1074 .I file
1075 and interpret the contents as commands.
1076 .
1077 .
1078 .TP
1079 .BI join\-authors\~ "string1 string2 string3"
1080 Join multiple authors together with
1081 .IR string s.
1082 .
1083 When there are exactly two authors,
1084 they will be joined with
1085 .IR string1 .
1086 .
1087 When there are more than two authors,
1088 all but the last two will be joined with
1089 .IR string2 ,
1090 and the last two authors will be joined with
1091 .IR string3 .
1092 .
1093 If
1094 .I string3
1095 is omitted,
1096 it will default to
1097 .IR string1 ;
1098 if
1099 .I string2
1100 is also omitted it will also default to
1101 .IR string1 .
1102 .
1103 For example,
1104 .
1105 .RS
1106 .RS
1107 .EX
1108 join\-authors \[dq] and \[dq] \[dq], \[dq] \[dq], and \[dq]
1109 .EE
1110 .RE
1111 .
1112 will restore the default method for joining authors.
1113 .RE
1114 .
1115 .
1116 .TP
1117 .B label\-in\-reference\*n
1118 When outputting the reference,
1119 define the string
1120 .B [F
1121 to be the reference's label.
1122 .
1123 This is the default behavior,
1124 so the negative version of this command is more useful.
1125 .
1126 .
1127 .TP
1128 .B label\-in\-text\*n
1129 For each reference output a label in the text.
1130 .
1131 The label will be separated from the surrounding text as described in
1132 the
1133 .B \%bracket\-label
1134 command.
1135 .
1136 This is the default behavior,
1137 so the negative version of this command is more useful.
1138 .
1139 .
1140 .TP
1141 .BI label\~ string
1142 .I string
1143 is a label expression describing how to label each reference.
1144 .
1145 .
1146 .TP
1147 .BI separate\-label\-second\-parts\~ string
1148 When merging two-part labels,
1149 separate the second part of the second label from the first label with
1150 .IR string .
1151 .
1152 See the description of the
1153 .B <>
1154 label expression.
1155 .
1156 .
1157 .TP
1158 .B move\-punctuation\*n
1159 In the text,
1160 move any punctuation at the end of line past the label.
1161 .
1162 It is usually a good idea to give this command unless you are using
1163 superscripted numbers as labels.
1164 .
1165 .
1166 .TP
1167 .BI reverse\*n\~ string
1168 Reverse the fields whose names
1169 are in
1170 .IR string .
1171 .
1172 Each field name can be followed by a number which says how many such
1173 fields should be reversed.
1174 .
1175 If no number is given for a field,
1176 all such fields will be reversed.
1177 .
1178 .
1179 .TP
1180 .BI search\-ignore\*n\~ fields
1181 While searching for keys in databases for which no index exists,
1182 ignore the contents of
1183 .IR fields .
1184 .
1185 Initially,
1186 fields
1187 .B XYZ
1188 are ignored.
1189 .
1190 .
1191 .TP
1192 .BI search\-truncate\*n\~ n
1193 Only require the first
1194 .I n
1195 characters of keys to be given.
1196 .
1197 In effect when searching for a given key words in the database are
1198 truncated to the maximum of
1199 .I n
1200 and the length of the key.
1201 .
1202 Initially,
1203 .I n
1204 is\~6.
1205 .
1206 .
1207 .TP
1208 .BI short\-label\*n\~ string
1209 .I string
1210 is a label expression that specifies an alternative
1211 (usually shorter)
1212 style of label.
1213 .
1214 This is used when the
1215 .B #
1216 flag is given in the citation.
1217 .
1218 When using author-date style labels,
1219 the identity of the author or authors is sometimes clear from the
1220 context,
1221 and so it may be desirable to omit the author or authors from the label.
1222 .
1223 The
1224 .B \%short\-label
1225 command will typically be used to specify a label containing just
1226 a date and possibly a disambiguating letter.
1227 .
1228 .
1229 .TP
1230 .BI sort\*n\~ string
1231 Sort references according to
1232 .IR string .
1233 .
1234 References will automatically be accumulated.
1235 .
1236 .I string
1237 should be a list of field names,
1238 each followed by a number,
1239 indicating how many fields with the name should be used for sorting.
1240 .
1241 .RB \[lq] + \[rq]
1242 can be used to indicate that all the fields with the name should be
1243 used.
1244 .
1245 Also
1246 .B .\&
1247 can be used to indicate the references should be sorted using the
1248 (tentative) label.
1249 .
1250 (Subsection \[lq]Label expressions\[rq] below describes the concept of a
1251 tentative label.)
1252 .
1253 .
1254 .TP
1255 .B sort\-adjacent\-labels\*n
1256 Sort labels that are adjacent in the text according to their position
1257 in the reference list.
1258 .
1259 This command should usually be given if the
1260 .B \%abbreviate\-label\-ranges
1261 command has been given,
1262 or if the label expression contains a
1263 .B <>
1264 expression.
1265 .
1266 This will have no effect unless references are being accumulated.
1267 .
1268 .
1269 .\" ====================================================================
1270 .SS "Label expressions"
1271 .\" ====================================================================
1272 .
1273 Label expressions can be evaluated both normally and tentatively.
1274 .
1275 The result of normal evaluation is used for output.
1276 .
1277 The result of tentative evaluation,
1278 called the
1279 .IR "tentative label" ,
1280 is used to gather the information that normal evaluation needs to
1281 disambiguate the label.
1282 .
1283 Label expressions specified by the
1284 .B \%date\-as\-label
1285 and
1286 .B \%short\-label
1287 commands are not evaluated tentatively.
1288 .
1289 Normal and tentative evaluation are the same for all types of expression
1290 other than
1291 .BR @ ,
1292 .BR * ,
1293 and
1294 .B %
1295 expressions.
1296 .
1297 The description below applies to normal evaluation,
1298 except where otherwise specified.
1299 .
1300 .
1301 .TP
1302 .I field
1303 .TQ
1304 .I field\~n
1305 The
1306 .IR n -th
1307 part of
1308 .IR field .
1309 .
1310 If
1311 .I n
1312 is omitted,
1313 it defaults to\~1.
1314 .
1315 .
1316 .TP
1317 .BI \[aq] string \[aq]
1318 The characters in
1319 .I string
1320 literally.
1321 .
1322 .
1323 .TP
1324 .B @
1325 All the authors joined as specified by the
1326 .B \%join\-authors
1327 command.
1328 .
1329 The whole of each author's name will be used.
1330 .
1331 However,
1332 if the references are sorted by author
1333 (that is,
1334 the sort specification starts with
1335 .RB \[lq] A+ \[rq]),
1336 then authors' last names will be used instead,
1337 provided that this does not introduce ambiguity,
1338 and also an initial subsequence of the authors may be used instead of
1339 all the authors,
1340 again provided that this does not introduce ambiguity.
1341 .
1342 The use of only the last name for the
1343 .IR i -th
1344 author of some reference
1345 is considered to be ambiguous if
1346 there is some other reference,
1347 such that the first
1348 .IR i \|\-\|1
1349 authors of the references are the same,
1350 the
1351 .IR i -th
1352 authors are not the same,
1353 but the
1354 .IR i -th
1355 authors last names are the same.
1356 .
1357 A proper initial subsequence of the sequence of authors for some
1358 reference is considered to be ambiguous if there is a reference with
1359 some other sequence of authors which also has that subsequence as a
1360 proper initial subsequence.
1361 .
1362 When an initial subsequence of authors is used,
1363 the remaining authors are replaced by the string specified by the
1364 .B \%et\-al
1365 command;
1366 this command may also specify additional requirements that must be
1367 met before an initial subsequence can be used.
1368 .
1369 .B @
1370 tentatively evaluates to a canonical representation of the authors,
1371 such that authors that compare equally for sorting purpose will have
1372 the same representation.
1373 .
1374 .
1375 .TP
1376 .BI % n
1377 .TQ
1378 .B %a
1379 .TQ
1380 .B %A
1381 .TQ
1382 .B %i
1383 .TQ
1384 .B %I
1385 The serial number of the reference formatted according to the
1386 character following the
1387 .BR % .
1388 The serial number of a reference is\~1 plus the number of earlier
1389 references with same tentative label as this reference.
1390 .
1391 These expressions tentatively evaluate to an empty string.
1392 .
1393 .TP
1394 .IB expr *
1395 If there is another reference with the same tentative label as this
1396 reference,
1397 then
1398 .IR expr ,
1399 otherwise an empty string.
1400 .
1401 It tentatively evaluates to an empty string.
1402 .
1403 .
1404 .TP
1405 .IB expr + n
1406 .TQ
1407 .IB expr \- n
1408 The first
1409 .RB ( + )
1410 or last
1411 .RB ( \- )
1412 .I n
1413 upper or lower case letters or digits of
1414 .IR expr .
1415 .
1416 .I roff
1417 special characters
1418 (such as
1419 .BR \e(\[aq]a )
1420 count as a single letter.
1421 .
1422 Accent strings are retained but do not count towards the total.
1423 .
1424 .
1425 .TP
1426 .IB expr .l
1427 .I expr
1428 converted to lowercase.
1429 .
1430 .
1431 .TP
1432 .IB expr .u
1433 .I expr
1434 converted to uppercase.
1435 .
1436 .
1437 .TP
1438 .IB expr .c
1439 .I expr
1440 converted to caps and small caps.
1441 .
1442 .
1443 .TP
1444 .IB expr .r
1445 .I expr
1446 reversed so that the last name is first.
1447 .
1448 .
1449 .TP
1450 .IB expr .a
1451 .I expr
1452 with first names abbreviated.
1453 .
1454 Fields specified in the
1455 .B \%abbreviate
1456 command are abbreviated before any labels are evaluated.
1457 .
1458 Thus
1459 .B .a
1460 is useful only when you want a field to be abbreviated in a label
1461 but not in a reference.
1462 .
1463 .
1464 .TP
1465 .IB expr .y
1466 The year part of
1467 .IR expr .
1468 .
1469 .
1470 .TP
1471 .IB expr .+y
1472 The part of
1473 .I expr
1474 before the year,
1475 or the whole of
1476 .I expr
1477 if it does not contain a year.
1478 .
1479 .
1480 .TP
1481 .IB expr .\-y
1482 The part of
1483 .I expr
1484 after the year,
1485 or an empty string if
1486 .I expr
1487 does not contain a year.
1488 .
1489 .
1490 .TP
1491 .IB expr .n
1492 The last name part of
1493 .IR expr .
1494 .
1495 .
1496 .TP
1497 .IB expr1 \[ti] expr2
1498 .I expr1
1499 except that if the last character of
1500 .I expr1
1501 is
1502 .B \-
1503 then it will be replaced by
1504 .IR expr2 .
1505 .
1506 .
1507 .TP
1508 .I expr1 expr2
1509 The concatenation of
1510 .I expr1
1511 and
1512 .IR expr2 .
1513 .
1514 .
1515 .TP
1516 .IB expr1 | expr2
1517 If
1518 .I expr1
1519 is non-empty then
1520 .I expr1
1521 otherwise
1522 .IR expr2 .
1523 .
1524 .
1525 .TP
1526 .IB expr1 & expr2
1527 If
1528 .I expr1
1529 is non-empty
1530 then
1531 .I expr2
1532 otherwise an empty string.
1533 .
1534 .
1535 .TP
1536 .IB expr1 ? expr2 : expr3
1537 If
1538 .I expr1
1539 is non-empty
1540 then
1541 .I expr2
1542 otherwise
1543 .IR expr3 .
1544 .
1545 .
1546 .TP
1547 .BI < expr >
1548 The label is in two parts,
1549 which are separated by
1550 .IR expr .
1551 .
1552 Two adjacent two-part labels which have the same first part will be
1553 merged by appending the second part of the second label onto the first
1554 label separated by the string specified in the
1555 .B \%separate\-label\-second\-parts
1556 command
1557 (initially,
1558 a comma followed by a space);
1559 the resulting label will also be a two-part label with the same first
1560 part as before merging,
1561 and so additional labels can be merged into it.
1562 .
1563 It is permissible for the first part to be empty;
1564 this may be desirable for expressions used in the
1565 .B \%short\-label
1566 command.
1567 .
1568 .
1569 .TP
1570 .BI ( expr )
1571 The same as
1572 .IR expr .
1573 .
1574 Used for grouping.
1575 .
1576 .
1577 .LP
1578 The above expressions are listed in order of precedence
1579 (highest first);
1580 .B &
1581 and
1582 .B |
1583 have the same precedence.
1584 .
1585 .
1586 .\" ====================================================================
1587 .SS "Macro interface"
1588 .\" ====================================================================
1589 .
1590 Each reference starts with a call to the macro
1591 .BR ]\- .
1592 .
1593 The string
1594 .B [F
1595 will be defined to be the label for this reference,
1596 unless the
1597 .B \%no\-label\-in\-reference
1598 command has been given.
1599 .
1600 There then follows a series of string definitions,
1601 one for each field:
1602 string
1603 .BI [ X
1604 corresponds to field
1605 .IR X .
1606 .
1607 The register
1608 .B [P
1609 is set to\~1 if the
1610 .B P
1611 field contains a range of pages.
1612 .
1613 The
1614 .BR [T ,
1615 .B [A
1616 and
1617 .B [O
1618 registers are set to\~1 according as the
1619 .BR T ,
1620 .B A
1621 and
1622 .B O
1623 fields end with any of
1624 .B .?!\&
1625 (an end-of-sentence character).
1626 .
1627 The
1628 .B [E
1629 register will be set to\~1 if the
1630 .B [E
1631 string contains more than one name.
1632 .
1633 The reference is followed by a call to the
1634 .B ][
1635 macro.
1636 .
1637 The first argument to this macro gives a number representing
1638 the type of the reference.
1639 .
1640 If a reference contains a
1641 .B J
1642 field,
1643 it will be classified as type\~1,
1644 otherwise if it contains a
1645 .B B
1646 field,
1647 it will be type\~3,
1648 otherwise if it contains a
1649 .B G
1650 or
1651 .B R
1652 field it will be type\~4,
1653 otherwise if it contains an
1654 .B I
1655 field it will be type\~2,
1656 otherwise it will be type\~0.
1657 .
1658 The second argument is a symbolic name for the type:
1659 .BR other ,
1660 .BR \%journal\-article ,
1661 .BR book ,
1662 .BR \%article\-in\-book ,
1663 or
1664 .BR \%tech\-report .
1665 .
1666 Groups of references that have been accumulated or are produced by the
1667 .B \%bibliography
1668 command are preceded by a call to the
1669 .B ]<
1670 macro and followed by a call to the
1671 .B ]>
1672 macro.
1673 .
1674 .
1675 .br
1676 .ne 4v
1677 .\" ====================================================================
1678 .SH Options
1679 .\" ====================================================================
1680 .
1681 .B \-\-help
1682 displays a usage message,
1683 while
1684 .B \-v
1685 and
1686 .B \-\-version
1687 show version information;
1688 all exit afterward.
1689 .
1690 .
1691 .TP
1692 .B \-R
1693 Don't recognize lines beginning with
1694 .BR .R1 / .R2 .
1695 .
1696 .
1697 .P
1698 Other options are equivalent to
1699 .I \%refer
1700 commands.
1701 .
1702 .
1703 .TP 16n
1704 .BI \-a\~ n
1705 .B reverse
1706 .BI A n
1707 .
1708 .
1709 .TP
1710 .B \-b
1711 .B "\%no\-label\-in\-text; \%no\-label\-in\-reference"
1712 .
1713 .
1714 .TP
1715 .B \-B
1716 See below.
1717 .
1718 .
1719 .TP
1720 .BI \-c\~ fields
1721 .B capitalize
1722 .I fields
1723 .
1724 .
1725 .TP
1726 .B \-C
1727 .B compatible
1728 .
1729 .
1730 .TP
1731 .B \-e
1732 .B accumulate
1733 .
1734 .
1735 .TP
1736 .BI \-f\~ n
1737 .B \%label
1738 .BI % n
1739 .
1740 .
1741 .TP
1742 .BI \-i\~ fields
1743 .B search\-ignore
1744 .I fields
1745 .
1746 .
1747 .TP
1748 .B \-k
1749 .B \%label
1750 .B L\[ti]%a
1751 .
1752 .
1753 .TP
1754 .BI \-k\~ field
1755 .B \%label
1756 .IB field \[ti]%a
1757 .
1758 .
1759 .TP
1760 .B \-l
1761 .B \%label
1762 .B A.nD.y%a
1763 .
1764 .
1765 .TP
1766 .BI \-l\~ m
1767 .B \%label
1768 .BI A.n+ m D.y%a
1769 .
1770 .
1771 .TP
1772 .BI \-l\~, n
1773 .B \%label
1774 .BI A.nD.y\- n %a
1775 .
1776 .
1777 .TP
1778 .BI \-l\~ m , n
1779 .B \%label
1780 .BI A.n+ m D.y\- n %a
1781 .
1782 .
1783 .TP
1784 .B \-n
1785 .B \%no\-default\-database
1786 .
1787 .
1788 .TP
1789 .BI \-p\~ db-file
1790 .B database
1791 .I db-file
1792 .
1793 .
1794 .TP
1795 .B \-P
1796 .B move\-punctuation
1797 .
1798 .
1799 .TP
1800 .BI \-s\~ spec
1801 .B sort
1802 .I spec
1803 .
1804 .
1805 .TP
1806 .B \-S
1807 .B \%label \[dq](A.n|Q) \[aq], \[aq] (D.y|D)\[dq]; \
1808 \%bracket-\%label \[dq]\~(\[dq]\~)\~\[dq];\~\[dq]
1809 .
1810 .
1811 .TP
1812 .BI \-t\~ n
1813 .B search\-truncate
1814 .I n
1815 .
1816 .
1817 .P
1818 The
1819 .B B
1820 option has command equivalents with the addition that the file names
1821 specified on the command line are processed as if they were arguments to
1822 the
1823 .B \%bibliography
1824 command instead of in the normal way.
1825 .
1826 .
1827 .TP 16n
1828 .B \-B
1829 .B "annotate X AP; \%no\-label\-in\-reference"
1830 .
1831 .
1832 .TP
1833 .BI \-B\~ field . macro
1834 .B annotate
1835 .I field
1836 .IB macro ;
1837 .B \%no\-label\-in\-reference
1838 .
1839 .
1840 .\" ====================================================================
1841 .SH Environment
1842 .\" ====================================================================
1843 .
1844 .TP
1845 .I REFER
1846 If set,
1847 overrides the default database.
1848 .
1849 .
1850 .\" ====================================================================
1851 .SH Files
1852 .\" ====================================================================
1853 .
1854 .TP
1855 .I /usr/\:\%dict/\:\%papers/\:\%Ind
1856 Default database.
1857 .
1858 .
1859 .TP
1860 .RI file \%.i
1861 Index files.
1862 .
1863 .
1864 .TP
1865 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:refer\:.tmac
1866 defines macros and strings facilitating integration with macro packages
1867 that wish to support
1868 .IR \%refer .
1869 .
1870 .
1871 .LP
1872 .I \%refer
1873 uses temporary files.
1874 .
1875 See the
1876 .MR groff 1
1877 man page for details of where such files are created.
1878 .
1879 .
1880 .\" ====================================================================
1881 .SH Bugs
1882 .\" ====================================================================
1883 .
1884 In label expressions,
1885 .B <>
1886 expressions are ignored inside
1887 .BI . char
1888 expressions.
1889 .
1890 .
1891 .\" ====================================================================
1892 .SH Examples
1893 .\" ====================================================================
1894 .
1895 We can illustrate the operation of
1896 .I \%refer
1897 with a sample bibliographic database containing one entry and a simple
1898 .I roff
1899 document to cite that entry.
1900 .
1901 .
1902 .P
1903 .RS
1904 .EX
1905 $ \c
1906 .B cat > my\-db\-file
1907 .B %A Daniel P.\[rs]& Friedman
1908 .B %A Matthias Felleisen
1909 .B %C Cambridge, Massachusetts
1910 .B %D 1996
1911 .B %I The MIT Press
1912 .B %T The Little Schemer, Fourth Edition
1913 $ \c
1914 .B refer -p my\-db\-file
1915 .B Read the book
1916 .B .[
1917 .B friedman
1918 .B .]
1919 .B on your summer vacation.
1920 .I <Control+D>
1921 \&.lf 1 \-
1922 Read the book\[rs]*([.1\[rs]*(.]
1923 \&.ds [F 1
1924 \&.]\-
1925 \&.ds [A Daniel P. Friedman and Matthias Felleisen
1926 \&.ds [C Cambridge, Massachusetts
1927 \&.ds [D 1996
1928 \&.ds [I The MIT Press
1929 \&.ds [T The Little Schemer, Fourth Edition
1930 \&.nr [T 0
1931 \&.nr [A 0
1932 \&.][ 2 book
1933 \&.lf 5 \-
1934 on your summer vacation.
1935 .EE
1936 .RE
1937 .
1938 .
1939 .P
1940 The foregoing shows us that
1941 .I \%refer
1942 (a) produces a label \[lq]1\[rq];
1943 (b) brackets that label with interpolations of the
1944 .RB \[lq] [. \[rq]
1945 and
1946 .RB \[lq] .] \[rq]
1947 strings;
1948 (c) calls a macro
1949 .RB \[lq] ]\- \[rq];
1950 (d) defines strings and registers containing the label and bibliographic
1951 data for the reference;
1952 (e) calls a macro
1953 .RB \[lq] ][ \[rq];
1954 and (f) uses the
1955 .B lf
1956 request to restore the line numbers of the original input.
1957 .
1958 As discussed in subsection \[lq]Macro interface\[rq] above,
1959 it is up to the document or a macro package to employ and format this
1960 information usefully.
1961 .
1962 Let us see how we might turn
1963 .MR groff_ms 7
1964 to this task.
1965 .
1966 .
1967 .P
1968 .RS
1969 .EX
1970 $ \c
1971 .B REFER=my\-db\-file groff \-R \-ms
1972 .B .LP
1973 .B Read the book
1974 .B .[
1975 .B friedman
1976 .B .]
1977 .B on your summer vacation.
1978 .B Commentary is available.\[rs]*{*\[rs]*}
1979 .B .FS \[rs]*{*\[rs]*}
1980 .B Space reserved for penetrating insight.
1981 .B .FE
1982 .EE
1983 .RE
1984 .
1985 .
1986 .LP
1987 .IR ms 's
1988 automatic footnote numbering mechanism is not aware of
1989 .IR \%refer 's
1990 label numbering,
1991 so we have manually specified a (superscripted) symbolic footnote for
1992 our non-bibliographic aside.
1993 .
1994 .
1995 .\" ====================================================================
1996 .SH "See also"
1997 .\" ====================================================================
1998 .
1999 \[lq]Some Applications of Inverted Indexes on the Unix System\[rq],
2000 by M.\& E.\& Lesk,
2001 1978,
2002 AT&T Bell Laboratories Computing Science Technical Report No.\& 69.
2003 .
2004 .
2005 .LP
2006 .MR \%indxbib 1 ,
2007 .MR \%lookbib 1 ,
2008 .MR lkbib 1
2009 .
2010 .
2011 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
2012 .cp \n[*groff_refer_1_man_C]
2013 .do rr *groff_refer_1_man_C
2014 .
2015 .
2016 .\" Local Variables:
2017 .\" fill-column: 72
2018 .\" mode: nroff
2019 .\" End:
2020 .\" vim: set filetype=groff textwidth=72: