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

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 1492 lines · 1489 code · 3 blank · 0 comment · 0 complexity · ba7d0a0efd87626b1887accb046abae1 MD5 · raw file

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