2 Copyright (C) 1989-2000, 2001, 2002, 2003 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
24 .\" Like TP, but if specified indent is more than half
25 .\" the current line-length - indent, use the default indent.
27 .ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
30 .\" The BSD man macros can't handle " in arguments to font change macros,
31 .\" so use \(ts instead of ".
33 .TH @G@REFER @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
35 @g@refer \- preprocess bibliographic references for groff
40 .in +\w'\fB@g@refer 'u
44 .ie \\n(.$-1 .RI "[\ \fB\\$1\fP" "\\$2" "\ ]"
45 .el .RB "[\ " "\\$1" "\ ]"
58 .RI [\ filename \|.\|.\|.\ ]
62 It is possible to have whitespace between a command line option and its
65 This file documents the GNU version of
67 which is part of the groff document formatting system.
69 copies the contents of
70 .IR filename \|.\|.\|.\&
71 to the standard output,
72 except that lines between
76 are interpreted as citations,
81 are interpreted as commands about how citations are to be processed.
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.
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
98 commands that can be used by a macro package to produce a formatted
99 reference for each citation.
102 must therefore be processed using a suitable macro package.
107 macros are both suitable.
108 The commands to format a citation's reference can be output immediately after
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.
115 The interpretation of lines between
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
132 to the beginning of the document.
135 to ignore everything between
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.
146 lines so that filenames and line numbers in messages produced
147 by commands that read
149 output will be correct;
150 it also interprets lines beginning with
152 so that filenames and line numbers in the messages and
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@).
159 Most options are equivalent to commands
160 (for a description of these commands see the
166 no-label-in-text; no-label-in-reference
172 .B no-default-database
182 label "(A.n|Q) ', ' (D.y|D)"; bracket-label " (" ) "; "
222 .BI A.n+ m D.y\- n %a
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
240 command instead of in the normal way:
244 annotate X AP; no-label-in-reference
246 .BI \-B field . macro
250 .B no-label-in-reference
252 The following options have no equivalent commands:
255 Print the version number.
258 Don't recognize lines beginning with
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
266 at the beginning of a line.
267 Each field has a one character name that immediately follows the
269 It is best to use only upper and lower case letters for the names
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:
277 The name of an author.
278 If the name contains a title such as
281 it should be separated from the last name by a comma.
282 There can be multiple occurrences of the
285 The order is significant.
286 It is a good idea always to supply an
293 For an article that is part of a book, the title of the book.
296 The place (city) of publication.
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
306 if the date is unknown, a value such as
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
321 should be appended to the last author.
324 US Government ordering number.
327 The publisher (issuer).
330 For an article in a journal, the name of the journal.
333 Keywords to be used for searching.
339 Journal issue number.
343 This is usually printed at the end of the reference.
347 A range of pages can be specified as
351 The name of the author, if the author is not a person.
352 This will only be used if there are no
355 There can only be one
360 Technical report number.
367 For an article in a book or journal,
368 this should be the title of the article.
371 Volume number of the journal or book.
376 For all fields except
380 if there is more than one occurrence of a particular field in a record,
381 only the last such field will be used.
383 If accent strings are used, they should follow the character to be accented.
386 macro must be used with the
389 Accent strings should not be quoted:
394 The format of a citation is
411 components are optional.
416 components need be specified.
420 component says to search the bibliographic databases for a reference
421 that contains all the words in
423 It is an error if more than one reference if found.
427 components specifies additional fields to replace or supplement
428 those specified in the reference.
429 When references are being accumulated and the
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.
440 component specifies strings to be used to bracket the label instead
441 of the strings specified in the
444 If either of these components is non-empty,
445 the strings specified in the
447 command will not be used;
448 this behaviour can be altered using the
453 Note that leading and trailing spaces are significant for these components.
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:
465 This says to use the label specified by the
468 instead of that specified by the
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;
476 is supposed to be suggestive of a numeric type of label.
481 with the first string specified in the
488 with the second string specified in the
492 One advantages of using the
496 flags rather than including the brackets in
501 you can change the style of bracket used in the document just by changing the
504 Another advantage is that sorting and merging of citations
505 will not necessarily be inhibited if the flags are used.
507 If a label is to be inserted into the text,
508 it will be attached to the line preceding the
511 If there is no such line, then an extra line will be inserted before the
513 line and a warning will be given.
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
520 The labels may also be sorted or merged.
521 See the description of the
523 label expression, and of the
524 .B sort-adjacent-labels
526 .B abbreviate-label-ranges
528 A label will not be merged if its citation has a non-empty
532 However, the labels for a citation using the
536 immediately followed by a citation using the
540 may be sorted and merged
541 even though the first citation's
543 or the second citation's
546 (If you wish to prevent this just make the first citation's
550 Commands are contained between lines starting with
554 Recognition of these lines can be prevented by the
559 line is recognized any accumulated references are flushed out.
565 nor anything between them
568 Commands are separated by newlines or
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
579 that is not followed by another
583 the word extends to the end of the line.
586 in a word beginning with
594 are recognized inside
596 A line can be continued by ending it with
598 this works everywhere except after a
604 that is marked with \*n has an associated negative command
606 that undoes the effect of
610 command specifies that references should not be sorted.
611 The negative commands take no arguments.
613 In the following description each argument must be a single word;
615 is used for a single upper or lower case letter naming a field;
617 is used for a sequence of such letters;
621 are used for a non-negative numbers;
623 is used for an arbitrary string;
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
630 An initial letter will be separated from another initial letter by
632 from the last name by
634 and from anything else
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
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
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
656 followed by the last label.
657 This is mainly useful with numeric labels.
660 is omitted it defaults to
664 Accumulate references instead of writing out each reference
665 as it is encountered.
666 Accumulated references will be written out whenever a reference
677 after all input files hve been processed,
683 .BI annotate\*n\ field\ string
686 print it at the end of the reference as a paragraph preceded by the line
693 is omitted it will default to
697 is also omitted it will default to
699 Only one field can be an annotation.
702 .BI articles\ string \fR\|.\|.\|.
704 are definite or indefinite articles, and should be ignored at the beginning of
712 are recognized as articles.
714 .BI bibliography\ filename \fR\|.\|.\|.
715 Write out all the references contained in the bibliographic databases
716 .IR filename \|.\|.\|.
718 .BI bracket-label\ string1\ string2\ string3
719 In the text, bracket each label
726 immediately followed by
730 The default behaviour is
734 bracket-label \e*([. \e*(.] ", "
737 .BI capitalize\ fields
740 to caps and small caps.
747 even when followed by a character other than space or newline.
749 .BI database\ filename \fR\|.\|.\|.
750 Search the bibliographic databases
751 .IR filename \|.\|.\|.
755 .IB filename @INDEX_SUFFIX@
757 .BR @g@indxbib (@MAN1EXT@)
758 exists, then it will be searched instead;
759 each index can cover multiple databases.
761 .BI date-as-label\*n\ string
763 is a label expression that specifies a string with which to replace the
765 field after constructing the label.
767 .B "Label expressions"
768 subsection for a description of label expressions.
769 This command is useful if you do not want explicit labels in the
770 reference list, but instead want to handle any necessary
771 disambiguation by qualifying the date in some way.
772 The label used in the text would typically be some combination of the
774 In most cases you should also use the
775 .B no-label-in-reference
781 date-as-label D.+yD.y%a*D.-y
783 would attach a disambiguating letter to the year part of the
785 field in the reference.
788 .B default-database\*n
789 The default database should be searched.
790 This is the default behaviour, so the negative version of
791 this command is more useful.
792 refer determines whether the default database should be searched
793 on the first occasion that it needs to do a search.
795 .B no-default-database
796 command must be given before then,
797 in order to be effective.
799 .BI discard\*n\ fields
800 When the reference is read,
803 no string definitions for
811 .BI et-al\*n\ string\ m\ n
817 expressions in label expressions.
818 If the number of authors needed to make the author sequence
821 and the total number of authors is
825 authors will be replaced by
835 The default behaviour is
842 .BI include\ filename
845 and interpret the contents as commands.
847 .BI join-authors\ string1\ string2\ string3
848 This says how authors should be joined together.
849 When there are exactly two authors, they will be joined with
851 When there are more than two authors, all but the last two will
854 and the last two authors will be joined with
863 is also omitted it will also default to
869 join-authors " and " ", " ", and "
871 will restore the default method for joining authors.
874 .B label-in-reference\*n
875 When outputting the reference,
878 to be the reference's label.
879 This is the default behaviour; so the negative version
880 of this command is more useful.
883 For each reference output a label in the text.
884 The label will be separated from the surrounding text as described in the
887 This is the default behaviour; so the negative version
888 of this command is more useful.
892 is a label expression describing how to label each reference.
894 .BI separate-label-second-parts\ string
895 When merging two-part labels, separate the second part of the second
896 label from the first label with
898 See the description of the
902 .B move-punctuation\*n
903 In the text, move any punctuation at the end of line past the label.
904 It is usually a good idea to give this command unless you are using
905 superscripted numbers as labels.
907 .BI reverse\*n\ string
908 Reverse the fields whose names
911 Each field name can be followed by a number which says
912 how many such fields should be reversed.
913 If no number is given for a field, all such fields will be reversed.
915 .BI search-ignore\*n\ fields
916 While searching for keys in databases for which no index exists,
917 ignore the contents of
923 .BI search-truncate\*n\ n
924 Only require the first
926 characters of keys to be given.
927 In effect when searching for a given key
928 words in the database are truncated to the maximum of
930 and the length of the key.
935 .BI short-label\*n\ string
937 is a label expression that specifies an alternative (usually shorter)
939 This is used when the
941 flag is given in the citation.
942 When using author-date style labels, the identity of the author
943 or authors is sometimes clear from the context, and so it
944 may be desirable to omit the author or authors from the label.
947 command will typically be used to specify a label containing just
948 a date and possibly a disambiguating letter.
951 Sort references according to
953 References will automatically be accumulated.
955 should be a list of field names, each followed by a number,
956 indicating how many fields with the name should be used for sorting.
958 can be used to indicate that all the fields with the name should be used.
961 can be used to indicate the references should be sorted using the
966 subsection describes the concept of a tentative label.)
968 .B sort-adjacent-labels\*n
969 Sort labels that are adjacent in the text according to their
970 position in the reference list.
971 This command should usually be given if the
972 .B abbreviate-label-ranges
973 command has been given,
974 or if the label expression contains a
977 This will have no effect unless references are being accumulated.
978 .SS Label expressions
980 Label expressions can be evaluated both normally and tentatively.
981 The result of normal evaluation is used for output.
982 The result of tentative evaluation, called the
985 is used to gather the information
986 that normal evaluation needs to disambiguate the label.
987 Label expressions specified by the
991 commands are not evaluated tentatively.
992 Normal and tentative evaluation are the same for all types
993 of expression other than
999 The description below applies to normal evaluation,
1000 except where otherwise specified.
1011 is omitted, it defaults to 1.
1019 All the authors joined as specified by the
1022 The whole of each author's name will be used.
1023 However, if the references are sorted by author
1024 (that is the sort specification starts with
1026 then authors' last names will be used instead, provided that this does
1027 not introduce ambiguity,
1028 and also an initial subsequence of the authors may be used
1029 instead of all the authors, again provided that this does not
1030 introduce ambiguity.
1031 The use of only the last name for the
1033 author of some reference
1034 is considered to be ambiguous if
1035 there is some other reference,
1038 authors of the references are the same,
1041 authors are not the same,
1044 authors' last names are the same.
1045 A proper initial subsequence of the sequence
1046 of authors for some reference is considered to be ambiguous if there is
1047 a reference with some other sequence of authors which also has
1048 that subsequence as a proper initial subsequence.
1049 When an initial subsequence of authors is used, the remaining
1050 authors are replaced by the string specified by the
1053 this command may also specify additional requirements that must be
1054 met before an initial subsequence can be used.
1056 tentatively evaluates to a canonical representation of the authors,
1057 such that authors that compare equally for sorting purpose
1058 will have the same representation.
1069 The serial number of the reference formatted according to the character
1072 The serial number of a reference is 1 plus the number of earlier references
1073 with same tentative label as this reference.
1074 These expressions tentatively evaluate to an empty string.
1077 If there is another reference with the same tentative label as
1078 this reference, then
1080 otherwise an empty string.
1081 It tentatively evaluates to an empty string.
1091 upper or lower case letters or digits of
1093 Troff special characters (such as
1095 count as a single letter.
1096 Accent strings are retained but do not count towards the total.
1100 converted to lowercase.
1104 converted to uppercase.
1108 converted to caps and small caps.
1112 reversed so that the last name is first.
1116 with first names abbreviated.
1117 Note that fields specified in the
1119 command are abbreviated before any labels are evaluated.
1122 is useful only when you want a field to be abbreviated in a label
1123 but not in a reference.
1132 before the year, or the whole of
1134 if it does not contain a year.
1139 after the year, or an empty string if
1141 does not contain a year.
1144 The last name part of
1147 .IB expr1 \(ti expr2
1149 except that if the last character of
1153 then it will be replaced by
1157 The concatenation of
1176 otherwise an empty string.
1178 .IB expr1 ? expr2 : expr3
1188 The label is in two parts, which are separated by
1190 Two adjacent two-part labels which have the same first part will be
1191 merged by appending the second part of the second label onto the first
1192 label separated by the string specified in the
1193 .B separate-label-second-parts
1194 command (initially, a comma followed by a space); the resulting label
1195 will also be a two-part label with the same first part as before
1196 merging, and so additional labels can be merged into it.
1197 Note that it is permissible for the first part to be empty;
1198 this maybe desirable for expressions used in the
1207 The above expressions are listed in order of precedence
1212 have the same precedence.
1214 Each reference starts with a call to the macro
1218 will be defined to be the label for this reference,
1220 .B no-label-in-reference
1221 command has been given.
1222 There then follows a series of string definitions,
1226 corresponds to field
1232 field contains a range of pages.
1238 number registers are set to 1 according as the
1243 fields end with one of the characters
1247 number register will be set to 1 if the
1249 string contains more than one name.
1250 The reference is followed by a call to the
1253 The first argument to this macro gives a number representing
1254 the type of the reference.
1255 If a reference contains a
1257 field, it will be classified as type 1,
1258 otherwise if it contains a
1260 field, it will type 3,
1261 otherwise if it contains a
1265 field it will be type 4,
1266 otherwise if contains a
1268 field it will be type 2,
1269 otherwise it will be type 0.
1270 The second argument is a symbolic name for the type:
1272 .BR journal-article ,
1277 Groups of references that have been accumulated
1278 or are produced by the
1280 command are preceded by a call to the
1282 macro and followed by a call to the
1286 .Tp \w'\fB@DEFAULT_INDEX@'u+2n
1290 .IB file @INDEX_SUFFIX@
1293 .Tp \w'\fBREFER'u+2n
1295 If set, overrides the default database.
1297 .BR @g@indxbib (@MAN1EXT@),
1298 .BR @g@lookbib (@MAN1EXT@),
1299 .BR lkbib (@MAN1EXT@)
1302 In label expressions,
1304 expressions are ignored inside
1308 .\" Local Variables:
projects / dragonfly.git / blob