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