refer.man revision 114402
179543Sru.ig 2114402SruCopyright (C) 1989-2000, 2001, 2002, 2003 Free Software Foundation, Inc. 375584Sru 475584SruPermission is granted to make and distribute verbatim copies of 575584Sruthis manual provided the copyright notice and this permission notice 675584Sruare preserved on all copies. 775584Sru 875584SruPermission is granted to copy and distribute modified versions of this 975584Srumanual under the conditions for verbatim copying, provided that the 1075584Sruentire resulting derived work is distributed under the terms of a 1175584Srupermission notice identical to this one. 1275584Sru 1375584SruPermission is granted to copy and distribute translations of this 1475584Srumanual into another language, under the above conditions for modified 1575584Sruversions, except that this permission notice may be included in 1675584Srutranslations approved by the Free Software Foundation instead of in 1775584Sruthe original English. 1875584Sru.. 1975584Sru.de TQ 2075584Sru.br 2175584Sru.ns 2275584Sru.TP \\$1 2375584Sru.. 2475584Sru.\" Like TP, but if specified indent is more than half 2575584Sru.\" the current line-length - indent, use the default indent. 2675584Sru.de Tp 2775584Sru.ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP 2875584Sru.el .TP "\\$1" 2975584Sru.. 3075584Sru.\" The BSD man macros can't handle " in arguments to font change macros, 3175584Sru.\" so use \(ts instead of ". 3275584Sru.tr \(ts" 3375584Sru.TH @G@REFER @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@" 3475584Sru.SH NAME 3575584Sru@g@refer \- preprocess bibliographic references for groff 3675584Sru.SH SYNOPSIS 3775584Sru.nr a \n(.j 3875584Sru.ad l 3975584Sru.nr i \n(.i 4075584Sru.in +\w'\fB@g@refer 'u 4175584Sru.ti \niu 4275584Sru.B @g@refer 4375584Sru.de OP 4475584Sru.ie \\n(.$-1 .RI "[\ \fB\\$1\fP" "\\$2" "\ ]" 4575584Sru.el .RB "[\ " "\\$1" "\ ]" 4675584Sru.. 4775584Sru.OP \-benvCPRS 4875584Sru.OP \-a n 4975584Sru.OP \-c fields 5075584Sru.OP \-f n 5175584Sru.OP \-i fields 5275584Sru.OP \-k field 5375584Sru.OP \-l m,n 5475584Sru.OP \-p filename 5575584Sru.OP \-s fields 5675584Sru.OP \-t n 5775584Sru.OP \-B field.macro 5875584Sru.RI [\ filename \|.\|.\|.\ ] 5975584Sru.br 6075584Sru.ad \na 6175584Sru.PP 6275584SruIt is possible to have whitespace between a command line option and its 6375584Sruparameter. 6475584Sru.SH DESCRIPTION 6575584SruThis file documents the GNU version of 6675584Sru.BR refer , 6775584Sruwhich is part of the groff document formatting system. 6875584Sru.B refer 6975584Srucopies the contents of 70114402Sru.IR filename \|.\|.\|.\& 7175584Sruto the standard output, 7275584Sruexcept that lines between 7375584Sru.B .[ 7475584Sruand 7575584Sru.B .] 7675584Sruare interpreted as citations, 7775584Sruand lines between 7875584Sru.B .R1 7975584Sruand 8075584Sru.B .R2 8175584Sruare interpreted as commands about how citations are to be processed. 8275584Sru.LP 8375584SruEach citation specifies a reference. 8475584SruThe citation can specify a reference that is contained in 8575584Srua bibliographic database by giving a set of keywords 8675584Sruthat only that reference contains. 8775584SruAlternatively it can specify a reference by supplying a database 8875584Srurecord in the citation. 8975584SruA combination of these alternatives is also possible. 9075584Sru.LP 9175584SruFor each citation, 9275584Sru.B refer 9375584Srucan produce a mark in the text. 9475584SruThis mark consists of some label which can be separated from 9575584Sruthe text and from other labels in various ways. 9675584SruFor each reference it also outputs 9775584Sru.B groff 9875584Srucommands that can be used by a macro package to produce a formatted 9975584Srureference for each citation. 10075584SruThe output of 10175584Sru.B refer 10275584Srumust therefore be processed using a suitable macro package. 10375584SruThe 10475584Sru.B \-ms 10575584Sruand 10675584Sru.B \-me 10775584Srumacros are both suitable. 10875584SruThe commands to format a citation's reference can be output immediately after 10975584Sruthe citation, 11075584Sruor the references may be accumulated, 11175584Sruand the commands output at some later point. 11275584SruIf the references are accumulated, then multiple citations of the same 11375584Srureference will produce a single formatted reference. 11475584Sru.LP 11575584SruThe interpretation of lines between 11675584Sru.B .R1 11775584Sruand 11875584Sru.B .R2 11975584Sruas commands is a new feature of GNU refer. 12075584SruDocuments making use of this feature can still be processed by 12175584SruUnix refer just by adding the lines 12275584Sru.RS 12375584Sru.LP 12475584Sru.nf 12575584Sru.ft B 12675584Sru\&.de R1 12775584Sru\&.ig R2 12875584Sru\&.. 12975584Sru.ft 13075584Sru.fi 13175584Sru.RE 13275584Sruto the beginning of the document. 13375584SruThis will cause 13475584Sru.B troff 13575584Sruto ignore everything between 13675584Sru.B .R1 13775584Sruand 13875584Sru.BR .R2 . 13975584SruThe effect of some commands can also be achieved by options. 14075584SruThese options are supported mainly for compatibility with Unix refer. 14175584SruIt is usually more convenient to use commands. 14275584Sru.LP 14375584Sru.B refer 14475584Srugenerates 14575584Sru.B .lf 14675584Srulines so that filenames and line numbers in messages produced 14775584Sruby commands that read 14875584Sru.B refer 14975584Sruoutput will be correct; 15075584Sruit also interprets lines beginning with 15175584Sru.B .lf 15275584Sruso that filenames and line numbers in the messages and 15375584Sru.B .lf 15475584Srulines that it produces will be accurate even if the input has been 15575584Srupreprocessed by a command such as 15675584Sru.BR @g@soelim (@MAN1EXT@). 15775584Sru.SH OPTIONS 15875584Sru.LP 15975584SruMost options are equivalent to commands 16075584Sru(for a description of these commands see the 16175584Sru.B Commands 16275584Srusubsection): 16375584Sru.TP 16475584Sru.B \-b 16575584Sru.B 16675584Sruno-label-in-text; no-label-in-reference 16775584Sru.TP 16875584Sru.B \-e 16975584Sru.B accumulate 17075584Sru.TP 17175584Sru.B \-n 17275584Sru.B no-default-database 17375584Sru.TP 17475584Sru.B \-C 17575584Sru.B compatible 17675584Sru.TP 17775584Sru.B \-P 17875584Sru.B move-punctuation 17975584Sru.TP 18075584Sru.B \-S 18175584Sru.B 18275584Srulabel "(A.n|Q) ', ' (D.y|D)"; bracket-label " (" ) "; " 18375584Sru.TP 18475584Sru.BI \-a n 18575584Sru.B reverse 18675584Sru.BI A n 18775584Sru.TP 18875584Sru.BI \-c fields 18975584Sru.B capitalize 19075584Sru.I fields 19175584Sru.TP 19275584Sru.BI \-f n 19375584Sru.B label 19475584Sru.BI % n 19575584Sru.TP 19675584Sru.BI \-i fields 19775584Sru.B search-ignore 19875584Sru.I fields 19975584Sru.TP 20075584Sru.B \-k 20175584Sru.B label 20275584Sru.B L\(ti%a 20375584Sru.TP 20475584Sru.BI \-k field 20575584Sru.B label 20675584Sru.IB field \(ti%a 20775584Sru.TP 20875584Sru.B \-l 20975584Sru.B label 21075584Sru.BI A.nD.y%a 21175584Sru.TP 21275584Sru.BI \-l m 21375584Sru.B label 21475584Sru.BI A.n+ m D.y%a 21575584Sru.TP 21675584Sru.BI \-l, n 21775584Sru.B label 21875584Sru.BI A.nD.y\- n %a 21975584Sru.TP 22075584Sru.BI \-l m , n 22175584Sru.B label 22275584Sru.BI A.n+ m D.y\- n %a 22375584Sru.TP 22475584Sru.BI \-p filename 22575584Sru.B database 22675584Sru.I filename 22775584Sru.TP 22875584Sru.BI \-s spec 22975584Sru.B sort 23075584Sru.I spec 23175584Sru.TP 23275584Sru.BI \-t n 23375584Sru.B search-truncate 23475584Sru.I n 23575584Sru.LP 23675584SruThese options are equivalent to the following commands with the 23775584Sruaddition that the filenames specified on the command line are 23875584Sruprocessed as if they were arguments to the 23975584Sru.B bibliography 24075584Srucommand instead of in the normal way: 24175584Sru.TP 24275584Sru.B \-B 24375584Sru.B 24475584Sruannotate X AP; no-label-in-reference 24575584Sru.TP 24675584Sru.BI \-B field . macro 24775584Sru.B annotate 24875584Sru.I field 24975584Sru.IB macro ; 25075584Sru.B no-label-in-reference 25175584Sru.LP 25275584SruThe following options have no equivalent commands: 25375584Sru.TP 25475584Sru.B \-v 25575584SruPrint the version number. 25675584Sru.TP 25775584Sru.B \-R 25875584SruDon't recognize lines beginning with 25975584Sru.BR .R1 / .R2 . 26075584Sru.SH USAGE 26175584Sru.SS Bibliographic databases 26275584SruThe bibliographic database is a text file consisting of records 26375584Sruseparated by one or more blank lines. 26475584SruWithin each record fields start with a 26575584Sru.B % 26675584Sruat the beginning of a line. 26775584SruEach field has a one character name that immediately follows the 26875584Sru.BR % . 26975584SruIt is best to use only upper and lower case letters for the names 27075584Sruof fields. 27175584SruThe name of the field should be followed by exactly one space, 27275584Sruand then by the contents of the field. 27375584SruEmpty fields are ignored. 27475584SruThe conventional meaning of each field is as follows: 27575584Sru.TP 27675584Sru.B A 27775584SruThe name of an author. 27875584SruIf the name contains a title such as 27975584Sru.B Jr. 28075584Sruat the end, 28175584Sruit should be separated from the last name by a comma. 28275584SruThere can be multiple occurrences of the 28375584Sru.B A 28475584Srufield. 28575584SruThe order is significant. 28675584SruIt is a good idea always to supply an 28775584Sru.B A 28875584Srufield or a 28975584Sru.B Q 29075584Srufield. 29175584Sru.TP 29275584Sru.B B 293114402SruFor an article that is part of a book, the title of the book. 29475584Sru.TP 29575584Sru.B C 29675584SruThe place (city) of publication. 29775584Sru.TP 29875584Sru.B D 29975584SruThe date of publication. 30075584SruThe year should be specified in full. 30175584SruIf the month is specified, the name rather than the number of the month 30275584Srushould be used, but only the first three letters are required. 30375584SruIt is a good idea always to supply a 30475584Sru.B D 30575584Srufield; 30675584Sruif the date is unknown, a value such as 30775584Sru.B in press 30875584Sruor 30975584Sru.B unknown 31075584Srucan be used. 31175584Sru.TP 31275584Sru.B E 31375584SruFor an article that is part of a book, the name of an editor of the book. 31475584SruWhere the work has editors and no authors, 31575584Sruthe names of the editors should be given as 31675584Sru.B A 31775584Srufields and 31875584Sru.B ,\ (ed) 31975584Sruor 32075584Sru.B ,\ (eds) 32175584Srushould be appended to the last author. 32275584Sru.TP 32375584Sru.B G 32475584SruUS Government ordering number. 32575584Sru.TP 32675584Sru.B I 32775584SruThe publisher (issuer). 32875584Sru.TP 32975584Sru.B J 33075584SruFor an article in a journal, the name of the journal. 33175584Sru.TP 33275584Sru.B K 33375584SruKeywords to be used for searching. 33475584Sru.TP 33575584Sru.B L 33675584SruLabel. 33775584Sru.TP 33875584Sru.B N 33975584SruJournal issue number. 34075584Sru.TP 34175584Sru.B O 34275584SruOther information. 34375584SruThis is usually printed at the end of the reference. 34475584Sru.TP 34575584Sru.B P 34675584SruPage number. 34775584SruA range of pages can be specified as 34875584Sru.IB m \- n\fR. 34975584Sru.TP 35075584Sru.B Q 35175584SruThe name of the author, if the author is not a person. 35275584SruThis will only be used if there are no 35375584Sru.B A 35475584Srufields. 35575584SruThere can only be one 35675584Sru.B Q 35775584Srufield. 35875584Sru.TP 35975584Sru.B R 36075584SruTechnical report number. 36175584Sru.TP 36275584Sru.B S 36375584SruSeries name. 36475584Sru.TP 36575584Sru.B T 36675584SruTitle. 36775584SruFor an article in a book or journal, 36875584Sruthis should be the title of the article. 36975584Sru.TP 37075584Sru.B V 37175584SruVolume number of the journal or book. 37275584Sru.TP 37375584Sru.B X 37475584SruAnnotation. 37575584Sru.LP 37675584SruFor all fields except 37775584Sru.B A 37875584Sruand 37975584Sru.BR E , 38075584Sruif there is more than one occurrence of a particular field in a record, 38175584Sruonly the last such field will be used. 38275584Sru.LP 38375584SruIf accent strings are used, they should follow the character to be accented. 38475584SruThis means that the 38575584Sru.B AM 38675584Srumacro must be used with the 38775584Sru.B \-ms 38875584Srumacros. 38975584SruAccent strings should not be quoted: 39075584Sruuse one 39175584Sru.B \e 39275584Srurather than two. 39375584Sru.SS Citations 39475584SruThe format of a citation is 39575584Sru.RS 39675584Sru.BI .[ opening-text 39775584Sru.br 39875584Sru.I 39975584Sruflags keywords 40075584Sru.br 40175584Sru.I fields 40275584Sru.br 40375584Sru.BI .] closing-text 40475584Sru.RE 40575584Sru.LP 40675584SruThe 40775584Sru.IR opening-text , 40875584Sru.IR closing-text 40975584Sruand 41075584Sru.I flags 41175584Srucomponents are optional. 41275584SruOnly one of the 41375584Sru.I keywords 41475584Sruand 41575584Sru.I fields 41675584Srucomponents need be specified. 41775584Sru.LP 41875584SruThe 41975584Sru.I keywords 42075584Srucomponent says to search the bibliographic databases for a reference 42175584Sruthat contains all the words in 42275584Sru.IR keywords . 42375584SruIt is an error if more than one reference if found. 42475584Sru.LP 42575584SruThe 42675584Sru.I fields 42775584Srucomponents specifies additional fields to replace or supplement 42875584Sruthose specified in the reference. 42975584SruWhen references are being accumulated and the 43075584Sru.I keywords 43175584Srucomponent is non-empty, 43275584Sruthen additional fields should be specified only on the first 43375584Sruoccasion that a particular reference is cited, 43475584Sruand will apply to all citations of that reference. 43575584Sru.LP 43675584SruThe 43775584Sru.I opening-text 43875584Sruand 43975584Sru.I closing-text 44075584Srucomponent specifies strings to be used to bracket the label instead 44175584Sruof the strings specified in the 44275584Sru.B bracket-label 44375584Srucommand. 44475584SruIf either of these components is non-empty, 44575584Sruthe strings specified in the 44675584Sru.B bracket-label 44775584Srucommand will not be used; 44875584Sruthis behaviour can be altered using the 44975584Sru.B [ 45075584Sruand 45175584Sru.B ] 45275584Sruflags. 45375584SruNote that leading and trailing spaces are significant for these components. 45475584Sru.LP 45575584SruThe 45675584Sru.I flags 45775584Srucomponent is a list of 45875584Srunon-alphanumeric characters each of which modifies the treatment 45975584Sruof this particular citation. 46075584SruUnix refer will treat these flags as part of the keywords and 46175584Sruso will ignore them since they are non-alphanumeric. 46275584SruThe following flags are currently recognized: 46375584Sru.TP 46475584Sru.B # 46575584SruThis says to use the label specified by the 46675584Sru.B short-label 46775584Srucommand, 46875584Sruinstead of that specified by the 46975584Sru.B label 47075584Srucommand. 47175584SruIf no short label has been specified, the normal label will be used. 47275584SruTypically the short label is used with author-date labels 47375584Sruand consists of only the date and possibly a disambiguating letter; 47475584Sruthe 47575584Sru.B # 47675584Sruis supposed to be suggestive of a numeric type of label. 47775584Sru.TP 47875584Sru.B [ 47975584SruPrecede 48075584Sru.I opening-text 48175584Sruwith the first string specified in the 48275584Sru.B bracket-label 48375584Srucommand. 48475584Sru.TP 48575584Sru.B ] 48675584SruFollow 48775584Sru.I closing-text 48875584Sruwith the second string specified in the 48975584Sru.B bracket-label 49075584Srucommand. 49175584Sru.LP 49275584SruOne advantages of using the 49375584Sru.B [ 49475584Sruand 49575584Sru.B ] 49675584Sruflags rather than including the brackets in 49775584Sru.I opening-text 49875584Sruand 49975584Sru.I closing-text 50075584Sruis that 50175584Sruyou can change the style of bracket used in the document just by changing the 50275584Sru.B bracket-label 50375584Srucommand. 50475584SruAnother advantage is that sorting and merging of citations 50575584Sruwill not necessarily be inhibited if the flags are used. 50675584Sru.LP 50775584SruIf a label is to be inserted into the text, 50875584Sruit will be attached to the line preceding the 50975584Sru.B .[ 51075584Sruline. 51175584SruIf there is no such line, then an extra line will be inserted before the 51275584Sru.B .[ 51375584Sruline and a warning will be given. 51475584Sru.LP 51575584SruThere is no special notation for making a citation to multiple references. 51675584SruJust use a sequence of citations, one for each reference. 51775584SruDon't put anything between the citations. 51875584SruThe labels for all the citations will be attached to the line preceding 51975584Sruthe first citation. 52075584SruThe labels may also be sorted or merged. 52175584SruSee the description of the 52275584Sru.B <> 52375584Srulabel expression, and of the 52475584Sru.B sort-adjacent-labels 52575584Sruand 52675584Sru.B abbreviate-label-ranges 52775584Srucommand. 52875584SruA label will not be merged if its citation has a non-empty 52975584Sru.I opening-text 53075584Sruor 53175584Sru.IR closing-text . 53275584SruHowever, the labels for a citation using the 53375584Sru.B ] 53475584Sruflag and without any 53575584Sru.I closing-text 53675584Sruimmediately followed by a citation using the 53775584Sru.B [ 53875584Sruflag and without any 53975584Sru.I opening-text 54075584Srumay be sorted and merged 54175584Srueven though the first citation's 54275584Sru.I opening-text 54375584Sruor the second citation's 54475584Sru.I closing-text 54575584Sruis non-empty. 54675584Sru(If you wish to prevent this just make the first citation's 54775584Sru.I closing-text 54875584Sru.BR \e& .) 54975584Sru.SS Commands 55075584SruCommands are contained between lines starting with 55175584Sru.B .R1 55275584Sruand 55375584Sru.BR .R2 . 55475584SruRecognition of these lines can be prevented by the 55575584Sru.B \-R 55675584Sruoption. 55775584SruWhen a 55875584Sru.B .R1 55975584Sruline is recognized any accumulated references are flushed out. 56075584SruNeither 56175584Sru.B .R1 56275584Srunor 56375584Sru.B .R2 56475584Srulines, 56575584Srunor anything between them 56675584Sruis output. 56775584Sru.LP 56875584SruCommands are separated by newlines or 56975584Sru.BR ; s. 57075584Sru.B # 57175584Sruintroduces a comment that extends to the end of the line 57275584Sru(but does not conceal the newline). 57375584SruEach command is broken up into words. 57475584SruWords are separated by spaces or tabs. 57575584SruA word that begins with 57675584Sru.B \(ts 57775584Sruextends to the next 57875584Sru.B \(ts 57975584Sruthat is not followed by another 58075584Sru.BR \(ts . 58175584SruIf there is no such 58275584Sru.B \(ts 58375584Sruthe word extends to the end of the line. 58475584SruPairs of 58575584Sru.B \(ts 58675584Sruin a word beginning with 58775584Sru.B \(ts 58875584Srucollapse to a single 58975584Sru.BR \(ts . 59075584SruNeither 59175584Sru.B # 59275584Srunor 59375584Sru.B ; 59475584Sruare recognized inside 59575584Sru.BR \(ts s. 59675584SruA line can be continued by ending it with 59775584Sru.BR \e ; 59875584Sruthis works everywhere except after a 59975584Sru.BR # . 60075584Sru.LP 60175584Sru.ds n \fR* 60275584SruEach command 60375584Sru.I name 60475584Sruthat is marked with \*n has an associated negative command 60575584Sru.BI no- name 60675584Sruthat undoes the effect of 60775584Sru.IR name . 60875584SruFor example, the 60975584Sru.B no-sort 61075584Srucommand specifies that references should not be sorted. 61175584SruThe negative commands take no arguments. 61275584Sru.LP 61375584SruIn the following description each argument must be a single word; 61475584Sru.I field 61575584Sruis used for a single upper or lower case letter naming a field; 61675584Sru.I fields 61775584Sruis used for a sequence of such letters; 61875584Sru.I m 61975584Sruand 62075584Sru.I n 62175584Sruare used for a non-negative numbers; 62275584Sru.I string 62375584Sruis used for an arbitrary string; 62475584Sru.I filename 62575584Sruis used for the name of a file. 62675584Sru.Tp \w'\fBabbreviate-label-ranges'u+2n 62775584Sru.BI abbreviate\*n\ fields\ string1\ string2\ string3\ string4 62875584SruAbbreviate the first names of 62975584Sru.IR fields . 63075584SruAn initial letter will be separated from another initial letter by 63175584Sru.IR string1 , 63275584Srufrom the last name by 63375584Sru.IR string2 , 63475584Sruand from anything else 63575584Sru(such as a 63675584Sru.B von 63775584Sruor 63875584Sru.BR de ) 63975584Sruby 64075584Sru.IR string3 . 64175584SruThese default to a period followed by a space. 64275584SruIn a hyphenated first name, 64375584Sruthe initial of the first part of the name will be separated from the hyphen by 64475584Sru.IR string4 ; 64575584Sruthis defaults to a period. 64675584SruNo attempt is made to handle any ambiguities that might 64775584Sruresult from abbreviation. 64875584SruNames are abbreviated before sorting and before 64975584Srulabel construction. 65075584Sru.TP 65175584Sru.BI abbreviate-label-ranges\*n\ string 65275584SruThree or more adjacent labels that refer to consecutive references 65375584Sruwill be abbreviated to a label consisting 65475584Sruof the first label, followed by 65575584Sru.I string 65675584Srufollowed by the last label. 65775584SruThis is mainly useful with numeric labels. 65875584SruIf 65975584Sru.I string 66075584Sruis omitted it defaults to 66175584Sru.BR \- . 66275584Sru.TP 66375584Sru.B accumulate\*n 66475584SruAccumulate references instead of writing out each reference 66575584Sruas it is encountered. 66675584SruAccumulated references will be written out whenever a reference 66775584Sruof the form 66875584Sru.RS 66975584Sru.IP 67075584Sru.B .[ 67175584Sru.br 67275584Sru.B $LIST$ 67375584Sru.br 67475584Sru.B .] 67575584Sru.LP 67675584Sruis encountered, 67775584Sruafter all input files hve been processed, 67875584Sruand whenever 67975584Sru.B .R1 68075584Sruline is recognized. 68175584Sru.RE 68275584Sru.TP 68375584Sru.BI annotate\*n\ field\ string 68475584Sru.I field 68575584Sruis an annotation; 68675584Sruprint it at the end of the reference as a paragraph preceded by the line 68775584Sru.RS 68875584Sru.IP 68975584Sru.BI . string 69075584Sru.LP 69175584SruIf 69275584Sru.I macro 69375584Sruis omitted it will default to 69475584Sru.BR AP ; 69575584Sruif 69675584Sru.I field 69775584Sruis also omitted it will default to 69875584Sru.BR X . 69975584SruOnly one field can be an annotation. 70075584Sru.RE 70175584Sru.TP 70275584Sru.BI articles\ string \fR\|.\|.\|. 70375584Sru.IR string \|.\|.\|. 70475584Sruare definite or indefinite articles, and should be ignored at the beginning of 70575584Sru.B T 70675584Srufields when sorting. 70775584SruInitially, 70875584Sru.BR the , 70975584Sru.B a 71075584Sruand 71175584Sru.B an 71275584Sruare recognized as articles. 71375584Sru.TP 71475584Sru.BI bibliography\ filename \fR\|.\|.\|. 71575584SruWrite out all the references contained in the bibliographic databases 71675584Sru.IR filename \|.\|.\|. 71775584Sru.TP 71875584Sru.BI bracket-label\ string1\ string2\ string3 71975584SruIn the text, bracket each label 72075584Sruwith 72175584Sru.I string1 72275584Sruand 72375584Sru.IR string2 . 72475584SruAn occurrence of 72575584Sru.I string2 72675584Sruimmediately followed by 72775584Sru.I string1 72875584Sruwill be turned into 72975584Sru.IR string3 . 73075584SruThe default behaviour is 73175584Sru.RS 73275584Sru.IP 73375584Sru.B 73475584Srubracket-label \e*([. \e*(.] ", " 73575584Sru.RE 73675584Sru.TP 73775584Sru.BI capitalize\ fields 73875584SruConvert 73975584Sru.I fields 74075584Sruto caps and small caps. 74175584Sru.TP 74275584Sru.B compatible\*n 74375584SruRecognize 74475584Sru.B .R1 74575584Sruand 74675584Sru.B .R2 74775584Srueven when followed by a character other than space or newline. 74875584Sru.TP 74975584Sru.BI database\ filename \fR\|.\|.\|. 75075584SruSearch the bibliographic databases 75175584Sru.IR filename \|.\|.\|. 75275584SruFor each 75375584Sru.I filename 75475584Sruif an index 75575584Sru.IB filename @INDEX_SUFFIX@ 75675584Srucreated by 75775584Sru.BR @g@indxbib (@MAN1EXT@) 75875584Sruexists, then it will be searched instead; 75975584Srueach index can cover multiple databases. 76075584Sru.TP 76175584Sru.BI date-as-label\*n\ string 76275584Sru.I string 76375584Sruis a label expression that specifies a string with which to replace the 76475584Sru.B D 76575584Srufield after constructing the label. 76675584SruSee the 76775584Sru.B "Label expressions" 76875584Srusubsection for a description of label expressions. 76975584SruThis command is useful if you do not want explicit labels in the 77075584Srureference list, but instead want to handle any necessary 77175584Srudisambiguation by qualifying the date in some way. 77275584SruThe label used in the text would typically be some combination of the 77375584Sruauthor and date. 77475584SruIn most cases you should also use the 77575584Sru.B no-label-in-reference 77675584Srucommand. 77775584SruFor example, 77875584Sru.RS 77975584Sru.IP 78075584Sru.B 78175584Srudate-as-label D.+yD.y%a*D.-y 78275584Sru.LP 78375584Sruwould attach a disambiguating letter to the year part of the 78475584Sru.B D 78575584Srufield in the reference. 78675584Sru.RE 78775584Sru.TP 78875584Sru.B default-database\*n 78975584SruThe default database should be searched. 79075584SruThis is the default behaviour, so the negative version of 79175584Sruthis command is more useful. 79275584Srurefer determines whether the default database should be searched 79375584Sruon the first occasion that it needs to do a search. 79475584SruThus a 79575584Sru.B no-default-database 79675584Srucommand must be given before then, 79775584Sruin order to be effective. 79875584Sru.TP 79975584Sru.BI discard\*n\ fields 80075584SruWhen the reference is read, 80175584Sru.I fields 80275584Srushould be discarded; 80375584Sruno string definitions for 80475584Sru.I fields 80575584Sruwill be output. 80675584SruInitially, 80775584Sru.I fields 80875584Sruare 80975584Sru.BR XYZ . 81075584Sru.TP 81175584Sru.BI et-al\*n\ string\ m\ n 81275584SruControl use of 81375584Sru.B 81475584Sruet al 81575584Sruin the evaluation of 81675584Sru.B @ 81775584Sruexpressions in label expressions. 81875584SruIf the number of authors needed to make the author sequence 81975584Sruunambiguous is 82075584Sru.I u 82175584Sruand the total number of authors is 82275584Sru.I t 82375584Sruthen the last 82475584Sru.IR t \|\-\| u 82575584Sruauthors will be replaced by 82675584Sru.I string 82775584Sruprovided that 82875584Sru.IR t \|\-\| u 82975584Sruis not less than 83075584Sru.I m 83175584Sruand 83275584Sru.I t 83375584Sruis not less than 83475584Sru.IR n . 83575584SruThe default behaviour is 83675584Sru.RS 83775584Sru.IP 83875584Sru.B 83975584Sruet-al " et al" 2 3 84075584Sru.RE 84175584Sru.TP 84275584Sru.BI include\ filename 84375584SruInclude 84475584Sru.I filename 84575584Sruand interpret the contents as commands. 84675584Sru.TP 84775584Sru.BI join-authors\ string1\ string2\ string3 84875584SruThis says how authors should be joined together. 84975584SruWhen there are exactly two authors, they will be joined with 85075584Sru.IR string1 . 85175584SruWhen there are more than two authors, all but the last two will 85275584Srube joined with 85375584Sru.IR string2 , 85475584Sruand the last two authors will be joined with 85575584Sru.IR string3 . 85675584SruIf 85775584Sru.I string3 85875584Sruis omitted, 85975584Sruit will default to 86075584Sru.IR string1 ; 86175584Sruif 86275584Sru.I string2 86375584Sruis also omitted it will also default to 86475584Sru.IR string1 . 86575584SruFor example, 86675584Sru.RS 86775584Sru.IP 86875584Sru.B 86975584Srujoin-authors " and " ", " ", and " 87075584Sru.LP 87175584Sruwill restore the default method for joining authors. 87275584Sru.RE 87375584Sru.TP 87475584Sru.B label-in-reference\*n 87575584SruWhen outputting the reference, 87675584Srudefine the string 87775584Sru.B [F 87875584Sruto be the reference's label. 87975584SruThis is the default behaviour; so the negative version 88075584Sruof this command is more useful. 88175584Sru.TP 88275584Sru.B label-in-text\*n 88375584SruFor each reference output a label in the text. 88475584SruThe label will be separated from the surrounding text as described in the 88575584Sru.B bracket-label 88675584Srucommand. 88775584SruThis is the default behaviour; so the negative version 88875584Sruof this command is more useful. 88975584Sru.TP 89075584Sru.BI label\ string 89175584Sru.I string 89275584Sruis a label expression describing how to label each reference. 89375584Sru.TP 89475584Sru.BI separate-label-second-parts\ string 89575584SruWhen merging two-part labels, separate the second part of the second 89675584Srulabel from the first label with 89775584Sru.IR string . 89875584SruSee the description of the 89975584Sru.B <> 90075584Srulabel expression. 90175584Sru.TP 90275584Sru.B move-punctuation\*n 90375584SruIn the text, move any punctuation at the end of line past the label. 90475584SruIt is usually a good idea to give this command unless you are using 90575584Srusuperscripted numbers as labels. 90675584Sru.TP 90775584Sru.BI reverse\*n\ string 90875584SruReverse the fields whose names 90975584Sruare in 91075584Sru.IR string . 91175584SruEach field name can be followed by a number which says 91275584Sruhow many such fields should be reversed. 91375584SruIf no number is given for a field, all such fields will be reversed. 91475584Sru.TP 91575584Sru.BI search-ignore\*n\ fields 91675584SruWhile searching for keys in databases for which no index exists, 91775584Sruignore the contents of 91875584Sru.IR fields . 91975584SruInitially, fields 92075584Sru.B XYZ 92175584Sruare ignored. 92275584Sru.TP 92375584Sru.BI search-truncate\*n\ n 92475584SruOnly require the first 92575584Sru.I n 92675584Srucharacters of keys to be given. 92775584SruIn effect when searching for a given key 92875584Sruwords in the database are truncated to the maximum of 92975584Sru.I n 93075584Sruand the length of the key. 93175584SruInitially 93275584Sru.I n 93375584Sruis 6. 93475584Sru.TP 93575584Sru.BI short-label\*n\ string 93675584Sru.I string 93775584Sruis a label expression that specifies an alternative (usually shorter) 93875584Srustyle of label. 93975584SruThis is used when the 94075584Sru.B # 94175584Sruflag is given in the citation. 94275584SruWhen using author-date style labels, the identity of the author 94375584Sruor authors is sometimes clear from the context, and so it 94475584Srumay be desirable to omit the author or authors from the label. 94575584SruThe 94675584Sru.B short-label 94775584Srucommand will typically be used to specify a label containing just 94875584Srua date and possibly a disambiguating letter. 94975584Sru.TP 95075584Sru.BI sort\*n\ string 95175584SruSort references according to 95275584Sru.BR string . 95375584SruReferences will automatically be accumulated. 95475584Sru.I string 95575584Srushould be a list of field names, each followed by a number, 95675584Sruindicating how many fields with the name should be used for sorting. 95775584Sru.B + 95875584Srucan be used to indicate that all the fields with the name should be used. 95975584SruAlso 96075584Sru.B . 96175584Srucan be used to indicate the references should be sorted using the 96275584Sru(tentative) label. 96375584Sru(The 96475584Sru.B 96575584SruLabel expressions 96675584Srusubsection describes the concept of a tentative label.) 96775584Sru.TP 96875584Sru.B sort-adjacent-labels\*n 96975584SruSort labels that are adjacent in the text according to their 97075584Sruposition in the reference list. 97175584SruThis command should usually be given if the 97275584Sru.B abbreviate-label-ranges 97375584Srucommand has been given, 97475584Sruor if the label expression contains a 97575584Sru.B <> 97675584Sruexpression. 97775584SruThis will have no effect unless references are being accumulated. 97875584Sru.SS Label expressions 97975584Sru.LP 98075584SruLabel expressions can be evaluated both normally and tentatively. 98175584SruThe result of normal evaluation is used for output. 98275584SruThe result of tentative evaluation, called the 98375584Sru.I 98475584Srutentative label, 98575584Sruis used to gather the information 98675584Sruthat normal evaluation needs to disambiguate the label. 98775584SruLabel expressions specified by the 98875584Sru.B date-as-label 98975584Sruand 99075584Sru.B short-label 99175584Srucommands are not evaluated tentatively. 99275584SruNormal and tentative evaluation are the same for all types 99375584Sruof expression other than 99475584Sru.BR @ , 99575584Sru.BR * , 99675584Sruand 99775584Sru.B % 99875584Sruexpressions. 99975584SruThe description below applies to normal evaluation, 100075584Sruexcept where otherwise specified. 100175584Sru.TP 100275584Sru.I field 100375584Sru.TQ 100475584Sru.I field\ n 100575584SruThe 100675584Sru.IR n -th 100775584Srupart of 100875584Sru.IR field . 100975584SruIf 101075584Sru.I n 101175584Sruis omitted, it defaults to 1. 101275584Sru.TP 101375584Sru.BI ' string ' 101475584SruThe characters in 101575584Sru.I string 101675584Sruliterally. 101775584Sru.TP 101875584Sru.B @ 101975584SruAll the authors joined as specified by the 102075584Sru.B join-authors 102175584Srucommand. 102275584SruThe whole of each author's name will be used. 102375584SruHowever, if the references are sorted by author 102475584Sru(that is the sort specification starts with 102575584Sru.BR A+ ), 102675584Sruthen authors' last names will be used instead, provided that this does 102775584Srunot introduce ambiguity, 102875584Sruand also an initial subsequence of the authors may be used 102975584Sruinstead of all the authors, again provided that this does not 103075584Sruintroduce ambiguity. 103175584SruThe use of only the last name for the 103275584Sru.IR i -th 103375584Sruauthor of some reference 103475584Sruis considered to be ambiguous if 103575584Sruthere is some other reference, 103675584Srusuch that the first 103775584Sru.IR i \|-\|1 103875584Sruauthors of the references are the same, 103975584Sruthe 104075584Sru.IR i -th 104175584Sruauthors are not the same, 104275584Srubut the 104375584Sru.IR i -th 104475584Sruauthors' last names are the same. 104575584SruA proper initial subsequence of the sequence 104675584Sruof authors for some reference is considered to be ambiguous if there is 104775584Srua reference with some other sequence of authors which also has 104875584Sruthat subsequence as a proper initial subsequence. 104975584SruWhen an initial subsequence of authors is used, the remaining 105075584Sruauthors are replaced by the string specified by the 105175584Sru.B et-al 105275584Srucommand; 105375584Sruthis command may also specify additional requirements that must be 105475584Srumet before an initial subsequence can be used. 105575584Sru.B @ 105675584Srutentatively evaluates to a canonical representation of the authors, 105775584Srusuch that authors that compare equally for sorting purpose 105875584Sruwill have the same representation. 105975584Sru.TP 106075584Sru.BI % n 106175584Sru.TQ 106275584Sru.B %a 106375584Sru.TQ 106475584Sru.B %A 106575584Sru.TQ 106675584Sru.B %i 106775584Sru.TQ 106875584Sru.B %I 106975584SruThe serial number of the reference formatted according to the character 107075584Srufollowing the 107175584Sru.BR % . 107275584SruThe serial number of a reference is 1 plus the number of earlier references 107375584Sruwith same tentative label as this reference. 107475584SruThese expressions tentatively evaluate to an empty string. 107575584Sru.TP 107675584Sru.IB expr * 107775584SruIf there is another reference with the same tentative label as 107875584Sruthis reference, then 107975584Sru.IR expr , 108075584Sruotherwise an empty string. 108175584SruIt tentatively evaluates to an empty string. 108275584Sru.TP 108375584Sru.IB expr + n 108475584Sru.TQ 108575584Sru.IB expr \- n 108675584SruThe first 108775584Sru.RB ( + ) 108875584Sruor last 108975584Sru.RB ( \- ) 109075584Sru.I n 109175584Sruupper or lower case letters or digits of 109275584Sru.IR expr . 109375584SruTroff special characters (such as 109475584Sru.BR \e('a ) 109575584Srucount as a single letter. 109675584SruAccent strings are retained but do not count towards the total. 109775584Sru.TP 109875584Sru.IB expr .l 109975584Sru.I expr 110075584Sruconverted to lowercase. 110175584Sru.TP 110275584Sru.IB expr .u 110375584Sru.I expr 110475584Sruconverted to uppercase. 110575584Sru.TP 110675584Sru.IB expr .c 110775584Sru.I expr 110875584Sruconverted to caps and small caps. 110975584Sru.TP 111075584Sru.IB expr .r 111175584Sru.I expr 111275584Srureversed so that the last name is first. 111375584Sru.TP 111475584Sru.IB expr .a 111575584Sru.I expr 111675584Sruwith first names abbreviated. 111775584SruNote that fields specified in the 111875584Sru.B abbreviate 111975584Srucommand are abbreviated before any labels are evaluated. 112075584SruThus 112175584Sru.B .a 112275584Sruis useful only when you want a field to be abbreviated in a label 112375584Srubut not in a reference. 112475584Sru.TP 112575584Sru.IB expr .y 112675584SruThe year part of 112775584Sru.IR expr . 112875584Sru.TP 112975584Sru.IB expr .+y 113075584SruThe part of 113175584Sru.I expr 113275584Srubefore the year, or the whole of 113375584Sru.I expr 113475584Sruif it does not contain a year. 113575584Sru.TP 113675584Sru.IB expr .\-y 113775584SruThe part of 113875584Sru.I expr 113975584Sruafter the year, or an empty string if 114075584Sru.I expr 114175584Srudoes not contain a year. 114275584Sru.TP 114375584Sru.IB expr .n 114475584SruThe last name part of 114575584Sru.IR expr . 114675584Sru.TP 114775584Sru.IB expr1 \(ti expr2 114875584Sru.I expr1 114975584Sruexcept that if the last character of 115075584Sru.I expr1 115175584Sruis 115275584Sru.B \- 115375584Sruthen it will be replaced by 115475584Sru.IR expr2 . 115575584Sru.TP 115675584Sru.I expr1\ expr2 115775584SruThe concatenation of 115875584Sru.I expr1 115975584Sruand 116075584Sru.IR expr2 . 116175584Sru.TP 116275584Sru.IB expr1 | expr2 116375584SruIf 116475584Sru.I expr1 116575584Sruis non-empty then 116675584Sru.I expr1 116775584Sruotherwise 116875584Sru.IR expr2 . 116975584Sru.TP 117075584Sru.IB expr1 & expr2 117175584SruIf 117275584Sru.I expr1 117375584Sruis non-empty 117475584Sruthen 117575584Sru.I expr2 117675584Sruotherwise an empty string. 117775584Sru.TP 117875584Sru.IB expr1 ? expr2 : expr3 117975584SruIf 118075584Sru.I expr1 118175584Sruis non-empty 118275584Sruthen 118375584Sru.I expr2 118475584Sruotherwise 118575584Sru.IR expr3 . 118675584Sru.TP 118775584Sru.BI < expr > 118875584SruThe label is in two parts, which are separated by 118975584Sru.IR expr . 119075584SruTwo adjacent two-part labels which have the same first part will be 119175584Srumerged by appending the second part of the second label onto the first 119275584Srulabel separated by the string specified in the 119375584Sru.B separate-label-second-parts 119475584Srucommand (initially, a comma followed by a space); the resulting label 119575584Sruwill also be a two-part label with the same first part as before 119675584Srumerging, and so additional labels can be merged into it. 119775584SruNote that it is permissible for the first part to be empty; 119875584Sruthis maybe desirable for expressions used in the 119975584Sru.B short-label 120075584Srucommand. 120175584Sru.TP 120275584Sru.BI ( expr ) 120375584SruThe same as 120475584Sru.IR expr . 120575584SruUsed for grouping. 120675584Sru.LP 120775584SruThe above expressions are listed in order of precedence 120875584Sru(highest first); 120975584Sru.B & 121075584Sruand 121175584Sru.B | 121275584Sruhave the same precedence. 121375584Sru.SS Macro interface 121475584SruEach reference starts with a call to the macro 121575584Sru.BR ]- . 121675584SruThe string 121775584Sru.B [F 121875584Sruwill be defined to be the label for this reference, 121975584Sruunless the 122075584Sru.B no-label-in-reference 122175584Srucommand has been given. 122275584SruThere then follows a series of string definitions, 122375584Sruone for each field: 122475584Srustring 122575584Sru.BI [ X 122675584Srucorresponds to field 122775584Sru.IR X . 122875584SruThe number register 122975584Sru.B [P 123075584Sruis set to 1 if the 123175584Sru.B P 123275584Srufield contains a range of pages. 123375584SruThe 123475584Sru.BR [T , 123575584Sru.B [A 123675584Sruand 123775584Sru.B [O 123875584Srunumber registers are set to 1 according as the 123975584Sru.BR T , 124075584Sru.B A 124175584Sruand 124275584Sru.B O 124375584Srufields end with one of the characters 124475584Sru.BR .?! . 124575584SruThe 124675584Sru.B [E 124775584Srunumber register will be set to 1 if the 124875584Sru.B [E 124975584Srustring contains more than one name. 125075584SruThe reference is followed by a call to the 125175584Sru.B ][ 125275584Srumacro. 125375584SruThe first argument to this macro gives a number representing 125475584Sruthe type of the reference. 125575584SruIf a reference contains a 125675584Sru.B J 125775584Srufield, it will be classified as type 1, 125875584Sruotherwise if it contains a 125975584Sru.B B 126075584Srufield, it will type 3, 126175584Sruotherwise if it contains a 126275584Sru.B G 126375584Sruor 126475584Sru.B R 126575584Srufield it will be type 4, 126675584Sruotherwise if contains a 126775584Sru.B I 126875584Srufield it will be type 2, 126975584Sruotherwise it will be type 0. 127075584SruThe second argument is a symbolic name for the type: 127175584Sru.BR other , 127275584Sru.BR journal-article , 127375584Sru.BR book , 127475584Sru.B article-in-book 127575584Sruor 127675584Sru.BR tech-report . 127775584SruGroups of references that have been accumulated 127875584Sruor are produced by the 127975584Sru.B bibliography 128075584Srucommand are preceded by a call to the 128175584Sru.B ]< 128275584Srumacro and followed by a call to the 128375584Sru.B ]> 128475584Srumacro. 128575584Sru.SH FILES 128675584Sru.Tp \w'\fB@DEFAULT_INDEX@'u+2n 128775584Sru.B @DEFAULT_INDEX@ 128875584SruDefault database. 128975584Sru.TP 129075584Sru.IB file @INDEX_SUFFIX@ 129175584SruIndex files. 1292114402Sru.SH ENVIRONMENT 1293114402Sru.Tp \w'\fBREFER'u+2n 1294114402Sru.B REFER 1295114402SruIf set, overrides the default database. 129675584Sru.SH "SEE ALSO" 129775584Sru.BR @g@indxbib (@MAN1EXT@), 129875584Sru.BR @g@lookbib (@MAN1EXT@), 129975584Sru.BR lkbib (@MAN1EXT@) 130075584Sru.br 130175584Sru.SH BUGS 130275584SruIn label expressions, 130375584Sru.B <> 130475584Sruexpressions are ignored inside 130575584Sru.BI . char 130675584Sruexpressions. 130779543Sru. 130879543Sru.\" Local Variables: 130979543Sru.\" mode: nroff 131079543Sru.\" End: 1311