diff options
Diffstat (limited to 'upstream/mageia-cauldron/man1/refer.1')
| -rw-r--r-- | upstream/mageia-cauldron/man1/refer.1 | 1769 |
1 files changed, 1769 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1/refer.1 b/upstream/mageia-cauldron/man1/refer.1 new file mode 100644 index 00000000..b92d5ff8 --- /dev/null +++ b/upstream/mageia-cauldron/man1/refer.1 @@ -0,0 +1,1769 @@ +.TH REFER 1 "17 December 2018" "groff 1.22.4" +.SH NAME +refer \- preprocess bibliographic references for groff +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 1989-2018 Free Software Foundation, Inc. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Permission is granted to copy and distribute translations of this +.\" manual into another language, under the above conditions for +.\" modified versions, except that this permission notice may be +.\" included in translations approved by the Free Software Foundation +.\" instead of in the original English. +. +. +.\" ==================================================================== +.SH SYNOPSIS +.\" ==================================================================== +. +.SY refer +.OP \-benCPRS +.OP \-a n +.OP \-c fields +.OP \-f n +.OP \-i fields +.OP \-k field +.OP \-l m,n +.OP \-p filename +.OP \-s fields +.OP \-t n +.BI "\-B " field . macro +.RI [ file +\&.\|.\|.\&] +.YS +. +.SY refer +.B \-\-help +.YS +. +.SY refer +.B \-v +.SY refer +.B \-\-version +.YS +. +. +.\" ==================================================================== +.SH DESCRIPTION +.\" ==================================================================== +. +This file documents the GNU version of +.BR refer , +which is part of the groff document formatting system. +. +.B refer +copies the contents of +.IR filename \|.\|.\|.\& +to the standard output, +except that lines between +.B .[ +and +.B .]\& +are interpreted as citations, +and lines between +.B .R1 +and +.B .R2 +are interpreted as commands about how citations are to be processed. +. +. +.LP +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. +. +. +.LP +For each citation, +.B 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 +.B groff +commands that can be used by a macro package to produce a formatted +reference for each citation. +. +The output of +.B refer +must therefore be processed using a suitable macro package. +. +The +.B \-ms +and +.B \-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. +. +. +.LP +The interpretation of lines between +.B .R1 +and +.B .R2 +as commands is a new feature of GNU +.BR refer . +. +Documents making use of this feature can still be processed by +Unix refer just by adding the lines +. +.RS +.LP +.nf +.ft B +\&.de R1 +\&.ig R2 +\&.. +.ft +.fi +.RE +. +to the beginning of the document. +. +This will cause +.B troff +to ignore everything between +.B .R1 +and +.BR .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. +. +. +.LP +.B refer +generates +.B .lf +lines so that filenames and line numbers in messages produced +by commands that read +.B refer +output will be correct; +it also interprets lines beginning with +.B .lf +so that filenames and line numbers in the messages and +.B .lf +lines that it produces will be accurate even if the input has been +preprocessed by a command such as +.BR soelim (1). +. +. +.\" ==================================================================== +.SH OPTIONS +.\" ==================================================================== +. +Whitespace is permitted between a command-line option and its argument. +. +. +.LP +Most options are equivalent to commands +(for a description of these commands, +see subsection \(lqCommands\(rq below). +. +. +.nr a \n(.j +.ad l +.TP +.B \-b +.B "no-label-in-text; no-label-in-reference" +. +. +.TP +.B \-e +.B accumulate +. +. +.TP +.B \-n +.B no-default-database +. +. +.TP +.B \-C +.B compatible +. +. +.TP +.B \-P +.B move-punctuation +. +. +.TP +.B \-S +.B +label\ "(A.n|Q)\ ',\ '\ (D.y|D)"; \%bracket-label\ "\ ("\ )\ ";\ " +. +. +.TP +.BI \-a n +.B reverse +.BI A n +. +. +.TP +.BI \-c fields +.B capitalize +.I fields +. +. +.TP +.BI \-f n +.B label +.BI % n +. +. +.TP +.BI \-i fields +.B search-ignore +.I fields +. +. +.TP +.B \-k +.B label +.B L\(ti%a +. +. +.TP +.BI \-k field +.B label +.IB field \(ti%a +. +. +.TP +.B \-l +.B label +.B A.nD.y%a +. +. +.TP +.BI \-l m +.B label +.BI A.n+ m D.y%a +. +. +.TP +.BI \-l, n +.B label +.BI A.nD.y\- n %a +. +. +.TP +.BI \-l m , n +.B label +.BI A.n+ m D.y\- n %a +. +. +.TP +.BI \-p filename +.B database +.I filename +. +. +.TP +.BI \-s spec +.B sort +.I spec +. +. +.TP +.BI \-t n +.B search-truncate +.I n +.ad \na +. +. +.LP +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 +.B bibliography +command instead of in the normal way: +. +. +.TP +.B \-B +.B "annotate X AP; no-label-in-reference" +. +. +.TP +.BI \-B field . macro +.B annotate +.I field +.IB macro ; +.B no-label-in-reference +. +. +.LP +The following options have no equivalent commands: +. +. +.TP +.B \-v +Print the version number. +. +. +.TP +.B \-R +Don't recognize lines beginning with +.BR .R1 / .R2 . +. +. +.\" ==================================================================== +.SH USAGE +.\" ==================================================================== +. +.\" ==================================================================== +.SS 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 +.B % +at the beginning of a line. +. +Each field has a one character name that immediately follows the +.BR % . +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: +. +. +.TP +.B %A +The name of an author. +. +If the name contains a title such as +.B Jr.\& +at the end, +it should be separated from the last name by a comma. +. +There can be multiple occurrences of the +.B %A +field. +. +The order is significant. +. +It is a good idea always to supply an +.B %A +field or a +.B %Q +field. +. +. +.TP +.B %B +For an article that is part of a book, the title of the book. +. +. +.TP +.B %C +The place (city) of publication. +. +. +.TP +.B %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 +.B %D +field; +if the date is unknown, a value such as +.B in press +or +.B unknown +can be used. +. +. +.TP +.B %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 +.B %A +fields and +.B ,\ (ed) +or +.B ,\ (eds) +should be appended to the last author. +. +. +.TP +.B %G +US Government ordering number. +. +. +.TP +.B %I +The publisher (issuer). +. +. +.TP +.B %J +For an article in a journal, +the name of the journal. +. +. +.TP +.B %K +Keywords to be used for searching. +. +. +.TP +.B %L +Label. +. +. +.TP +.B %N +Journal issue number. +. +. +.TP +.B %O +Other information. +. +This is usually printed at the end of the reference. +. +. +.TP +.B %P +Page number. +A range of pages can be specified as +.IB m \- n\fR. +. +. +.TP +.B %Q +The name of the author, if the author is not a person. +. +This will only be used if there are no +.B %A +fields. +. +There can only be one +.B %Q +field. +. +. +.TP +.B %R +Technical report number. +. +. +.TP +.B %S +Series name. +. +. +.TP +.B %T +Title. +. +For an article in a book or journal, +this should be the title of the article. +. +. +.TP +.B %V +Volume number of the journal or book. +. +. +.TP +.B %X +Annotation. +. +. +.LP +For all fields except +.B %A +and +.BR %E , +if there is more than one occurrence of a particular field in a record, +only the last such field will be used. +. +. +.LP +If accent strings are used, they should follow the character to be accented. +This means that the +.B AM +macro must be used with the +.B \-ms +macros. +. +Accent strings should not be quoted: +use one +.B \e +rather than two. +. +. +.\" ==================================================================== +.SS Citations +.\" ==================================================================== +. +The format of a citation is +. +.RS +.BI .[ opening-text +.br +.I "flags keywords" +.br +.I fields +.br +.BI .] closing-text +.RE +. +. +.LP +The +.IR opening-text , +.IR closing-text , +and +.I flags +components are optional. +. +Only one of the +.I keywords +and +.I fields +components need be specified. +. +. +.LP +The +.I keywords +component says to search the bibliographic databases for a reference +that contains all the words in +.IR keywords . +. +It is an error if more than one reference if found. +. +. +.LP +The +.I fields +components specifies additional fields to replace or supplement +those specified in the reference. +. +When references are being accumulated and the +.I 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. +. +. +.LP +The +.I opening-text +and +.I closing-text +component specifies strings to be used to bracket the label instead +of the strings specified in the +.B bracket-label +command. +. +If either of these components is non-empty, +the strings specified in the +.B bracket-label +command will not be used; +this behaviour can be altered using the +.B [ +and +.B ] +flags. +Note that leading and trailing spaces are significant for these components. +. +. +.LP +The +.I 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: +. +. +.TP +.B # +This says to use the label specified by the +.B short-label +command, +instead of that specified by the +.B 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 +.B # +is supposed to be suggestive of a numeric type of label. +. +. +.TP +.B [ +Precede +.I opening-text +with the first string specified in the +.B bracket-label +command. +. +. +.TP +.B ] +Follow +.I closing-text +with the second string specified in the +.B bracket-label +command. +. +. +.LP +One advantages of using the +.B [ +and +.B ] +flags rather than including the brackets in +.I opening-text +and +.I closing-text +is that +you can change the style of bracket used in the document just by changing the +.B bracket-label +command. +. +Another advantage is that sorting and merging of citations +will not necessarily be inhibited if the flags are used. +. +. +.LP +If a label is to be inserted into the text, +it will be attached to the line preceding the +.B .[ +line. +. +If there is no such line, then an extra line will be inserted before the +.B .[ +line and a warning will be given. +. +. +.LP +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 +.B <> +label expression, and of the +.B sort-adjacent-labels +and +.B abbreviate-label-ranges +command. +A label will not be merged if its citation has a non-empty +.I opening-text +or +.IR closing-text . +. +However, +the labels for a citation using the +.B ] +flag and without any +.I closing-text +immediately followed by a citation using the +.B [ +flag and without any +.I opening-text +may be sorted and merged +even though the first citation's +.I opening-text +or the second citation's +.I closing-text +is non-empty. +. +(If you wish to prevent this just make the first citation's +.I closing-text +.BR \e& .) +. +. +.\" ==================================================================== +.SS Commands +.\" ==================================================================== +. +Commands are contained between lines starting with +.B .R1 +and +.BR .R2 . +. +Recognition of these lines can be prevented by the +.B \-R +option. +. +When a +.B .R1 +line is recognized any accumulated references are flushed out. +. +Neither +.B .R1 +nor +.B .R2 +lines, +nor anything between them +is output. +. +. +.LP +Commands are separated by newlines or +.BR ; s. +.B # +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 +.B \[dq] +extends to the next +.B \[dq] +that is not followed by another +.BR \[dq] . +. +If there is no such +.B \[dq] +the word extends to the end of the line. +. +Pairs of +.B \[dq] +in a word beginning with +.B \[dq] +collapse to a single +.BR \[dq] . +. +Neither +.B # +nor +.B ; +are recognized inside +.BR \[dq] s. +. +A line can be continued by ending it with +.BR \e ; +this works everywhere except after a +.BR # . +. +. +.LP +.ds n \fR* +Each command +.I name +that is marked with \*n has an associated negative command +.BI no- name +that undoes the effect of +.IR name . +. +For example, the +.B no-sort +command specifies that references should not be sorted. +. +The negative commands take no arguments. +. +. +.LP +In the following description each argument must be a single word; +.I field +is used for a single upper or lower case letter naming a field; +.I fields +is used for a sequence of such letters; +.I m +and +.I n +are used for a non-negative numbers; +.I string +is used for an arbitrary string; +.I filename +is used for the name of a file. +. +. +.TP +.BI abbreviate\*n\ fields\ string1\ string2\ string3\ string4 +Abbreviate the first names of +.IR fields . +. +An initial letter will be separated from another initial letter by +.IR string1 , +from the last name by +.IR string2 , +and from anything else +(such as a +.B von +or +.BR de ) +by +.IR 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 +.IR 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. +. +. +.TP +.BI abbreviate-label-ranges\*n\ string +. +Three or more adjacent labels that refer to consecutive references +will be abbreviated to a label consisting of the first label, +followed by +.I string +followed by the last label. +. +This is mainly useful with numeric labels. +. +If +.I string +is omitted it defaults to +.BR \- . +. +. +.TP +.B accumulate\*n +Accumulate references instead of writing out each reference +as it is encountered. +. +Accumulated references will be written out whenever a reference +of the form +. +.RS +.IP +.B .[ +.br +.B $LIST$ +.br +.B .] +. +. +.LP +is encountered, +after all input files have been processed, +and whenever +.B .R1 +line is recognized. +.RE +. +. +.TP +.BI annotate\*n\ field\ string +.I field +is an annotation; +print it at the end of the reference as a paragraph preceded by the line +. +.RS +.IP +.BI . string +. +. +.LP +If +.I string +is omitted it will default to +.BR AP ; +if +.I field +is also omitted it will default to +.BR X . +. +Only one field can be an annotation. +.RE +. +. +.TP +.BI articles\ string \fR\|.\|.\|. +.IR string \|.\|.\|.\& +are definite or indefinite articles, and should be ignored at the beginning of +.B T +fields when sorting. +. +Initially, +.BR the , +.B a +and +.B an +are recognized as articles. +. +. +.TP +.BI bibliography\ filename \fR\|.\|.\|. +. +Write out all the references contained in the bibliographic databases +.IR filename \|.\|.\|. +. +This command should come last in a +.BR .R1 / .R2 +block. +. +. +.TP +.BI bracket-label\ string1\ string2\ string3 +In the text, bracket each label +with +.I string1 +and +.IR string2 . +. +An occurrence of +.I string2 +immediately followed by +.I string1 +will be turned into +.IR string3 . +. +The default behaviour is +. +.RS +.IP +.B +bracket-label \e*([. \e*(.] ", " +.RE +. +. +.TP +.BI capitalize\ fields +Convert +.I fields +to caps and small caps. +. +. +.TP +.B compatible\*n +Recognize +.B .R1 +and +.B .R2 +even when followed by a character other than space or newline. +. +. +.TP +.BI database\ filename \fR\|.\|.\|. +Search the bibliographic databases +.IR filename \|.\|.\|. +. +For each +.I filename +if an index +.IB filename .i +created by +.BR indxbib (1) +exists, then it will be searched instead; +each index can cover multiple databases. +. +. +.TP +.BI date-as-label\*n\ string +.I string +is a label expression that specifies a string with which to replace the +.B D +field after constructing the label. +. +See subsection \(lqLabel expressions\(rq below 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 +.B no-label-in-reference +command. +For example, +. +.RS +.IP +.B "date-as-label D.+yD.y%a*D.-y" +. +. +.LP +would attach a disambiguating letter to the year part of the +.B D +field in the reference. +.RE +. +. +.TP +.B default-database\*n +The default database should be searched. +. +This is the default behaviour, +so the negative version of this command is more useful. +. +.B refer +determines whether the default database should be searched +on the first occasion that it needs to do a search. +. +Thus a +.B no-default-database +command must be given before then, +in order to be effective. +. +. +.TP +.BI discard\*n\ fields +When the reference is read, +.I fields +should be discarded; +no string definitions for +.I fields +will be output. +. +Initially, +.I fields +are +.BR XYZ . +. +. +.TP +.BI et-al\*n\ string\ m\ n +Control use of +.B "et al" +in the evaluation of +.B @ +expressions in label expressions. +. +If the number of authors needed to make the author sequence +unambiguous is +.I u +and the total number of authors is +.I t +then the last +.IR t \|\-\| u +authors will be replaced by +.I string +provided that +.IR t \|\-\| u +is not less than +.I m +and +.I t +is not less than +.IR n . +. +The default behaviour is +. +.RS +.IP +.B +et-al " et al" 2 3 +.RE +. +. +.TP +.BI include\ filename +Include +.I filename +and interpret the contents as commands. +. +. +.TP +.BI join-authors\ string1\ string2\ string3 +This says how authors should be joined together. +. +When there are exactly two authors, they will be joined with +.IR string1 . +. +When there are more than two authors, +all but the last two will be joined with +.IR string2 , +and the last two authors will be joined with +.IR string3 . +. +If +.I string3 +is omitted, +it will default to +.IR string1 ; +if +.I string2 +is also omitted it will also default to +.IR string1 . +. +For example, +. +.RS +.IP +.B +join-authors " and " ", " ", and " +. +. +.LP +will restore the default method for joining authors. +.RE +. +. +.TP +.B label-in-reference\*n +When outputting the reference, +define the string +.B [F +to be the reference's label. +. +This is the default behaviour; so the negative version +of this command is more useful. +. +. +.TP +.B label-in-text\*n +For each reference output a label in the text. +. +The label will be separated from the surrounding text as described in the +.B bracket-label +command. +. +This is the default behaviour; so the negative version +of this command is more useful. +. +. +.TP +.BI label\ string +.I string +is a label expression describing how to label each reference. +. +. +.TP +.BI separate-label-second-parts\ string +When merging two-part labels, separate the second part of the second +label from the first label with +.IR string . +. +See the description of the +.B <> +label expression. +. +. +.TP +.B move-punctuation\*n +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. +. +. +.TP +.BI reverse\*n\ string +Reverse the fields whose names +are in +.IR 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. +. +. +.TP +.BI search-ignore\*n\ fields +While searching for keys in databases for which no index exists, +ignore the contents of +.IR fields . +. +Initially, fields +.B XYZ +are ignored. +. +. +.TP +.BI search-truncate\*n\ n +Only require the first +.I 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 +.I n +and the length of the key. +. +Initially +.I n +is\ 6. +. +. +.TP +.BI short-label\*n\ string +.I string +is a label expression that specifies an alternative (usually shorter) +style of label. +. +This is used when the +.B # +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 +.B short-label +command will typically be used to specify a label containing just +a date and possibly a disambiguating letter. +. +. +.TP +.BI sort\*n\ string +Sort references according to +.BR string . +. +References will automatically be accumulated. +. +.I 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. +. +.B + +can be used to indicate that all the fields with the name should be used. +. +Also +.B .\& +can be used to indicate the references should be sorted using the +(tentative) label. +. +(Subsection \(lqLabel expressions\(rq below describes the concept of a +tentative label.) +. +. +.TP +.B sort-adjacent-labels\*n +Sort labels that are adjacent in the text according to their position +in the reference list. +. +This command should usually be given if the +.B abbreviate-label-ranges +command has been given, +or if the label expression contains a +.B <> +expression. +. +This will have no effect unless references are being accumulated. +. +. +.\" ==================================================================== +.SS 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 +.IR "tentative label" , +is used to gather the information that normal evaluation needs to +disambiguate the label. +. +Label expressions specified by the +.B date-as-label +and +.B short-label +commands are not evaluated tentatively. +. +Normal and tentative evaluation are the same for all types of +expression other than +.BR @ , +.BR * , +and +.B % +expressions. +. +The description below applies to normal evaluation, +except where otherwise specified. +. +. +.TP +.I field +.TQ +.I field\ n +The +.IR n -th +part of +.IR field . +. +If +.I n +is omitted, it defaults to\ 1. +. +. +.TP +.BI ' string ' +The characters in +.I string +literally. +. +. +.TP +.B @ +All the authors joined as specified by the +.B 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 +.BR 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 +.IR i -th +author of some reference +is considered to be ambiguous if +there is some other reference, +such that the first +.IR i \|\-\|1 +authors of the references are the same, +the +.IR i -th +authors are not the same, +but the +.IR 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 +.B et-al +command; +this command may also specify additional requirements that must be +met before an initial subsequence can be used. +. +.B @ +tentatively evaluates to a canonical representation of the authors, +such that authors that compare equally for sorting purpose will have +the same representation. +. +. +.TP +.BI % n +.TQ +.B %a +.TQ +.B %A +.TQ +.B %i +.TQ +.B %I +The serial number of the reference formatted according to the +character following the +.BR % . +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. +. +.TP +.IB expr * +If there is another reference with the same tentative label as this +reference, +then +.IR expr , +otherwise an empty string. +. +It tentatively evaluates to an empty string. +. +. +.TP +.IB expr + n +.TQ +.IB expr \- n +The first +.RB ( + ) +or last +.RB ( \- ) +.I n +upper or lower case letters or digits of +.IR expr . +. +Troff special characters (such as +.BR \e('a ) +count as a single letter. +. +Accent strings are retained but do not count towards the total. +. +. +.TP +.IB expr .l +.I expr +converted to lowercase. +. +. +.TP +.IB expr .u +.I expr +converted to uppercase. +. +. +.TP +.IB expr .c +.I expr +converted to caps and small caps. +. +. +.TP +.IB expr .r +.I expr +reversed so that the last name is first. +. +. +.TP +.IB expr .a +.I expr +with first names abbreviated. +. +Note that fields specified in the +.B abbreviate +command are abbreviated before any labels are evaluated. +. +Thus +.B .a +is useful only when you want a field to be abbreviated in a label +but not in a reference. +. +. +.TP +.IB expr .y +The year part of +.IR expr . +. +. +.TP +.IB expr .+y +The part of +.I expr +before the year, +or the whole of +.I expr +if it does not contain a year. +. +. +.TP +.IB expr .\-y +The part of +.I expr +after the year, +or an empty string if +.I expr +does not contain a year. +. +. +.TP +.IB expr .n +The last name part of +.IR expr . +. +. +.TP +.IB expr1 \(ti expr2 +.I expr1 +except that if the last character of +.I expr1 +is +.B \- +then it will be replaced by +.IR expr2 . +. +. +.TP +.I expr1\ expr2 +The concatenation of +.I expr1 +and +.IR expr2 . +. +. +.TP +.IB expr1 | expr2 +If +.I expr1 +is non-empty then +.I expr1 +otherwise +.IR expr2 . +. +. +.TP +.IB expr1 & expr2 +If +.I expr1 +is non-empty +then +.I expr2 +otherwise an empty string. +. +. +.TP +.IB expr1 ? expr2 : expr3 +If +.I expr1 +is non-empty +then +.I expr2 +otherwise +.IR expr3 . +. +. +.TP +.BI < expr > +The label is in two parts, which are separated by +.IR 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 +.B 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 +.B short-label +command. +. +. +.TP +.BI ( expr ) +The same as +.IR expr . +. +Used for grouping. +. +. +.LP +The above expressions are listed in order of precedence +(highest first); +.B & +and +.B | +have the same precedence. +. +. +.\" ==================================================================== +.SS Macro interface +.\" ==================================================================== +. +Each reference starts with a call to the macro +.BR ]- . +. +The string +.B [F +will be defined to be the label for this reference, +unless the +.B no-label-in-reference +command has been given. +. +There then follows a series of string definitions, +one for each field: +string +.BI [ X +corresponds to field +.IR X . +. +The number register +.B [P +is set to\ 1 if the +.B P +field contains a range of pages. +. +The +.BR [T , +.B [A +and +.B [O +number registers are set to\ 1 according as the +.BR T , +.B A +and +.B O +fields end with one of the characters +.BR .?! . +. +The +.B [E +number register will be set to\ 1 if the +.B [E +string contains more than one name. +. +The reference is followed by a call to the +.B ][ +macro. +. +The first argument to this macro gives a number representing +the type of the reference. +. +If a reference contains a +.B J +field, it will be classified as type\ 1, +otherwise if it contains a +.B B +field, it will type\ 3, +otherwise if it contains a +.B G +or +.B R +field it will be type\ 4, +otherwise if it contains an +.B I +field it will be type\ 2, +otherwise it will be type\ 0. +. +The second argument is a symbolic name for the type: +.BR other , +.BR journal-article , +.BR book , +.B article-in-book +or +.BR tech-report . +. +Groups of references that have been accumulated or are produced by the +.B bibliography +command are preceded by a call to the +.B ]< +macro and followed by a call to the +.B ]> +macro. +. +. +.\" ==================================================================== +.SH FILES +.\" ==================================================================== +. +.TP +.I /usr/\:dict/\:papers/\:Ind +Default database. +. +. +.TP +.RI file .i +Index files. +. +. +.LP +.B refer +uses temporary files. +. +See the +.BR groff (1) +man page for details where such files are created. +. +. +.\" ==================================================================== +.SH ENVIRONMENT +.\" ==================================================================== +. +.TP +.I REFER +If set, overrides the default database. +. +. +.\" ==================================================================== +.SH "SEE ALSO" +.\" ==================================================================== +. +.BR indxbib (1), +.BR lookbib (1), +.BR lkbib (1) +.br +. +. +.\" ==================================================================== +.SH BUGS +.\" ==================================================================== +. +In label expressions, +.B <> +expressions are ignored inside +.BI . char +expressions. +. +. +.\" Local Variables: +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff: |