1 .TH @G@REFER @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
3 @g@refer \- preprocess bibliographic references for groff
6 .\" --------------------------------------------------------------------
8 .\" --------------------------------------------------------------------
11 Copyright \[co] 1989-2014 Free Software Foundation, Inc.
13 Permission is granted to make and distribute verbatim copies of
14 this manual provided the copyright notice and this permission notice
15 are preserved on all copies.
17 Permission is granted to copy and distribute modified versions of this
18 manual under the conditions for verbatim copying, provided that the
19 entire resulting derived work is distributed under the terms of a
20 permission notice identical to this one.
22 Permission is granted to copy and distribute translations of this
23 manual into another language, under the above conditions for modified
24 versions, except that this permission notice may be included in
25 translations approved by the Free Software Foundation instead of in
29 .\" --------------------------------------------------------------------
31 .\" --------------------------------------------------------------------
39 .\" Like TP, but if specified indent is more than half
40 .\" the current line-length - indent, use the default indent.
42 . ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
46 .\" The BSD man macros can't handle " in arguments to font change macros,
47 .\" so use \(ts instead of ".
51 .\" --------------------------------------------------------------------
53 .\" --------------------------------------------------------------------
58 .in +\w'\fB@g@refer 'u
63 . ie \\n(.$-1 .RI "[\ \fB\\$1\fP" "\\$2" "\ ]"
64 . el .RB "[\ " "\\$1" "\ ]"
78 .RI [\ \%filename \|.\|.\|.\ ]
83 \" --------------------------------------------------------------------
85 .\" --------------------------------------------------------------------
87 This file documents the GNU version of
89 which is part of the groff document formatting system.
92 copies the contents of
93 .IR filename \|.\|.\|.\&
94 to the standard output,
95 except that lines between
99 are interpreted as citations,
104 are interpreted as commands about how citations are to be processed.
108 Each citation specifies a reference.
110 The citation can specify a reference that is contained in
111 a bibliographic database by giving a set of keywords
112 that only that reference contains.
114 Alternatively it can specify a reference by supplying a database
115 record in the citation.
117 A combination of these alternatives is also possible.
123 can produce a mark in the text.
125 This mark consists of some label which can be separated from
126 the text and from other labels in various ways.
128 For each reference it also outputs
130 commands that can be used by a macro package to produce a formatted
131 reference for each citation.
135 must therefore be processed using a suitable macro package.
141 macros are both suitable.
143 The commands to format a citation's reference can be output immediately after
145 or the references may be accumulated,
146 and the commands output at some later point.
148 If the references are accumulated, then multiple citations of the same
149 reference will produce a single formatted reference.
153 The interpretation of lines between
157 as commands is a new feature of GNU
160 Documents making use of this feature can still be processed by
161 Unix refer just by adding the lines
174 to the beginning of the document.
178 to ignore everything between
183 The effect of some commands can also be achieved by options.
185 These options are supported mainly for compatibility with Unix refer.
187 It is usually more convenient to use commands.
194 lines so that filenames and line numbers in messages produced
195 by commands that read
197 output will be correct;
198 it also interprets lines beginning with
200 so that filenames and line numbers in the messages and
202 lines that it produces will be accurate even if the input has been
203 preprocessed by a command such as
204 .BR @g@soelim (@MAN1EXT@).
207 .\" --------------------------------------------------------------------
209 .\" --------------------------------------------------------------------
211 It is possible to have whitespace between a command line option and its
216 Most options are equivalent to commands
217 (for a description of these commands see the
226 .B "no-label-in-text; no-label-in-reference"
236 .B no-default-database
252 label\ "(A.n|Q)\ ',\ '\ (D.y|D)"; \%bracket-label\ "\ ("\ )\ ";\ "
312 .BI A.n+ m D.y\- n %a
335 These options are equivalent to the following commands with the
336 addition that the filenames specified on the command line are
337 processed as if they were arguments to the
339 command instead of in the normal way:
344 .B "annotate X AP; no-label-in-reference"
348 .BI \-B field . macro
352 .B no-label-in-reference
356 The following options have no equivalent commands:
361 Print the version number.
366 Don't recognize lines beginning with
370 .\" --------------------------------------------------------------------
372 .\" --------------------------------------------------------------------
374 .\" --------------------------------------------------------------------
375 .SS Bibliographic databases
376 .\" --------------------------------------------------------------------
378 The bibliographic database is a text file consisting of records
379 separated by one or more blank lines.
381 Within each record fields start with a
383 at the beginning of a line.
385 Each field has a one character name that immediately follows the
387 It is best to use only upper and lower case letters for the names
390 The name of the field should be followed by exactly one space,
391 and then by the contents of the field.
393 Empty fields are ignored.
395 The conventional meaning of each field is as follows:
400 The name of an author.
402 If the name contains a title such as
405 it should be separated from the last name by a comma.
407 There can be multiple occurrences of the
411 The order is significant.
413 It is a good idea always to supply an
422 For an article that is part of a book, the title of the book.
427 The place (city) of publication.
432 The date of publication.
434 The year should be specified in full.
436 If the month is specified, the name rather than the number of the month
437 should be used, but only the first three letters are required.
439 It is a good idea always to supply a
442 if the date is unknown, a value such as
451 For an article that is part of a book, the name of an editor of the book.
453 Where the work has editors and no authors,
454 the names of the editors should be given as
460 should be appended to the last author.
465 US Government ordering number.
470 The publisher (issuer).
475 For an article in a journal,
476 the name of the journal.
481 Keywords to be used for searching.
491 Journal issue number.
498 This is usually printed at the end of the reference.
504 A range of pages can be specified as
510 The name of the author, if the author is not a person.
512 This will only be used if there are no
516 There can only be one
523 Technical report number.
535 For an article in a book or journal,
536 this should be the title of the article.
541 Volume number of the journal or book.
550 For all fields except
554 if there is more than one occurrence of a particular field in a record,
555 only the last such field will be used.
559 If accent strings are used, they should follow the character to be accented.
562 macro must be used with the
566 Accent strings should not be quoted:
572 .\" --------------------------------------------------------------------
574 .\" --------------------------------------------------------------------
576 The format of a citation is
595 components are optional.
601 components need be specified.
607 component says to search the bibliographic databases for a reference
608 that contains all the words in
611 It is an error if more than one reference if found.
617 components specifies additional fields to replace or supplement
618 those specified in the reference.
620 When references are being accumulated and the
622 component is non-empty,
623 then additional fields should be specified only on the first
624 occasion that a particular reference is cited,
625 and will apply to all citations of that reference.
633 component specifies strings to be used to bracket the label instead
634 of the strings specified in the
638 If either of these components is non-empty,
639 the strings specified in the
641 command will not be used;
642 this behaviour can be altered using the
647 Note that leading and trailing spaces are significant for these components.
653 component is a list of
654 non-alphanumeric characters each of which modifies the treatment
655 of this particular citation.
657 Unix refer will treat these flags as part of the keywords and
658 so will ignore them since they are non-alphanumeric.
660 The following flags are currently recognized:
665 This says to use the label specified by the
668 instead of that specified by the
672 If no short label has been specified, the normal label will be used.
674 Typically the short label is used with author-date labels
675 and consists of only the date and possibly a disambiguating letter;
678 is supposed to be suggestive of a numeric type of label.
685 with the first string specified in the
694 with the second string specified in the
700 One advantages of using the
704 flags rather than including the brackets in
709 you can change the style of bracket used in the document just by changing the
713 Another advantage is that sorting and merging of citations
714 will not necessarily be inhibited if the flags are used.
718 If a label is to be inserted into the text,
719 it will be attached to the line preceding the
723 If there is no such line, then an extra line will be inserted before the
725 line and a warning will be given.
729 There is no special notation for making a citation to multiple references.
730 Just use a sequence of citations, one for each reference.
732 Don't put anything between the citations.
734 The labels for all the citations will be attached to the line preceding
737 The labels may also be sorted or merged.
739 See the description of the
741 label expression, and of the
742 .B sort-adjacent-labels
744 .B abbreviate-label-ranges
746 A label will not be merged if its citation has a non-empty
752 the labels for a citation using the
756 immediately followed by a citation using the
760 may be sorted and merged
761 even though the first citation's
763 or the second citation's
767 (If you wish to prevent this just make the first citation's
772 .\" --------------------------------------------------------------------
774 .\" --------------------------------------------------------------------
776 Commands are contained between lines starting with
781 Recognition of these lines can be prevented by the
787 line is recognized any accumulated references are flushed out.
794 nor anything between them
799 Commands are separated by newlines or
802 introduces a comment that extends to the end of the line
803 (but does not conceal the newline).
805 Each command is broken up into words.
807 Words are separated by spaces or tabs.
809 A word that begins with
813 that is not followed by another
818 the word extends to the end of the line.
822 in a word beginning with
831 are recognized inside
834 A line can be continued by ending it with
836 this works everywhere except after a
844 that is marked with \*n has an associated negative command
846 that undoes the effect of
851 command specifies that references should not be sorted.
853 The negative commands take no arguments.
857 In the following description each argument must be a single word;
859 is used for a single upper or lower case letter naming a field;
861 is used for a sequence of such letters;
865 are used for a non-negative numbers;
867 is used for an arbitrary string;
869 is used for the name of a file.
872 .Tp \w'\fBabbreviate-label-ranges'u+2n
873 .BI abbreviate\*n\ fields\ string1\ string2\ string3\ string4
874 Abbreviate the first names of
877 An initial letter will be separated from another initial letter by
879 from the last name by
881 and from anything else
889 These default to a period followed by a space.
891 In a hyphenated first name,
892 the initial of the first part of the name will be separated from the
895 this defaults to a period.
897 No attempt is made to handle any ambiguities that might
898 result from abbreviation.
900 Names are abbreviated before sorting and before label construction.
904 .BI abbreviate-label-ranges\*n\ string
906 Three or more adjacent labels that refer to consecutive references
907 will be abbreviated to a label consisting of the first label,
910 followed by the last label.
912 This is mainly useful with numeric labels.
916 is omitted it defaults to
922 Accumulate references instead of writing out each reference
923 as it is encountered.
925 Accumulated references will be written out whenever a reference
939 after all input files have been processed,
947 .BI annotate\*n\ field\ string
950 print it at the end of the reference as a paragraph preceded by the line
960 is omitted it will default to
964 is also omitted it will default to
967 Only one field can be an annotation.
972 .BI articles\ string \fR\|.\|.\|.
973 .IR string \|.\|.\|.\&
974 are definite or indefinite articles, and should be ignored at the beginning of
983 are recognized as articles.
987 .BI bibliography\ filename \fR\|.\|.\|.
989 Write out all the references contained in the bibliographic databases
990 .IR filename \|.\|.\|.
992 This command should come last in a
998 .BI bracket-label\ string1\ string2\ string3
999 In the text, bracket each label
1007 immediately followed by
1012 The default behaviour is
1017 bracket-label \e*([. \e*(.] ", "
1022 .BI capitalize\ fields
1025 to caps and small caps.
1034 even when followed by a character other than space or newline.
1038 .BI database\ filename \fR\|.\|.\|.
1039 Search the bibliographic databases
1040 .IR filename \|.\|.\|.
1045 .IB filename @INDEX_SUFFIX@
1047 .BR @g@indxbib (@MAN1EXT@)
1048 exists, then it will be searched instead;
1049 each index can cover multiple databases.
1053 .BI date-as-label\*n\ string
1055 is a label expression that specifies a string with which to replace the
1057 field after constructing the label.
1060 .B "Label expressions"
1061 subsection for a description of label expressions.
1063 This command is useful if you do not want explicit labels in the
1065 but instead want to handle any necessary disambiguation by qualifying
1066 the date in some way.
1068 The label used in the text would typically be some combination of the
1071 In most cases you should also use the
1072 .B no-label-in-reference
1078 .B "date-as-label D.+yD.y%a*D.-y"
1082 would attach a disambiguating letter to the year part of the
1084 field in the reference.
1089 .B default-database\*n
1090 The default database should be searched.
1092 This is the default behaviour,
1093 so the negative version of this command is more useful.
1096 determines whether the default database should be searched
1097 on the first occasion that it needs to do a search.
1100 .B no-default-database
1101 command must be given before then,
1102 in order to be effective.
1106 .BI discard\*n\ fields
1107 When the reference is read,
1109 should be discarded;
1110 no string definitions for
1121 .BI et-al\*n\ string\ m\ n
1124 in the evaluation of
1126 expressions in label expressions.
1128 If the number of authors needed to make the author sequence
1131 and the total number of authors is
1135 authors will be replaced by
1146 The default behaviour is
1156 .BI include\ filename
1159 and interpret the contents as commands.
1163 .BI join-authors\ string1\ string2\ string3
1164 This says how authors should be joined together.
1166 When there are exactly two authors, they will be joined with
1169 When there are more than two authors,
1170 all but the last two will be joined with
1172 and the last two authors will be joined with
1182 is also omitted it will also default to
1190 join-authors " and " ", " ", and "
1194 will restore the default method for joining authors.
1199 .B label-in-reference\*n
1200 When outputting the reference,
1203 to be the reference's label.
1205 This is the default behaviour; so the negative version
1206 of this command is more useful.
1211 For each reference output a label in the text.
1213 The label will be separated from the surrounding text as described in the
1217 This is the default behaviour; so the negative version
1218 of this command is more useful.
1224 is a label expression describing how to label each reference.
1228 .BI separate-label-second-parts\ string
1229 When merging two-part labels, separate the second part of the second
1230 label from the first label with
1233 See the description of the
1239 .B move-punctuation\*n
1241 move any punctuation at the end of line past the label.
1243 It is usually a good idea to give this command unless you are using
1244 superscripted numbers as labels.
1248 .BI reverse\*n\ string
1249 Reverse the fields whose names
1253 Each field name can be followed by a number which says
1254 how many such fields should be reversed.
1256 If no number is given for a field, all such fields will be reversed.
1260 .BI search-ignore\*n\ fields
1261 While searching for keys in databases for which no index exists,
1262 ignore the contents of
1271 .BI search-truncate\*n\ n
1272 Only require the first
1274 characters of keys to be given.
1276 In effect when searching for a given key words in the database are
1277 truncated to the maximum of
1279 and the length of the key.
1287 .BI short-label\*n\ string
1289 is a label expression that specifies an alternative (usually shorter)
1292 This is used when the
1294 flag is given in the citation.
1296 When using author-date style labels, the identity of the author
1297 or authors is sometimes clear from the context, and so it
1298 may be desirable to omit the author or authors from the label.
1302 command will typically be used to specify a label containing just
1303 a date and possibly a disambiguating letter.
1308 Sort references according to
1311 References will automatically be accumulated.
1314 should be a list of field names,
1315 each followed by a number,
1316 indicating how many fields with the name should be used for sorting.
1319 can be used to indicate that all the fields with the name should be used.
1323 can be used to indicate the references should be sorted using the
1327 .B "Label expressions"
1328 subsection describes the concept of a tentative label.)
1332 .B sort-adjacent-labels\*n
1333 Sort labels that are adjacent in the text according to their position
1334 in the reference list.
1336 This command should usually be given if the
1337 .B abbreviate-label-ranges
1338 command has been given,
1339 or if the label expression contains a
1343 This will have no effect unless references are being accumulated.
1346 .\" --------------------------------------------------------------------
1347 .SS Label expressions
1348 .\" --------------------------------------------------------------------
1350 Label expressions can be evaluated both normally and tentatively.
1352 The result of normal evaluation is used for output.
1354 The result of tentative evaluation, called the
1355 .IR "tentative label" ,
1356 is used to gather the information that normal evaluation needs to
1357 disambiguate the label.
1359 Label expressions specified by the
1363 commands are not evaluated tentatively.
1365 Normal and tentative evaluation are the same for all types of
1366 expression other than
1373 The description below applies to normal evaluation,
1374 except where otherwise specified.
1388 is omitted, it defaults to\ 1.
1400 All the authors joined as specified by the
1404 The whole of each author's name will be used.
1406 However, if the references are sorted by author (that is the sort
1407 specification starts with
1409 then authors last names will be used instead,
1410 provided that this does not introduce ambiguity,
1411 and also an initial subsequence of the authors may be used instead of
1413 again provided that this does not introduce ambiguity.
1415 The use of only the last name for the
1417 author of some reference
1418 is considered to be ambiguous if
1419 there is some other reference,
1422 authors of the references are the same,
1425 authors are not the same,
1428 authors last names are the same.
1430 A proper initial subsequence of the sequence of authors for some
1431 reference is considered to be ambiguous if there is a reference with
1432 some other sequence of authors which also has that subsequence as a
1433 proper initial subsequence.
1435 When an initial subsequence of authors is used, the remaining authors
1436 are replaced by the string specified by the
1439 this command may also specify additional requirements that must be
1440 met before an initial subsequence can be used.
1443 tentatively evaluates to a canonical representation of the authors,
1444 such that authors that compare equally for sorting purpose will have
1445 the same representation.
1458 The serial number of the reference formatted according to the
1459 character following the
1461 The serial number of a reference is\ 1 plus the number of earlier
1462 references with same tentative label as this reference.
1464 These expressions tentatively evaluate to an empty string.
1468 If there is another reference with the same tentative label as this
1472 otherwise an empty string.
1474 It tentatively evaluates to an empty string.
1486 upper or lower case letters or digits of
1489 Troff special characters (such as
1491 count as a single letter.
1493 Accent strings are retained but do not count towards the total.
1499 converted to lowercase.
1505 converted to uppercase.
1511 converted to caps and small caps.
1517 reversed so that the last name is first.
1523 with first names abbreviated.
1525 Note that fields specified in the
1527 command are abbreviated before any labels are evaluated.
1531 is useful only when you want a field to be abbreviated in a label
1532 but not in a reference.
1548 if it does not contain a year.
1556 or an empty string if
1558 does not contain a year.
1563 The last name part of
1568 .IB expr1 \(ti expr2
1570 except that if the last character of
1574 then it will be replaced by
1580 The concatenation of
1603 otherwise an empty string.
1607 .IB expr1 ? expr2 : expr3
1619 The label is in two parts, which are separated by
1622 Two adjacent two-part labels which have the same first part will be
1623 merged by appending the second part of the second label onto the first
1624 label separated by the string specified in the
1625 .B separate-label-second-parts
1627 a comma followed by a space);
1628 the resulting label will also be a two-part label with the same first
1629 part as before merging,
1630 and so additional labels can be merged into it.
1632 Note that it is permissible for the first part to be empty;
1633 this maybe desirable for expressions used in the
1647 The above expressions are listed in order of precedence
1652 have the same precedence.
1655 .\" --------------------------------------------------------------------
1657 .\" --------------------------------------------------------------------
1659 Each reference starts with a call to the macro
1664 will be defined to be the label for this reference,
1666 .B no-label-in-reference
1667 command has been given.
1669 There then follows a series of string definitions,
1673 corresponds to field
1680 field contains a range of pages.
1687 number registers are set to\ 1 according as the
1692 fields end with one of the characters
1697 number register will be set to\ 1 if the
1699 string contains more than one name.
1701 The reference is followed by a call to the
1705 The first argument to this macro gives a number representing
1706 the type of the reference.
1708 If a reference contains a
1710 field, it will be classified as type\ 1,
1711 otherwise if it contains a
1713 field, it will type\ 3,
1714 otherwise if it contains a
1718 field it will be type\ 4,
1719 otherwise if contains a
1721 field it will be type\ 2,
1722 otherwise it will be type\ 0.
1724 The second argument is a symbolic name for the type:
1726 .BR journal-article ,
1732 Groups of references that have been accumulated or are produced by the
1734 command are preceded by a call to the
1736 macro and followed by a call to the
1741 .\" --------------------------------------------------------------------
1743 .\" --------------------------------------------------------------------
1745 .Tp \w'\fB@DEFAULT_INDEX@'u+2n
1751 .IB file @INDEX_SUFFIX@
1757 uses temporary files.
1760 .BR groff (@MAN1EXT@)
1761 man page for details where such files are created.
1764 .\" --------------------------------------------------------------------
1766 .\" --------------------------------------------------------------------
1768 .Tp \w'\fBREFER'u+2n
1770 If set, overrides the default database.
1773 .\" --------------------------------------------------------------------
1775 .\" --------------------------------------------------------------------
1777 .BR @g@indxbib (@MAN1EXT@),
1778 .BR @g@lookbib (@MAN1EXT@),
1779 .BR lkbib (@MAN1EXT@)
1783 .\" --------------------------------------------------------------------
1785 .\" --------------------------------------------------------------------
1787 In label expressions,
1789 expressions are ignored inside
1794 .\" --------------------------------------------------------------------
1796 .\" --------------------------------------------------------------------
1800 .\" Local Variables:
projects / platform / upstream / groff.git / blob