4 Copyright (c) 2014 - 2015 Steffen (Daode) Nurpmeso <sdaoden@users.sf.net>.
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
31 .\" Like TP, but if specified indent is more than half
32 .\" the current line-length - indent, use the default indent.
34 . ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
38 .\" The BSD man macros can't handle " in arguments to font change macros,
39 .\" so use \(ts instead of ".
43 .TH @U_P_REFER@ @MAN1EXT@ "@MDATE@" "@T_ROFF@ v@VERSION@"
48 @L_P_REFER@ \- preprocess bibliographic references for @T_ROFF@
55 .in +\w'\fB@L_P_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
87 copies the contents of
88 .IR filename \|.\|.\|.\&
89 to the standard output,
90 except that lines between
94 are interpreted as citations,
99 are interpreted as commands about how citations are to be processed.
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.
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
118 commands that can be used by a macro package to produce a formatted
119 reference for each citation.
122 must therefore be processed using a suitable macro package.
127 macros are both suitable.
128 The commands to format a citation's reference can be output immediately after
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.
136 The interpretation of lines between
140 as commands is a new feature of GNU
142 Documents making use of this feature can still be processed by
143 Unix refer just by adding the lines
156 to the beginning of the document.
159 to ignore everything between
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.
171 lines so that filenames and line numbers in messages produced
172 by commands that read
174 output will be correct;
175 it also interprets lines beginning with
177 so that filenames and line numbers in the messages and
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@).
188 Most options are equivalent to commands
189 (for a description of these commands see the
197 .B "no-label-in-text; no-label-in-reference"
205 .B no-default-database
218 label\ "(A.n|Q)\ ',\ '\ (D.y|D)"; \%bracket-label\ "\ ("\ )\ ";\ "
268 .BI A.n+ m D.y\- n %a
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
291 command instead of in the normal way:
295 .B "annotate X AP; no-label-in-reference"
298 .BI \-B field . macro
302 .B no-label-in-reference
305 The following options have no equivalent commands:
309 Print the version number.
313 Don't recognize lines beginning with
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
326 at the beginning of a line.
327 Each field has a one character name that immediately follows the
329 It is best to use only upper and lower case letters for the names
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:
338 The name of an author.
339 If the name contains a title such as
342 it should be separated from the last name by a comma.
343 There can be multiple occurrences of the
346 The order is significant.
347 It is a good idea always to supply an
355 For an article that is part of a book, the title of the book.
359 The place (city) of publication.
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
370 if the date is unknown, a value such as
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
386 should be appended to the last author.
390 US Government ordering number.
394 The publisher (issuer).
398 For an article in a journal, the name of the journal.
402 Keywords to be used for searching.
410 Journal issue number.
415 This is usually printed at the end of the reference.
420 A range of pages can be specified as
425 The name of the author, if the author is not a person.
426 This will only be used if there are no
429 There can only be one
435 Technical report number.
444 For an article in a book or journal,
445 this should be the title of the article.
449 Volume number of the journal or book.
456 For all fields except
460 if there is more than one occurrence of a particular field in a record,
461 only the last such field will be used.
464 If accent strings are used, they should follow the character to be accented.
467 macro must be used with the
470 Accent strings should not be quoted:
477 The format of a citation is
495 components are optional.
500 components need be specified.
505 component says to search the bibliographic databases for a reference
506 that contains all the words in
508 It is an error if more than one reference if found.
513 components specifies additional fields to replace or supplement
514 those specified in the reference.
515 When references are being accumulated and the
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.
527 component specifies strings to be used to bracket the label instead
528 of the strings specified in the
531 If either of these components is non-empty,
532 the strings specified in the
534 command will not be used;
535 this behaviour can be altered using the
540 Note that leading and trailing spaces are significant for these components.
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:
554 This says to use the label specified by the
557 instead of that specified by the
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;
565 is supposed to be suggestive of a numeric type of label.
571 with the first string specified in the
579 with the second string specified in the
584 One advantages of using the
588 flags rather than including the brackets in
593 you can change the style of bracket used in the document just by changing the
596 Another advantage is that sorting and merging of citations
597 will not necessarily be inhibited if the flags are used.
600 If a label is to be inserted into the text,
601 it will be attached to the line preceding the
604 If there is no such line, then an extra line will be inserted before the
606 line and a warning will be given.
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
614 The labels may also be sorted or merged.
615 See the description of the
617 label expression, and of the
618 .B sort-adjacent-labels
620 .B abbreviate-label-ranges
622 A label will not be merged if its citation has a non-empty
626 However, the labels for a citation using the
630 immediately followed by a citation using the
634 may be sorted and merged
635 even though the first citation's
637 or the second citation's
640 (If you wish to prevent this just make the first citation's
646 Commands are contained between lines starting with
650 Recognition of these lines can be prevented by the
655 line is recognized any accumulated references are flushed out.
661 nor anything between them
665 Commands are separated by newlines or
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
676 that is not followed by another
680 the word extends to the end of the line.
683 in a word beginning with
691 are recognized inside
693 A line can be continued by ending it with
695 this works everywhere except after a
702 that is marked with \*n has an associated negative command
704 that undoes the effect of
708 command specifies that references should not be sorted.
709 The negative commands take no arguments.
712 In the following description each argument must be a single word;
714 is used for a single upper or lower case letter naming a field;
716 is used for a sequence of such letters;
720 are used for a non-negative numbers;
722 is used for an arbitrary string;
724 is used for the name of a file.
726 .Tp \w'\fBabbreviate-label-ranges'u+2n
727 .BI abbreviate\*n\ fields\ string1\ string2\ string3\ string4
728 Abbreviate the first names of
730 An initial letter will be separated from another initial letter by
732 from the last name by
734 and from anything else
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
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
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
757 followed by the last label.
758 This is mainly useful with numeric labels.
761 is omitted it defaults to
766 Accumulate references instead of writing out each reference
767 as it is encountered.
768 Accumulated references will be written out whenever a reference
781 after all input files have been processed,
788 .BI annotate\*n\ field\ string
791 print it at the end of the reference as a paragraph preceded by the line
800 is omitted it will default to
804 is also omitted it will default to
806 Only one field can be an annotation.
810 .BI articles\ string \fR\|.\|.\|.
811 .IR string \|.\|.\|.\&
812 are definite or indefinite articles, and should be ignored at the beginning of
820 are recognized as articles.
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
831 .BI bracket-label\ string1\ string2\ string3
832 In the text, bracket each label
839 immediately followed by
843 The default behaviour is
848 bracket-label \e*([. \e*(.] ", "
852 .BI capitalize\ fields
855 to caps and small caps.
863 even when followed by a character other than space or newline.
866 .BI database\ filename \fR\|.\|.\|.
867 Search the bibliographic databases
868 .IR filename \|.\|.\|.
872 .IB filename @INDEX_SUFFIX@
874 .BR @L_INDXBIB@ (@MAN1EXT@)
875 exists, then it will be searched instead;
876 each index can cover multiple databases.
879 .BI date-as-label\*n\ string
881 is a label expression that specifies a string with which to replace the
883 field after constructing the label.
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
892 In most cases you should also use the
893 .B no-label-in-reference
899 .B "date-as-label D.+yD.y%a*D.-y"
902 would attach a disambiguating letter to the year part of the
904 field in the reference.
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.
913 determines whether the default database should be searched
914 on the first occasion that it needs to do a search.
916 .B no-default-database
917 command must be given before then,
918 in order to be effective.
921 .BI discard\*n\ fields
922 When the reference is read,
925 no string definitions for
934 .BI et-al\*n\ string\ m\ n
939 expressions in label expressions.
940 If the number of authors needed to make the author sequence
943 and the total number of authors is
947 authors will be replaced by
957 The default behaviour is
966 .BI include\ filename
969 and interpret the contents as commands.
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
976 When there are more than two authors, all but the last two will
979 and the last two authors will be joined with
988 is also omitted it will also default to
995 join-authors " and " ", " ", and "
998 will restore the default method for joining authors.
1002 .B label-in-reference\*n
1003 When outputting the reference,
1006 to be the reference's label.
1007 This is the default behaviour; so the negative version
1008 of this command is more useful.
1012 For each reference output a label in the text.
1013 The label will be separated from the surrounding text as described in the
1016 This is the default behaviour; so the negative version
1017 of this command is more useful.
1022 is a label expression describing how to label each reference.
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
1029 See the description of the
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.
1040 .BI reverse\*n\ string
1041 Reverse the fields whose names
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.
1049 .BI search-ignore\*n\ fields
1050 While searching for keys in databases for which no index exists,
1051 ignore the contents of
1058 .BI search-truncate\*n\ n
1059 Only require the first
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
1065 and the length of the key.
1071 .BI short-label\*n\ string
1073 is a label expression that specifies an alternative (usually shorter)
1075 This is used when the
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.
1083 command will typically be used to specify a label containing just
1084 a date and possibly a disambiguating letter.
1088 Sort references according to
1090 References will automatically be accumulated.
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.
1095 can be used to indicate that all the fields with the name should be used.
1098 can be used to indicate the references should be sorted using the
1101 .B "Label expressions"
1102 subsection describes the concept of a tentative label.)
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
1114 This will have no effect unless references are being accumulated.
1117 .SS Label expressions
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
1130 commands are not evaluated tentatively.
1131 Normal and tentative evaluation are the same for all types
1132 of expression other than
1138 The description below applies to normal evaluation,
1139 except where otherwise specified.
1151 is omitted, it defaults to\ 1.
1161 All the authors joined as specified by the
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
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
1175 author of some reference
1176 is considered to be ambiguous if
1177 there is some other reference,
1180 authors of the references are the same,
1183 authors are not the same,
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
1195 this command may also specify additional requirements that must be
1196 met before an initial subsequence can be used.
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.
1212 The serial number of the reference formatted according to the character
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.
1221 If there is another reference with the same tentative label as
1222 this reference, then
1224 otherwise an empty string.
1225 It tentatively evaluates to an empty string.
1236 upper or lower case letters or digits of
1238 Troff special characters (such as
1240 count as a single letter.
1241 Accent strings are retained but do not count towards the total.
1246 converted to lowercase.
1251 converted to uppercase.
1256 converted to caps and small caps.
1261 reversed so that the last name is first.
1266 with first names abbreviated.
1267 Note that fields specified in the
1269 command are abbreviated before any labels are evaluated.
1272 is useful only when you want a field to be abbreviated in a label
1273 but not in a reference.
1284 before the year, or the whole of
1286 if it does not contain a year.
1292 after the year, or an empty string if
1294 does not contain a year.
1298 The last name part of
1302 .IB expr1 \(ti expr2
1304 except that if the last character of
1308 then it will be replaced by
1313 The concatenation of
1334 otherwise an empty string.
1337 .IB expr1 ? expr2 : expr3
1348 The label is in two parts, which are separated by
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
1369 The above expressions are listed in order of precedence
1374 have the same precedence.
1378 Each reference starts with a call to the macro
1382 will be defined to be the label for this reference,
1384 .B no-label-in-reference
1385 command has been given.
1386 There then follows a series of string definitions,
1390 corresponds to field
1396 field contains a range of pages.
1402 number registers are set to\ 1 according as the
1407 fields end with one of the characters
1411 number register will be set to\ 1 if the
1413 string contains more than one name.
1414 The reference is followed by a call to the
1417 The first argument to this macro gives a number representing
1418 the type of the reference.
1419 If a reference contains a
1421 field, it will be classified as type\ 1,
1422 otherwise if it contains a
1424 field, it will type\ 3,
1425 otherwise if it contains a
1429 field it will be type\ 4,
1430 otherwise if contains a
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:
1436 .BR journal-article ,
1441 Groups of references that have been accumulated
1442 or are produced by the
1444 command are preceded by a call to the
1446 macro and followed by a call to the
1454 .Tp \w'\fB@DEFAULT_INDEX@'u+2n
1459 .IB file @INDEX_SUFFIX@
1466 .Tp \w'\fBREFER'u+2n
1468 If set, overrides the default database.
1473 .BR @L_INDXBIB@ (@MAN1EXT@),
1474 .BR @L_LOOKBIB@ (@MAN1EXT@),
1475 .BR @L_LKBIB@ (@MAN1EXT@)
1481 In label expressions,
1483 expressions are ignored inside