diff options
Diffstat (limited to 'Master/texmf-doc/source/english/tex-refs/tex-refs-chapter-bibtex.xml')
-rw-r--r-- | Master/texmf-doc/source/english/tex-refs/tex-refs-chapter-bibtex.xml | 1345 |
1 files changed, 1345 insertions, 0 deletions
diff --git a/Master/texmf-doc/source/english/tex-refs/tex-refs-chapter-bibtex.xml b/Master/texmf-doc/source/english/tex-refs/tex-refs-chapter-bibtex.xml new file mode 100644 index 00000000000..cb397dd336e --- /dev/null +++ b/Master/texmf-doc/source/english/tex-refs/tex-refs-chapter-bibtex.xml @@ -0,0 +1,1345 @@ +<?xml version='1.0' encoding='ISO-8859-1'?> + +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" +[ + <!ENTITY % tex-refs-ent SYSTEM "tex-refs.ent" > +%tex-refs-ent; +]> + +<!-- $Id: tex-refs-chapter-bibtex.xml 139 2004-08-26 16:58:10Z mw $ --> + +<chapter id="bibtex" lang="en"> + <title id="bibtex-title">&bibtex;</title> + <indexterm><primary>BibTeX</primary></indexterm> + + <note><para>The contents of this section was taken from the HTML + helppages for &bibtex; of Norman Walsh (Version 1.0, 12 Apr 94). + </para></note> + + <para>Invokes the &bibtex; utility to compile a bibliography file + for &latex;. Full details can be found in + "&latex;: A Document Preparation System" by Leslie Lamport. + </para> + + <section id="bibtex-parameters"> + <title>Parameters</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Parameters</secondary> + </indexterm> + <para><literal>bibliography-file-spec</literal></para> + <para>Specifies the name of the bibliography database file + to be compiled by &bibtex;. If the file specification does + not include a file type, &bibtex; assumes a default type of BIB. + </para> + </section> + + <section id="bibtex-command-qualifiers"> + <title>Command Qualifiers</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Command Qualifiers</secondary> + </indexterm> + <para><literal>/BIBINPUTS /BIBINPUTS=(name,...)</literal></para> + <para>Specify directories containing input files, and the order + in which they will be searched to locate each input file. + A null value in the list indicates the current directory. + The search procedure &tex; uses to locate input files is to + first search your default directory and then search each of + the directories specified by the <literal>/BIBINPUTS</literal> + option. + </para> + <para>Default is <literal>/BIBINPUTS=(TEX_BIB:)</literal>; + &tex; looks in the directory associated with the logical name + <literal>TEX_BIB.</literal> + </para> + <para><literal>/STATS /STATS /NOSTATS [D]</literal></para> + <para>This qualifier is used while debugging + <literal>.BST</literal> files to determine BIBTEX memory usage. + </para> + <para><literal>/TEXINPUTS /TEXINPUTS=(name,...)</literal></para> + <para>Specify directories containing input files, and the order + in which they will be searched to locate each input file. + A null value in the list indicates the current directory. + The search procedure &tex; uses to locate input files is to + first search your default directory and then search each of + the directories specified by the + <literal>/TEXINPUTS</literal> option. + </para> + <para>Default is <literal>/TEXINPUTS=(TEX_INPUTS)</literal>; + &tex; looks in the directory associated with the logical name + <literal>TEX_INPUTS</literal>. + </para> + <para><literal>/TRACE /TRACE /NOTRACE [D]</literal></para> + <para>This qualifier is used while debugging + <literal>.BST</literal> files to follow program flow. + </para> + </section> + + <section id="bibtex-bib-files"> + <title>bib files</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>bib files</secondary> + </indexterm> + + <para>This help entry contains the same information as + Appendix B of the &latex; manual. It describes the format + of a bibliography database (<literal>.BIB</literal>) file. + </para> + <para>A bibliography database file may contains two types + of entry - an abbreviation definition or a reference entry + for citation. + </para> + + <section id="bibtex-string-command"> + <title><filename role="nohyphenation">@STRING</filename> command</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>bib files</secondary> + <tertiary>@STRING command</tertiary> + </indexterm> + + <para>The <literal>@STRING</literal> command is used to define + abbreviations for use by &bibtex; within the bibliography + database file. The command + <programlisting> @string{jgg1 = "Journal of Gnats and Gnus, Series~1"}</programlisting> + defines 'jgg1' to be the abbreviation for the string + "Journal of Gnats and Gnus, Series~1". Parentheses can be used + in place of the outermost braces in the @string command, + and braces can be used instead of the quotation marks. + The text must have matching braces. + </para> + <para>The case of letters is ignored in an abbreviation as well + as in the command name @string, so the command above could + have been written: + <programlisting> @STRING{JgG1 = "Journal of Gnats and Gnus, Series~1"} </programlisting> + </para> + <para>A <literal>@string</literal> command can appear anywhere + before or between entries in a bibliography database file. + However, it must come before any use of the abbreviation, + so a sensible place for <literal>@string</literal> commands + is at the beginning of the file. A <literal>@string</literal> + command in the bibliography database file takes precedence + over a definition made by the bibliography style, so it can + be used to change the definition of an abbreviation such as + 'Feb'. + </para> + + </section> + + <section id="bibtex-entry-format"> + <title>Entry Format</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>bib files</secondary> + <tertiary>Entry Format</tertiary> + </indexterm> + + <para>A bibliography database file contains a series of + reference entries like the following: + <programlisting> @BOOK{kn:gnus, + AUTHOR = "Donald E. Knudson", + TITLE = "1966 World Gnus Almanac", + PUBLISHER = {Permafrost Press}, + ADDRESS = {Novisibirsk} }</programlisting> + </para> + <para>The <literal>@BOOK</literal> states that this is an + entry of type book. various entry types are described below. + The 'kn:gnus' is the citation key, as it appears in the + argument of a <literal>\cite</literal> command referring + to the entry. + </para> + <para>This entry has four fields, named + <literal>AUTHOR</literal>, <literal>TITLE</literal>, + <literal>PUBLISHER</literal> and <literal>ADDRESS</literal>. + The meanings of these and other fields are described below. + A field consists of the name, an '=' character with optional + space around it, followed by its text. The text of a field + is a string of characters, with no unmatched braces, + surrounded by either a pair of braces or a pair of '"' + characters. Entry fields are separated from one another, + and from the citation key, by commas. A comma may have + optional space around it. + </para> + <para>The outermost braces that surround the entire entry + may be replaced by parentheses. As in &tex; input files, + an end-of-line character counts as a space and one space + is equivalent to many spaces. Unlike &tex;, &bibtex; ignores + the case of letters in the entry type, citation key and + field names. The above entry could have been typed as follows: + <programlisting>@BOOK(kn:gnus, author = {Donald E. Knudson}, + TITLE = "1966 World Gnus Almanac", + PUBLISHER = {Permafrost Press}, + ADDRESS = {Novisibirsk} )</programlisting> + </para> + <para>However, the case of letters does matter to &latex;, + so the citation key ("kn:gnus" in the example above) + should appear exactly the same in all <literal>\cite</literal> + commands in the &latex; input file. + </para> + <para>The quotes or braces can be omitted around text consisting + entirely of numerals. The following two fields are equivalent: + <programlisting>Volume = "27" Volume = 27</programlisting> + </para> + </section> + + <section id="bibtex-entry-types"> + <title>Entry Types</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>bib files</secondary> + <tertiary>Entry Types</tertiary> + </indexterm> + <para>When entering a reference in the bibliography database, + the first thing to decide is what type of entry it is. No + fixed classification scheme can be complete, but &bibtex; + provides enough entry types to handle almost any reference + reasonably well. + </para> + <para>References to different types of publications contain + different information; a reference to a journal might + include the volume and number of the journal, which is + usually not meaningful for a book. Therefore, database + entries of different types have different fields for each + entry type, the fields are divided into three classes: + <variablelist role="db2latex:compact"> + <varlistentry> + <term>Required</term> + <listitem> + <para>omitting the field will produce an error + message and may result in a badly formatted + bibliography entry. If the required information + is not meaningful, you are using the wrong entry type. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Optional</term> + <listitem> + <para>the field's information will be used if present, + but can be omitted without causing any formatting + problems. A reference should contain any available + information that might help the reader, so you should + include the optional field if it is applicable. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Ignored</term> + <listitem> + <para>the field is ignored. &bibtex; ignores any field + that is not required or optional, so you can include + any fields you want in a bibliography entry. It's + often a good idea to put all relevant information + about a reference in its bibliography entry - even + information that may never appear in the bibliography. + For example, if you want to keep an abstract of a + paper in a computer file, put it in an 'abstract' + field in the paper's bibliography entry. The + bibliography database file is likely to be as good + a place as any for the abstract, and it is possible + to design a bibliography style for printing + selected abstracts. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para>&bibtex; ignores the case of letters in the entry + type.</para> + + <section id="bibtex-entry-types-article"> + <title>article entry</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Entry Types</secondary> + <tertiary>article entry</tertiary> + </indexterm> + <para>An article from a journal or magazine.</para> + <para>Format: + <programlisting>@ARTICLE{citation_key, + required_fields [, optional_fields] }</programlisting> + </para> + <para>Required fields: + <link linkend="bibtex-field-types-author">author</link>, + <link linkend="bibtex-field-types-title">title</link>, + <link linkend="bibtex-field-types-journal">journal</link>, + <link linkend="bibtex-field-types-year">year</link> + </para> + <para>Optional fields: + <link linkend="bibtex-field-types-volume">volume</link>, + <link linkend="bibtex-field-types-number">number</link>, + <link linkend="bibtex-field-types-pages">pages</link>, + <link linkend="bibtex-field-types-month">month</link>, + <link linkend="bibtex-field-types-note">note</link>, + <link linkend="bibtex-field-types-key">key</link> + </para> + </section> + + <section id="bibtex-entry-types-book"> + <title>book entry</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Entry Types</secondary> + <tertiary>book entry</tertiary> + </indexterm> + <para>A book with an explicit publisher.</para> + <para>Format: + <programlisting>@BOOK{citation_key, + required_fields [, optional_fields] }</programlisting> + </para> + <para>Required fields: + <link linkend="bibtex-field-types-author">author</link> or + <link linkend="bibtex-field-types-editor">editor</link>, + <link linkend="bibtex-field-types-title">title</link>, + <link linkend="bibtex-field-types-publisher">publisher</link>, + <link linkend="bibtex-field-types-year">year</link> + </para> + <para>Optional fields: + <link linkend="bibtex-field-types-volume">volume</link>, + <link linkend="bibtex-field-types-series">series</link>, + <link linkend="bibtex-field-types-address">address</link>, + <link linkend="bibtex-field-types-edition">edition</link>, + <link linkend="bibtex-field-types-month">month</link>, + <link linkend="bibtex-field-types-note">note</link>, + <link linkend="bibtex-field-types-key">key</link> + </para> + </section> + + <section id="bibtex-entry-types-booklet"> + <title>booklet entry</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Entry Types</secondary> + <tertiary>booklet entry</tertiary> + </indexterm> + <para>A work that is printed and bound, but without a + named publisher or sponsoring institution. + </para> + <para>Format: + <programlisting>@BOOKLET{citation_key, + required_fields [, optional_fields] }</programlisting> + </para> + <para>Required fields: + <link linkend="bibtex-field-types-title">title</link> + </para> + <para>Optional fields: + <link linkend="bibtex-field-types-author">author</link>, + <link linkend="bibtex-field-types-howpublished">howpublished</link>, + <link linkend="bibtex-field-types-address">address</link>, + <link linkend="bibtex-field-types-month">month</link>, + <link linkend="bibtex-field-types-year">year</link>, + <link linkend="bibtex-field-types-note">note</link>, + <link linkend="bibtex-field-types-key">key</link> + </para> + </section> + + <section id="bibtex-entry-types-conference"> + <title>conference entry</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Entry Types</secondary> + <tertiary>conference entry</tertiary> + </indexterm> + <para>An article in the proceedings of a conference. + This entry is identical to the 'inproceedings' entry + and is included for compatibility with another text + formatting system. + </para> + <para>Format: + <programlisting>@CONFERENCE{citation_key, + required_fields [, optional_fields] }</programlisting> + </para> + <para>Required fields: + <link linkend="bibtex-field-types-author">author</link>, + <link linkend="bibtex-field-types-title">title</link>, + <link linkend="bibtex-field-types-booktitle">booktitle</link>, + <link linkend="bibtex-field-types-year">year</link> + </para> + <para>Optional fields: + <link linkend="bibtex-field-types-editor">editor</link>, + <link linkend="bibtex-field-types-pages">pages</link>, + <link linkend="bibtex-field-types-organization">organization</link>, + <link linkend="bibtex-field-types-publisher">publisher</link>, + <link linkend="bibtex-field-types-address">address</link>, + <link linkend="bibtex-field-types-month">month</link>, + <link linkend="bibtex-field-types-note">note</link>, + <link linkend="bibtex-field-types-key">key</link> + </para> + </section> + + <section id="bibtex-entry-types-inbook"> + <title>inbook entry</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Entry Types</secondary> + <tertiary>inbook entry</tertiary> + </indexterm> + <para>A part of a book, which may be a chapter and/or + a range of pages. + </para> + <para>Format: + <programlisting>@INBOOK{citation_key, + required_fields [, optional_fields] }</programlisting> + </para> + <para>Required fields: + <link linkend="bibtex-field-types-author">author</link> + or + <link linkend="bibtex-field-types-editor">editor</link>, + <link linkend="bibtex-field-types-title">title</link>, + <link linkend="bibtex-field-types-chapter">chapter</link> + and/or + <link linkend="bibtex-field-types-pages">pages</link>, + <link linkend="bibtex-field-types-publisher">publisher</link>, + <link linkend="bibtex-field-types-year">year</link> + </para> + <para>Optional fields: + <link linkend="bibtex-field-types-volume">volume</link>, + <link linkend="bibtex-field-types-series">series</link>, + <link linkend="bibtex-field-types-address">address</link>, + <link linkend="bibtex-field-types-edition">edition</link>, + <link linkend="bibtex-field-types-month">month</link>, + <link linkend="bibtex-field-types-note">note</link>, + <link linkend="bibtex-field-types-key">key</link> + </para> + </section> + + <section id="bibtex-entry-types-incollection"> + <title>incollection entry</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Entry Types</secondary> + <tertiary>incollection entry</tertiary> + </indexterm> + <para>A part of a book with its own title.</para> + <para>Format: + <programlisting>@INCOLLECTION{citation_key, + required_fields [, optional_fields] }</programlisting> + </para> + <para>Required fields: + <link linkend="bibtex-field-types-author">author</link>, + <link linkend="bibtex-field-types-title">title</link>, + <link linkend="bibtex-field-types-booktitle">booktitle</link>, + <link linkend="bibtex-field-types-year">year</link> + </para> + <para>Optional fields: + <link linkend="bibtex-field-types-editor">editor</link>, + <link linkend="bibtex-field-types-pages">pages</link>, + <link linkend="bibtex-field-types-organization">organization</link>, + <link linkend="bibtex-field-types-publisher">publisher</link>, + <link linkend="bibtex-field-types-address">address</link>, + <link linkend="bibtex-field-types-month">month</link>, + <link linkend="bibtex-field-types-note">note</link>, + <link linkend="bibtex-field-types-key">key</link> + </para> + </section> + + <section id="bibtex-entry-types-inproceedings"> + <title>inproceedings entry</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Entry Types</secondary> + <tertiary>inproceedings entry</tertiary> + </indexterm> + <para>An article in the proceedings of a conference.</para> + <para>Format: + <programlisting>@INPROCEEDINGS{citation_key, + required_fields [, optional_fields] }</programlisting> + </para> + <para>Required fields: + <link linkend="bibtex-field-types-author">author</link>, + <link linkend="bibtex-field-types-title">title</link>, + <link linkend="bibtex-field-types-booktitle">booktitle</link>, + <link linkend="bibtex-field-types-year">year</link> + </para> + <para>Optional fields: + <link linkend="bibtex-field-types-editor">editor</link>, + <link linkend="bibtex-field-types-pages">pages</link>, + <link linkend="bibtex-field-types-organization">organization</link>, + <link linkend="bibtex-field-types-publisher">publisher</link>, + <link linkend="bibtex-field-types-address">address</link>, + <link linkend="bibtex-field-types-month">month</link>, + <link linkend="bibtex-field-types-note">note</link>, + <link linkend="bibtex-field-types-key">key</link> + </para> + </section> + + <section id="bibtex-entry-types-manual"> + <title>manual entry</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Entry Types</secondary> + <tertiary>manual entry</tertiary> + </indexterm> + <para>Technical documentation.</para> + <para>Format: + <programlisting>@MANUAL{citation_key, + required_fields [, optional_fields] }</programlisting> + </para> + <para>Required fields: + <link linkend="bibtex-field-types-title">title</link> + </para> + <para>Optional fields: + <link linkend="bibtex-field-types-author">author</link>, + <link linkend="bibtex-field-types-organization">organization</link>, + <link linkend="bibtex-field-types-address">address</link>, + <link linkend="bibtex-field-types-edition">edition</link>, + <link linkend="bibtex-field-types-month">month</link>, + <link linkend="bibtex-field-types-year">year</link>, + <link linkend="bibtex-field-types-note">note</link>, + <link linkend="bibtex-field-types-key">key</link> + </para> + </section> + + <section id="bibtex-entry-types-mastersthesis"> + <title>mastersthesis entry</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Entry Types</secondary> + <tertiary>mastersthesis entry</tertiary> + </indexterm> + <para>A Master's thesis.</para> + <para>Format: + <programlisting>@MASTERSTHESIS{citation_key, + required_fields [, optional_fields] }</programlisting> + </para> + <para>Required fields: + <link linkend="bibtex-field-types-author">author</link>, + <link linkend="bibtex-field-types-title">title</link>, + <link linkend="bibtex-field-types-school">school</link>, + <link linkend="bibtex-field-types-year">year</link> + </para> + <para>Optional fields: + <link linkend="bibtex-field-types-address">address</link>, + <link linkend="bibtex-field-types-month">month</link>, + <link linkend="bibtex-field-types-note">note</link>, + <link linkend="bibtex-field-types-key">key</link> + </para> + </section> + + <section id="bibtex-entry-types-misc"> + <title>misc entry</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Entry Types</secondary> + <tertiary>misc entry</tertiary> + </indexterm> + <para>Use this type when nothing else seems + appropriate.</para> + <para>Format: + <programlisting>@MISC{citation_key, + required_fields [, optional_fields] }</programlisting> + </para> + <para>Required fields: none + </para> + <para>Optional fields: + <link linkend="bibtex-field-types-author">author</link>, + <link linkend="bibtex-field-types-title">title</link>, + <link linkend="bibtex-field-types-howpublished">howpublished</link>, + <link linkend="bibtex-field-types-month">month</link>, + <link linkend="bibtex-field-types-year">year</link>, + <link linkend="bibtex-field-types-note">note</link>, + <link linkend="bibtex-field-types-key">key</link> + </para> + </section> + + <section id="bibtex-entry-types-phdthesis"> + <title>phdthesis entry</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Entry Types</secondary> + <tertiary>phdthesis entry</tertiary> + </indexterm> + <para>A PhD thesis. + </para> + <para>Format: + <programlisting>@PHDTHESIS{citation_key, + required_fields [, optional_fields] }</programlisting> + </para> + <para>Required fields: + <link linkend="bibtex-field-types-author">author</link>, + <link linkend="bibtex-field-types-title">title</link>, + <link linkend="bibtex-field-types-school">school</link>, + <link linkend="bibtex-field-types-year">year</link> + </para> + <para>Optional fields: + <link linkend="bibtex-field-types-address">address</link>, + <link linkend="bibtex-field-types-month">month</link>, + <link linkend="bibtex-field-types-note">note</link>, + <link linkend="bibtex-field-types-key">key</link> + </para> + </section> + + <section id="bibtex-entry-types-proceedings"> + <title>proceedings entry</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Entry Types</secondary> + <tertiary>proceedings entry</tertiary> + </indexterm> + <para>The proceedings of a conference. + </para> + <para>Format: + <programlisting>@PROCEEDINGS{citation_key, + required_fields [, optional_fields] }</programlisting> + </para> + <para>Required fields: + <link linkend="bibtex-field-types-title">title</link>, + <link linkend="bibtex-field-types-year">year</link> + </para> + <para>Optional fields: + <link linkend="bibtex-field-types-editor">editor</link>, + <link linkend="bibtex-field-types-publisher">publisher</link>, + <link linkend="bibtex-field-types-organization">organization</link>, + <link linkend="bibtex-field-types-address">address</link>, + <link linkend="bibtex-field-types-month">month</link>, + <link linkend="bibtex-field-types-note">note</link>, + <link linkend="bibtex-field-types-key">key</link> + </para> + </section> + + <section id="bibtex-entry-types-techreport"> + <title>techreport entry</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Entry Types</secondary> + <tertiary>techreport entry</tertiary> + </indexterm> + <para>A report published by a school or other institution, + usually numbered within a series. + </para> + <para>Format: + <programlisting>@TECHREPORT{citation_key, + required_fields [, optional_fields] }</programlisting> + </para> + <para>Required fields: + <link linkend="bibtex-field-types-author">author</link>, + <link linkend="bibtex-field-types-title">title</link>, + <link linkend="bibtex-field-types-institution">institution</link>, + <link linkend="bibtex-field-types-year">year</link> + </para> + <para>Optional fields: + <link linkend="bibtex-field-types-type">type</link>, + <link linkend="bibtex-field-types-number">number</link>, + <link linkend="bibtex-field-types-address">address</link>, + <link linkend="bibtex-field-types-month">month</link>, + <link linkend="bibtex-field-types-note">note</link>, + <link linkend="bibtex-field-types-key">key</link> + </para> + </section> + + <section id="bibtex-entry-types-unpublished"> + <title>unpublished entry</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Entry Types</secondary> + <tertiary>unpublished entry</tertiary> + </indexterm> + <para> A document with an author and title, but not + formally published. + </para> + <para>Format: + <programlisting>@UNPUBLISHED{citation_key, + required_fields [, optional_fields] }</programlisting> + </para> + <para>Required fields: + <link linkend="bibtex-field-types-author">author</link>, + <link linkend="bibtex-field-types-title">title</link>, + <link linkend="bibtex-field-types-note">note</link> + </para> + <para>Optional fields: + <link linkend="bibtex-field-types-month">month</link>, + <link linkend="bibtex-field-types-year">year</link>, + <link linkend="bibtex-field-types-key">key</link> + </para> + </section> + + </section> + + <section id="bibtex-field-text"> + <title>Field Text</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>bib files</secondary> + <tertiary>Field Text</tertiary> + </indexterm> + <para>The text of the field is enclosed in braces or double + quote characters. A part of the text is said to be enclosed + in braces if it lies inside a matching pair of braces other + than the ones enclosing the entire entry or the entire field text. + </para> + <para>&bibtex; manipulates the case of letters in the field text + as described in the subtopics below. + </para> + + <section id="bibtex-field-text-names"> + <title>Names</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Field Text</secondary> + <tertiary>Names</tertiary> + </indexterm> + <para>The text of an author or editor field represents a + list of names. The bibliography style determines the format + in which the name is printed: whether the first name or + last name appears first, if the full first name or just + the first initial is used, etc. The bibliography file entry + simply tells &bibtex; what the name is. + </para> + <para>You should type an author's complete name and let the + bibliography style decide what to abbreviate. (But an + author's complete name may be "Donald~E. Knuth" or + even "J.~P.~Morgan"; you should type it the way the + author would like it to appear, if that's known.) + </para> + <para>Most names can be entered in the obvious way, either + with or without a comma, as in the following examples: + </para> + <para>"John Paul Jones" "Jones, John Paul" + "Ludwig von Beethoven" "von Beethoven, Ludwig" + </para> + <para>Some people have multiple last names - for example, + Per Brinch Hansen's last name is Brinch~Hansen. + His name should be typed with a comma: + </para> + <para> "Brinch Hansen, Per" + </para> + <para>To understand why, you must understand how &bibtex; + handles names (for what follows, a "name" corresponds + to a person). + </para> + <para>Each name consists of four parts: First, von, Last, + and~Jr; each part consists of a (possibly empty) list + of name-tokens. For example the First part of + Per Brinch~Hansen's name has the single token "Per"; + the Last part has two, "Brinch" and "Hansen"; and the + von and Jr parts are empty. If you had typed + </para> + <para>"Per Brinch Hansen"</para> + <para>instead, &bibtex; would erroneously think "Brinch" + were a First-part token, just as "Paul" is a First-part + token in "John~Paul Jones". + </para> + <para>Here's another example:</para> + <para>"Charles Louis Xavier Joseph de la Vallee + Poussin" + </para> + <para>This name has four tokens in the First part, two + in the von, and two in the Last. Here &bibtex; knows + where one part ends and the other begins because the + tokens in the von part begin with lower-case letters. + </para> + <para>If you want &bibtex; to consider something a single + token, enclose it in braces. You should do this, + for example, if a comma is part of a name: + </para> + <para>"{Barnes and Noble, Inc.}" "{Barnes and} {Noble, Inc.}" + "{Barnes} {and} {Noble,} {Inc.}" + </para> + <para>The braces surrounding the comma keep "Inc." from + being interpreted as a First token; this name has only + a Last part, with either one, two, or four tokens + (there must be a space separating the tokens in the + second and third forms). Probably the second form is + slightly more meaningful, but don't lose sleep over this + since only rarely will an institution be an author or + editor. + </para> + <para>So the two names</para> + <para>"von Beethoven, Ludwig" "{von Beethoven}, Ludwig" + </para> + <para>are considered by &bibtex; to be different names. + In the first, "Beethoven" is the Last part and "von" + is the von part; in the second, which in this case + happens to be incorrect, the Last part has a single + token and there's no von part. The bibliography style + will probably print both the same, but it may alphabetize + and label them differently. + </para> + <para>"Juniors" pose a special problem. Most people having + "Jr." in their name precede it with a comma. Such a name + should be entered as follows: + </para> + <para>"Ford, Jr., Henry"</para> + <para>However, a few people do not use a comma. They are + handled by considering the "Jr." to be part of the last + Last token: + </para> + <para>"{Steele Jr.}, Guy L." "Guy L. {Steele Jr.}"</para> + <para>This name has no Jr part.</para> + <para>To summarize, you may type a name in one of + three forms: + </para> + <para>"First von Last" "von Last, First" + "von Last, Jr, First" + </para> + <para>You may almost always use the first form; you shouldn't + if either there's a Jr part or the Last part has multiple + tokens but there's no von part. + </para> + <para>If there are multiple authors or editors, their + names must be separated by the word "and", surrounded + by spaces, not enclosed in braces: + </para> + <para>AUTHOR = "Ralph Alpher and Bethe, Hans and George Gamow" + </para> + <para>Since &bibtex; interprets commas as separating parts + of a name and "and" as separating names themselves, + this example has three coauthors: Ralph Alpher, + Hans Bethe, and George Gamow. If the word "and" appears + as part of a name, it must be enclosed in braces, as in + the example of "Barnes and Noble,~Inc." given above. + If you have too many names to list in a field, you can + end the list with "and others"; the standard styles + appropriately append an "et al." + </para> + <para>&bibtex;'s rules are actually a bit more complicated + than indicated here, but this description will + suffice for most names. + </para> + </section> + + <section id="bibtex-field-text-titles"> + <title>Titles</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Field Text</secondary> + <tertiary>Titles</tertiary> + </indexterm> + <para>The bibliography style determines whether or not a + title is capitalized; the titles of books usually are, + the title of articles usually are not. You type a title + the way it should appear if it is capitalized (you + should capitalize everything but articles and unstressed + conjunctions and prepositions, and even these should + be capitalized as the first word or + the first after a colon): + </para> + <para>TITLE = "The Agony and the Ecstasy"</para> + <para>&bibtex; will change uppercase letters to lowercase + if appropriate. Uppercase letters that should not be + changed are enclosed in braces. The following two + titles are equivalent; the "A" of "Africa" will not + be made lowercase. + </para> + <para>"The Gnats and Gnus of {Africa}" + "The Gnats and Gnus of {A}frica" + </para> + </section> + + <section id="bibtex-field-text-abbr"> + <title>Abbreviations</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Field Text</secondary> + <tertiary>Abbreviations</tertiary> + </indexterm> + <para>Instead of an ordinary text string, the text of a + field can be replaced by an abbreviation for it. An + abbreviation is a string of characters that starts + with a letter and does not contain a space or any + of the following ten characters: + </para> + <para><literal>" # % ' ( ) , = { }</literal></para> + <para>The abbreviation is typed in place of the text + field, with no braces or quotation marks. If 'jgg1' + is an abbreviation for + </para> + <para>Journal of Gnats and Gnus, Series~1</para> + <para>then the following are equivalent:</para> + <para>JOURNAL = jgg1 JOURNAL = "Journal of Gnats and + Gnus, Series~1"</para> + <para>Some abbreviations are predefined by the bibliography + style. These always include the usual 3 letter + abbreviations for the month: jan, feb, mar etc. + </para> + <para>Bibliography styles usually contain abbreviations + for the names of commonly referenced journals. Consult + the Local Guide for a list of the predefined abbreviations + for the bibliography styles available. + </para> + <para>You can define your own abbreviations by using + &bibtex;'s <literal>@STRING</literal> command. + </para> + </section> + + </section> + + <section id="bibtex-field-types"> + <title>Field Types</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>bib files</secondary> + <tertiary>Field Types</tertiary> + </indexterm> + <para>Below is a list of all fields recognized by the + standard bibliography styles. An entry can also contain + other fields, which are ignored by those styles. + </para> + <para>&bibtex; ignores the case of letters in the + field names. + </para> + + <section id="bibtex-field-types-address"> + <title>address field</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Field Types</secondary> + <tertiary>address field</tertiary> + </indexterm> + <para>Publisher's address. For major publishing houses, + just the city is given. For small publishers, you can + help the reader by giving the complete address. + </para> + <para>Format: + <programlisting>ADDRESS = field_text</programlisting> + </para> + </section> + + <section id="bibtex-field-types-annote"> + <title>annote field</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Field Types</secondary> + <tertiary>annote field</tertiary> + </indexterm> + <para>An annotation, used only for annotated bibliography + styles (which are not among the standard ones). + </para> + <para>Format: + <programlisting>ANNOTE = field_text</programlisting> + </para> + </section> + + <section id="bibtex-field-types-author"> + <title>author field</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Field Types</secondary> + <tertiary>author field</tertiary> + </indexterm> + <para>The name(s) of the author(s). + </para> + <para>Format: + <programlisting>AUTHOR = field_text</programlisting> + </para> + </section> + + <section id="bibtex-field-types-booktitle"> + <title>booktitle field</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Field Types</secondary> + <tertiary>booktitle field</tertiary> + </indexterm> + <para>Title of a book, part of which is being cited.</para> + <para>Format: + <programlisting>BOOKTITLE = field_text</programlisting> + </para> + </section> + + <section id="bibtex-field-types-chapter"> + <title>chapter field</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Field Types</secondary> + <tertiary>chapter field</tertiary> + </indexterm> + <para>A chapter number.</para> + <para>Format: + <programlisting>CHAPTER = field_text</programlisting> + </para> + </section> + + <section id="bibtex-field-types-edition"> + <title>edition field</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Field Types</secondary> + <tertiary>edition field</tertiary> + </indexterm> + <para>The edition of a book - for example, "second".</para> + <para>Format: + <programlisting>EDITION = field_text</programlisting> + </para> + </section> + + <section id="bibtex-field-types-editor"> + <title>editor field</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Field Types</secondary> + <tertiary>editor field</tertiary> + </indexterm> + <para>Name(s) of editor(s). If there is also an "author" + field, then the "editor" field gives the editor of + the book or collection in which the reference appears. + </para> + <para>Format: + <programlisting>EDITOR = field_text</programlisting> + </para> + </section> + + <section id="bibtex-field-types-howpublished"> + <title>howpublished field</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Field Types</secondary> + <tertiary>howpublished field</tertiary> + </indexterm> + <para>How something strange has been published.</para> + <para>Format: + <programlisting>HOWPUBLISHED = field_text</programlisting> + </para> + </section> + + <section id="bibtex-field-types-institution"> + <title>institution field</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Field Types</secondary> + <tertiary>institution field</tertiary> + </indexterm> + <para>The institution that published the work.</para> + <para>Format: + <programlisting>INSTITUTION = field_text</programlisting> + </para> + </section> + + <section id="bibtex-field-types-journal"> + <title>journal field</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Field Types</secondary> + <tertiary>journal field</tertiary> + </indexterm> + <para>A journal name. Abbreviations are provided for many + journals; see the Local Guide. + </para> + <para>Format: + <programlisting>JOURNAL = field_text</programlisting> + </para> + </section> + + <section id="bibtex-field-types-key"> + <title>key field</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Field Types</secondary> + <tertiary>key field</tertiary> + </indexterm> + <para> Used for alphabetizing and creating a label + when the "author" and "editor" fields are missing. + This field should not be confused with the citation + key that appears in the <literal>\cite</literal> + command and at the beginning of the entry. + </para> + <para>Format: + <programlisting>KEY = field_text</programlisting> + </para> + </section> + + <section id="bibtex-field-types-month"> + <title>month field</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Field Types</secondary> + <tertiary>month field</tertiary> + </indexterm> + <para>The month in which the work was published or, + for an unpublished work, in which it was written. + </para> + <para>Format: + <programlisting>MONTH = field_text</programlisting> + </para> + </section> + + <section id="bibtex-field-types-note"> + <title>note field</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Field Types</secondary> + <tertiary>note field</tertiary> + </indexterm> + <para>Any additional information that can help the reader. + </para> + <para>Format: + <programlisting>NOTE = field_text</programlisting> + </para> + </section> + + <section id="bibtex-field-types-number"> + <title>number field</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Field Types</secondary> + <tertiary>number field</tertiary> + </indexterm> + <para>The number of a journal, magazine, or technical + report. An issue of a journal or magazine is usually + identified by its volume and number; the organization + that issues a technical report usually gives it a number. + </para> + <para>Format: + <programlisting>NUMBER = field_text</programlisting> + </para> + </section> + + <section id="bibtex-field-types-organization"> + <title>organization field</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Field Types</secondary> + <tertiary>organization field</tertiary> + </indexterm> + <para>The organization sponsoring a conference. + </para> + <para>Format: + <programlisting>ORGANIZATION = field_text</programlisting> + </para> + </section> + + <section id="bibtex-field-types-pages"> + <title>pages field</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Field Types</secondary> + <tertiary>pages field</tertiary> + </indexterm> + <para>A page number or range of numbers such as "42--111"; + you may also have several of these, separating them with + commas: "7,41,73--97". The standard styles convert a + single dash to a double. > + </para> + <para>Format: + <programlisting>PAGES = field_text</programlisting> + </para> + </section> + + <section id="bibtex-field-types-publisher"> + <title>publisher field</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Field Types</secondary> + <tertiary>publisher field</tertiary> + </indexterm> + <para>The publisher's name. + </para> + <para>Format: + <programlisting>PUBLISHER = field_text</programlisting> + </para> + </section> + + <section id="bibtex-field-types-school"> + <title>school field</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Field Types</secondary> + <tertiary>school field</tertiary> + </indexterm> + <para>The name of the school where a thesis was written. + </para> + <para>Format: + <programlisting>SCHOOL = field_text</programlisting> + </para> + </section> + + <section id="bibtex-field-types-series"> + <title>series field</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Field Types</secondary> + <tertiary>series field</tertiary> + </indexterm> + <para>The name of a series or set of books. When citing + an entire book, the the "title" field gives its title + and an optional "series" field gives the name of a series + in which the book is published. + </para> + <para>Format: + <programlisting>SERIES = field_text</programlisting> + </para> + </section> + + <section id="bibtex-field-types-title"> + <title>title field</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Field Types</secondary> + <tertiary>title field</tertiary> + </indexterm> + <para>The work's title. + </para> + <para>Format: + <programlisting>TITLE = field_text</programlisting> + </para> + </section> + + <section id="bibtex-field-types-type"> + <title>type field</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Field Types</secondary> + <tertiary>type field</tertiary> + </indexterm> + <para>The type of a technical report - for example, + "Research Note". + </para> + <para>Format: + <programlisting>TYPE = field_text</programlisting> + </para> + </section> + + <section id="bibtex-field-types-volume"> + <title>volume field</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Field Types</secondary> + <tertiary>volume field</tertiary> + </indexterm> + <para>The volume of a journal or multivolume book work. + </para> + <para>Format: + <programlisting>VOLUME = field_text</programlisting> + </para> + </section> + + <section id="bibtex-field-types-year"> + <title>year field</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>Field Types</secondary> + <tertiary>year field</tertiary> + </indexterm> + <para>The year of publication or, for an unpublished + work, the year it was written. This field's text + should contain only numerals. + </para> + <para>Format: + <programlisting>YEAR = field_text</programlisting> + </para> + </section> + + </section> + + </section> + + <section id="bibtex-bst-files"> + <title>bst files</title> + <indexterm> + <primary>BibTeX</primary> + <secondary>bst files</secondary> + </indexterm> + <para>Bibliography style files define the style of a + bibliography source list.</para> + <para>The standard bibliography style files are + <link linkend="bibtex-bst-plain"><filename role="nohyphenation">PLAIN</filename></link>, + <link linkend="bibtex-bst-unsrt"><filename role="nohyphenation">UNSRT</filename></link>, + <link linkend="bibtex-bst-alpha"><filename role="nohyphenation">ALPHA</filename></link> + and + <link linkend="bibtex-bst-abbr"><filename role="nohyphenation">ABBRV</filename></link>. + </para> + <para>If you want to make a bibliography style of your own, + look at <link linkend="bibtex-bst-sample"><filename role="nohyphenation">SAMPLE.BST</filename></link>. + </para> + + <section id="bibtex-bst-abbr"> + <title><filename role="nohyphenation">ABBRV.BST</filename></title> + <indexterm> + <primary>BibTeX</primary> + <secondary>bst files</secondary> + <tertiary>ABBRV.BST</tertiary> + </indexterm> + <para>This style is the same as the style defined in + <filename>PLAIN.BST</filename>, except that entries are + more compact because first names, month names and journal + names are abbreviated. + </para> + </section> + + <section id="bibtex-bst-alpha"> + <title><filename role="nohyphenation">ALPHA.BST</filename></title> + <indexterm> + <primary>BibTeX</primary> + <secondary>bst files</secondary> + <tertiary>ALPHA.BST</tertiary> + </indexterm> + <para>This style is the same as the style defined in + <filename>PLAIN.BST</filename> except that entry labels + like "Knu66", formed from the author's name and the year + of publication, are used. + </para> + </section> + + <section id="bibtex-bst-plain"> + <title><filename role="nohyphenation">PLAIN.BST</filename></title> + <indexterm> + <primary>BibTeX</primary> + <secondary>bst files</secondary> + <tertiary>PLAIN.BST</tertiary> + </indexterm> + <para>This style is formatted more or less as suggested + by Mary-Claire van Leunen in "A Handbook for Scholars" + (Alfred A. Knopf, New York, 1979). Entries are sorted + alphabetically and are labelled with numbers. + </para> + </section> + + <section id="bibtex-bst-sample"> + <title><filename role="nohyphenation">SAMPLE.BST</filename></title> + <indexterm> + <primary>BibTeX</primary> + <secondary>bst files</secondary> + <tertiary>SAMPLE.BST</tertiary> + </indexterm> + <para>This is a sample bibliography style file meant to + help you construct a new style. It creates a bibliography + in which entries appear as follows: + </para> + <para>[Jones79] Jones, R. L. and Richards, P. Q. The Birds + and the Bees. {\it Journal of Irreproducible Results 4}, + 2 (Jan. 1979), 27-33. + </para> + <para>[Jones82a] Jones, P. G. The Bees and the + Trees ... (1982). + </para> + <para>[Jones82b] Jones, R. L. The Trees and the + Peas ... (1982). + </para> + <para>[Krist74] Kristofferson, R. P. Peopl and + Places ... (1974) + </para> + <para>It should illustrate how you write a style file. + The functions are described in an informal Pascal-like + style in comments. Because of the way while loops and + if-then-else statements must use functions, the following + convention is used. If a while loop is labeled 'foo' + in the informal description, then its test and body + are the functions named 'foo.test' and 'foo.body'. + If an if statement is labeled 'foo', then its two clauses + are the functions named 'foo.then' and 'foo.else'. + (Null clauses just use the 'skip$' function.) Note that + because functions have to be defined in terms of + already-defined functions, the actual function definitions + are given in a 'bottom-up' order. + </para> + </section> + + <section id="bibtex-bst-unsrt"> + <title><filename role="nohyphenation">UNSRT.BST</filename></title> + <indexterm> + <primary>BibTeX</primary> + <secondary>bst files</secondary> + <tertiary>UNSRT.BST</tertiary> + </indexterm> + <para>This style is that same as <filename>PLAIN.BST</filename> + except that entries appear in the order of their + first citation. + </para> + </section> + + </section> + +</chapter> |