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