U-REF 7

NAME

U-ref: Format references for the U troff macros.

DESCRIPTION

The u-ref macro manage references in refer format for the U troff macros set (utmac). u-ref has high level built-in capabilities:

• It formats the bibliography following the iso-690 bibliography standart which defines a lot of fields, and which fix the order on which they must appear.
• It formats differently footnotes references and bibliography list to increase readability.
• It replaces yet cited references by "Idem." or "op. cit. hereinbefore" or "op. cit. p xx.", depending if the references has been cited just before, in the same page, or in the page xx of the document. If only the heading (%h field) or or the page (%p field) of the reference differ, they are simply written after these replacement strings.
• It builds an index of references that can be printed with the .AR macro.

u-ref uses a new version of refer instead of the original heirloom refer to handle correctly the Iso-690 bibliography standart.

USAGE

Macros

The following macro can be used by the user:

• AB file.ref: Print a bibliography list of the file file.ref.
• AR: Print an index of references.
• RI: Reverse usage of Idem in reference. The first call of this macro will remove the usage of Idem, so the reference will never be replaced by "idem". Default is to replace all informations similar to the previous reference.
• RO: Reverse usage of op. cit. in reference. The first call of this macro will remove the usage of op. cit., so the reference will never be replaced by "op. cit.". Default is to replace issuer, city and date by op. cit. p. xx if the same reference appears before in the text.
• RN: Reverse usage of notes in reference. The first call of this macro will remove the usage of the note to print references, but use the PQ macro to print them in the text. Default is to enclose all references with NS and NE to print them as a notes.

Example

• Use the .[ and .] refer macro to insert the reference. The first line following the .[ macro must contain words to find the correct reference. Following lines can contain fields definition.
• Since u-ref write the reference in a note by default, you must add the \** string to insert, where appropriate, a note number in the text.
• Since the note number is inserted manually, you should use the bare mode of refer (the -b option), so that the refer command line is on the form: refer -b -p file.ref.

He said: «a short citation\**».
.[
Keywords...
%p 3
.]

FIELDS

u-ref use uppercase and lowercase fields. The conventional meaning of each field is as follows:

• A: The name of an author. If the name contains a title such as Jr. at the end, it should be separated from the last name by a comma. There can be multiple occurrences of the A field. The order is significant. It is a good idea always to supply an A field or a Q field.
• B: For an article that is part of a book, the title of the book.
• C: The place (city) of publication.
• D: The date of publication. The year should be specified in full. If the month is specified, the name rather than the number of the month should be used. It is a good idea always to supply a D field; if the date is unknown, a value such as in press or unknown can be used.
• E: For an article that is part of a book, the name of an editor of the book. For a serie of journals, the responsable of the serie. For a serie of books, the responsable of the serie. Refer man page say that where the work has editors and no authors, the names of the editors should be given as A fields and (ed) or (eds) should be appended to the last author. On the one hand this might be a good idea for sorting purpose and to be sure that the name of the editor appear before the title of the book, but on the other end, the standart says that ed should be written without parenthesis, thing that might be confusing for refer. You should try both solution and choose the best one in each situation.
• F: Internally used by refer: the number of the reference. It must should be defined by user.
• G: For a book, the ISBN (International Standard Book Number). For a Journal, the ISSN (International Standard Serial Number).
• H: Information about the publication: first edition, french edition, etc.
• h: Heading of the section of the book where the citation appears.
• I: The publisher (issuer).
• J: Defines a periodical publication: For an article in a journal, the name of the journal. For a journal from a serie, the name of the journal. For a serie of journals, the name of the serie.
• K: Keywords used for searching. This field is required by u-ref to replace citations by Idem. and co. It must be defined for u- ref to work properly, and should contain only ascii characters.
• L: Label. Not used by u-ref.
• M: The collection in which the reference is published.
• N: Journal issue number.
• O: Other information. This is usually printed at the end of the reference, before the field G. It’s the place to mention the support of an electronic document (e-mail, pdf, html...)
• P: Total number of page of the book.
• p: Exact page of the citation, or position of the article in a book. A range of pages can be specified as m−n.
• Q: The name of the author, if the author is not a person. This will only be used if there are no A fields. There can only be one Q field.
• R: Technical or scientific report number.
• S: Series name.
• T: Title. For an article in a book or a journal, this should be the title of the article.
• U: Co-author (translator, illustrator...). Should be preceded by its function: tr. for a translator, etc.
• V: For a book in a serie, the volume number of that book. For a whole serie, the number of books in that serie.
• w: Type (which) of an electronic document (online, CD-ROM...)
• X: Annotation.
• x: URL of an online document. u-ref doesn’t have macro to hyphenate correctly urls. In you bibliography database, you should use the special character \: to tell troff where to hyphenate the url, for example like this:

%x http:\://\:example.\:com/

• y: Update date of an electronic document.
• z: Date of last access to an electronic document.

For all fields except A and E, if there is more than one occurrence of a particular field in a record, only the last such field will be used.

FILES

@MACDIR@/u-ref, the macro file.

SEE ALSO

Iso-690 bibliography standart, utmac(7), refer(1), referformat(7).

Rossitza Kyheng wrote an overview of the iso-690 bibliography stanadart in an online french article: La référence bibliographique, normes et praxis.

LICENSE

u-ref macro and this manual page are distributed under an isc license.

AUTHOR

Pierre-Jean Fichet.