1 .TH @G@REFER @MAN1EXT@ "@MDATE@" "groff @VERSION@"
3 @g@refer \- preprocess bibliographic references for groff
6 .\" ====================================================================
8 .\" ====================================================================
10 .\" Copyright (C) 1989-2018 Free Software Foundation, Inc.
12 .\" Permission is granted to make and distribute verbatim copies of this
13 .\" manual provided the copyright notice and this permission notice are
14 .\" preserved on all copies.
16 .\" Permission is granted to copy and distribute modified versions of
17 .\" this manual under the conditions for verbatim copying, provided that
18 .\" the entire resulting derived work is distributed under the terms of
19 .\" a permission notice identical to this one.
21 .\" Permission is granted to copy and distribute translations of this
22 .\" manual into another language, under the above conditions for
23 .\" modified versions, except that this permission notice may be
24 .\" included in translations approved by the Free Software Foundation
25 .\" instead of in the original English.
28 .\" ====================================================================
30 .\" ====================================================================
43 .BI "\-B " field . macro
59 .\" ====================================================================
61 .\" ====================================================================
63 This file documents the GNU version of
65 which is part of the groff document formatting system.
68 copies the contents of
69 .IR filename \|.\|.\|.\&
70 to the standard output,
71 except that lines between
75 are interpreted as citations,
80 are interpreted as commands about how citations are to be processed.
84 Each citation specifies a reference.
86 The citation can specify a reference that is contained in
87 a bibliographic database by giving a set of keywords
88 that only that reference contains.
90 Alternatively it can specify a reference by supplying a database
91 record in the citation.
93 A combination of these alternatives is also possible.
99 can produce a mark in the text.
101 This mark consists of some label which can be separated from
102 the text and from other labels in various ways.
104 For each reference it also outputs
106 commands that can be used by a macro package to produce a formatted
107 reference for each citation.
111 must therefore be processed using a suitable macro package.
117 macros are both suitable.
119 The commands to format a citation's reference can be output immediately after
121 or the references may be accumulated,
122 and the commands output at some later point.
124 If the references are accumulated, then multiple citations of the same
125 reference will produce a single formatted reference.
129 The interpretation of lines between
133 as commands is a new feature of GNU
136 Documents making use of this feature can still be processed by
137 Unix refer just by adding the lines
150 to the beginning of the document.
154 to ignore everything between
159 The effect of some commands can also be achieved by options.
161 These options are supported mainly for compatibility with Unix refer.
163 It is usually more convenient to use commands.
170 lines so that filenames and line numbers in messages produced
171 by commands that read
173 output will be correct;
174 it also interprets lines beginning with
176 so that filenames and line numbers in the messages and
178 lines that it produces will be accurate even if the input has been
179 preprocessed by a command such as
180 .BR @g@soelim (@MAN1EXT@).
183 .\" ====================================================================
185 .\" ====================================================================
187 Whitespace is permitted between a command-line option and its argument.
191 Most options are equivalent to commands
192 (for a description of these commands,
193 see subsection \(lqCommands\(rq below).
200 .B "no-label-in-text; no-label-in-reference"
210 .B no-default-database
226 label\ "(A.n|Q)\ ',\ '\ (D.y|D)"; \%bracket-label\ "\ ("\ )\ ";\ "
286 .BI A.n+ m D.y\- n %a
309 These options are equivalent to the following commands with the
310 addition that the filenames specified on the command line are
311 processed as if they were arguments to the
313 command instead of in the normal way:
318 .B "annotate X AP; no-label-in-reference"
322 .BI \-B field . macro
326 .B no-label-in-reference
330 The following options have no equivalent commands:
335 Print the version number.
340 Don't recognize lines beginning with
344 .\" ====================================================================
346 .\" ====================================================================
348 .\" ====================================================================
349 .SS Bibliographic databases
350 .\" ====================================================================
352 The bibliographic database is a text file consisting of records
353 separated by one or more blank lines.
355 Within each record fields start with a
357 at the beginning of a line.
359 Each field has a one character name that immediately follows the
361 It is best to use only upper and lower case letters for the names
364 The name of the field should be followed by exactly one space,
365 and then by the contents of the field.
367 Empty fields are ignored.
369 The conventional meaning of each field is as follows:
374 The name of an author.
376 If the name contains a title such as
379 it should be separated from the last name by a comma.
381 There can be multiple occurrences of the
385 The order is significant.
387 It is a good idea always to supply an
396 For an article that is part of a book, the title of the book.
401 The place (city) of publication.
406 The date of publication.
408 The year should be specified in full.
410 If the month is specified, the name rather than the number of the month
411 should be used, but only the first three letters are required.
413 It is a good idea always to supply a
416 if the date is unknown, a value such as
425 For an article that is part of a book, the name of an editor of the book.
427 Where the work has editors and no authors,
428 the names of the editors should be given as
434 should be appended to the last author.
439 US Government ordering number.
444 The publisher (issuer).
449 For an article in a journal,
450 the name of the journal.
455 Keywords to be used for searching.
465 Journal issue number.
472 This is usually printed at the end of the reference.
478 A range of pages can be specified as
484 The name of the author, if the author is not a person.
486 This will only be used if there are no
490 There can only be one
497 Technical report number.
509 For an article in a book or journal,
510 this should be the title of the article.
515 Volume number of the journal or book.
524 For all fields except
528 if there is more than one occurrence of a particular field in a record,
529 only the last such field will be used.
533 If accent strings are used, they should follow the character to be accented.
536 macro must be used with the
540 Accent strings should not be quoted:
546 .\" ====================================================================
548 .\" ====================================================================
550 The format of a citation is
569 components are optional.
575 components need be specified.
581 component says to search the bibliographic databases for a reference
582 that contains all the words in
585 It is an error if more than one reference if found.
591 components specifies additional fields to replace or supplement
592 those specified in the reference.
594 When references are being accumulated and the
596 component is non-empty,
597 then additional fields should be specified only on the first
598 occasion that a particular reference is cited,
599 and will apply to all citations of that reference.
607 component specifies strings to be used to bracket the label instead
608 of the strings specified in the
612 If either of these components is non-empty,
613 the strings specified in the
615 command will not be used;
616 this behaviour can be altered using the
621 Note that leading and trailing spaces are significant for these components.
627 component is a list of
628 non-alphanumeric characters each of which modifies the treatment
629 of this particular citation.
631 Unix refer will treat these flags as part of the keywords and
632 so will ignore them since they are non-alphanumeric.
634 The following flags are currently recognized:
639 This says to use the label specified by the
642 instead of that specified by the
646 If no short label has been specified, the normal label will be used.
648 Typically the short label is used with author-date labels
649 and consists of only the date and possibly a disambiguating letter;
652 is supposed to be suggestive of a numeric type of label.
659 with the first string specified in the
668 with the second string specified in the
674 One advantages of using the
678 flags rather than including the brackets in
683 you can change the style of bracket used in the document just by changing the
687 Another advantage is that sorting and merging of citations
688 will not necessarily be inhibited if the flags are used.
692 If a label is to be inserted into the text,
693 it will be attached to the line preceding the
697 If there is no such line, then an extra line will be inserted before the
699 line and a warning will be given.
703 There is no special notation for making a citation to multiple references.
704 Just use a sequence of citations, one for each reference.
706 Don't put anything between the citations.
708 The labels for all the citations will be attached to the line preceding
711 The labels may also be sorted or merged.
713 See the description of the
715 label expression, and of the
716 .B sort-adjacent-labels
718 .B abbreviate-label-ranges
720 A label will not be merged if its citation has a non-empty
726 the labels for a citation using the
730 immediately followed by a citation using the
734 may be sorted and merged
735 even though the first citation's
737 or the second citation's
741 (If you wish to prevent this just make the first citation's
746 .\" ====================================================================
748 .\" ====================================================================
750 Commands are contained between lines starting with
755 Recognition of these lines can be prevented by the
761 line is recognized any accumulated references are flushed out.
768 nor anything between them
773 Commands are separated by newlines or
776 introduces a comment that extends to the end of the line
777 (but does not conceal the newline).
779 Each command is broken up into words.
781 Words are separated by spaces or tabs.
783 A word that begins with
787 that is not followed by another
792 the word extends to the end of the line.
796 in a word beginning with
805 are recognized inside
808 A line can be continued by ending it with
810 this works everywhere except after a
818 that is marked with \*n has an associated negative command
820 that undoes the effect of
825 command specifies that references should not be sorted.
827 The negative commands take no arguments.
831 In the following description each argument must be a single word;
833 is used for a single upper or lower case letter naming a field;
835 is used for a sequence of such letters;
839 are used for a non-negative numbers;
841 is used for an arbitrary string;
843 is used for the name of a file.
847 .BI abbreviate\*n\ fields\ string1\ string2\ string3\ string4
848 Abbreviate the first names of
851 An initial letter will be separated from another initial letter by
853 from the last name by
855 and from anything else
863 These default to a period followed by a space.
865 In a hyphenated first name,
866 the initial of the first part of the name will be separated from the
869 this defaults to a period.
871 No attempt is made to handle any ambiguities that might
872 result from abbreviation.
874 Names are abbreviated before sorting and before label construction.
878 .BI abbreviate-label-ranges\*n\ string
880 Three or more adjacent labels that refer to consecutive references
881 will be abbreviated to a label consisting of the first label,
884 followed by the last label.
886 This is mainly useful with numeric labels.
890 is omitted it defaults to
896 Accumulate references instead of writing out each reference
897 as it is encountered.
899 Accumulated references will be written out whenever a reference
913 after all input files have been processed,
921 .BI annotate\*n\ field\ string
924 print it at the end of the reference as a paragraph preceded by the line
934 is omitted it will default to
938 is also omitted it will default to
941 Only one field can be an annotation.
946 .BI articles\ string \fR\|.\|.\|.
947 .IR string \|.\|.\|.\&
948 are definite or indefinite articles, and should be ignored at the beginning of
957 are recognized as articles.
961 .BI bibliography\ filename \fR\|.\|.\|.
963 Write out all the references contained in the bibliographic databases
964 .IR filename \|.\|.\|.
966 This command should come last in a
972 .BI bracket-label\ string1\ string2\ string3
973 In the text, bracket each label
981 immediately followed by
986 The default behaviour is
991 bracket-label \e*([. \e*(.] ", "
996 .BI capitalize\ fields
999 to caps and small caps.
1008 even when followed by a character other than space or newline.
1012 .BI database\ filename \fR\|.\|.\|.
1013 Search the bibliographic databases
1014 .IR filename \|.\|.\|.
1019 .IB filename @INDEX_SUFFIX@
1021 .BR @g@indxbib (@MAN1EXT@)
1022 exists, then it will be searched instead;
1023 each index can cover multiple databases.
1027 .BI date-as-label\*n\ string
1029 is a label expression that specifies a string with which to replace the
1031 field after constructing the label.
1033 See subsection \(lqLabel expressions\(rq below for a description of
1036 This command is useful if you do not want explicit labels in the
1038 but instead want to handle any necessary disambiguation by qualifying
1039 the date in some way.
1041 The label used in the text would typically be some combination of the
1044 In most cases you should also use the
1045 .B no-label-in-reference
1051 .B "date-as-label D.+yD.y%a*D.-y"
1055 would attach a disambiguating letter to the year part of the
1057 field in the reference.
1062 .B default-database\*n
1063 The default database should be searched.
1065 This is the default behaviour,
1066 so the negative version of this command is more useful.
1069 determines whether the default database should be searched
1070 on the first occasion that it needs to do a search.
1073 .B no-default-database
1074 command must be given before then,
1075 in order to be effective.
1079 .BI discard\*n\ fields
1080 When the reference is read,
1082 should be discarded;
1083 no string definitions for
1094 .BI et-al\*n\ string\ m\ n
1097 in the evaluation of
1099 expressions in label expressions.
1101 If the number of authors needed to make the author sequence
1104 and the total number of authors is
1108 authors will be replaced by
1119 The default behaviour is
1129 .BI include\ filename
1132 and interpret the contents as commands.
1136 .BI join-authors\ string1\ string2\ string3
1137 This says how authors should be joined together.
1139 When there are exactly two authors, they will be joined with
1142 When there are more than two authors,
1143 all but the last two will be joined with
1145 and the last two authors will be joined with
1155 is also omitted it will also default to
1163 join-authors " and " ", " ", and "
1167 will restore the default method for joining authors.
1172 .B label-in-reference\*n
1173 When outputting the reference,
1176 to be the reference's label.
1178 This is the default behaviour; so the negative version
1179 of this command is more useful.
1184 For each reference output a label in the text.
1186 The label will be separated from the surrounding text as described in the
1190 This is the default behaviour; so the negative version
1191 of this command is more useful.
1197 is a label expression describing how to label each reference.
1201 .BI separate-label-second-parts\ string
1202 When merging two-part labels, separate the second part of the second
1203 label from the first label with
1206 See the description of the
1212 .B move-punctuation\*n
1214 move any punctuation at the end of line past the label.
1216 It is usually a good idea to give this command unless you are using
1217 superscripted numbers as labels.
1221 .BI reverse\*n\ string
1222 Reverse the fields whose names
1226 Each field name can be followed by a number which says
1227 how many such fields should be reversed.
1229 If no number is given for a field, all such fields will be reversed.
1233 .BI search-ignore\*n\ fields
1234 While searching for keys in databases for which no index exists,
1235 ignore the contents of
1244 .BI search-truncate\*n\ n
1245 Only require the first
1247 characters of keys to be given.
1249 In effect when searching for a given key words in the database are
1250 truncated to the maximum of
1252 and the length of the key.
1260 .BI short-label\*n\ string
1262 is a label expression that specifies an alternative (usually shorter)
1265 This is used when the
1267 flag is given in the citation.
1269 When using author-date style labels, the identity of the author
1270 or authors is sometimes clear from the context, and so it
1271 may be desirable to omit the author or authors from the label.
1275 command will typically be used to specify a label containing just
1276 a date and possibly a disambiguating letter.
1281 Sort references according to
1284 References will automatically be accumulated.
1287 should be a list of field names,
1288 each followed by a number,
1289 indicating how many fields with the name should be used for sorting.
1292 can be used to indicate that all the fields with the name should be used.
1296 can be used to indicate the references should be sorted using the
1299 (Subsection \(lqLabel expressions\(rq below describes the concept of a
1304 .B sort-adjacent-labels\*n
1305 Sort labels that are adjacent in the text according to their position
1306 in the reference list.
1308 This command should usually be given if the
1309 .B abbreviate-label-ranges
1310 command has been given,
1311 or if the label expression contains a
1315 This will have no effect unless references are being accumulated.
1318 .\" ====================================================================
1319 .SS Label expressions
1320 .\" ====================================================================
1322 Label expressions can be evaluated both normally and tentatively.
1324 The result of normal evaluation is used for output.
1326 The result of tentative evaluation, called the
1327 .IR "tentative label" ,
1328 is used to gather the information that normal evaluation needs to
1329 disambiguate the label.
1331 Label expressions specified by the
1335 commands are not evaluated tentatively.
1337 Normal and tentative evaluation are the same for all types of
1338 expression other than
1345 The description below applies to normal evaluation,
1346 except where otherwise specified.
1360 is omitted, it defaults to\ 1.
1372 All the authors joined as specified by the
1376 The whole of each author's name will be used.
1378 However, if the references are sorted by author (that is the sort
1379 specification starts with
1381 then authors last names will be used instead,
1382 provided that this does not introduce ambiguity,
1383 and also an initial subsequence of the authors may be used instead of
1385 again provided that this does not introduce ambiguity.
1387 The use of only the last name for the
1389 author of some reference
1390 is considered to be ambiguous if
1391 there is some other reference,
1394 authors of the references are the same,
1397 authors are not the same,
1400 authors last names are the same.
1402 A proper initial subsequence of the sequence of authors for some
1403 reference is considered to be ambiguous if there is a reference with
1404 some other sequence of authors which also has that subsequence as a
1405 proper initial subsequence.
1407 When an initial subsequence of authors is used, the remaining authors
1408 are replaced by the string specified by the
1411 this command may also specify additional requirements that must be
1412 met before an initial subsequence can be used.
1415 tentatively evaluates to a canonical representation of the authors,
1416 such that authors that compare equally for sorting purpose will have
1417 the same representation.
1430 The serial number of the reference formatted according to the
1431 character following the
1433 The serial number of a reference is\ 1 plus the number of earlier
1434 references with same tentative label as this reference.
1436 These expressions tentatively evaluate to an empty string.
1440 If there is another reference with the same tentative label as this
1444 otherwise an empty string.
1446 It tentatively evaluates to an empty string.
1458 upper or lower case letters or digits of
1461 Troff special characters (such as
1463 count as a single letter.
1465 Accent strings are retained but do not count towards the total.
1471 converted to lowercase.
1477 converted to uppercase.
1483 converted to caps and small caps.
1489 reversed so that the last name is first.
1495 with first names abbreviated.
1497 Note that fields specified in the
1499 command are abbreviated before any labels are evaluated.
1503 is useful only when you want a field to be abbreviated in a label
1504 but not in a reference.
1520 if it does not contain a year.
1528 or an empty string if
1530 does not contain a year.
1535 The last name part of
1540 .IB expr1 \(ti expr2
1542 except that if the last character of
1546 then it will be replaced by
1552 The concatenation of
1575 otherwise an empty string.
1579 .IB expr1 ? expr2 : expr3
1591 The label is in two parts, which are separated by
1594 Two adjacent two-part labels which have the same first part will be
1595 merged by appending the second part of the second label onto the first
1596 label separated by the string specified in the
1597 .B separate-label-second-parts
1599 a comma followed by a space);
1600 the resulting label will also be a two-part label with the same first
1601 part as before merging,
1602 and so additional labels can be merged into it.
1604 Note that it is permissible for the first part to be empty;
1605 this maybe desirable for expressions used in the
1619 The above expressions are listed in order of precedence
1624 have the same precedence.
1627 .\" ====================================================================
1629 .\" ====================================================================
1631 Each reference starts with a call to the macro
1636 will be defined to be the label for this reference,
1638 .B no-label-in-reference
1639 command has been given.
1641 There then follows a series of string definitions,
1645 corresponds to field
1652 field contains a range of pages.
1659 number registers are set to\ 1 according as the
1664 fields end with one of the characters
1669 number register will be set to\ 1 if the
1671 string contains more than one name.
1673 The reference is followed by a call to the
1677 The first argument to this macro gives a number representing
1678 the type of the reference.
1680 If a reference contains a
1682 field, it will be classified as type\ 1,
1683 otherwise if it contains a
1685 field, it will type\ 3,
1686 otherwise if it contains a
1690 field it will be type\ 4,
1691 otherwise if it contains an
1693 field it will be type\ 2,
1694 otherwise it will be type\ 0.
1696 The second argument is a symbolic name for the type:
1698 .BR journal-article ,
1704 Groups of references that have been accumulated or are produced by the
1706 command are preceded by a call to the
1708 macro and followed by a call to the
1713 .\" ====================================================================
1715 .\" ====================================================================
1723 .RI file @INDEX_SUFFIX@
1729 uses temporary files.
1732 .BR groff (@MAN1EXT@)
1733 man page for details where such files are created.
1736 .\" ====================================================================
1738 .\" ====================================================================
1742 If set, overrides the default database.
1745 .\" ====================================================================
1747 .\" ====================================================================
1749 .BR @g@indxbib (@MAN1EXT@),
1750 .BR @g@lookbib (@MAN1EXT@),
1751 .BR lkbib (@MAN1EXT@)
1755 .\" ====================================================================
1757 .\" ====================================================================
1759 In label expressions,
1761 expressions are ignored inside
1766 .\" Local Variables:
1769 .\" vim: set filetype=groff:
projects / platform / upstream / groff.git / blob