2 Copyright (C) 1989-2000, 2001, 2002, 2003, 2004, 2005
3 Free Software Foundation, Inc.
5 Permission is granted to make and distribute verbatim copies of
6 this manual provided the copyright notice and this permission notice
7 are preserved on all copies.
9 Permission is granted to copy and distribute modified versions of this
10 manual under the conditions for verbatim copying, provided that the
11 entire resulting derived work is distributed under the terms of a
12 permission notice identical to this one.
14 Permission is granted to copy and distribute translations of this
15 manual into another language, under the above conditions for modified
16 versions, except that this permission notice may be included in
17 translations approved by the Free Software Foundation instead of in
29 .\" Like TP, but if specified indent is more than half
30 .\" the current line-length - indent, use the default indent.
32 . ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
37 .\" The BSD man macros can't handle " in arguments to font change macros,
38 .\" so use \(ts instead of ".
42 .TH @G@REFER @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
47 @g@refer \- preprocess bibliographic references for groff
55 .in +\w'\fB@g@refer 'u
60 . ie \\n(.$-1 .RI "[\ \fB\\$1\fP" "\\$2" "\ ]"
61 . el .RB "[\ " "\\$1" "\ ]"
75 .RI [\ \%filename \|.\|.\|.\ ]
80 It is possible to have whitespace between a command line option and its
86 This file documents the GNU version of
88 which is part of the groff document formatting system.
90 copies the contents of
91 .IR filename \|.\|.\|.\&
92 to the standard output,
93 except that lines between
97 are interpreted as citations,
102 are interpreted as commands about how citations are to be processed.
105 Each citation specifies a reference.
106 The citation can specify a reference that is contained in
107 a bibliographic database by giving a set of keywords
108 that only that reference contains.
109 Alternatively it can specify a reference by supplying a database
110 record in the citation.
111 A combination of these alternatives is also possible.
116 can produce a mark in the text.
117 This mark consists of some label which can be separated from
118 the text and from other labels in various ways.
119 For each reference it also outputs
121 commands that can be used by a macro package to produce a formatted
122 reference for each citation.
125 must therefore be processed using a suitable macro package.
130 macros are both suitable.
131 The commands to format a citation's reference can be output immediately after
133 or the references may be accumulated,
134 and the commands output at some later point.
135 If the references are accumulated, then multiple citations of the same
136 reference will produce a single formatted reference.
139 The interpretation of lines between
143 as commands is a new feature of GNU
145 Documents making use of this feature can still be processed by
146 Unix refer just by adding the lines
159 to the beginning of the document.
162 to ignore everything between
166 The effect of some commands can also be achieved by options.
167 These options are supported mainly for compatibility with Unix refer.
168 It is usually more convenient to use commands.
174 lines so that filenames and line numbers in messages produced
175 by commands that read
177 output will be correct;
178 it also interprets lines beginning with
180 so that filenames and line numbers in the messages and
182 lines that it produces will be accurate even if the input has been
183 preprocessed by a command such as
184 .BR @g@soelim (@MAN1EXT@).
191 Most options are equivalent to commands
192 (for a description of these commands see the
200 .B "no-label-in-text; no-label-in-reference"
208 .B no-default-database
221 label\ "(A.n|Q)\ ',\ '\ (D.y|D)"; \%bracket-label\ "\ ("\ )\ ";\ "
271 .BI A.n+ m D.y\- n %a
290 These options are equivalent to the following commands with the
291 addition that the filenames specified on the command line are
292 processed as if they were arguments to the
294 command instead of in the normal way:
298 .B "annotate X AP; no-label-in-reference"
301 .BI \-B field . macro
305 .B no-label-in-reference
308 The following options have no equivalent commands:
312 Print the version number.
316 Don't recognize lines beginning with
324 .SS Bibliographic databases
325 The bibliographic database is a text file consisting of records
326 separated by one or more blank lines.
327 Within each record fields start with a
329 at the beginning of a line.
330 Each field has a one character name that immediately follows the
332 It is best to use only upper and lower case letters for the names
334 The name of the field should be followed by exactly one space,
335 and then by the contents of the field.
336 Empty fields are ignored.
337 The conventional meaning of each field is as follows:
341 The name of an author.
342 If the name contains a title such as
345 it should be separated from the last name by a comma.
346 There can be multiple occurrences of the
349 The order is significant.
350 It is a good idea always to supply an
358 For an article that is part of a book, the title of the book.
362 The place (city) of publication.
366 The date of publication.
367 The year should be specified in full.
368 If the month is specified, the name rather than the number of the month
369 should be used, but only the first three letters are required.
370 It is a good idea always to supply a
373 if the date is unknown, a value such as
381 For an article that is part of a book, the name of an editor of the book.
382 Where the work has editors and no authors,
383 the names of the editors should be given as
389 should be appended to the last author.
393 US Government ordering number.
397 The publisher (issuer).
401 For an article in a journal, the name of the journal.
405 Keywords to be used for searching.
413 Journal issue number.
418 This is usually printed at the end of the reference.
423 A range of pages can be specified as
428 The name of the author, if the author is not a person.
429 This will only be used if there are no
432 There can only be one
438 Technical report number.
447 For an article in a book or journal,
448 this should be the title of the article.
452 Volume number of the journal or book.
459 For all fields except
463 if there is more than one occurrence of a particular field in a record,
464 only the last such field will be used.
467 If accent strings are used, they should follow the character to be accented.
470 macro must be used with the
473 Accent strings should not be quoted:
480 The format of a citation is
498 components are optional.
503 components need be specified.
508 component says to search the bibliographic databases for a reference
509 that contains all the words in
511 It is an error if more than one reference if found.
516 components specifies additional fields to replace or supplement
517 those specified in the reference.
518 When references are being accumulated and the
520 component is non-empty,
521 then additional fields should be specified only on the first
522 occasion that a particular reference is cited,
523 and will apply to all citations of that reference.
530 component specifies strings to be used to bracket the label instead
531 of the strings specified in the
534 If either of these components is non-empty,
535 the strings specified in the
537 command will not be used;
538 this behaviour can be altered using the
543 Note that leading and trailing spaces are significant for these components.
548 component is a list of
549 non-alphanumeric characters each of which modifies the treatment
550 of this particular citation.
551 Unix refer will treat these flags as part of the keywords and
552 so will ignore them since they are non-alphanumeric.
553 The following flags are currently recognized:
557 This says to use the label specified by the
560 instead of that specified by the
563 If no short label has been specified, the normal label will be used.
564 Typically the short label is used with author-date labels
565 and consists of only the date and possibly a disambiguating letter;
568 is supposed to be suggestive of a numeric type of label.
574 with the first string specified in the
582 with the second string specified in the
587 One advantages of using the
591 flags rather than including the brackets in
596 you can change the style of bracket used in the document just by changing the
599 Another advantage is that sorting and merging of citations
600 will not necessarily be inhibited if the flags are used.
603 If a label is to be inserted into the text,
604 it will be attached to the line preceding the
607 If there is no such line, then an extra line will be inserted before the
609 line and a warning will be given.
612 There is no special notation for making a citation to multiple references.
613 Just use a sequence of citations, one for each reference.
614 Don't put anything between the citations.
615 The labels for all the citations will be attached to the line preceding
617 The labels may also be sorted or merged.
618 See the description of the
620 label expression, and of the
621 .B sort-adjacent-labels
623 .B abbreviate-label-ranges
625 A label will not be merged if its citation has a non-empty
629 However, the labels for a citation using the
633 immediately followed by a citation using the
637 may be sorted and merged
638 even though the first citation's
640 or the second citation's
643 (If you wish to prevent this just make the first citation's
649 Commands are contained between lines starting with
653 Recognition of these lines can be prevented by the
658 line is recognized any accumulated references are flushed out.
664 nor anything between them
668 Commands are separated by newlines or
671 introduces a comment that extends to the end of the line
672 (but does not conceal the newline).
673 Each command is broken up into words.
674 Words are separated by spaces or tabs.
675 A word that begins with
679 that is not followed by another
683 the word extends to the end of the line.
686 in a word beginning with
694 are recognized inside
696 A line can be continued by ending it with
698 this works everywhere except after a
705 that is marked with \*n has an associated negative command
707 that undoes the effect of
711 command specifies that references should not be sorted.
712 The negative commands take no arguments.
715 In the following description each argument must be a single word;
717 is used for a single upper or lower case letter naming a field;
719 is used for a sequence of such letters;
723 are used for a non-negative numbers;
725 is used for an arbitrary string;
727 is used for the name of a file.
729 .Tp \w'\fBabbreviate-label-ranges'u+2n
730 .BI abbreviate\*n\ fields\ string1\ string2\ string3\ string4
731 Abbreviate the first names of
733 An initial letter will be separated from another initial letter by
735 from the last name by
737 and from anything else
744 These default to a period followed by a space.
745 In a hyphenated first name,
746 the initial of the first part of the name will be separated from the hyphen by
748 this defaults to a period.
749 No attempt is made to handle any ambiguities that might
750 result from abbreviation.
751 Names are abbreviated before sorting and before
755 .BI abbreviate-label-ranges\*n\ string
756 Three or more adjacent labels that refer to consecutive references
757 will be abbreviated to a label consisting
758 of the first label, followed by
760 followed by the last label.
761 This is mainly useful with numeric labels.
764 is omitted it defaults to
769 Accumulate references instead of writing out each reference
770 as it is encountered.
771 Accumulated references will be written out whenever a reference
784 after all input files hve been processed,
791 .BI annotate\*n\ field\ string
794 print it at the end of the reference as a paragraph preceded by the line
803 is omitted it will default to
807 is also omitted it will default to
809 Only one field can be an annotation.
813 .BI articles\ string \fR\|.\|.\|.
814 .IR string \|.\|.\|.\&
815 are definite or indefinite articles, and should be ignored at the beginning of
823 are recognized as articles.
826 .BI bibliography\ filename \fR\|.\|.\|.
827 Write out all the references contained in the bibliographic databases
828 .IR filename \|.\|.\|.
829 This command should come last in a
834 .BI bracket-label\ string1\ string2\ string3
835 In the text, bracket each label
842 immediately followed by
846 The default behaviour is
851 bracket-label \e*([. \e*(.] ", "
855 .BI capitalize\ fields
858 to caps and small caps.
866 even when followed by a character other than space or newline.
869 .BI database\ filename \fR\|.\|.\|.
870 Search the bibliographic databases
871 .IR filename \|.\|.\|.
875 .IB filename @INDEX_SUFFIX@
877 .BR @g@indxbib (@MAN1EXT@)
878 exists, then it will be searched instead;
879 each index can cover multiple databases.
882 .BI date-as-label\*n\ string
884 is a label expression that specifies a string with which to replace the
886 field after constructing the label.
888 .B "Label expressions"
889 subsection for a description of label expressions.
890 This command is useful if you do not want explicit labels in the
891 reference list, but instead want to handle any necessary
892 disambiguation by qualifying the date in some way.
893 The label used in the text would typically be some combination of the
895 In most cases you should also use the
896 .B no-label-in-reference
902 .B "date-as-label D.+yD.y%a*D.-y"
905 would attach a disambiguating letter to the year part of the
907 field in the reference.
911 .B default-database\*n
912 The default database should be searched.
913 This is the default behaviour, so the negative version of
914 this command is more useful.
916 determines whether the default database should be searched
917 on the first occasion that it needs to do a search.
919 .B no-default-database
920 command must be given before then,
921 in order to be effective.
924 .BI discard\*n\ fields
925 When the reference is read,
928 no string definitions for
937 .BI et-al\*n\ string\ m\ n
942 expressions in label expressions.
943 If the number of authors needed to make the author sequence
946 and the total number of authors is
950 authors will be replaced by
960 The default behaviour is
969 .BI include\ filename
972 and interpret the contents as commands.
975 .BI join-authors\ string1\ string2\ string3
976 This says how authors should be joined together.
977 When there are exactly two authors, they will be joined with
979 When there are more than two authors, all but the last two will
982 and the last two authors will be joined with
991 is also omitted it will also default to
998 join-authors " and " ", " ", and "
1001 will restore the default method for joining authors.
1005 .B label-in-reference\*n
1006 When outputting the reference,
1009 to be the reference's label.
1010 This is the default behaviour; so the negative version
1011 of this command is more useful.
1015 For each reference output a label in the text.
1016 The label will be separated from the surrounding text as described in the
1019 This is the default behaviour; so the negative version
1020 of this command is more useful.
1025 is a label expression describing how to label each reference.
1028 .BI separate-label-second-parts\ string
1029 When merging two-part labels, separate the second part of the second
1030 label from the first label with
1032 See the description of the
1037 .B move-punctuation\*n
1038 In the text, move any punctuation at the end of line past the label.
1039 It is usually a good idea to give this command unless you are using
1040 superscripted numbers as labels.
1043 .BI reverse\*n\ string
1044 Reverse the fields whose names
1047 Each field name can be followed by a number which says
1048 how many such fields should be reversed.
1049 If no number is given for a field, all such fields will be reversed.
1052 .BI search-ignore\*n\ fields
1053 While searching for keys in databases for which no index exists,
1054 ignore the contents of
1061 .BI search-truncate\*n\ n
1062 Only require the first
1064 characters of keys to be given.
1065 In effect when searching for a given key
1066 words in the database are truncated to the maximum of
1068 and the length of the key.
1074 .BI short-label\*n\ string
1076 is a label expression that specifies an alternative (usually shorter)
1078 This is used when the
1080 flag is given in the citation.
1081 When using author-date style labels, the identity of the author
1082 or authors is sometimes clear from the context, and so it
1083 may be desirable to omit the author or authors from the label.
1086 command will typically be used to specify a label containing just
1087 a date and possibly a disambiguating letter.
1091 Sort references according to
1093 References will automatically be accumulated.
1095 should be a list of field names, each followed by a number,
1096 indicating how many fields with the name should be used for sorting.
1098 can be used to indicate that all the fields with the name should be used.
1101 can be used to indicate the references should be sorted using the
1104 .B "Label expressions"
1105 subsection describes the concept of a tentative label.)
1108 .B sort-adjacent-labels\*n
1109 Sort labels that are adjacent in the text according to their
1110 position in the reference list.
1111 This command should usually be given if the
1112 .B abbreviate-label-ranges
1113 command has been given,
1114 or if the label expression contains a
1117 This will have no effect unless references are being accumulated.
1120 .SS Label expressions
1123 Label expressions can be evaluated both normally and tentatively.
1124 The result of normal evaluation is used for output.
1125 The result of tentative evaluation, called the
1126 .IR "tentative label" ,
1127 is used to gather the information
1128 that normal evaluation needs to disambiguate the label.
1129 Label expressions specified by the
1133 commands are not evaluated tentatively.
1134 Normal and tentative evaluation are the same for all types
1135 of expression other than
1141 The description below applies to normal evaluation,
1142 except where otherwise specified.
1154 is omitted, it defaults to\ 1.
1164 All the authors joined as specified by the
1167 The whole of each author's name will be used.
1168 However, if the references are sorted by author
1169 (that is the sort specification starts with
1171 then authors' last names will be used instead, provided that this does
1172 not introduce ambiguity,
1173 and also an initial subsequence of the authors may be used
1174 instead of all the authors, again provided that this does not
1175 introduce ambiguity.
1176 The use of only the last name for the
1178 author of some reference
1179 is considered to be ambiguous if
1180 there is some other reference,
1183 authors of the references are the same,
1186 authors are not the same,
1189 authors' last names are the same.
1190 A proper initial subsequence of the sequence
1191 of authors for some reference is considered to be ambiguous if there is
1192 a reference with some other sequence of authors which also has
1193 that subsequence as a proper initial subsequence.
1194 When an initial subsequence of authors is used, the remaining
1195 authors are replaced by the string specified by the
1198 this command may also specify additional requirements that must be
1199 met before an initial subsequence can be used.
1201 tentatively evaluates to a canonical representation of the authors,
1202 such that authors that compare equally for sorting purpose
1203 will have the same representation.
1215 The serial number of the reference formatted according to the character
1218 The serial number of a reference is\ 1 plus the number of earlier references
1219 with same tentative label as this reference.
1220 These expressions tentatively evaluate to an empty string.
1224 If there is another reference with the same tentative label as
1225 this reference, then
1227 otherwise an empty string.
1228 It tentatively evaluates to an empty string.
1239 upper or lower case letters or digits of
1241 Troff special characters (such as
1243 count as a single letter.
1244 Accent strings are retained but do not count towards the total.
1249 converted to lowercase.
1254 converted to uppercase.
1259 converted to caps and small caps.
1264 reversed so that the last name is first.
1269 with first names abbreviated.
1270 Note that fields specified in the
1272 command are abbreviated before any labels are evaluated.
1275 is useful only when you want a field to be abbreviated in a label
1276 but not in a reference.
1287 before the year, or the whole of
1289 if it does not contain a year.
1295 after the year, or an empty string if
1297 does not contain a year.
1301 The last name part of
1305 .IB expr1 \(ti expr2
1307 except that if the last character of
1311 then it will be replaced by
1316 The concatenation of
1337 otherwise an empty string.
1340 .IB expr1 ? expr2 : expr3
1351 The label is in two parts, which are separated by
1353 Two adjacent two-part labels which have the same first part will be
1354 merged by appending the second part of the second label onto the first
1355 label separated by the string specified in the
1356 .B separate-label-second-parts
1357 command (initially, a comma followed by a space); the resulting label
1358 will also be a two-part label with the same first part as before
1359 merging, and so additional labels can be merged into it.
1360 Note that it is permissible for the first part to be empty;
1361 this maybe desirable for expressions used in the
1372 The above expressions are listed in order of precedence
1377 have the same precedence.
1381 Each reference starts with a call to the macro
1385 will be defined to be the label for this reference,
1387 .B no-label-in-reference
1388 command has been given.
1389 There then follows a series of string definitions,
1393 corresponds to field
1399 field contains a range of pages.
1405 number registers are set to\ 1 according as the
1410 fields end with one of the characters
1414 number register will be set to\ 1 if the
1416 string contains more than one name.
1417 The reference is followed by a call to the
1420 The first argument to this macro gives a number representing
1421 the type of the reference.
1422 If a reference contains a
1424 field, it will be classified as type\ 1,
1425 otherwise if it contains a
1427 field, it will type\ 3,
1428 otherwise if it contains a
1432 field it will be type\ 4,
1433 otherwise if contains a
1435 field it will be type\ 2,
1436 otherwise it will be type\ 0.
1437 The second argument is a symbolic name for the type:
1439 .BR journal-article ,
1444 Groups of references that have been accumulated
1445 or are produced by the
1447 command are preceded by a call to the
1449 macro and followed by a call to the
1457 .Tp \w'\fB@DEFAULT_INDEX@'u+2n
1462 .IB file @INDEX_SUFFIX@
1469 .Tp \w'\fBREFER'u+2n
1471 If set, overrides the default database.
1476 .BR @g@indxbib (@MAN1EXT@),
1477 .BR @g@lookbib (@MAN1EXT@),
1478 .BR lkbib (@MAN1EXT@)
1484 In label expressions,
1486 expressions are ignored inside
1490 .\" Local Variables:
projects / FreeBSD / releng / 9.2.git / blob