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