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