/contrib/groff/src/preproc/refer/refer.man

   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: