refer.man revision 114402
1.ig 2Copyright (C) 1989-2000, 2001, 2002, 2003 Free Software Foundation, Inc. 3 4Permission is granted to make and distribute verbatim copies of 5this manual provided the copyright notice and this permission notice 6are preserved on all copies. 7 8Permission is granted to copy and distribute modified versions of this 9manual under the conditions for verbatim copying, provided that the 10entire resulting derived work is distributed under the terms of a 11permission notice identical to this one. 12 13Permission is granted to copy and distribute translations of this 14manual into another language, under the above conditions for modified 15versions, except that this permission notice may be included in 16translations approved by the Free Software Foundation instead of in 17the original English. 18.. 19.de TQ 20.br 21.ns 22.TP \\$1 23.. 24.\" Like TP, but if specified indent is more than half 25.\" the current line-length - indent, use the default indent. 26.de Tp 27.ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP 28.el .TP "\\$1" 29.. 30.\" The BSD man macros can't handle " in arguments to font change macros, 31.\" so use \(ts instead of ". 32.tr \(ts" 33.TH @G@REFER @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@" 34.SH NAME 35@g@refer \- preprocess bibliographic references for groff 36.SH SYNOPSIS 37.nr a \n(.j 38.ad l 39.nr i \n(.i 40.in +\w'\fB@g@refer 'u 41.ti \niu 42.B @g@refer 43.de OP 44.ie \\n(.$-1 .RI "[\ \fB\\$1\fP" "\\$2" "\ ]" 45.el .RB "[\ " "\\$1" "\ ]" 46.. 47.OP \-benvCPRS 48.OP \-a n 49.OP \-c fields 50.OP \-f n 51.OP \-i fields 52.OP \-k field 53.OP \-l m,n 54.OP \-p filename 55.OP \-s fields 56.OP \-t n 57.OP \-B field.macro 58.RI [\ filename \|.\|.\|.\ ] 59.br 60.ad \na 61.PP 62It is possible to have whitespace between a command line option and its 63parameter. 64.SH DESCRIPTION 65This file documents the GNU version of 66.BR refer , 67which is part of the groff document formatting system. 68.B refer 69copies the contents of 70.IR filename \|.\|.\|.\& 71to the standard output, 72except that lines between 73.B .[ 74and 75.B .] 76are interpreted as citations, 77and lines between 78.B .R1 79and 80.B .R2 81are interpreted as commands about how citations are to be processed. 82.LP 83Each citation specifies a reference. 84The citation can specify a reference that is contained in 85a bibliographic database by giving a set of keywords 86that only that reference contains. 87Alternatively it can specify a reference by supplying a database 88record in the citation. 89A combination of these alternatives is also possible. 90.LP 91For each citation, 92.B refer 93can produce a mark in the text. 94This mark consists of some label which can be separated from 95the text and from other labels in various ways. 96For each reference it also outputs 97.B groff 98commands that can be used by a macro package to produce a formatted 99reference for each citation. 100The output of 101.B refer 102must therefore be processed using a suitable macro package. 103The 104.B \-ms 105and 106.B \-me 107macros are both suitable. 108The commands to format a citation's reference can be output immediately after 109the citation, 110or the references may be accumulated, 111and the commands output at some later point. 112If the references are accumulated, then multiple citations of the same 113reference will produce a single formatted reference. 114.LP 115The interpretation of lines between 116.B .R1 117and 118.B .R2 119as commands is a new feature of GNU refer. 120Documents making use of this feature can still be processed by 121Unix refer just by adding the lines 122.RS 123.LP 124.nf 125.ft B 126\&.de R1 127\&.ig R2 128\&.. 129.ft 130.fi 131.RE 132to the beginning of the document. 133This will cause 134.B troff 135to ignore everything between 136.B .R1 137and 138.BR .R2 . 139The effect of some commands can also be achieved by options. 140These options are supported mainly for compatibility with Unix refer. 141It is usually more convenient to use commands. 142.LP 143.B refer 144generates 145.B .lf 146lines so that filenames and line numbers in messages produced 147by commands that read 148.B refer 149output will be correct; 150it also interprets lines beginning with 151.B .lf 152so that filenames and line numbers in the messages and 153.B .lf 154lines that it produces will be accurate even if the input has been 155preprocessed by a command such as 156.BR @g@soelim (@MAN1EXT@). 157.SH OPTIONS 158.LP 159Most options are equivalent to commands 160(for a description of these commands see the 161.B Commands 162subsection): 163.TP 164.B \-b 165.B 166no-label-in-text; no-label-in-reference 167.TP 168.B \-e 169.B accumulate 170.TP 171.B \-n 172.B no-default-database 173.TP 174.B \-C 175.B compatible 176.TP 177.B \-P 178.B move-punctuation 179.TP 180.B \-S 181.B 182label "(A.n|Q) ', ' (D.y|D)"; bracket-label " (" ) "; " 183.TP 184.BI \-a n 185.B reverse 186.BI A n 187.TP 188.BI \-c fields 189.B capitalize 190.I fields 191.TP 192.BI \-f n 193.B label 194.BI % n 195.TP 196.BI \-i fields 197.B search-ignore 198.I fields 199.TP 200.B \-k 201.B label 202.B L\(ti%a 203.TP 204.BI \-k field 205.B label 206.IB field \(ti%a 207.TP 208.B \-l 209.B label 210.BI A.nD.y%a 211.TP 212.BI \-l m 213.B label 214.BI A.n+ m D.y%a 215.TP 216.BI \-l, n 217.B label 218.BI A.nD.y\- n %a 219.TP 220.BI \-l m , n 221.B label 222.BI A.n+ m D.y\- n %a 223.TP 224.BI \-p filename 225.B database 226.I filename 227.TP 228.BI \-s spec 229.B sort 230.I spec 231.TP 232.BI \-t n 233.B search-truncate 234.I n 235.LP 236These options are equivalent to the following commands with the 237addition that the filenames specified on the command line are 238processed as if they were arguments to the 239.B bibliography 240command instead of in the normal way: 241.TP 242.B \-B 243.B 244annotate X AP; no-label-in-reference 245.TP 246.BI \-B field . macro 247.B annotate 248.I field 249.IB macro ; 250.B no-label-in-reference 251.LP 252The following options have no equivalent commands: 253.TP 254.B \-v 255Print the version number. 256.TP 257.B \-R 258Don't recognize lines beginning with 259.BR .R1 / .R2 . 260.SH USAGE 261.SS Bibliographic databases 262The bibliographic database is a text file consisting of records 263separated by one or more blank lines. 264Within each record fields start with a 265.B % 266at the beginning of a line. 267Each field has a one character name that immediately follows the 268.BR % . 269It is best to use only upper and lower case letters for the names 270of fields. 271The name of the field should be followed by exactly one space, 272and then by the contents of the field. 273Empty fields are ignored. 274The conventional meaning of each field is as follows: 275.TP 276.B A 277The name of an author. 278If the name contains a title such as 279.B Jr. 280at the end, 281it should be separated from the last name by a comma. 282There can be multiple occurrences of the 283.B A 284field. 285The order is significant. 286It is a good idea always to supply an 287.B A 288field or a 289.B Q 290field. 291.TP 292.B B 293For an article that is part of a book, the title of the book. 294.TP 295.B C 296The place (city) of publication. 297.TP 298.B D 299The date of publication. 300The year should be specified in full. 301If the month is specified, the name rather than the number of the month 302should be used, but only the first three letters are required. 303It is a good idea always to supply a 304.B D 305field; 306if the date is unknown, a value such as 307.B in press 308or 309.B unknown 310can be used. 311.TP 312.B E 313For an article that is part of a book, the name of an editor of the book. 314Where the work has editors and no authors, 315the names of the editors should be given as 316.B A 317fields and 318.B ,\ (ed) 319or 320.B ,\ (eds) 321should be appended to the last author. 322.TP 323.B G 324US Government ordering number. 325.TP 326.B I 327The publisher (issuer). 328.TP 329.B J 330For an article in a journal, the name of the journal. 331.TP 332.B K 333Keywords to be used for searching. 334.TP 335.B L 336Label. 337.TP 338.B N 339Journal issue number. 340.TP 341.B O 342Other information. 343This is usually printed at the end of the reference. 344.TP 345.B P 346Page number. 347A range of pages can be specified as 348.IB m \- n\fR. 349.TP 350.B Q 351The name of the author, if the author is not a person. 352This will only be used if there are no 353.B A 354fields. 355There can only be one 356.B Q 357field. 358.TP 359.B R 360Technical report number. 361.TP 362.B S 363Series name. 364.TP 365.B T 366Title. 367For an article in a book or journal, 368this should be the title of the article. 369.TP 370.B V 371Volume number of the journal or book. 372.TP 373.B X 374Annotation. 375.LP 376For all fields except 377.B A 378and 379.BR E , 380if there is more than one occurrence of a particular field in a record, 381only the last such field will be used. 382.LP 383If accent strings are used, they should follow the character to be accented. 384This means that the 385.B AM 386macro must be used with the 387.B \-ms 388macros. 389Accent strings should not be quoted: 390use one 391.B \e 392rather than two. 393.SS Citations 394The format of a citation is 395.RS 396.BI .[ opening-text 397.br 398.I 399flags keywords 400.br 401.I fields 402.br 403.BI .] closing-text 404.RE 405.LP 406The 407.IR opening-text , 408.IR closing-text 409and 410.I flags 411components are optional. 412Only one of the 413.I keywords 414and 415.I fields 416components need be specified. 417.LP 418The 419.I keywords 420component says to search the bibliographic databases for a reference 421that contains all the words in 422.IR keywords . 423It is an error if more than one reference if found. 424.LP 425The 426.I fields 427components specifies additional fields to replace or supplement 428those specified in the reference. 429When references are being accumulated and the 430.I keywords 431component is non-empty, 432then additional fields should be specified only on the first 433occasion that a particular reference is cited, 434and will apply to all citations of that reference. 435.LP 436The 437.I opening-text 438and 439.I closing-text 440component specifies strings to be used to bracket the label instead 441of the strings specified in the 442.B bracket-label 443command. 444If either of these components is non-empty, 445the strings specified in the 446.B bracket-label 447command will not be used; 448this behaviour can be altered using the 449.B [ 450and 451.B ] 452flags. 453Note that leading and trailing spaces are significant for these components. 454.LP 455The 456.I flags 457component is a list of 458non-alphanumeric characters each of which modifies the treatment 459of this particular citation. 460Unix refer will treat these flags as part of the keywords and 461so will ignore them since they are non-alphanumeric. 462The following flags are currently recognized: 463.TP 464.B # 465This says to use the label specified by the 466.B short-label 467command, 468instead of that specified by the 469.B label 470command. 471If no short label has been specified, the normal label will be used. 472Typically the short label is used with author-date labels 473and consists of only the date and possibly a disambiguating letter; 474the 475.B # 476is supposed to be suggestive of a numeric type of label. 477.TP 478.B [ 479Precede 480.I opening-text 481with the first string specified in the 482.B bracket-label 483command. 484.TP 485.B ] 486Follow 487.I closing-text 488with the second string specified in the 489.B bracket-label 490command. 491.LP 492One advantages of using the 493.B [ 494and 495.B ] 496flags rather than including the brackets in 497.I opening-text 498and 499.I closing-text 500is that 501you can change the style of bracket used in the document just by changing the 502.B bracket-label 503command. 504Another advantage is that sorting and merging of citations 505will not necessarily be inhibited if the flags are used. 506.LP 507If a label is to be inserted into the text, 508it will be attached to the line preceding the 509.B .[ 510line. 511If there is no such line, then an extra line will be inserted before the 512.B .[ 513line and a warning will be given. 514.LP 515There is no special notation for making a citation to multiple references. 516Just use a sequence of citations, one for each reference. 517Don't put anything between the citations. 518The labels for all the citations will be attached to the line preceding 519the first citation. 520The labels may also be sorted or merged. 521See the description of the 522.B <> 523label expression, and of the 524.B sort-adjacent-labels 525and 526.B abbreviate-label-ranges 527command. 528A label will not be merged if its citation has a non-empty 529.I opening-text 530or 531.IR closing-text . 532However, the labels for a citation using the 533.B ] 534flag and without any 535.I closing-text 536immediately followed by a citation using the 537.B [ 538flag and without any 539.I opening-text 540may be sorted and merged 541even though the first citation's 542.I opening-text 543or the second citation's 544.I closing-text 545is non-empty. 546(If you wish to prevent this just make the first citation's 547.I closing-text 548.BR \e& .) 549.SS Commands 550Commands are contained between lines starting with 551.B .R1 552and 553.BR .R2 . 554Recognition of these lines can be prevented by the 555.B \-R 556option. 557When a 558.B .R1 559line is recognized any accumulated references are flushed out. 560Neither 561.B .R1 562nor 563.B .R2 564lines, 565nor anything between them 566is output. 567.LP 568Commands are separated by newlines or 569.BR ; s. 570.B # 571introduces a comment that extends to the end of the line 572(but does not conceal the newline). 573Each command is broken up into words. 574Words are separated by spaces or tabs. 575A word that begins with 576.B \(ts 577extends to the next 578.B \(ts 579that is not followed by another 580.BR \(ts . 581If there is no such 582.B \(ts 583the word extends to the end of the line. 584Pairs of 585.B \(ts 586in a word beginning with 587.B \(ts 588collapse to a single 589.BR \(ts . 590Neither 591.B # 592nor 593.B ; 594are recognized inside 595.BR \(ts s. 596A line can be continued by ending it with 597.BR \e ; 598this works everywhere except after a 599.BR # . 600.LP 601.ds n \fR* 602Each command 603.I name 604that is marked with \*n has an associated negative command 605.BI no- name 606that undoes the effect of 607.IR name . 608For example, the 609.B no-sort 610command specifies that references should not be sorted. 611The negative commands take no arguments. 612.LP 613In the following description each argument must be a single word; 614.I field 615is used for a single upper or lower case letter naming a field; 616.I fields 617is used for a sequence of such letters; 618.I m 619and 620.I n 621are used for a non-negative numbers; 622.I string 623is used for an arbitrary string; 624.I filename 625is used for the name of a file. 626.Tp \w'\fBabbreviate-label-ranges'u+2n 627.BI abbreviate\*n\ fields\ string1\ string2\ string3\ string4 628Abbreviate the first names of 629.IR fields . 630An initial letter will be separated from another initial letter by 631.IR string1 , 632from the last name by 633.IR string2 , 634and from anything else 635(such as a 636.B von 637or 638.BR de ) 639by 640.IR string3 . 641These default to a period followed by a space. 642In a hyphenated first name, 643the initial of the first part of the name will be separated from the hyphen by 644.IR string4 ; 645this defaults to a period. 646No attempt is made to handle any ambiguities that might 647result from abbreviation. 648Names are abbreviated before sorting and before 649label construction. 650.TP 651.BI abbreviate-label-ranges\*n\ string 652Three or more adjacent labels that refer to consecutive references 653will be abbreviated to a label consisting 654of the first label, followed by 655.I string 656followed by the last label. 657This is mainly useful with numeric labels. 658If 659.I string 660is omitted it defaults to 661.BR \- . 662.TP 663.B accumulate\*n 664Accumulate references instead of writing out each reference 665as it is encountered. 666Accumulated references will be written out whenever a reference 667of the form 668.RS 669.IP 670.B .[ 671.br 672.B $LIST$ 673.br 674.B .] 675.LP 676is encountered, 677after all input files hve been processed, 678and whenever 679.B .R1 680line is recognized. 681.RE 682.TP 683.BI annotate\*n\ field\ string 684.I field 685is an annotation; 686print it at the end of the reference as a paragraph preceded by the line 687.RS 688.IP 689.BI . string 690.LP 691If 692.I macro 693is omitted it will default to 694.BR AP ; 695if 696.I field 697is also omitted it will default to 698.BR X . 699Only one field can be an annotation. 700.RE 701.TP 702.BI articles\ string \fR\|.\|.\|. 703.IR string \|.\|.\|. 704are definite or indefinite articles, and should be ignored at the beginning of 705.B T 706fields when sorting. 707Initially, 708.BR the , 709.B a 710and 711.B an 712are recognized as articles. 713.TP 714.BI bibliography\ filename \fR\|.\|.\|. 715Write out all the references contained in the bibliographic databases 716.IR filename \|.\|.\|. 717.TP 718.BI bracket-label\ string1\ string2\ string3 719In the text, bracket each label 720with 721.I string1 722and 723.IR string2 . 724An occurrence of 725.I string2 726immediately followed by 727.I string1 728will be turned into 729.IR string3 . 730The default behaviour is 731.RS 732.IP 733.B 734bracket-label \e*([. \e*(.] ", " 735.RE 736.TP 737.BI capitalize\ fields 738Convert 739.I fields 740to caps and small caps. 741.TP 742.B compatible\*n 743Recognize 744.B .R1 745and 746.B .R2 747even when followed by a character other than space or newline. 748.TP 749.BI database\ filename \fR\|.\|.\|. 750Search the bibliographic databases 751.IR filename \|.\|.\|. 752For each 753.I filename 754if an index 755.IB filename @INDEX_SUFFIX@ 756created by 757.BR @g@indxbib (@MAN1EXT@) 758exists, then it will be searched instead; 759each index can cover multiple databases. 760.TP 761.BI date-as-label\*n\ string 762.I string 763is a label expression that specifies a string with which to replace the 764.B D 765field after constructing the label. 766See the 767.B "Label expressions" 768subsection for a description of label expressions. 769This command is useful if you do not want explicit labels in the 770reference list, but instead want to handle any necessary 771disambiguation by qualifying the date in some way. 772The label used in the text would typically be some combination of the 773author and date. 774In most cases you should also use the 775.B no-label-in-reference 776command. 777For example, 778.RS 779.IP 780.B 781date-as-label D.+yD.y%a*D.-y 782.LP 783would attach a disambiguating letter to the year part of the 784.B D 785field in the reference. 786.RE 787.TP 788.B default-database\*n 789The default database should be searched. 790This is the default behaviour, so the negative version of 791this command is more useful. 792refer determines whether the default database should be searched 793on the first occasion that it needs to do a search. 794Thus a 795.B no-default-database 796command must be given before then, 797in order to be effective. 798.TP 799.BI discard\*n\ fields 800When the reference is read, 801.I fields 802should be discarded; 803no string definitions for 804.I fields 805will be output. 806Initially, 807.I fields 808are 809.BR XYZ . 810.TP 811.BI et-al\*n\ string\ m\ n 812Control use of 813.B 814et al 815in the evaluation of 816.B @ 817expressions in label expressions. 818If the number of authors needed to make the author sequence 819unambiguous is 820.I u 821and the total number of authors is 822.I t 823then the last 824.IR t \|\-\| u 825authors will be replaced by 826.I string 827provided that 828.IR t \|\-\| u 829is not less than 830.I m 831and 832.I t 833is not less than 834.IR n . 835The default behaviour is 836.RS 837.IP 838.B 839et-al " et al" 2 3 840.RE 841.TP 842.BI include\ filename 843Include 844.I filename 845and interpret the contents as commands. 846.TP 847.BI join-authors\ string1\ string2\ string3 848This says how authors should be joined together. 849When there are exactly two authors, they will be joined with 850.IR string1 . 851When there are more than two authors, all but the last two will 852be joined with 853.IR string2 , 854and the last two authors will be joined with 855.IR string3 . 856If 857.I string3 858is omitted, 859it will default to 860.IR string1 ; 861if 862.I string2 863is also omitted it will also default to 864.IR string1 . 865For example, 866.RS 867.IP 868.B 869join-authors " and " ", " ", and " 870.LP 871will restore the default method for joining authors. 872.RE 873.TP 874.B label-in-reference\*n 875When outputting the reference, 876define the string 877.B [F 878to be the reference's label. 879This is the default behaviour; so the negative version 880of this command is more useful. 881.TP 882.B label-in-text\*n 883For each reference output a label in the text. 884The label will be separated from the surrounding text as described in the 885.B bracket-label 886command. 887This is the default behaviour; so the negative version 888of this command is more useful. 889.TP 890.BI label\ string 891.I string 892is a label expression describing how to label each reference. 893.TP 894.BI separate-label-second-parts\ string 895When merging two-part labels, separate the second part of the second 896label from the first label with 897.IR string . 898See the description of the 899.B <> 900label expression. 901.TP 902.B move-punctuation\*n 903In the text, move any punctuation at the end of line past the label. 904It is usually a good idea to give this command unless you are using 905superscripted numbers as labels. 906.TP 907.BI reverse\*n\ string 908Reverse the fields whose names 909are in 910.IR string . 911Each field name can be followed by a number which says 912how many such fields should be reversed. 913If no number is given for a field, all such fields will be reversed. 914.TP 915.BI search-ignore\*n\ fields 916While searching for keys in databases for which no index exists, 917ignore the contents of 918.IR fields . 919Initially, fields 920.B XYZ 921are ignored. 922.TP 923.BI search-truncate\*n\ n 924Only require the first 925.I n 926characters of keys to be given. 927In effect when searching for a given key 928words in the database are truncated to the maximum of 929.I n 930and the length of the key. 931Initially 932.I n 933is 6. 934.TP 935.BI short-label\*n\ string 936.I string 937is a label expression that specifies an alternative (usually shorter) 938style of label. 939This is used when the 940.B # 941flag is given in the citation. 942When using author-date style labels, the identity of the author 943or authors is sometimes clear from the context, and so it 944may be desirable to omit the author or authors from the label. 945The 946.B short-label 947command will typically be used to specify a label containing just 948a date and possibly a disambiguating letter. 949.TP 950.BI sort\*n\ string 951Sort references according to 952.BR string . 953References will automatically be accumulated. 954.I string 955should be a list of field names, each followed by a number, 956indicating how many fields with the name should be used for sorting. 957.B + 958can be used to indicate that all the fields with the name should be used. 959Also 960.B . 961can be used to indicate the references should be sorted using the 962(tentative) label. 963(The 964.B 965Label expressions 966subsection describes the concept of a tentative label.) 967.TP 968.B sort-adjacent-labels\*n 969Sort labels that are adjacent in the text according to their 970position in the reference list. 971This command should usually be given if the 972.B abbreviate-label-ranges 973command has been given, 974or if the label expression contains a 975.B <> 976expression. 977This will have no effect unless references are being accumulated. 978.SS Label expressions 979.LP 980Label expressions can be evaluated both normally and tentatively. 981The result of normal evaluation is used for output. 982The result of tentative evaluation, called the 983.I 984tentative label, 985is used to gather the information 986that normal evaluation needs to disambiguate the label. 987Label expressions specified by the 988.B date-as-label 989and 990.B short-label 991commands are not evaluated tentatively. 992Normal and tentative evaluation are the same for all types 993of expression other than 994.BR @ , 995.BR * , 996and 997.B % 998expressions. 999The description below applies to normal evaluation, 1000except where otherwise specified. 1001.TP 1002.I field 1003.TQ 1004.I field\ n 1005The 1006.IR n -th 1007part of 1008.IR field . 1009If 1010.I n 1011is omitted, it defaults to 1. 1012.TP 1013.BI ' string ' 1014The characters in 1015.I string 1016literally. 1017.TP 1018.B @ 1019All the authors joined as specified by the 1020.B join-authors 1021command. 1022The whole of each author's name will be used. 1023However, if the references are sorted by author 1024(that is the sort specification starts with 1025.BR A+ ), 1026then authors' last names will be used instead, provided that this does 1027not introduce ambiguity, 1028and also an initial subsequence of the authors may be used 1029instead of all the authors, again provided that this does not 1030introduce ambiguity. 1031The use of only the last name for the 1032.IR i -th 1033author of some reference 1034is considered to be ambiguous if 1035there is some other reference, 1036such that the first 1037.IR i \|-\|1 1038authors of the references are the same, 1039the 1040.IR i -th 1041authors are not the same, 1042but the 1043.IR i -th 1044authors' last names are the same. 1045A proper initial subsequence of the sequence 1046of authors for some reference is considered to be ambiguous if there is 1047a reference with some other sequence of authors which also has 1048that subsequence as a proper initial subsequence. 1049When an initial subsequence of authors is used, the remaining 1050authors are replaced by the string specified by the 1051.B et-al 1052command; 1053this command may also specify additional requirements that must be 1054met before an initial subsequence can be used. 1055.B @ 1056tentatively evaluates to a canonical representation of the authors, 1057such that authors that compare equally for sorting purpose 1058will have the same representation. 1059.TP 1060.BI % n 1061.TQ 1062.B %a 1063.TQ 1064.B %A 1065.TQ 1066.B %i 1067.TQ 1068.B %I 1069The serial number of the reference formatted according to the character 1070following the 1071.BR % . 1072The serial number of a reference is 1 plus the number of earlier references 1073with same tentative label as this reference. 1074These expressions tentatively evaluate to an empty string. 1075.TP 1076.IB expr * 1077If there is another reference with the same tentative label as 1078this reference, then 1079.IR expr , 1080otherwise an empty string. 1081It tentatively evaluates to an empty string. 1082.TP 1083.IB expr + n 1084.TQ 1085.IB expr \- n 1086The first 1087.RB ( + ) 1088or last 1089.RB ( \- ) 1090.I n 1091upper or lower case letters or digits of 1092.IR expr . 1093Troff special characters (such as 1094.BR \e('a ) 1095count as a single letter. 1096Accent strings are retained but do not count towards the total. 1097.TP 1098.IB expr .l 1099.I expr 1100converted to lowercase. 1101.TP 1102.IB expr .u 1103.I expr 1104converted to uppercase. 1105.TP 1106.IB expr .c 1107.I expr 1108converted to caps and small caps. 1109.TP 1110.IB expr .r 1111.I expr 1112reversed so that the last name is first. 1113.TP 1114.IB expr .a 1115.I expr 1116with first names abbreviated. 1117Note that fields specified in the 1118.B abbreviate 1119command are abbreviated before any labels are evaluated. 1120Thus 1121.B .a 1122is useful only when you want a field to be abbreviated in a label 1123but not in a reference. 1124.TP 1125.IB expr .y 1126The year part of 1127.IR expr . 1128.TP 1129.IB expr .+y 1130The part of 1131.I expr 1132before the year, or the whole of 1133.I expr 1134if it does not contain a year. 1135.TP 1136.IB expr .\-y 1137The part of 1138.I expr 1139after the year, or an empty string if 1140.I expr 1141does not contain a year. 1142.TP 1143.IB expr .n 1144The last name part of 1145.IR expr . 1146.TP 1147.IB expr1 \(ti expr2 1148.I expr1 1149except that if the last character of 1150.I expr1 1151is 1152.B \- 1153then it will be replaced by 1154.IR expr2 . 1155.TP 1156.I expr1\ expr2 1157The concatenation of 1158.I expr1 1159and 1160.IR expr2 . 1161.TP 1162.IB expr1 | expr2 1163If 1164.I expr1 1165is non-empty then 1166.I expr1 1167otherwise 1168.IR expr2 . 1169.TP 1170.IB expr1 & expr2 1171If 1172.I expr1 1173is non-empty 1174then 1175.I expr2 1176otherwise an empty string. 1177.TP 1178.IB expr1 ? expr2 : expr3 1179If 1180.I expr1 1181is non-empty 1182then 1183.I expr2 1184otherwise 1185.IR expr3 . 1186.TP 1187.BI < expr > 1188The label is in two parts, which are separated by 1189.IR expr . 1190Two adjacent two-part labels which have the same first part will be 1191merged by appending the second part of the second label onto the first 1192label separated by the string specified in the 1193.B separate-label-second-parts 1194command (initially, a comma followed by a space); the resulting label 1195will also be a two-part label with the same first part as before 1196merging, and so additional labels can be merged into it. 1197Note that it is permissible for the first part to be empty; 1198this maybe desirable for expressions used in the 1199.B short-label 1200command. 1201.TP 1202.BI ( expr ) 1203The same as 1204.IR expr . 1205Used for grouping. 1206.LP 1207The above expressions are listed in order of precedence 1208(highest first); 1209.B & 1210and 1211.B | 1212have the same precedence. 1213.SS Macro interface 1214Each reference starts with a call to the macro 1215.BR ]- . 1216The string 1217.B [F 1218will be defined to be the label for this reference, 1219unless the 1220.B no-label-in-reference 1221command has been given. 1222There then follows a series of string definitions, 1223one for each field: 1224string 1225.BI [ X 1226corresponds to field 1227.IR X . 1228The number register 1229.B [P 1230is set to 1 if the 1231.B P 1232field contains a range of pages. 1233The 1234.BR [T , 1235.B [A 1236and 1237.B [O 1238number registers are set to 1 according as the 1239.BR T , 1240.B A 1241and 1242.B O 1243fields end with one of the characters 1244.BR .?! . 1245The 1246.B [E 1247number register will be set to 1 if the 1248.B [E 1249string contains more than one name. 1250The reference is followed by a call to the 1251.B ][ 1252macro. 1253The first argument to this macro gives a number representing 1254the type of the reference. 1255If a reference contains a 1256.B J 1257field, it will be classified as type 1, 1258otherwise if it contains a 1259.B B 1260field, it will type 3, 1261otherwise if it contains a 1262.B G 1263or 1264.B R 1265field it will be type 4, 1266otherwise if contains a 1267.B I 1268field it will be type 2, 1269otherwise it will be type 0. 1270The second argument is a symbolic name for the type: 1271.BR other , 1272.BR journal-article , 1273.BR book , 1274.B article-in-book 1275or 1276.BR tech-report . 1277Groups of references that have been accumulated 1278or are produced by the 1279.B bibliography 1280command are preceded by a call to the 1281.B ]< 1282macro and followed by a call to the 1283.B ]> 1284macro. 1285.SH FILES 1286.Tp \w'\fB@DEFAULT_INDEX@'u+2n 1287.B @DEFAULT_INDEX@ 1288Default database. 1289.TP 1290.IB file @INDEX_SUFFIX@ 1291Index files. 1292.SH ENVIRONMENT 1293.Tp \w'\fBREFER'u+2n 1294.B REFER 1295If set, overrides the default database. 1296.SH "SEE ALSO" 1297.BR @g@indxbib (@MAN1EXT@), 1298.BR @g@lookbib (@MAN1EXT@), 1299.BR lkbib (@MAN1EXT@) 1300.br 1301.SH BUGS 1302In label expressions, 1303.B <> 1304expressions are ignored inside 1305.BI . char 1306expressions. 1307. 1308.\" Local Variables: 1309.\" mode: nroff 1310.\" End: 1311