Home
Main website
Display Sidebar
Hide Ads
Recent Changes
View Source:
refer(1)
Edit
PageHistory
Diff
Info
LikePages
REFER !!!REFER NAME SYNOPSIS DESCRIPTION OPTIONS USAGE FILES SEE ALSO BUGS ---- !!NAME refer - preprocess bibliographic references for groff !!SYNOPSIS __refer__ [[ __-benvCPRS__ ] [[ __-a__''n'' ] [[ __-c__''fields'' ] [[ __-f__''n'' ] [[ __-i__''fields'' ] [[ __-k__''field'' ] [[ __-l__''m,n'' ] [[ __-p__''filename'' ] [[ __-s__''fields'' ] [[ __-t__''n'' ] [[ __-B__''field.macro'' ] [[ ''filename''... ] It is possible to have whitespace between a command line option and its parameter. !!DESCRIPTION This file documents the GNU version of __refer__, which is part of the groff document formatting system. __refer__ copies the contents of ''filename''... to the standard output, except that lines between __.[[__ and __.]__ are interpreted as citations, and lines between __.R1__ and __.R2__ are interpreted as commands about how citations are to be processed. Each citation specifies a reference. The citation can specify a reference that is contained in a bibliographic database by giving a set of keywords that only that reference contains. Alternatively it can specify a reference by supplying a database record in the citation. A combination of these alternatives is also possible. For each citation, __refer__ can produce a mark in the text. This mark consists of some label which can be separated from the text and from other labels in various ways. For each reference it also outputs __groff__ commands that can be used by a macro package to produce a formatted reference for each citation. The output of __refer__ must therefore be processed using a suitable macro package. The __-ms__ and __-me__ macros are both suitable. The commands to format a citation's reference can be output immediately after the citation, or the references may be accumulated, and the commands output at some later point. If the references are accumulated, then multiple citations of the same reference will produce a single formatted reference. The interpretation of lines between __.R1__ and __.R2__ as commands is a new feature of GNU refer. Documents making use of this feature can still be processed by Unix refer just by adding the lines __.de R1 .ig R2 .. __ to the beginning of the document. This will cause __troff__ to ignore everything between __.R1__ and __.R2__. The effect of some commands can also be achieved by options. These options are supported mainly for compatibility with Unix refer. It is usually more convenient to use commands. __refer__ generates __.lf__ lines so that filenames and line numbers in messages produced by commands that read __refer__ output will be correct; it also interprets lines beginning with __.lf__ so that filenames and line numbers in the messages and __.lf__ lines that it produces will be accurate even if the input has been preprocessed by a command such as soelim(1). !!OPTIONS Most options are equivalent to commands (for a description of these commands see the __Commands__ subsection): __-b__ __no-label-in-text; no-label-in-reference__ __-e__ __accumulate__ __-n__ __no-default-database__ __-C__ __compatible__ __-P__ __move-punctuation__ __-S__ __label __ __-a__''n'' __reverse A__''n'' __-c__''fields'' __capitalize__ ''fields'' __-f__''n'' __label %__''n'' __-i__''fields'' __search-ignore__ ''fields'' __-k__ __label L~%a__ __-k__''field'' __label__ ''field''__~%a__ __-l__ __label A.nD.y%a__ __-l__''m'' __label A.n+__''m''__D.y%a__ __-l,__''n'' __label A.nD.y-__''n''__%a__ __-l__''m''__,__''n'' __label A.n+__''m''__D.y-__''n''__%a__ __-p__''filename'' __database__ ''filename'' __-s__''spec'' __sort__ ''spec'' __-t__''n'' __search-truncate__ ''n'' These options are equivalent to the following commands with the addition that the filenames specified on the command line are processed as if they were arguments to the __bibliography__ command instead of in the normal way: __-B__ __annotate X AP; no-label-in-reference__ __-B__''field''__.__''macro'' __annotate__ ''field macro''__; no-label-in-reference__ The following options have no equivalent commands: __-v__ Print the version number. __-R__ Don't recognize lines beginning with __.R1__/__.R2__. !!USAGE __Bibliographic databases__ The bibliographic database is a text file consisting of records separated by one or more blank lines. Within each record fields start with a __%__ at the beginning of a line. Each field has a one character name that immediately follows the __%__. It is best to use only upper and lower case letters for the names of fields. The name of the field should be followed by exactly one space, and then by the contents of the field. Empty fields are ignored. The conventional meaning of each field is as follows: __A__ The name of an author. If the name contains a title such as __Jr.__ at the end, it should be separated from the last name by a comma. There can be multiple occurrences of the __A__ field. The order is significant. It is a good idea always to supply an __A__ field or a __Q__ field. __B__ For an article that is part of a book, the title of the book __C__ The place (city) of publication. __D__ The date of publication. The year should be specified in full. If the month is specified, the name rather than the number of the month should be used, but only the first three letters are required. It is a good idea always to supply a __D__ field; if the date is unknown, a value such as __in press__ or __unknown__ can be used. __E__ For an article that is part of a book, the name of an editor of the book. Where the work has editors and no authors, the names of the editors should be given as __A__ fields and __, (ed)__ or __, (eds)__ should be appended to the last author. __G__ US Government ordering number. __I__ The publisher (issuer). __J__ For an article in a journal, the name of the journal. __K__ Keywords to be used for searching. __L__ Label. __N__ Journal issue number. __O__ Other information. This is usually printed at the end of the reference. __P__ Page number. A range of pages can be specified as ''m''__-__''n''. __Q__ The name of the author, if the author is not a person. This will only be used if there are no __A__ fields. There can only be one __Q__ field. __R__ Technical report number. __S__ Series name. __T__ Title. For an article in a book or journal, this should be the title of the article. __V__ Volume number of the journal or book. __X__ Annotation. For all fields except __A__ and __E__, if there is more than one occurrence of a particular field in a record, only the last such field will be used. If accent strings are used, they should follow the character to be accented. This means that the __AM__ macro must be used with the __-ms__ macros. Accent strings should not be quoted: use one __\__ rather than two. __Citations__ The format of a citation is __.[[__''opening-text flags keywords fields''__ .]__''closing-text'' The ''opening-text'', ''closing-text'' and ''flags'' components are optional. Only one of the ''keywords'' and ''fields'' components need be specified. The ''keywords'' component says to search the bibliographic databases for a reference that contains all the words in ''keywords''. It is an error if more than one reference if found. The ''fields'' components specifies additional fields to replace or supplement those specified in the reference. When references are being accumulated and the ''keywords'' component is non-empty, then additional fields should be specified only on the first occasion that a particular reference is cited, and will apply to all citations of that reference. The ''opening-text'' and ''closing-text'' component specifies strings to be used to bracket the label instead of the strings specified in the __bracket-label__ command. If either of these components is non-empty, the strings specified in the __bracket-label__ command will not be used; this behaviour can be altered using the __[[__ and __]__ flags. Note that leading and trailing spaces are significant for these components. The ''flags'' component is a list of non-alphanumeric characters each of which modifies the treatment of this particular citation. Unix refer will treat these flags as part of the keywords and so will ignore them since they are non-alphanumeric. The following flags are currently recognized: __#__ This says to use the label specified by the __short-label__ command, instead of that specified by the __label__ command. If no short label has been specified, the normal label will be used. Typically the short label is used with author-date labels and consists of only the date and possibly a disambiguating letter; the __#__ is supposed to be suggestive of a numeric type of label. __[[__ Precede ''opening-text'' with the first string specified in the __bracket-label__ command. __]__ Follow ''closing-text'' with the second string specified in the __bracket-label__ command. One advantages of using the __[[__ and __]__ flags rather than including the brackets in ''opening-text'' and ''closing-text'' is that you can change the style of bracket used in the document just by changing the __bracket-label__ command. Another advantage is that sorting and merging of citations will not necessarily be inhibited if the flags are used. If a label is to be inserted into the text, it will be attached to the line preceding the __.[[__ line. If there is no such line, then an extra line will be inserted before the __.[[__ line and a warning will be given. There is no special notation for making a citation to multiple references. Just use a sequence of citations, one for each reference. Don't put anything between the citations. The labels for all the citations will be attached to the line preceding the first citation. The labels may also be sorted or merged. See the description of the ____ label expression, and of the __sort-adjacent-labels__ and __abbreviate-label-ranges__ command. A label will not be merged if its citation has a non-empty ''opening-text'' or ''closing-text''. However, the labels for a citation using the __]__ flag and without any ''closing-text'' immediately followed by a citation using the __[[__ flag and without any ''opening-text'' may be sorted and merged even though the first citation's ''opening-text'' or the second citation's ''closing-text'' is non-empty. (If you wish to prevent this just make the first citation's ''closing-text'' ____.) __Commands__ Commands are contained between lines starting with __.R1__ and __.R2__. Recognition of these lines can be prevented by the __-R__ option. When a __.R1__ line is recognized any accumulated references are flushed out. Neither __.R1__ nor __.R2__ lines, nor anything between them is output. Commands are separated by newlines or __;__s. __#__ introduces a comment that extends to the end of the line (but does not conceal the newline). Each command is broken up into words. Words are separated by spaces or tabs. A word that begins with ____ extends to the next ____ that is not followed by another ____. If there is no such ____ the word extends to the end of the line. Pairs of ____ in a word beginning with ____ collapse to a single ____. Neither __#__ nor __;__ are recognized inside ____s. A line can be continued by ending it with __\__; this works everywhere except after a __#__. Each command ''name'' that is marked with * has an associated negative command __no-__''name'' that undoes the effect of ''name''. For example, the __no-sort__ command specifies that references should not be sorted. The negative commands take no arguments. In the following description each argument must be a single word; ''field'' is used for a single upper or lower case letter naming a field; ''fields'' is used for a sequence of such letters; ''m'' and ''n'' are used for a non-negative numbers; ''string'' is used for an arbitrary string; ''filename'' is used for the name of a file. __abbreviate__* ''fields string1 string2 string3 string4'' Abbreviate the first names of ''fields''. An initial letter will be separated from another initial letter by ''string1'', from the last name by ''string2'', and from anything else (such as a __von__ or __de__) by ''string3''. These default to a period followed by a space. In a hyphenated first name, the initial of the first part of the name will be separated from the hyphen by ''string4''; this defaults to a period. No attempt is made to handle any ambiguities that might result from abbreviation. Names are abbreviated before sorting and before label construction. __abbreviate-label-ranges__* ''string'' Three or more adjacent labels that refer to consecutive references will be abbreviated to a label consisting of the first label, followed by ''string'' followed by the last label. This is mainly useful with numeric labels. If ''string'' is omitted it defaults to __-__. __accumulate__* Accumulate references instead of writing out each reference as it is encountered. Accumulated references will be written out whenever a reference of the form __.[[ $LIST$ .]__ is encountered, after all input files hve been processed, and whenever __.R1__ line is recognized. __annotate__* ''field string'' ''field'' is an annotation; print it at the end of the reference as a paragraph preceded by the line __.__''string'' If ''macro'' is omitted it will default to __AP__; if ''field'' is also omitted it will default to __X__. Only one field can be an annotation. __articles__ ''string''... ''string''... are definite or indefinite articles, and should be ignored at the beginning of __T__ fields when sorting. Initially, __the__, __a__ and __an__ are recognized as articles. __bibliography__ ''filename''... Write out all the references contained in the bibliographic databases ''filename''... __bracket-label__ ''string1 string2 string3'' In the text, bracket each label with ''string1'' and ''string2''. An occurrence of ''string2'' immediately followed by ''string1'' will be turned into ''string3''. The default behaviour is __bracket-label *([[. *(.] __ __capitalize__ ''fields'' Convert ''fields'' to caps and small caps. __compatible__* Recognize __.R1__ and __.R2__ even when followed by a character other than space or newline. __database__ ''filename''... Search the bibliographic databases ''filename''... For each ''filename'' if an index ''filename''__.i__ created by indxbib(1) exists, then it will be searched instead; each index can cover multiple databases. __date-as-label__* ''string'' ''string'' is a label expression that specifies a string with which to replace the __D__ field after constructing the label. See the __Label expressions__ subsection for a description of label expressions. This command is useful if you do not want explicit labels in the reference list, but instead want to handle any necessary disambiguation by qualifying the date in some way. The label used in the text would typically be some combination of the author and date. In most cases you should also use the __no-label-in-reference__ command. For example, __date-as-label D.+yD.y%a*D.-y__ would attach a disambiguating letter to the year part of the __D__ field in the reference. __default-database__* The default database should be searched. This is the default behaviour, so the negative version of this command is more useful. refer determines whether the default database should be searched on the first occasion that it needs to do a search. Thus a __no-default-database__ command must be given before then, in order to be effective. __discard__* ''fields'' When the reference is read, ''fields'' should be discarded; no string definitions for ''fields'' will be output. Initially, ''fields'' are __XYZ__. __et-al__* ''string m n'' Control use of __et al__ in the evaluation of __@__ expressions in label expressions. If the number of authors needed to make the author sequence unambiguous is ''u'' and the total number of authors is ''t'' then the last ''t''-''u'' authors will be replaced by ''string'' provided that ''t''-''u'' is not less than ''m'' and ''t'' is not less than ''n''. The default behaviour is __et-al __ __include__ ''filename'' Include ''filename'' and interpret the contents as commands. __join-authors__ ''string1 string2 string3'' This says how authors should be joined together. When there are exactly two authors, they will be joined with ''string1''. When there are more than two authors, all but the last two will be joined with ''string2'', and the last two authors will be joined with ''string3''. If ''string3'' is omitted, it will default to ''string1''; if ''string2'' is also omitted it will also default to ''string1''. For example, __join-authors __ will restore the default method for joining authors. __label-in-reference__* When outputting the reference, define the string __[[F__ to be the reference's label. This is the default behaviour; so the negative version of this command is more useful. __label-in-text__* For each reference output a label in the text. The label will be separated from the surrounding text as described in the __bracket-label__ command. This is the default behaviour; so the negative version of this command is more useful. __label__ ''string string'' is a label expression describing how to label each reference. __separate-label-second-parts__ ''string'' When merging two-part labels, separate the second part of the second label from the first label with ''string''. See the description of the ____ label expression. __move-punctuation__* In the text, move any punctuation at the end of line past the label. It is usually a good idea to give this command unless you are using superscripted numbers as labels. __reverse__* ''string'' Reverse the fields whose names are in ''string''. Each field name can be followed by a number which says how many such fields should be reversed. If no number is given for a field, all such fields will be reversed. __search-ignore__* ''fields'' While searching for keys in databases for which no index exists, ignore the contents of ''fields''. Initially, fields __XYZ__ are ignored. __search-truncate__* ''n'' Only require the first ''n'' characters of keys to be given. In effect when searching for a given key words in the database are truncated to the maximum of ''n'' and the length of the key. Initially ''n'' is 6. __short-label__* ''string'' ''string'' is a label expression that specifies an alternative (usually shorter) style of label. This is used when the __#__ flag is given in the citation. When using author-date style labels, the identity of the author or authors is sometimes clear from the context, and so it may be desirable to omit the author or authors from the label. The __short-label__ command will typically be used to specify a label containing just a date and possibly a disambiguating letter. __sort__* ''string'' Sort references according to __string__. References will automatically be accumulated. ''string'' should be a list of field names, each followed by a number, indicating how many fields with the name should be used for sorting. __+__ can be used to indicate that all the fields with the name should be used. Also __.__ can be used to indicate the references should be sorted using the (tentative) label. (The __Label expressions__ subsection describes the concept of a tentative label.) __sort-adjacent-labels__* Sort labels that are adjacent in the text according to their position in the reference list. This command should usually be given if the __abbreviate-label-ranges__ command has been given, or if the label expression contains a ____ expression. This will have no effect unless references are being accumulated. __Label expressions__ Label expressions can be evaluated both normally and tentatively. The result of normal evaluation is used for output. The result of tentative evaluation, called the ''tentative label,'' is used to gather the information that normal evaluation needs to disambiguate the label. Label expressions specified by the __date-as-label__ and __short-label__ commands are not evaluated tentatively. Normal and tentative evaluation are the same for all types of expression other than __@__, __*__, and __%__ expressions. The description below applies to normal evaluation, except where otherwise specified. ''field'' ''field n'' The ''n''-th part of ''field''. If ''n'' is omitted, it defaults to 1. __'__''string''__'__ The characters in ''string'' literally. __@__ All the authors joined as specified by the __join-authors__ command. The whole of each author's name will be used. However, if the references are sorted by author (that is the sort specification starts with __A+__), then authors' last names will be used instead, provided that this does not introduce ambiguity, and also an initial subsequence of the authors may be used instead of all the authors, again provided that this does not introduce ambiguity. The use of only the last name for the ''i''-th author of some reference is considered to be ambiguous if there is some other reference, such that the first ''i''-1 authors of the references are the same, the ''i''-th authors are not the same, but the ''i''-th authors' last names are the same. A proper initial subsequence of the sequence of authors for some reference is considered to be ambiguous if there is a reference with some other sequence of authors which also has that subsequence as a proper initial subsequence. When an initial subsequence of authors is used, the remaining authors are replaced by the string specified by the __et-al__ command; this command may also specify additional requirements that must be met before an initial subsequence can be used. __@__ tentatively evaluates to a canonical representation of the authors, such that authors that compare equally for sorting purpose will have the same representation. __%__''n'' __%a__ __%A__ __%i__ __%I__ The serial number of the reference formatted according to the character following the __%__. The serial number of a reference is 1 plus the number of earlier references with same tentative label as this reference. These expressions tentatively evaluate to an empty string. ''expr''__*__ If there is another reference with the same tentative label as this reference, then ''expr'', otherwise an empty string. It tentatively evaluates to an empty string. ''expr''__+__''n'' ''expr''__-__''n'' The first (__+__) or last (__-__) ''n'' upper or lower case letters or digits of ''expr''. Troff special characters (such as ____) count as a single letter. Accent strings are retained but do not count towards the total. ''expr''__.l__ ''expr'' converted to lowercase. ''expr''__.u__ ''expr'' converted to uppercase. ''expr''__.c__ ''expr'' converted to caps and small caps. ''expr''__.r__ ''expr'' reversed so that the last name is first. ''expr''__.a__ ''expr'' with first names abbreviated. Note that fields specified in the __abbreviate__ command are abbreviated before any labels are evaluated. Thus __.a__ is useful only when you want a field to be abbreviated in a label but not in a reference. ''expr''__.y__ The year part of ''expr''. ''expr''__.+y__ The part of ''expr'' before the year, or the whole of ''expr'' if it does not contain a year. ''expr''__.-y__ The part of ''expr'' after the year, or an empty string if ''expr'' does not contain a year. ''expr''__.n__ The last name part of ''expr''. ''expr1''__~__''expr2'' ''expr1'' except that if the last character of ''expr1'' is __-__ then it will be replaced by ''expr2''. ''expr1 expr2'' The concatenation of ''expr1'' and ''expr2''. ''expr1''__|__''expr2'' If ''expr1'' is non-empty then ''expr1'' otherwise ''expr2''. ''expr1''____''expr2'' If ''expr1'' is non-empty then ''expr2'' otherwise an empty string. ''expr1''__?__''expr2''__:__''expr3'' If ''expr1'' is non-empty then ''expr2'' otherwise ''expr3''. ____''expr''____ The label is in two parts, which are separated by ''expr''. Two adjacent two-part labels which have the same first part will be merged by appending the second part of the second label onto the first label separated by the string specified in the __separate-label-second-parts__ command (initially, a comma followed by a space); the resulting label will also be a two-part label with the same first part as before merging, and so additional labels can be merged into it. Note that it is permissible for the first part to be empty; this maybe desirable for expressions used in the __short-label__ command. __(__''expr''__)__ The same as ''expr''. Used for grouping. The above expressions are listed in order of precedence (highest first); ____ and __|__ have the same precedence. __Macro interface__ Each reference starts with a call to the macro __]-__. The string __[[F__ will be defined to be the label for this reference, unless the __no-label-in-reference__ command has been given. There then follows a series of string definitions, one for each field: string __[[__''X'' corresponds to field ''X''. The number register __[[P__ is set to 1 if the __P__ field contains a range of pages. The __[[T__, __[[A__ and __[[O__ number registers are set to 1 according as the __T__, __A__ and __O__ fields end with one of the characters __.?!__. The __[[E__ number register will be set to 1 if the __[[E__ string contains more than one name. The reference is followed by a call to the __][[__ macro. The first argument to this macro gives a number representing the type of the reference. If a reference contains a __J__ field, it will be classified as type 1, otherwise if it contains a __B__ field, it will type 3, otherwise if it contains a __G__ or __R__ field it will be type 4, otherwise if contains a __I__ field it will be type 2, otherwise it will be type 0. The second argument is a symbolic name for the type: __other__, __journal-article__, __book__, __article-in-book__ or __tech-report__. Groups of references that have been accumulated or are produced by the __bibliography__ command are preceded by a call to the __]__ macro and followed by a call to the __]__ macro. !!FILES __/usr/dict/papers/Ind__ Default database. ''file''__.i__ Index files. !!SEE ALSO indxbib(1), lookbib(1), lkbib(1) !!BUGS In label expressions, ____ expressions are ignored inside __.__''char'' expressions. ----
12 pages link to
refer(1)
:
Man1r
roff(7)
troff(1)
groff(1)
groff_man(7)
grog(1)
indxbib(1)
lkbib(1)
lookbib(1)
mdoc.samples(7)
groff_mdoc(7)
man(7)
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.
