| blob | 0881657d404471f905e09c1c8c953ae9ce7dbf06 |
1 .ig
2 Copyright (C) 1989-2000, 2001, 2002, 2003, 2004, 2005
3 Free Software Foundation, Inc.
5 Permission is granted to make and distribute verbatim copies of
6 this manual provided the copyright notice and this permission notice
7 are preserved on all copies.
9 Permission is granted to copy and distribute modified versions of this
10 manual under the conditions for verbatim copying, provided that the
11 entire resulting derived work is distributed under the terms of a
12 permission notice identical to this one.
14 Permission is granted to copy and distribute translations of this
15 manual into another language, under the above conditions for modified
16 versions, except that this permission notice may be included in
17 translations approved by the Free Software Foundation instead of in
18 the original English.
19 ..
20 .
21 .
22 .de TQ
23 . br
24 . ns
25 . TP \\$1
26 ..
27 .
28 .
29 .\" Like TP, but if specified indent is more than half
30 .\" the current line-length - indent, use the default indent.
31 .de Tp
32 . ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
33 . el .TP "\\$1"
34 .
35 .
36 ..
37 .\" The BSD man macros can't handle " in arguments to font change macros,
38 .\" so use \(ts instead of ".
39 .tr \(ts"
40 .
41 .
42 .TH @G@REFER @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
43 .
44 .
45 .
46 .SH NAME
47 @g@refer \- preprocess bibliographic references for groff
48 .
49 .
50 .
51 .SH SYNOPSIS
52 .nr a \n(.j
53 .ad l
54 .nr i \n(.i
55 .in +\w'\fB@g@refer 'u
56 .ti \niu
57 .B @g@refer
58 .
59 .de OP
60 . ie \\n(.$-1 .RI "[\ \fB\\$1\fP" "\\$2" "\ ]"
61 . el .RB "[\ " "\\$1" "\ ]"
62 ..
63 .
64 .OP \-benvCPRS
65 .OP \-a n
66 .OP \-c fields
67 .OP \-f n
68 .OP \-i fields
69 .OP \-k field
70 .OP \-l m,n
71 .OP \-p \%filename
72 .OP \-s fields
73 .OP \-t n
74 .OP \-B field.macro
75 .RI [\ \%filename \|.\|.\|.\ ]
76 .br
77 .ad \na
78 .
79 .LP
80 It is possible to have whitespace between a command line option and its
81 parameter.
82 .
83 .
84 .
85 .SH DESCRIPTION
86 This file documents the GNU version of
87 .BR refer ,
88 which is part of the groff document formatting system.
89 .B refer
90 copies the contents of
91 .IR filename \|.\|.\|.\&
92 to the standard output,
93 except that lines between
94 .B .[
95 and
96 .B .]\&
97 are interpreted as citations,
98 and lines between
99 .B .R1
100 and
101 .B .R2
102 are interpreted as commands about how citations are to be processed.
103 .
104 .LP
105 Each citation specifies a reference.
106 The citation can specify a reference that is contained in
107 a bibliographic database by giving a set of keywords
108 that only that reference contains.
109 Alternatively it can specify a reference by supplying a database
110 record in the citation.
111 A combination of these alternatives is also possible.
112 .
113 .LP
114 For each citation,
115 .B refer
116 can produce a mark in the text.
117 This mark consists of some label which can be separated from
118 the text and from other labels in various ways.
119 For each reference it also outputs
120 .B groff
121 commands that can be used by a macro package to produce a formatted
122 reference for each citation.
123 The output of
124 .B refer
125 must therefore be processed using a suitable macro package.
126 The
127 .B \-ms
128 and
129 .B \-me
130 macros are both suitable.
131 The commands to format a citation's reference can be output immediately after
132 the citation,
133 or the references may be accumulated,
134 and the commands output at some later point.
135 If the references are accumulated, then multiple citations of the same
136 reference will produce a single formatted reference.
137 .
138 .LP
139 The interpretation of lines between
140 .B .R1
141 and
142 .B .R2
143 as commands is a new feature of GNU
144 .BR refer .
145 Documents making use of this feature can still be processed by
146 Unix refer just by adding the lines
147 .
148 .RS
149 .LP
150 .nf
151 .ft B
152 \&.de R1
153 \&.ig R2
154 \&..
155 .ft
156 .fi
157 .RE
158 .
159 to the beginning of the document.
160 This will cause
161 .B troff
162 to ignore everything between
163 .B .R1
164 and
165 .BR .R2 .
166 The effect of some commands can also be achieved by options.
167 These options are supported mainly for compatibility with Unix refer.
168 It is usually more convenient to use commands.
169 .
170 .LP
171 .B refer
172 generates
173 .B .lf
174 lines so that filenames and line numbers in messages produced
175 by commands that read
176 .B refer
177 output will be correct;
178 it also interprets lines beginning with
179 .B .lf
180 so that filenames and line numbers in the messages and
181 .B .lf
182 lines that it produces will be accurate even if the input has been
183 preprocessed by a command such as
184 .BR @g@soelim (@MAN1EXT@).
185 .
186 .
187 .
188 .SH OPTIONS
189 .
190 .LP
191 Most options are equivalent to commands
192 (for a description of these commands see the
193 .B Commands
194 subsection):
195 .
196 .nr a \n(.j
197 .ad l
198 .TP
199 .B \-b
200 .B "no-label-in-text; no-label-in-reference"
201 .
202 .TP
203 .B \-e
204 .B accumulate
205 .
206 .TP
207 .B \-n
208 .B no-default-database
209 .
210 .TP
211 .B \-C
212 .B compatible
213 .
214 .TP
215 .B \-P
216 .B move-punctuation
217 .
218 .TP
219 .B \-S
220 .B
221 label\ "(A.n|Q)\ ',\ '\ (D.y|D)"; \%bracket-label\ "\ ("\ )\ ";\ "
222 .
223 .TP
224 .BI \-a n
225 .B reverse
226 .BI A n
227 .
228 .TP
229 .BI \-c fields
230 .B capitalize
231 .I fields
232 .
233 .TP
234 .BI \-f n
235 .B label
236 .BI % n
237 .
238 .TP
239 .BI \-i fields
240 .B search-ignore
241 .I fields
242 .
243 .TP
244 .B \-k
245 .B label
246 .B L\(ti%a
247 .
248 .TP
249 .BI \-k field
250 .B label
251 .IB field \(ti%a
252 .
253 .TP
254 .B \-l
255 .B label
256 .BI A.nD.y%a
257 .
258 .TP
259 .BI \-l m
260 .B label
261 .BI A.n+ m D.y%a
262 .
263 .TP
264 .BI \-l, n
265 .B label
266 .BI A.nD.y\- n %a
267 .
268 .TP
269 .BI \-l m , n
270 .B label
271 .BI A.n+ m D.y\- n %a
272 .
273 .TP
274 .BI \-p filename
275 .B database
276 .I filename
277 .
278 .TP
279 .BI \-s spec
280 .B sort
281 .I spec
282 .
283 .TP
284 .BI \-t n
285 .B search-truncate
286 .I n
287 .ad \na
288 .
289 .LP
290 These options are equivalent to the following commands with the
291 addition that the filenames specified on the command line are
292 processed as if they were arguments to the
293 .B bibliography
294 command instead of in the normal way:
295 .
296 .TP
297 .B \-B
298 .B "annotate X AP; no-label-in-reference"
299 .
300 .TP
301 .BI \-B field . macro
302 .B annotate
303 .I field
304 .IB macro ;
305 .B no-label-in-reference
306 .
307 .LP
308 The following options have no equivalent commands:
309 .
310 .TP
311 .B \-v
312 Print the version number.
313 .
314 .TP
315 .B \-R
316 Don't recognize lines beginning with
317 .BR .R1 / .R2 .
318 .
319 .
320 .
321 .SH USAGE
322 .
323 .
324 .SS Bibliographic databases
325 The bibliographic database is a text file consisting of records
326 separated by one or more blank lines.
327 Within each record fields start with a
328 .B %
329 at the beginning of a line.
330 Each field has a one character name that immediately follows the
331 .BR % .
332 It is best to use only upper and lower case letters for the names
333 of fields.
334 The name of the field should be followed by exactly one space,
335 and then by the contents of the field.
336 Empty fields are ignored.
337 The conventional meaning of each field is as follows:
338 .
339 .TP
340 .B A
341 The name of an author.
342 If the name contains a title such as
343 .B Jr.\&
344 at the end,
345 it should be separated from the last name by a comma.
346 There can be multiple occurrences of the
347 .B A
348 field.
349 The order is significant.
350 It is a good idea always to supply an
351 .B A
352 field or a
353 .B Q
354 field.
355 .
356 .TP
357 .B B
358 For an article that is part of a book, the title of the book.
359 .
360 .TP
361 .B C
362 The place (city) of publication.
363 .
364 .TP
365 .B D
366 The date of publication.
367 The year should be specified in full.
368 If the month is specified, the name rather than the number of the month
369 should be used, but only the first three letters are required.
370 It is a good idea always to supply a
371 .B D
372 field;
373 if the date is unknown, a value such as
374 .B in press
375 or
376 .B unknown
377 can be used.
378 .
379 .TP
380 .B E
381 For an article that is part of a book, the name of an editor of the book.
382 Where the work has editors and no authors,
383 the names of the editors should be given as
384 .B A
385 fields and
386 .B ,\ (ed)
387 or
388 .B ,\ (eds)
389 should be appended to the last author.
390 .
391 .TP
392 .B G
393 US Government ordering number.
394 .
395 .TP
396 .B I
397 The publisher (issuer).
398 .
399 .TP
400 .B J
401 For an article in a journal, the name of the journal.
402 .
403 .TP
404 .B K
405 Keywords to be used for searching.
406 .
407 .TP
408 .B L
409 Label.
410 .
411 .TP
412 .B N
413 Journal issue number.
414 .
415 .TP
416 .B O
417 Other information.
418 This is usually printed at the end of the reference.
419 .
420 .TP
421 .B P
422 Page number.
423 A range of pages can be specified as
424 .IB m \- n\fR.
425 .
426 .TP
427 .B Q
428 The name of the author, if the author is not a person.
429 This will only be used if there are no
430 .B A
431 fields.
432 There can only be one
433 .B Q
434 field.
435 .
436 .TP
437 .B R
438 Technical report number.
439 .
440 .TP
441 .B S
442 Series name.
443 .
444 .TP
445 .B T
446 Title.
447 For an article in a book or journal,
448 this should be the title of the article.
449 .
450 .TP
451 .B V
452 Volume number of the journal or book.
453 .
454 .TP
455 .B X
456 Annotation.
457 .
458 .LP
459 For all fields except
460 .B A
461 and
462 .BR E ,
463 if there is more than one occurrence of a particular field in a record,
464 only the last such field will be used.
465 .
466 .LP
467 If accent strings are used, they should follow the character to be accented.
468 This means that the
469 .B AM
470 macro must be used with the
471 .B \-ms
472 macros.
473 Accent strings should not be quoted:
474 use one
475 .B \e
476 rather than two.
477 .
478 .
479 .SS Citations
480 The format of a citation is
481 .
482 .RS
483 .BI .[ opening-text
484 .br
485 .I "flags keywords"
486 .br
487 .I fields
488 .br
489 .BI .] closing-text
490 .RE
491 .
492 .LP
493 The
494 .IR opening-text ,
495 .IR closing-text
496 and
497 .I flags
498 components are optional.
499 Only one of the
500 .I keywords
501 and
502 .I fields
503 components need be specified.
504 .
505 .LP
506 The
507 .I keywords
508 component says to search the bibliographic databases for a reference
509 that contains all the words in
510 .IR keywords .
511 It is an error if more than one reference if found.
512 .
513 .LP
514 The
515 .I fields
516 components specifies additional fields to replace or supplement
517 those specified in the reference.
518 When references are being accumulated and the
519 .I keywords
520 component is non-empty,
521 then additional fields should be specified only on the first
522 occasion that a particular reference is cited,
523 and will apply to all citations of that reference.
524 .
525 .LP
526 The
527 .I opening-text
528 and
529 .I closing-text
530 component specifies strings to be used to bracket the label instead
531 of the strings specified in the
532 .B bracket-label
533 command.
534 If either of these components is non-empty,
535 the strings specified in the
536 .B bracket-label
537 command will not be used;
538 this behaviour can be altered using the
539 .B [
540 and
541 .B ]
542 flags.
543 Note that leading and trailing spaces are significant for these components.
544 .
545 .LP
546 The
547 .I flags
548 component is a list of
549 non-alphanumeric characters each of which modifies the treatment
550 of this particular citation.
551 Unix refer will treat these flags as part of the keywords and
552 so will ignore them since they are non-alphanumeric.
553 The following flags are currently recognized:
554 .
555 .TP
556 .B #
557 This says to use the label specified by the
558 .B short-label
559 command,
560 instead of that specified by the
561 .B label
562 command.
563 If no short label has been specified, the normal label will be used.
564 Typically the short label is used with author-date labels
565 and consists of only the date and possibly a disambiguating letter;
566 the
567 .B #
568 is supposed to be suggestive of a numeric type of label.
569 .
570 .TP
571 .B [
572 Precede
573 .I opening-text
574 with the first string specified in the
575 .B bracket-label
576 command.
577 .
578 .TP
579 .B ]
580 Follow
581 .I closing-text
582 with the second string specified in the
583 .B bracket-label
584 command.
585 .
586 .LP
587 One advantages of using the
588 .B [
589 and
590 .B ]
591 flags rather than including the brackets in
592 .I opening-text
593 and
594 .I closing-text
595 is that
596 you can change the style of bracket used in the document just by changing the
597 .B bracket-label
598 command.
599 Another advantage is that sorting and merging of citations
600 will not necessarily be inhibited if the flags are used.
601 .
602 .LP
603 If a label is to be inserted into the text,
604 it will be attached to the line preceding the
605 .B .[
606 line.
607 If there is no such line, then an extra line will be inserted before the
608 .B .[
609 line and a warning will be given.
610 .
611 .LP
612 There is no special notation for making a citation to multiple references.
613 Just use a sequence of citations, one for each reference.
614 Don't put anything between the citations.
615 The labels for all the citations will be attached to the line preceding
616 the first citation.
617 The labels may also be sorted or merged.
618 See the description of the
619 .B <>
620 label expression, and of the
621 .B sort-adjacent-labels
622 and
623 .B abbreviate-label-ranges
624 command.
625 A label will not be merged if its citation has a non-empty
626 .I opening-text
627 or
628 .IR closing-text .
629 However, the labels for a citation using the
630 .B ]
631 flag and without any
632 .I closing-text
633 immediately followed by a citation using the
634 .B [
635 flag and without any
636 .I opening-text
637 may be sorted and merged
638 even though the first citation's
639 .I opening-text
640 or the second citation's
641 .I closing-text
642 is non-empty.
643 (If you wish to prevent this just make the first citation's
644 .I closing-text
645 .BR \e& .)
646 .
647 .
648 .SS Commands
649 Commands are contained between lines starting with
650 .B .R1
651 and
652 .BR .R2 .
653 Recognition of these lines can be prevented by the
654 .B \-R
655 option.
656 When a
657 .B .R1
658 line is recognized any accumulated references are flushed out.
659 Neither
660 .B .R1
661 nor
662 .B .R2
663 lines,
664 nor anything between them
665 is output.
666 .
667 .LP
668 Commands are separated by newlines or
669 .BR ; s.
670 .B #
671 introduces a comment that extends to the end of the line
672 (but does not conceal the newline).
673 Each command is broken up into words.
674 Words are separated by spaces or tabs.
675 A word that begins with
676 .B \(ts
677 extends to the next
678 .B \(ts
679 that is not followed by another
680 .BR \(ts .
681 If there is no such
682 .B \(ts
683 the word extends to the end of the line.
684 Pairs of
685 .B \(ts
686 in a word beginning with
687 .B \(ts
688 collapse to a single
689 .BR \(ts .
690 Neither
691 .B #
692 nor
693 .B ;
694 are recognized inside
695 .BR \(ts s.
696 A line can be continued by ending it with
697 .BR \e ;
698 this works everywhere except after a
699 .BR # .
700 .
701 .LP
702 .ds n \fR*
703 Each command
704 .I name
705 that is marked with \*n has an associated negative command
706 .BI no- name
707 that undoes the effect of
708 .IR name .
709 For example, the
710 .B no-sort
711 command specifies that references should not be sorted.
712 The negative commands take no arguments.
713 .
714 .LP
715 In the following description each argument must be a single word;
716 .I field
717 is used for a single upper or lower case letter naming a field;
718 .I fields
719 is used for a sequence of such letters;
720 .I m
721 and
722 .I n
723 are used for a non-negative numbers;
724 .I string
725 is used for an arbitrary string;
726 .I filename
727 is used for the name of a file.
728 .
729 .Tp \w'\fBabbreviate-label-ranges'u+2n
730 .BI abbreviate\*n\ fields\ string1\ string2\ string3\ string4
731 Abbreviate the first names of
732 .IR fields .
733 An initial letter will be separated from another initial letter by
734 .IR string1 ,
735 from the last name by
736 .IR string2 ,
737 and from anything else
738 (such as a
739 .B von
740 or
741 .BR de )
742 by
743 .IR string3 .
744 These default to a period followed by a space.
745 In a hyphenated first name,
746 the initial of the first part of the name will be separated from the hyphen by
747 .IR string4 ;
748 this defaults to a period.
749 No attempt is made to handle any ambiguities that might
750 result from abbreviation.
751 Names are abbreviated before sorting and before
752 label construction.
753 .
754 .TP
755 .BI abbreviate-label-ranges\*n\ string
756 Three or more adjacent labels that refer to consecutive references
757 will be abbreviated to a label consisting
758 of the first label, followed by
759 .I string
760 followed by the last label.
761 This is mainly useful with numeric labels.
762 If
763 .I string
764 is omitted it defaults to
765 .BR \- .
766 .
767 .TP
768 .B accumulate\*n
769 Accumulate references instead of writing out each reference
770 as it is encountered.
771 Accumulated references will be written out whenever a reference
772 of the form
773 .
774 .RS
775 .IP
776 .B .[
777 .br
778 .B $LIST$
779 .br
780 .B .]
781 .
782 .LP
783 is encountered,
784 after all input files hve been processed,
785 and whenever
786 .B .R1
787 line is recognized.
788 .RE
789 .
790 .TP
791 .BI annotate\*n\ field\ string
792 .I field
793 is an annotation;
794 print it at the end of the reference as a paragraph preceded by the line
795 .
796 .RS
797 .IP
798 .BI . string
799 .
800 .LP
801 If
802 .I macro
803 is omitted it will default to
804 .BR AP ;
805 if
806 .I field
807 is also omitted it will default to
808 .BR X .
809 Only one field can be an annotation.
810 .RE
811 .
812 .TP
813 .BI articles\ string \fR\|.\|.\|.
814 .IR string \|.\|.\|.\&
815 are definite or indefinite articles, and should be ignored at the beginning of
816 .B T
817 fields when sorting.
818 Initially,
819 .BR the ,
820 .B a
821 and
822 .B an
823 are recognized as articles.
824 .
825 .TP
826 .BI bibliography\ filename \fR\|.\|.\|.
827 Write out all the references contained in the bibliographic databases
828 .IR filename \|.\|.\|.
829 This command should come last in a
830 .BR .R1 / .R2
831 block.
832 .
833 .TP
834 .BI bracket-label\ string1\ string2\ string3
835 In the text, bracket each label
836 with
837 .I string1
838 and
839 .IR string2 .
840 An occurrence of
841 .I string2
842 immediately followed by
843 .I string1
844 will be turned into
845 .IR string3 .
846 The default behaviour is
847 .
848 .RS
849 .IP
850 .B
851 bracket-label \e*([. \e*(.] ", "
852 .RE
853 .
854 .TP
855 .BI capitalize\ fields
856 Convert
857 .I fields
858 to caps and small caps.
859 .
860 .TP
861 .B compatible\*n
862 Recognize
863 .B .R1
864 and
865 .B .R2
866 even when followed by a character other than space or newline.
867 .
868 .TP
869 .BI database\ filename \fR\|.\|.\|.
870 Search the bibliographic databases
871 .IR filename \|.\|.\|.
872 For each
873 .I filename
874 if an index
875 .IB filename @INDEX_SUFFIX@
876 created by
877 .BR @g@indxbib (@MAN1EXT@)
878 exists, then it will be searched instead;
879 each index can cover multiple databases.
880 .
881 .TP
882 .BI date-as-label\*n\ string
883 .I string
884 is a label expression that specifies a string with which to replace the
885 .B D
886 field after constructing the label.
887 See the
888 .B "Label expressions"
889 subsection for a description of label expressions.
890 This command is useful if you do not want explicit labels in the
891 reference list, but instead want to handle any necessary
892 disambiguation by qualifying the date in some way.
893 The label used in the text would typically be some combination of the
894 author and date.
895 In most cases you should also use the
896 .B no-label-in-reference
897 command.
898 For example,
899 .
900 .RS
901 .IP
902 .B "date-as-label D.+yD.y%a*D.-y"
903 .
904 .LP
905 would attach a disambiguating letter to the year part of the
906 .B D
907 field in the reference.
908 .RE
909 .
910 .TP
911 .B default-database\*n
912 The default database should be searched.
913 This is the default behaviour, so the negative version of
914 this command is more useful.
915 .B refer
916 determines whether the default database should be searched
917 on the first occasion that it needs to do a search.
918 Thus a
919 .B no-default-database
920 command must be given before then,
921 in order to be effective.
922 .
923 .TP
924 .BI discard\*n\ fields
925 When the reference is read,
926 .I fields
927 should be discarded;
928 no string definitions for
929 .I fields
930 will be output.
931 Initially,
932 .I fields
933 are
934 .BR XYZ .
935 .
936 .TP
937 .BI et-al\*n\ string\ m\ n
938 Control use of
939 .B "et al"
940 in the evaluation of
941 .B @
942 expressions in label expressions.
943 If the number of authors needed to make the author sequence
944 unambiguous is
945 .I u
946 and the total number of authors is
947 .I t
948 then the last
949 .IR t \|\-\| u
950 authors will be replaced by
951 .I string
952 provided that
953 .IR t \|\-\| u
954 is not less than
955 .I m
956 and
957 .I t
958 is not less than
959 .IR n .
960 The default behaviour is
961 .
962 .RS
963 .IP
964 .B
965 et-al " et al" 2 3
966 .RE
967 .
968 .TP
969 .BI include\ filename
970 Include
971 .I filename
972 and interpret the contents as commands.
973 .
974 .TP
975 .BI join-authors\ string1\ string2\ string3
976 This says how authors should be joined together.
977 When there are exactly two authors, they will be joined with
978 .IR string1 .
979 When there are more than two authors, all but the last two will
980 be joined with
981 .IR string2 ,
982 and the last two authors will be joined with
983 .IR string3 .
984 If
985 .I string3
986 is omitted,
987 it will default to
988 .IR string1 ;
989 if
990 .I string2
991 is also omitted it will also default to
992 .IR string1 .
993 For example,
994 .
995 .RS
996 .IP
997 .B
998 join-authors " and " ", " ", and "
999 .
1000 .LP
1001 will restore the default method for joining authors.
1002 .RE
1003 .
1004 .TP
1005 .B label-in-reference\*n
1006 When outputting the reference,
1007 define the string
1008 .B [F
1009 to be the reference's label.
1010 This is the default behaviour; so the negative version
1011 of this command is more useful.
1012 .
1013 .TP
1014 .B label-in-text\*n
1015 For each reference output a label in the text.
1016 The label will be separated from the surrounding text as described in the
1017 .B bracket-label
1018 command.
1019 This is the default behaviour; so the negative version
1020 of this command is more useful.
1021 .
1022 .TP
1023 .BI label\ string
1024 .I string
1025 is a label expression describing how to label each reference.
1026 .
1027 .TP
1028 .BI separate-label-second-parts\ string
1029 When merging two-part labels, separate the second part of the second
1030 label from the first label with
1031 .IR string .
1032 See the description of the
1033 .B <>
1034 label expression.
1035 .
1036 .TP
1037 .B move-punctuation\*n
1038 In the text, move any punctuation at the end of line past the label.
1039 It is usually a good idea to give this command unless you are using
1040 superscripted numbers as labels.
1041 .
1042 .TP
1043 .BI reverse\*n\ string
1044 Reverse the fields whose names
1045 are in
1046 .IR string .
1047 Each field name can be followed by a number which says
1048 how many such fields should be reversed.
1049 If no number is given for a field, all such fields will be reversed.
1050 .
1051 .TP
1052 .BI search-ignore\*n\ fields
1053 While searching for keys in databases for which no index exists,
1054 ignore the contents of
1055 .IR fields .
1056 Initially, fields
1057 .B XYZ
1058 are ignored.
1059 .
1060 .TP
1061 .BI search-truncate\*n\ n
1062 Only require the first
1063 .I n
1064 characters of keys to be given.
1065 In effect when searching for a given key
1066 words in the database are truncated to the maximum of
1067 .I n
1068 and the length of the key.
1069 Initially
1070 .I n
1071 is\ 6.
1072 .
1073 .TP
1074 .BI short-label\*n\ string
1075 .I string
1076 is a label expression that specifies an alternative (usually shorter)
1077 style of label.
1078 This is used when the
1079 .B #
1080 flag is given in the citation.
1081 When using author-date style labels, the identity of the author
1082 or authors is sometimes clear from the context, and so it
1083 may be desirable to omit the author or authors from the label.
1084 The
1085 .B short-label
1086 command will typically be used to specify a label containing just
1087 a date and possibly a disambiguating letter.
1088 .
1089 .TP
1090 .BI sort\*n\ string
1091 Sort references according to
1092 .BR string .
1093 References will automatically be accumulated.
1094 .I string
1095 should be a list of field names, each followed by a number,
1096 indicating how many fields with the name should be used for sorting.
1097 .B +
1098 can be used to indicate that all the fields with the name should be used.
1099 Also
1100 .B .\&
1101 can be used to indicate the references should be sorted using the
1102 (tentative) label.
1103 (The
1104 .B "Label expressions"
1105 subsection describes the concept of a tentative label.)
1106 .
1107 .TP
1108 .B sort-adjacent-labels\*n
1109 Sort labels that are adjacent in the text according to their
1110 position in the reference list.
1111 This command should usually be given if the
1112 .B abbreviate-label-ranges
1113 command has been given,
1114 or if the label expression contains a
1115 .B <>
1116 expression.
1117 This will have no effect unless references are being accumulated.
1118 .
1119 .
1120 .SS Label expressions
1121 .
1122 .LP
1123 Label expressions can be evaluated both normally and tentatively.
1124 The result of normal evaluation is used for output.
1125 The result of tentative evaluation, called the
1126 .IR "tentative label" ,
1127 is used to gather the information
1128 that normal evaluation needs to disambiguate the label.
1129 Label expressions specified by the
1130 .B date-as-label
1131 and
1132 .B short-label
1133 commands are not evaluated tentatively.
1134 Normal and tentative evaluation are the same for all types
1135 of expression other than
1136 .BR @ ,
1137 .BR * ,
1138 and
1139 .B %
1140 expressions.
1141 The description below applies to normal evaluation,
1142 except where otherwise specified.
1143 .
1144 .TP
1145 .I field
1146 .TQ
1147 .I field\ n
1148 The
1149 .IR n -th
1150 part of
1151 .IR field .
1152 If
1153 .I n
1154 is omitted, it defaults to\ 1.
1155 .
1156 .TP
1157 .BI ' string '
1158 The characters in
1159 .I string
1160 literally.
1161 .
1162 .TP
1163 .B @
1164 All the authors joined as specified by the
1165 .B join-authors
1166 command.
1167 The whole of each author's name will be used.
1168 However, if the references are sorted by author
1169 (that is the sort specification starts with
1170 .BR A+ ),
1171 then authors' last names will be used instead, provided that this does
1172 not introduce ambiguity,
1173 and also an initial subsequence of the authors may be used
1174 instead of all the authors, again provided that this does not
1175 introduce ambiguity.
1176 The use of only the last name for the
1177 .IR i -th
1178 author of some reference
1179 is considered to be ambiguous if
1180 there is some other reference,
1181 such that the first
1182 .IR i \|-\|1
1183 authors of the references are the same,
1184 the
1185 .IR i -th
1186 authors are not the same,
1187 but the
1188 .IR i -th
1189 authors' last names are the same.
1190 A proper initial subsequence of the sequence
1191 of authors for some reference is considered to be ambiguous if there is
1192 a reference with some other sequence of authors which also has
1193 that subsequence as a proper initial subsequence.
1194 When an initial subsequence of authors is used, the remaining
1195 authors are replaced by the string specified by the
1196 .B et-al
1197 command;
1198 this command may also specify additional requirements that must be
1199 met before an initial subsequence can be used.
1200 .B @
1201 tentatively evaluates to a canonical representation of the authors,
1202 such that authors that compare equally for sorting purpose
1203 will have the same representation.
1204 .
1205 .TP
1206 .BI % n
1207 .TQ
1208 .B %a
1209 .TQ
1210 .B %A
1211 .TQ
1212 .B %i
1213 .TQ
1214 .B %I
1215 The serial number of the reference formatted according to the character
1216 following the
1217 .BR % .
1218 The serial number of a reference is\ 1 plus the number of earlier references
1219 with same tentative label as this reference.
1220 These expressions tentatively evaluate to an empty string.
1221 .
1222 .TP
1223 .IB expr *
1224 If there is another reference with the same tentative label as
1225 this reference, then
1226 .IR expr ,
1227 otherwise an empty string.
1228 It tentatively evaluates to an empty string.
1229 .
1230 .TP
1231 .IB expr + n
1232 .TQ
1233 .IB expr \- n
1234 The first
1235 .RB ( + )
1236 or last
1237 .RB ( \- )
1238 .I n
1239 upper or lower case letters or digits of
1240 .IR expr .
1241 Troff special characters (such as
1242 .BR \e('a )
1243 count as a single letter.
1244 Accent strings are retained but do not count towards the total.
1245 .
1246 .TP
1247 .IB expr .l
1248 .I expr
1249 converted to lowercase.
1250 .
1251 .TP
1252 .IB expr .u
1253 .I expr
1254 converted to uppercase.
1255 .
1256 .TP
1257 .IB expr .c
1258 .I expr
1259 converted to caps and small caps.
1260 .
1261 .TP
1262 .IB expr .r
1263 .I expr
1264 reversed so that the last name is first.
1265 .
1266 .TP
1267 .IB expr .a
1268 .I expr
1269 with first names abbreviated.
1270 Note that fields specified in the
1271 .B abbreviate
1272 command are abbreviated before any labels are evaluated.
1273 Thus
1274 .B .a
1275 is useful only when you want a field to be abbreviated in a label
1276 but not in a reference.
1277 .
1278 .TP
1279 .IB expr .y
1280 The year part of
1281 .IR expr .
1282 .
1283 .TP
1284 .IB expr .+y
1285 The part of
1286 .I expr
1287 before the year, or the whole of
1288 .I expr
1289 if it does not contain a year.
1290 .
1291 .TP
1292 .IB expr .\-y
1293 The part of
1294 .I expr
1295 after the year, or an empty string if
1296 .I expr
1297 does not contain a year.
1298 .
1299 .TP
1300 .IB expr .n
1301 The last name part of
1302 .IR expr .
1303 .
1304 .TP
1305 .IB expr1 \(ti expr2
1306 .I expr1
1307 except that if the last character of
1308 .I expr1
1309 is
1310 .B \-
1311 then it will be replaced by
1312 .IR expr2 .
1313 .
1314 .TP
1315 .I expr1\ expr2
1316 The concatenation of
1317 .I expr1
1318 and
1319 .IR expr2 .
1320 .
1321 .TP
1322 .IB expr1 | expr2
1323 If
1324 .I expr1
1325 is non-empty then
1326 .I expr1
1327 otherwise
1328 .IR expr2 .
1329 .
1330 .TP
1331 .IB expr1 & expr2
1332 If
1333 .I expr1
1334 is non-empty
1335 then
1336 .I expr2
1337 otherwise an empty string.
1338 .
1339 .TP
1340 .IB expr1 ? expr2 : expr3
1341 If
1342 .I expr1
1343 is non-empty
1344 then
1345 .I expr2
1346 otherwise
1347 .IR expr3 .
1348 .
1349 .TP
1350 .BI < expr >
1351 The label is in two parts, which are separated by
1352 .IR expr .
1353 Two adjacent two-part labels which have the same first part will be
1354 merged by appending the second part of the second label onto the first
1355 label separated by the string specified in the
1356 .B separate-label-second-parts
1357 command (initially, a comma followed by a space); the resulting label
1358 will also be a two-part label with the same first part as before
1359 merging, and so additional labels can be merged into it.
1360 Note that it is permissible for the first part to be empty;
1361 this maybe desirable for expressions used in the
1362 .B short-label
1363 command.
1364 .
1365 .TP
1366 .BI ( expr )
1367 The same as
1368 .IR expr .
1369 Used for grouping.
1370 .
1371 .LP
1372 The above expressions are listed in order of precedence
1373 (highest first);
1374 .B &
1375 and
1376 .B |
1377 have the same precedence.
1378 .
1379 .
1380 .SS Macro interface
1381 Each reference starts with a call to the macro
1382 .BR ]- .
1383 The string
1384 .B [F
1385 will be defined to be the label for this reference,
1386 unless the
1387 .B no-label-in-reference
1388 command has been given.
1389 There then follows a series of string definitions,
1390 one for each field:
1391 string
1392 .BI [ X
1393 corresponds to field
1394 .IR X .
1395 The number register
1396 .B [P
1397 is set to\ 1 if the
1398 .B P
1399 field contains a range of pages.
1400 The
1401 .BR [T ,
1402 .B [A
1403 and
1404 .B [O
1405 number registers are set to\ 1 according as the
1406 .BR T ,
1407 .B A
1408 and
1409 .B O
1410 fields end with one of the characters
1411 .BR .?! .
1412 The
1413 .B [E
1414 number register will be set to\ 1 if the
1415 .B [E
1416 string contains more than one name.
1417 The reference is followed by a call to the
1418 .B ][
1419 macro.
1420 The first argument to this macro gives a number representing
1421 the type of the reference.
1422 If a reference contains a
1423 .B J
1424 field, it will be classified as type\ 1,
1425 otherwise if it contains a
1426 .B B
1427 field, it will type\ 3,
1428 otherwise if it contains a
1429 .B G
1430 or
1431 .B R
1432 field it will be type\ 4,
1433 otherwise if contains a
1434 .B I
1435 field it will be type\ 2,
1436 otherwise it will be type\ 0.
1437 The second argument is a symbolic name for the type:
1438 .BR other ,
1439 .BR journal-article ,
1440 .BR book ,
1441 .B article-in-book
1442 or
1443 .BR tech-report .
1444 Groups of references that have been accumulated
1445 or are produced by the
1446 .B bibliography
1447 command are preceded by a call to the
1448 .B ]<
1449 macro and followed by a call to the
1450 .B ]>
1451 macro.
1452 .
1453 .
1454 .
1455 .SH FILES
1456 .
1457 .Tp \w'\fB@DEFAULT_INDEX@'u+2n
1458 .B @DEFAULT_INDEX@
1459 Default database.
1460 .
1461 .TP
1462 .IB file @INDEX_SUFFIX@
1463 Index files.
1464 .
1465 .
1466 .
1467 .SH ENVIRONMENT
1468 .
1469 .Tp \w'\fBREFER'u+2n
1470 .B REFER
1471 If set, overrides the default database.
1472 .
1473 .
1474 .
1475 .SH "SEE ALSO"
1476 .BR @g@indxbib (@MAN1EXT@),
1477 .BR @g@lookbib (@MAN1EXT@),
1478 .BR lkbib (@MAN1EXT@)
1479 .br
1480 .
1481 .
1482 .
1483 .SH BUGS
1484 In label expressions,
1485 .B <>
1486 expressions are ignored inside
1487 .BI . char
1488 expressions.
1489 .
1490 .\" Local Variables:
1491 .\" mode: nroff
1492 .\" End: