incubator-ooo-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r1175536 [6/11] - /incubator/ooo/ooo-site/trunk/content/bibliographic/
Date Sun, 25 Sep 2011 19:39:01 GMT
Added: incubator/ooo/ooo-site/trunk/content/bibliographic/bibtex.html
--- incubator/ooo/ooo-site/trunk/content/bibliographic/bibtex.html (added)
+++ incubator/ooo/ooo-site/trunk/content/bibliographic/bibtex.html Sun Sep 25 19:38:58 2011
@@ -0,0 +1,1175 @@
+<!--Converted with LaTeX2HTML 2002-1 (1.68)
+original version by:  Nikos Drakos, CBLU, University of Leeds
+* revised and updated by:  Marcus Hennecke, Ross Moore, Herb Swan
+* with significant contributions from:
+  Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
+<META NAME="description" CONTENT="btxdoc">
+<META NAME="keywords" CONTENT="btxdoc">
+<META NAME="resource-type" CONTENT="document">
+<META NAME="distribution" CONTENT="global">
+<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
+<META NAME="Generator" CONTENT="LaTeX2HTML v2002-1">
+<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
+<LINK REL="STYLESHEET" HREF="btxdoc.css">
+<BODY >
+<!--Navigation Panel-->
+<IMG WIDTH="81" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next_inactive"
+ SRC="file:/usr/lib/latex2html/icons/nx_grp_g.png"> 
+ SRC="file:/usr/lib/latex2html/icons/up_g.png"> 
+<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous"
+ SRC="file:/usr/lib/latex2html/icons/prev_g.png">   
+<!--End of Navigation Panel-->
+<H1><A NAME="SECTION00010000000000000000">
+1 Overview</A>
+[This document will be expanded when 
+version 1.00 comes out. Please report typos, omissions, inaccuracies,
+and especially unclear explanations to me (<TT>patashnik@SCORE.STANFORD.EDU</TT>).
+Suggestions for improvements are wanted and welcome.]
+This documentation, for 
+version 0.99b, is meant for general 
+users; bibliography-style designers should read this document and
+then read ``Designing 
+ HREF="btxdoc.html#btxhak">3</A>], which is meant for just them.
+This document has three parts: Section&nbsp;<A HREF="btxdoc.html#differences">2</A> describes
+the differences between versions 0.98i and 0.99b of 
+and between the corresponding versions of the standard styles; Section&nbsp;<A HREF="btxdoc.html#latex-appendix">3</A>
+updates Appendix&nbsp;B.2 of the L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X book&nbsp;[<A
+ HREF="btxdoc.html#latex">2</A>]; and Section&nbsp;<A HREF="btxdoc.html#odds-and-ends">4</A>
+gives some general and specific tips that aren't documented elsewhere.
+It's assumed throughout that you're familiar with the relevant sections
+This documentation also serves as sample input to help 
+implementors get it running. For most documents, this one included,
+you produce the reference list by: running L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X on the document
+(to produce the <TT>aux</TT> file(s)), then running 
+ (to produce the <TT>bbl</TT> file), then L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X twice more (first
+to find the information in the <TT>bbl</TT> file and then to get the
+forward references correct). In very rare circumstances you may need
+an extra /L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X run.
+version 0.99b should be used with L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X version 2.09, for which
+the closed bibliography format is the default; to get the open format,
+use the optional document style <TT>openbib</TT> (in an open format
+there's a line break between major blocks of a reference-list entry;
+in a closed format the blocks run together).]
+0.99b is not compatible with the old style files; nor is 
+0.98i compatible with the new ones (the new , however, is
+compatible with old database files).
+Note for implementors: 
+provides logical-area names <TT>TEXINPUTS:</TT> for bibliography-style
+files and <TT>TEXBIB:</TT> for database files it can't otherwise
+<H1><A NAME="SECTION00020000000000000000">
+2 Changes</A>
+<A NAME="differences"></A>
+This section describes the differences between 
+versions 0.98i and 0.99b, and also between the corresponding standard
+styles. There were a lot of differences; there will be a lot fewer
+between 0.99 and 1.00.
+<H2><A NAME="SECTION00021000000000000000">
+2.1 New 
+<A NAME="features"></A>
+The following list explains 's new features and how to use
+<LI>With the single command `<code>\nocite{*}</code>' you can now include
+in the reference list every entry in the database files, without having
+to explicitly <code>\cite</code> or <code>\nocite</code> each entry.
+Giving this command, in essence, <code>\nocite</code>s all the enties
+in the database, in database order, at the very spot in your document
+where you give the command.
+<LI><A NAME="concat"></A> You can now have as a field value (or an <TT>@STRING</TT>
+definition) the concatenation of several strings. For example if you've
+defined <PRE>
+    @STRING( WGA = " World Gnus Almanac" )
+</PRE> then it's easy to produce nearly-identical <TT>title</TT> fields
+for different entries: <PRE>
+  @BOOK(almanac-66,
+    title = 1966 # WGA,
+    .  .  .
+  @BOOK(almanac-67,
+    title = 1967 # WGA,
+</PRE> and so on. Or, you could have a field like <PRE>
+    month = "1~" # jan,
+</PRE> which would come out something like `<code>1~January</code>' or
+`<code>1~Jan.</code>' in the <TT>bbl</TT> file, depending on how
+your bibliography style defines the <TT>jan</TT> abbreviation. You
+may concatenate as many strings as you like (except that there's a
+limit to the overall length of the resulting field); just be sure
+to put the concatenation character `<TT>#</TT>', surrounded
+by optional spaces or newlines, between each successive pair of strings.
+has a new cross-referencing feature, explained by an example. Suppose
+you say <code>\cite{no-gnats}</code> in your document, and suppose
+you have these two entries in your database file: <PRE>
+  @INPROCEEDINGS(no-gnats,
+    crossref = "gg-proceedings",
+    author = "Rocky Gneisser",
+    title = "No Gnats Are Taken for Granite",
+    pages = "133-139")
+  .  .  .
+  @PROCEEDINGS(gg-proceedings,
+    editor = "Gerald Ford and Jimmy Carter",
+    title = "The Gnats and Gnus 1988 Proceedings",
+    booktitle = "The Gnats and Gnus 1988 Proceedings")
+</PRE> Two things happen. First, the special <TT>crossref</TT> field
+that the <TT>no-gnats</TT> entry should inherit any fields
+it's missing from the entry it cross references, <TT>gg-proceedings</TT>.
+In this case it in inherits the two fields <TT>editor</TT>
+and <TT>booktitle</TT>. Note that, in the standard styles
+at least, the <TT>booktitle</TT> field is irrelevant for the
+<TT>PROCEEDINGS</TT> entry type. The <TT>booktitle</TT>
+field appears here in the <TT>gg-proceedings</TT> entry only
+so that the entries that cross reference it may inherit the field.
+No matter how many papers from this meeting exist in the database,
+this <TT>booktitle</TT> field need only appear once.
+The second thing that happens: 
+automatically puts the entry <TT>gg-proceedings</TT> into
+the reference list if it's cross referenced by two or more entries
+that you <code>\cite</code> or <code>\nocite</code>, even if you don't
+<code>\cite</code> or <code>\nocite</code> the <TT>gg-proceedings</TT>
+entry itself. So <TT>gg-proceedings</TT> will automatically
+appear on the reference list if one other entry besides <TT>no-gnats</TT>
+cross references it.
+To guarantee that this scheme works, however, a cross-referenced entry
+must occur later in the database files than every entry that cross-references
+it. Thus, putting all cross-referenced entries at the end makes sense.
+(Moreover, you may not reliably nest cross references; that is, a
+cross-referenced entry may not itself reliably cross reference an
+entry. This is almost certainly not something you'd want to do, though.)
+One final note: This cross-referencing feature is completely unrelated
+to the old 's cross referencing, which is still allowed. Thus,
+having a field like <PRE>
+    note = "Jones \cite{jones-proof} improves the result"
+</PRE> is not affected by the new feature.
+now handles accented characters. For example if you have an entry
+with the two fields <PRE>
+    author = "Kurt G{\"o}del",
+    year = 1931,
+</PRE> and if you're using the <TT>alpha</TT> bibliography style,
+will construct the label [G&#246;d31] for this entry, which
+is what you'd want. To get this feature to work you must place the
+entire accented character in braces; in this case either <code>{\"o}</code>
+or <code>{\"{o}}</code> will do. Furthermore these braces must not
+themselves be enclosed in braces (other than the ones that might delimit
+the entire field or the entire entry); and there must be a backslash
+as the very first character inside the braces. Thus neither <code>{G{\"{o}}del}</code>
+nor <code>{G\"{o}del}</code> will work for this example.
+This feature handles all the accented characters and all but the nonbackslashed
+foreign symbols found in Tables 3.1 and&nbsp;3.2 of the L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X book.
+This feature behaves similarly for ``accents'' you might define;
+we'll see an example shortly. For the purposes of counting letters
+in labels, 
+considers everything contained inside the braces as a single letter.
+also handles hyphenated names. For example if you have an entry with
+    author = "Jean-Paul Sartre",
+</PRE> and if you're using the <TT>abbrv</TT> style, then the result
+is `J.-P. Sartre'.
+<LI><A NAME="preamble"></A> There's now an <code>@PREAMBLE</code> command
+for the database files. This command's syntax is just like <code>@STRING</code>'s,
+except that there is no name or equals-sign, just the string. Here's
+an example: <PRE>
+    @PREAMBLE{ "\newcommand{\noopsort}[1]{} "
+             # "\newcommand{\singleletter}[1]{#1} " }
+</PRE> (note the use of concatenation here, too). The standard styles output
+whatever information you give this command (L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X macros most
+likely) directly to the <TT>bbl</TT> file. We'll look at one possible
+use of this command, based on the <code>\noopsort</code> command
+just defined.
+The issue here is sorting (alphabetizing). 
+does a pretty good job, but occasionally weird circumstances conspire
+to confuse : Suppose that you have entries in your database
+for the two books in a two-volume set by the same author, and that
+you'd like volume&nbsp;1 to appear just before volume&nbsp;2 in your reference
+list. Further suppose that there's now a second edition of volume&nbsp;1,
+which came out in 1973, say, but that there's still just one edition
+of volume&nbsp;2, which came out in 1971. Since the <TT>plain</TT> standard
+style sorts by author and then year, it will place volume&nbsp;2 first
+(because its edition came out two years earlier) unless you help .
+You can do this by using the <TT>year</TT> fields below for the two
+volumes: <PRE>
+    year = "{\noopsort{a}}1973"
+    .  .  .
+    year = "{\noopsort{b}}1971"
+</PRE> According to the definition of <code>\noopsort</code>, L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X will
+print nothing but the true year for these fields. But 
+will be perfectly happy pretending that <code>\noopsort</code> specifies
+some fancy accent that's supposed to adorn the `a' and the&nbsp;`b'; thus
+sorts it will pretend that `a1973' and `b1971' are the real years,
+and since `a' comes before&nbsp;`b', it will place volume&nbsp;1 before
+volume&nbsp;2, just what you wanted. By the way, if this author has any
+other works included in your database, you'd probably want to use
+instead something like <code>{\noopsort{1968a}}1973</code> and <code>{\noopsort{1968b}}1971</code>,
+so that these two books would come out in a reasonable spot relative
+to the author's other works (this assumes that 1968 results in a reasonable
+spot, say because that's when the first edition of volume&nbsp;1 appeared).
+There is a limit to the number of <code>@PREAMBLE</code> commands
+you may use, but you'll never exceed this limit if you restrict yourself
+to one per database file; this is not a serious restriction, given
+the concatenation feature (item&nbsp;<A HREF="btxdoc.html#concat">2</A>).
+<LI>'s sorting algorithm is now stable. This means that if two
+entries have identical sort keys, those two entries will appear in
+citation order. (The bibliography styles construct these sort keys--usually
+the author information followed by the year and the title.)
+no longer does case conversion for file names; this will make 
+easier to install on Unix systems, for example.
+<LI>It's now easier to add code for processing a command-line <TT>aux</TT>-file
+<H2><A NAME="SECTION00022000000000000000">
+2.2 Changes to the standard styles</A>
+This section describes changes to the standard styles (<TT>plain</TT>,
+<TT>unsrt</TT>, <TT>alpha</TT>, <TT>abbrv</TT>) that affect ordinary
+users. Changes that affect style designers appear in the document
+ HREF="btxdoc.html#btxhak">3</A>]. 
+<LI>In general, sorting is now by ``author'', then year, then
+title--the old versions didn't use the year field. (The <TT>alpha</TT>
+style, however, sorts first by label, then ``author'', year,
+and title.) The quotes around author mean that some entry types might
+use something besides the author, like the editor or organization.
+<LI>Many unnecessary ties (<code>~</code>) have been removed. L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X thus
+will produce slightly fewer `<TT>Underfull</TT>
+<code>\hbox</code>' messages when it's formatting the reference list.
+<LI>Emphasizing (<code>{\em ...}</code>) has replaced italicizing (<code>{\it ...}</code>).
+This will almost never result in a difference between the old output
+and the new.
+<LI>The <TT>alpha</TT> style now uses a superscripted&nbsp;`<IMG
+ SRC="img2.png"
+ ALT="$^{+}$">' instead
+of a&nbsp;`*' to represent names omitted in constructing the label.
+If you really liked it the way it was, however, or if you want to
+omit the character entirely, you don't have to modify the style file--you
+can override the&nbsp;`<IMG
+ SRC="img2.png"
+ ALT="$^{+}$">' by redefining the <code>\etalchar</code>
+command that the <TT>alpha</TT> style writes onto the <TT>bbl</TT>
+file (just preceding the <code>\thebibliography</code> environment);
+use L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X's <code>\renewcommand</code> inside a database <TT>@PREAMBLE</TT>
+command, described in the previous subsection's item&nbsp;<A HREF="btxdoc.html#preamble">6</A>.
+<LI>The <TT>abbrv</TT> style now uses `Mar.' and `Sept.' for those months rather than `March' and `Sep.'
+<LI>The standard styles use 's new cross-referencing feature by
+giving a <code>\cite</code> of the cross-referenced entry and by omitting
+from the cross-referencing entry (most of the) information that appears
+in the cross-referenced entry. These styles do this when a titled
+thing (the cross-referencing entry) is part of a larger titled thing
+(the cross-referenced entry). There are five such situations: when
+which is the same) cross references a <TT>PROCEEDINGS</TT>;
+when (2)&nbsp;a <TT>BOOK</TT>, (3)&nbsp;an <TT>INBOOK</TT>, or (4)&nbsp;an
+<TT>INCOLLECTION</TT> cross references a <TT>BOOK</TT> (in
+these cases, the cross-referencing entry is a single volume in a multi-volume
+work); and when (5)&nbsp;an <TT>ARTICLE</TT> cross references
+an <TT>ARTICLE</TT> (in this case, the cross-referenced entry
+is really a journal, but there's no <TT>JOURNAL</TT> entry
+type; this will result in warning messages about an empty <TT>author</TT>
+and <TT>title</TT> for the journal--you should just ignore
+these warnings).
+entry types now take an optional <TT>type</TT> field. For example
+you can get the standard styles to call your reference a `Ph.D. dissertation'
+instead of the default `PhD thesis' by including a <PRE>
+    type = "{Ph.D.} dissertation"
+</PRE> in your database entry.
+<LI>Similarly, the <TT>INBOOK</TT> and <TT>INCOLLECTION</TT>
+entry types now take an optional <TT>type</TT> field, allowing `section&nbsp;1.2'
+instead of the default `chapter&nbsp;1.2'. You get this by putting
+    chapter = "1.2",
+    type = "Section"
+</PRE> in your database entry.
+<TT>TECHREPORT</TT> entry types now format their <TT>title</TT>
+fields as if they were <TT>ARTICLE</TT>
+<TT>title</TT>s rather than <TT>BOOK</TT>
+entry types now use the <TT>address</TT> field to tell where
+a conference was held, rather than to give the address of the publisher
+or organization. If you want to include the publisher's or organization's
+address, put it in the <TT>publisher</TT> or <TT>organization</TT>
+and <TT>PROCEEDINGS</TT> entry types now allow either <TT>volume</TT>
+or <TT>number</TT> (but not both), rather than just <TT>volume</TT>.
+<LI>The <TT>INCOLLECTION</TT> entry type now allows a <TT>series</TT>
+and an <TT>edition</TT> field.
+entry types now allow either a <TT>volume</TT> or <TT>number</TT>,
+and also a <TT>series</TT> field.
+<LI>The <TT>UNPUBLISHED</TT> entry type now outputs, in one block,
+the <TT>note</TT> field followed by the date information.
+<LI>The <TT>MANUAL</TT> entry type now prints out the <TT>organization</TT>
+in the first block if the <TT>author</TT> field is empty.
+<LI>The <TT>MISC</TT> entry type now issues a warning if all the optional
+fields are empty (that is, if the entire entry is empty).
+<H1><A NAME="SECTION00030000000000000000">
+3 The Entries</A>
+<A NAME="latex-appendix"></A>
+This section is simply a corrected version of Appendix&nbsp;B.2 of the
+ HREF="btxdoc.html#latex">2</A>], &#169;&nbsp;1986, by Addison-Wesley.
+The basic scheme is the same, only a few details have changed.
+<H2><A NAME="SECTION00031000000000000000">
+3.1 Entry Types</A>
+When entering a reference in the database, the first thing to decide
+is what type of entry it is. No fixed classification scheme can be
+complete, but 
+provides enough entry types to handle almost any reference reasonably
+References to different types of publications contain different information;
+a reference to a journal article 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: 
+<DD>Omitting the field will produce a warning message and,
+rarely, a badly formatted bibliography entry. If the required information
+is not meaningful, you are using the wrong entry type. However, if
+the required information is meaningful but, say, already included
+is some other field, simply ignore the warning.
+<DD>The field's information will be used if present, but can
+be omitted without causing any formatting problems. You should include
+the optional field if it will help the reader.
+<DD>The field is ignored. 
+ignores any field that is not required or optional, so you can include
+any fields you want in a <TT>bib</TT> file entry. It's a good
+idea to put all relevant information about a reference in its <TT>bib</TT>
+file 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 <TT>abstract</TT> field in the paper's
+<TT>bib</TT> file entry. The <TT>bib</TT> 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. Note:
+Misspelling a field name will result in its being ignored, so watch
+out for typos (especially for optional fields, since 
+won't warn you when those are missing).
+The following are the standard entry types, along with their required
+and optional fields, that are used by the standard bibliography styles.
+The fields within each class (required or optional) are listed in
+order of occurrence in the output, except that a few entry types may
+perturb the order slightly, depending on what fields are missing.
+These entry types are similar to those adapted by Brian Reid from
+the classification scheme of van&nbsp;Leunen&nbsp;[<A
+ HREF="btxdoc.html#van-leunen">4</A>] for use
+in the <I>Scribe</I> system. The meanings of the individual fields
+are explained in the next section. Some nonstandard bibliography styles
+may ignore some optional fields in creating the reference. Remember
+that, when used in the <TT>bib</TT> file, the entry-type name
+is preceded by an <TT>@</TT> character.
+<DD>An article from a journal or magazine. Required
+fields: <TT>author</TT>, <TT>title</TT>, <TT>journal</TT>,
+<TT>year</TT>. Optional fields: <TT>volume</TT>, <TT>number</TT>,
+<TT>pages</TT>, <TT>month</TT>, <TT>note</TT>.
+<DD>A book with an explicit publisher. Required fields:
+<TT>author</TT> or <TT>editor</TT>, <TT>title</TT>,
+<TT>publisher</TT>, <TT>year</TT>. Optional fields:
+<TT>volume</TT> or <TT>number</TT>, <TT>series</TT>,
+<TT>address</TT>, <TT>edition</TT>, <TT>month</TT>,
+<DD>A work that is printed and bound, but without a
+named publisher or sponsoring institution. Required field: <TT>title</TT>.
+Optional fields: <TT>author</TT>, <TT>howpublished</TT>,
+<TT>address</TT>, <TT>month</TT>, <TT>year</TT>,
+<DD>The same as <TT>INPROCEEDINGS</TT>, included
+for <I>Scribe</I> compatibility.
+<DD>A part of a book, which may be a chapter (or section
+or whatever) and/or a range of pages. Required fields: <TT>author</TT>
+or <TT>editor</TT>, <TT>title</TT>, <TT>chapter</TT>
+and/or <TT>pages</TT>, <TT>publisher</TT>, <TT>year</TT>.
+Optional fields: <TT>volume</TT> or <TT>number</TT>,
+<TT>series</TT>, <TT>type</TT>, <TT>address</TT>,
+<TT>edition</TT>, <TT>month</TT>, <TT>note</TT>.
+<DD>A part of a book having its own title. Required
+fields: <TT>author</TT>, <TT>title</TT>, <TT>booktitle</TT>,
+<TT>publisher</TT>, <TT>year</TT>. Optional fields:
+<TT>editor</TT>, <TT>volume</TT> or <TT>number</TT>,
+<TT>series</TT>, <TT>type</TT>, <TT>chapter</TT>,
+<TT>pages</TT>, <TT>address</TT>, <TT>edition</TT>,
+<TT>month</TT>, <TT>note</TT>.
+<DD>An article in a conference proceedings. Required
+fields: <TT>author</TT>, <TT>title</TT>, <TT>booktitle</TT>,
+<TT>year</TT>. Optional fields: <TT>editor</TT>, <TT>volume</TT>
+or <TT>number</TT>, <TT>series</TT>, <TT>pages</TT>,
+<TT>address</TT>, <TT>month</TT>, <TT>organization</TT>,
+<TT>publisher</TT>, <TT>note</TT>.
+<DD>Technical documentation. Required field: <TT>title</TT>.
+Optional fields: <TT>author</TT>, <TT>organization</TT>,
+<TT>address</TT>, <TT>edition</TT>, <TT>month</TT>,
+<TT>year</TT>, <TT>note</TT>.
+<DD>A Master's thesis. Required fields: <TT>author</TT>,
+<TT>title</TT>, <TT>school</TT>, <TT>year</TT>.
+Optional fields: <TT>type</TT>, <TT>address</TT>,
+<TT>month</TT>, <TT>note</TT>.
+<DD>Use this type when nothing else fits. Required fields:
+none. Optional fields: <TT>author</TT>, <TT>title</TT>,
+<TT>howpublished</TT>, <TT>month</TT>, <TT>year</TT>,
+<DD>A PhD thesis. Required fields: <TT>author</TT>,
+<TT>title</TT>, <TT>school</TT>, <TT>year</TT>.
+Optional fields: <TT>type</TT>, <TT>address</TT>,
+<TT>month</TT>, <TT>note</TT>.
+<DD>The proceedings of a conference. Required fields:
+<TT>title</TT>, <TT>year</TT>. Optional fields: <TT>editor</TT>,
+<TT>volume</TT> or <TT>number</TT>, <TT>series</TT>,
+<TT>address</TT>, <TT>month</TT>, <TT>organization</TT>,
+<TT>publisher</TT>, <TT>note</TT>.
+<DD>A report published by a school or other institution,
+usually numbered within a series. Required fields: <TT>author</TT>,
+<TT>title</TT>, <TT>institution</TT>, <TT>year</TT>.
+Optional fields: <TT>type</TT>, <TT>number</TT>, <TT>address</TT>,
+<TT>month</TT>, <TT>note</TT>.
+<DD>A document having an author and title, but not
+formally published. Required fields: <TT>author</TT>, <TT>title</TT>,
+<TT>note</TT>. Optional fields: <TT>month</TT>, <TT>year</TT>.
+In addition to the fields listed above, each entry type also has an
+optional <TT>key</TT> field, used in some styles for alphabetizing,
+for cross referencing, or for forming a <code>\bibitem</code> label.
+You should include a <TT>key</TT> field for any entry whose
+``author'' information is missing; the ``author'' information
+is usually the <TT>author</TT> field, but for some entry types
+it can be the <TT>editor</TT> or even the <TT>organization</TT>
+field (Section&nbsp;<A HREF="btxdoc.html#odds-and-ends">4</A> describes this in more detail).
+Do not confuse the <TT>key</TT> field with the key that appears
+in the <code>\cite</code> command and at the beginning of the database
+entry; this field is named ``key'' only for compatibility with
+<H2><A NAME="SECTION00032000000000000000">
+3.2 Fields</A>
+Below is a description of all fields recognized by the standard bibliography
+styles. An entry can also contain other fields, which are ignored
+by those styles. 
+<DD>Usually the address of the <TT>publisher</TT>
+or other type of institution. For major publishing houses, van&nbsp;Leunen
+recommends omitting the information entirely. For small publishers,
+on the other hand, you can help the reader by giving the complete
+<DD>An annotation. It is not used by the standard bibliography
+styles, but may be used by others that produce an annotated bibliography.
+<DD>The name(s) of the author(s), in the format described
+<DD>Title of a book, part of which is being cited.
+See the L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X book for how to type titles. For book entries,
+use the <TT>title</TT> field instead.
+<DD>A chapter (or section or whatever) number.
+<DD>The database key of the entry being cross referenced.
+<DD>The edition of a book--for example, ``Second''.
+This should be an ordinal, and should have the first letter capitalized,
+as shown here; the standard styles convert to lower case when necessary.
+<DD>Name(s) of editor(s), typed as indicated in the L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X book.
+If there is also an <TT>author</TT> field, then the <TT>editor</TT>
+field gives the editor of the book or collection in which the reference
+<DD>How something strange has been published. The
+first word should be capitalized.
+<DD>The sponsoring institution of a technical report.
+<DD>A journal name. Abbreviations are provided for many
+journals; see the <I>Local Guide</I>.
+<DD>Used for alphabetizing, cross referencing, and creating
+a label when the ``author'' information (described in Section&nbsp;<A HREF="btxdoc.html#odds-and-ends">4</A>)
+is missing. This field should not be confused with the key that appears
+in the <code>\cite</code> command and at the beginning of the database
+<DD>The month in which the work was published or, for
+an unpublished work, in which it was written. You should use the standard
+three-letter abbreviation, as described in Appendix B.1.3 of the L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X book.
+<DD>Any additional information that can help the reader.
+The first word should be capitalized.
+<DD>The number of a journal, magazine, technical report,
+or of a work in a series. 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; and sometimes books
+are given numbers in a named series.
+<DD>The organization that sponsors a conference
+or that publishes a manual.
+<DD>One or more page numbers or range of numbers, such
+as <TT>42-111</TT> or <TT>7,41,73-97</TT> or <TT>43+</TT>
+(the `<TT>+</TT>' in this last example indicates pages following that
+don't form a simple range). To make it easier to maintain <I>Scribe</I>-compatible
+databases, the standard styles convert a single dash (as in <TT>7-33</TT>)
+to the double dash used in T<SMALL>E</SMALL>X to denote number ranges (as in
+<DD>The publisher's name.
+<DD>The name of the school where a thesis was written.
+<DD>The name of a series or set of books. When citing
+an entire book, the the <TT>title</TT> field gives its title
+and an optional <TT>series</TT> field gives the name of a
+series or multi-volume set in which the book is published.
+<DD>The work's title, typed as explained in the L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X book.
+<DD>The type of a technical report--for example, ``Research
+<DD>The volume of a journal or multivolume book.
+<DD>The year of publication or, for an unpublished work,
+the year it was written. Generally it should consist of four numerals,
+such as <TT>1984</TT>, although the standard styles can handle any
+<TT>year</TT> whose last four nonpunctuation characters are numerals,
+such as `(about 1984)'.
+<H1><A NAME="SECTION00040000000000000000">
+4 Helpful Hints</A>
+<A NAME="odds-and-ends"></A>
+This section gives some random tips that aren't documented elsewhere,
+at least not in this detail. They are, roughly, in order of least
+esoteric to most. First, however, a brief spiel.
+I understand that there's often little choice in choosing a bibliography
+ SRC="img3.png"
+ ALT="$X$"> says you must use style&nbsp;<IMG
+ SRC="img4.png"
+ ALT="$Y$"> and that's that.
+If you have a choice, however, I strongly recommend that you choose
+something like the <TT>plain</TT> standard style. Such a style, van&nbsp;Leunen&nbsp;[<A
+ HREF="btxdoc.html#van-leunen">4</A>]
+argues convincingly, encourages better writing than the alternatives--more
+concrete, more vivid.
+<I>The Chicago Manual of Style</I>&nbsp;[<A
+ HREF="btxdoc.html#chicago">1</A>], on the other
+hand, espouse the author-date system, in which the citation might
+appear in the text as `(Jones, 1986)'. I argue that this system,
+besides cluttering up the text with information that may or may not
+be relevant, encourages the passive voice and vague writing. Furthermore
+the strongest arguments for using the author-date system--like ``it's
+the most practical''--fall flat on their face with the advent of
+computer-typesetting technology. For instance the <I>Chicago Manual</I>
+contains, right in the middle of page&nbsp;401, this anachronism: ``The
+chief disadvantage of [a style like <TT>plain</TT>] is that additions
+or deletions cannot be made after the manuscript is typed without
+changing numbers in both text references and list.'' L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X, obviously,
+sidesteps the disadvantage.
+Finally, the logical deficiencies of the author-date style are quite
+evident once you've written a program to implement it. For example,
+in a large bibliography, using the standard alphabetizing scheme,
+the entry for `(Aho et&nbsp;al., 1983b)' might be half a page later than
+the one for `(Aho et&nbsp;al., 1983a)'. Fixing this problem results
+in even worse ones. What a mess. (I have, unfortunately, programmed
+such a style, and if you're saddled with an unenlightened publisher
+or if you don't buy my propaganda, it's available from the Rochester
+style collection.)
+Ok, so the spiel wasn't very brief; but it made me feel better, and
+now my blood pressure is back to normal. Here are the tips for using
+with the standard styles (although many of them hold for nonstandard
+styles, too). 
+<LI>With 's style-designing language you can program general database
+manipulations, in addition to bibliography styles. For example it's
+a fairly easy task for someone familiar with the language to produce
+a database-key/author index of all the entries in a database. Consult
+the <I>Local Guide</I> to see what tools are available on your
+<LI>The standard style's thirteen entry types do reasonably well at formatting
+most entries, but no scheme with just thirteen formats can do everything
+perfectly. Thus, you should feel free to be creative in how you use
+these entry types (but if you have to be too creative, there's a good
+chance you're using the wrong entry type).
+<LI>Don't take the field names too seriously. Sometimes, for instance,
+you might have to include the publisher's address along with the publisher's
+name in the <TT>publisher</TT> field, rather than putting
+it in the <TT>address</TT> field. Or sometimes, difficult
+entries work best when you make judicious use of the <TT>note</TT>
+<LI>Don't take the warning messages too seriously. Sometimes, for instance,
+the year appears in the title, as in <I>The 1966 World Gnus Almanac</I>.
+In this case it's best to omit the <TT>year</TT> field and to ignore
+'s warning message.
+<LI>If you have too many names to list in an <TT>author</TT> or
+<TT>editor</TT> field, you can end the list with ``and
+others''; the standard styles appropriately append an ``et&nbsp;al.''
+<LI>In general, if you want to keep 
+from changing something to lower case, you enclose it in braces. You
+might not get the effect you want, however, if the very first character
+after the left brace is a backslash. The ``special characters''
+item later in this section explains.
+<LI>For <I>Scribe</I> compatibility, the database files allow an
+<TT>@COMMENT</TT> command; it's not really needed because
+allows in the database files any comment that's not within an entry.
+If you want to comment out an entry, simply remove the `<TT>@</TT>'
+character preceding the entry type.
+<LI>The standard styles have journal abbreviations that are computer-science
+oriented; these are in the style files primarily for the example.
+If you have a different set of journal abbreviations, it's sensible
+to put them in <TT>@STRING</TT> commands in their own database
+file and to list this database file as an argument to L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X's <code>\bibliography</code>
+command (but you should list this argument before the ones that specify
+real database entries).
+<LI>It's best to use the three-letter abbreviations for the month, rather
+than spelling out the month yourself. This lets the bibliography style
+be consistent. And if you want to include information for the day
+of the month, the <TT>month</TT> field is usually the best place.
+For example <PRE>
+    month = jul # "~4,"
+</PRE> will probably produce just what you want.
+<LI>If you're using the <TT>unsrt</TT> style (references are listed
+in order of citation) along with the <code>\nocite{*}</code> feature
+(all entries in the database are included), the placement of the <code>\nocite{*}</code>
+command within your document file will determine the reference order.
+According to the rule given in Section&nbsp;<A HREF="btxdoc.html#features">2.1</A>: If the command
+is placed at the beginning of the document, the entries will be listed
+in exactly the order they occur in the database; if it's placed at
+the end, the entries that you explicitly <code>\cite</code> or <code>\nocite</code>
+will occur in citation order, and the remaining database entries will
+be in database order.
+<LI>For theses, van Leunen recommends not giving the school's department
+after the name of the degree, since schools, not departments, issue
+degrees. If you really think that giving the department information
+will help the reader find the thesis, put that information in the
+<TT>address</TT> field.
+entry types are so named for <I>Scribe</I> compatibility; <TT>MINORTHESIS</TT>
+and <TT>MAJORTHESIS</TT> probably would have been better names.
+Keep this in mind when trying to classify a non-U.S. thesis.
+<LI>Here's yet another suggestion for what to do when an author's name
+appears slightly differently in two publications. Suppose, for example,
+two journals articles use these fields. <PRE>
+    author = "Donald E. Knuth"
+    .  .  .
+    author = "D. E. Knuth"
+</PRE> There are two possibilities. You could (1)&nbsp;simply leave them as
+is, or (2)&nbsp;assuming you know for sure that these authors are one
+and the same person, you could list both in the form that the author
+prefers (say, `Donald&nbsp;E. Knuth'). In the first case, the entries
+might be alphabetized incorrectly, and in the second, the slightly
+altered name might foul up somebody's electronic library search. But
+there's a third possibility, which is the one I prefer. You could
+convert the second journal's field to <PRE>
+    author = "D[onald] E. Knuth"
+</PRE> This avoids the pitfalls of the previous two solutions, since 
+alphabetizes this as if the brackets weren't there, and since the
+brackets clue the reader in that a full first name was missing from
+the original. Of course it introduces another pitfall--`D[onald]&nbsp;E. Knuth'
+looks ugly--but in this case I think the increase in accuracy outweighs
+the loss in aesthetics.
+<LI>L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X's comment character `<TT>%</TT>' is not a comment character
+in the database files.
+<LI>Here's a more complete description of the ``author'' information
+referred to in previous sections. For most entry types the ``author''
+information is simply the <TT>author</TT> field. However:
+For the <TT>BOOK</TT> and <TT>INBOOK</TT> entry types
+it's the <TT>author</TT> field, but if there's no author then
+it's the <TT>editor</TT> field; for the <TT>MANUAL</TT>
+entry type it's the <TT>author</TT> field, but if there's
+no author then it's the <TT>organization</TT> field; and for
+the <TT>PROCEEDINGS</TT> entry type it's the <TT>editor</TT>
+field, but if there's no editor then it's the <TT>organization</TT>
+<LI>When creating a label, the <TT>alpha</TT> style uses the ``author''
+information described above, but with a slight change--for the <TT>MANUAL</TT>
+and <TT>PROCEEDINGS</TT> entry types, the <TT>key</TT> field
+takes precedence over the <TT>organization</TT> field. Here's
+a situation where this is useful. <PRE>
+   organization = "The Association for Computing Machinery",
+   key = "ACM"
+</PRE> Without the <TT>key</TT> field, the <TT>alpha</TT> style
+would make a label from the first three letters of information in
+the <TT>organization</TT> field; <TT>alpha</TT> knows
+to strip off the `<TT>The </TT>', but it would still
+form a label like `[Ass86]', which, however intriguing,
+is uninformative. Including the <TT>key</TT> field, as above, would
+yield the better label `[ACM86]'.
+You won't always need the <TT>key</TT> field to override the <TT>organization</TT>,
+though: With <PRE>
+    organization = "Unilogic, Ltd.",
+</PRE> for instance, the <TT>alpha</TT> style would form the perfectly
+reasonable label `[Uni86]'.
+<LI>Section&nbsp;<A HREF="btxdoc.html#features">2.1</A> discusses accented characters. To ,
+an accented character is really a special case of a ``special character'',
+which consists of everything from a left brace at the top-most level,
+immediately followed by a backslash, up through the matching right
+brace. For example in the field <PRE>
+    author = "\AA{ke} {Jos{\'{e}} {\'{E}douard} G{\"o}del"
+</PRE> there are just two special characters, `<code>{\'{E}douard}</code>'
+and `<code>{\"o}</code>' (the same would be true if the pair of
+double quotes delimiting the field were braces instead). In general,
+will not do any processing of a T<SMALL>E</SMALL>X or L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X control sequence
+inside a special character, but it <I>will</I> process other
+characters. Thus a style that converts all titles to lower case would
+convert <PRE>
+    The {\TeX BOOK\NOOP} Experience
+</PRE> to <PRE>
+    The {\TeX book\NOOP} experience
+</PRE> (the `<TT>The</TT>' is still capitalized because it's the first word
+of the title).
+This special-character scheme is useful for handling accented characters,
+for getting 's alphabetizing to do what you want, and, since
+counts an entire special character as just one letter, for stuffing
+extra characters inside labels. The file <TT>XAMPL.BIB</TT>
+distributed with 
+gives examples of all three uses.
+<LI>This final item of the section describes 's names (which appear
+in the <TT>author</TT> or <TT>editor</TT> field) in
+slightly more detail than what appears in Appendix&nbsp;B of the L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X book.
+In what follows, a ``name'' corresponds to a person. (Recall that
+you separate multiple names in a single field with the word ``and'',
+surrounded by spaces, and not enclosed in braces. This item concerns
+itself with the structure of a single name.)
+Each name consists of four parts: First, von, Last, and&nbsp;Jr; each
+part consists of a (possibly empty) list of name-tokens. The Last
+part will be nonempty if any part is, so if there's just one token,
+it's always a Last token.
+Recall that Per Brinch&nbsp;Hansen's name should be typed <PRE>
+    "Brinch Hansen, Per"
+</PRE> The First part of his name has the single token ``Per''; the
+Last part has two tokens, ``Brinch'' and ``Hansen''; and the
+von and Jr parts are empty. If you had typed <PRE>
+    "Per Brinch Hansen"
+</PRE> instead, 
+would (erroneously) think ``Brinch'' were a First-part token,
+just as ``Paul'' is a First-part token in ``John&nbsp;Paul Jones'',
+so this erroneous form would have two First tokens and one Last token.
+Here's another example: <PRE>
+    "Charles Louis Xavier Joseph de la Vall{\'e}e Poussin"
+</PRE> This name has four tokens in the First part, two in the von, and
+two in the Last. Here 
+knows where one part ends and the other begins because the tokens
+in the von part begin with lower-case letters.
+In general, it's a von token if the first letter at brace-level&nbsp;0
+is in lower case. Since technically everything in a ``special character''
+is at brace-level&nbsp;0, you can trick 
+into thinking that a token is or is not a von token by prepending
+a dummy special character whose first letter past the T<SMALL>E</SMALL>X control
+sequence is in the desired case, upper or lower.
+To summarize, 
+allows three possible forms for the name: <PRE>
+    "First von Last"
+    "von Last, First"
+    "von Last, Jr, First"
+</PRE> 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.
+<H2><A NAME="SECTION00050000000000000000">
+</H2><DL COMPACT><DD><P></P><DT><A NAME="chicago">1</A>
+<EM>The Chicago Manual of Style</EM>, pages 400-401.
+<BR>University of Chicago Press, thirteenth edition, 1982.
+<P></P><DT><A NAME="latex">2</A>
+Leslie Lamport.
+<BR>L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X:<EM> A Document Preparation System</EM>.
+<BR>Addison-Wesley, 1986.
+<P></P><DT><A NAME="btxhak">3</A>
+Oren Patashnik.
+<BR>Designing  styles.
+<BR>The part of 's documentation that's not meant for general
+  users, 8&nbsp;February 1988.
+<P></P><DT><A NAME="van-leunen">4</A>
+Mary-Claire van Leunen.
+<BR><EM>A Handbook for Scholars</EM>.
+<BR>Knopf, 1979.
+<H1><A NAME="SECTION00060000000000000000">
+About this document ...</A>
+ <P>
+This document was generated using the
+<A HREF=""><STRONG>LaTeX</STRONG>2<tt>HTML</tt></A> translator Version 2002-1 (1.68)
+Copyright &#169; 1993, 1994, 1995, 1996,
+<A HREF="">Nikos Drakos</A>, 
+Computer Based Learning Unit, University of Leeds.
+<BR>Copyright &#169; 1997, 1998, 1999,
+<A HREF="">Ross Moore</A>, 
+Mathematics Department, Macquarie University, Sydney.
+The command line arguments were: <BR>
+ <STRONG>latex2html</STRONG> <TT>-no_subdir -split 0 -show_section_numbers /tmp/lyx_tmpdir15095W9Gc8W/lyx_tmpbuf1/btxdoc.tex</TT>
+The translation was initiated by root on 2002-12-22<HR>
+<!--Navigation Panel-->
+<IMG WIDTH="81" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next_inactive"
+ SRC="file:/usr/lib/latex2html/icons/nx_grp_g.png"> 
+ SRC="file:/usr/lib/latex2html/icons/up_g.png"> 
+<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous"
+ SRC="file:/usr/lib/latex2html/icons/prev_g.png">   
+<!--End of Navigation Panel-->

Propchange: incubator/ooo/ooo-site/trunk/content/bibliographic/bibtex.html
    svn:eol-style = native

Added: incubator/ooo/ooo-site/trunk/content/bibliographic/
Binary file - no diff available.

Propchange: incubator/ooo/ooo-site/trunk/content/bibliographic/
    svn:mime-type = application/x-gzip

Added: incubator/ooo/ooo-site/trunk/content/bibliographic/bthack.html
--- incubator/ooo/ooo-site/trunk/content/bibliographic/bthack.html (added)
+++ incubator/ooo/ooo-site/trunk/content/bibliographic/bthack.html Sun Sep 25 19:38:58 2011
@@ -0,0 +1,538 @@
+<body lang="en-US">
+<h2>5 Bibliography-style hacking</h2>
+<p align="right"><em>A printer friendly PDF version of this page is available
+<ahref="index.pdf"><a href="bthack.pdf">bthack.pdf (84Kb)</a></em></p>
+<p>This document starts (and ends) with Section&nbsp;<a
+href="bthack.html#style">5</a>, because in reality it is the final section of
+"BibTeXing''&nbsp;[<a href="bthack.html#btxdoc">4</a>], the general
+documentation for . But that document was meant for all users, while this one
+is just for style designers, so the two are physically separate. Still, you
+should be completely familiar with &#x201c;BibTeXing'', and all references in
+this document to sections and section numbers assume that the two documents
+are one.</p>
+<p>This section, along with the standard-style documentation file
+<tt>btxbst.doc</tt>, should explain how to modify existing style files and to
+produce new ones. If you're a serious style hacker you should be familiar
+with van&nbsp;Leunen&nbsp;[<a href="bthack.html#van-leunen">7</a>] for points
+of style, with Lamport&nbsp;[<a href="bthack.html#latex">3</a>] and
+Knuth&nbsp;[<a href="bthack.html#texbook">2</a>] for formatting matters, and
+perhaps with <i>Scribe</i>&nbsp;[<a href="bthack.html#scribe">6</a>] for
+compatibility details. And while you're at it, if you don't read the great
+little book by Strunk and White&nbsp;[<a
+href="bthack.html#strunk-and-white">5</a>], you should at least look at its
+entries in the database and the reference list to see how handles multiple
+<p>To create a new style, it's best to start with an existing style that's
+close to yours, and then modify that. This is true even if you're simply
+updating an old style for version 0.99 (I've updated four nonstandard styles,
+so I say this with some experience). If you want to insert into a new style
+some function you'd written for an old (version 0.98i) style, keep in mind
+that the order of the arguments to the assignment (<tt>:=</tt>) function has
+been reversed. When you're finished with your style, you may want to try
+running it on the entire <tt>XAMPL.BIB</tt> database to make sure it handles
+all the standard entry types.</p>
+<p>If you find any bugs in the standard styles, or if there are things you'd
+like to do with bibliography-style files but can't, please complain to Oren
+<h3>5.1 General description</h3>
+<p>You write bibliography styles in a postfix stack language. It's not too
+hard to figure out how by looking at the standard-style documentation, but
+this description fills in a few details (it will fill in more details if
+there's a demand for it).</p>
+<p>Basically the style file is a program, written in an unnamed language,
+that tells how to format the entries that will go in the reference list
+(henceforth ``the entries'' will be ``the entry list'' or simply ``the
+list'', context permitting). This programming language has ten commands,
+described in the next subsection. These commands manipulate the language's
+objects: constants, variables, functions, the stack, and the entry list.
+(Warning: The terminology in this documentation, chosen for ease of
+explanation, is slightly different from 's. For example, this documentation's
+``variables'' and ``functions'' are both ``functions'' to . Keep this in mind
+when interpreting 's error messages.)</p>
+<p>There are two types of functions: <i>built-in</i> ones that provides
+(these are described in Section&nbsp;<a
+href="bthack.html#built-in-fns">5.3</a>), and ones you define using either
+the <tt>MACRO</tt> or <tt>FUNCTION</tt> command.</p>
+<p>Your most time-consuming task, as a style designer, will be creating or
+modifying functions using the <tt>FUNCTION</tt> command (actually, becoming
+familiar with the references listed above will be more time consuming, but
+assume for the moment that that's done).</p>
+<p>Let's look at a sample function fragment. Suppose you have a string
+variable named <tt>label</tt> and an integer variable named
+<tt>lab.width</tt>, and suppose you want to append the character `<tt>a</tt>'
+to <tt>label</tt> and to increment <tt>lab.width</tt>:</p>
+<pre>    .  .  .
+    label "a" * 'label :=          % label := label * "a"
+    lab.width #1 + 'lab.width :=   % lab.width := lab.width + 1
+    .  .  .</pre>
+<p>In the first line, <tt>label</tt> pushes that variable's value onto the
+stack. Next, the <tt>"a"</tt> pushes the string constant `<tt>a</tt>' onto
+the stack. Then the built-in function <tt>*</tt> pops the top two strings and
+pushes their concatenation. The <tt>'label</tt> pushes that variable's name
+onto the stack. And finally, the built-in function <tt>:=</tt> pops the
+variable name and the concatenation and performs the assignment treats the
+stuff following the <tt>%</tt> as a comment in the style file. The second
+line is similar except that it uses <tt>#1</tt>, with no spaces intervening
+between the `<tt>#</tt>' and the `<tt>1</tt>', to push this integer
+<p>The nonnull spacing here is arbitrary: multiple spaces, tabs, or newlines
+are equivalent to a single one (except that you're probably better off not
+having blank lines within commands, as explained shortly).</p>
+<p>For string constants, absolutely any printing character is legal between
+two consecutive double quotes, but here (and only here) treats upper- and
+lower-case equivalents as different. Furthermore, spacing <i>is</i> relevant
+within a string constant, and you mustn't split a string constant across
+lines (that is, the beginning and ending double quotes must be on the same
+<p>Variable and function names may not begin with a numeral and may not
+contain any of the ten restricted characters on page&nbsp;143 of the
+L<sup>A</sup>TEX book, but may otherwise contain any printing characters.
+Also, considers upper- and lower-case equivalents to be the same.</p>
+<p>Integers and strings are the only value types for constants and variables
+(booleans are implemented simply as 0-or-1 integers). There are three kinds
+of variables:</p>
+  <dt><strong>global&nbsp;variables</strong></dt>
+    <dd>These are either integer- or string-valued, declared using an
+      <tt>INTEGERS</tt> or <tt>STRINGS</tt> command.</dd>
+  <dt><strong>entry&nbsp;variables</strong></dt>
+    <dd>These are either integer- or string-valued, declared using the
+      <tt>ENTRY</tt> command. Each has a value for each entry on the list
+      (example: a variable <tt>label</tt> might store the label string you'll
+      use for the entry).</dd>
+  <dt><strong>fields</strong></dt>
+    <dd><p>These are string-valued, read-only variables that store the
+      information from the database file; their values are set by the
+      <tt>READ</tt> command. As with entry variables, each has a value for
+      each entry.</p>
+    </dd>
+<h3>5.2 Commands</h3>
+<p>There are ten style-file commands: Five (<tt>ENTRY</tt>,
+<tt>FUNCTION</tt>, <tt>INTEGERS</tt>, <tt>MACRO</tt>, and <tt>STRINGS</tt>)
+declare and define variables and functions; one (<tt>READ</tt>) reads in the
+database information; and four (<tt>EXECUTE</tt>, <tt>ITERATE</tt>,
+<tt>REVERSE</tt>, and <tt>SORT</tt>) manipulate the entries and produce
+output. Although the command names appear here in upper case, ignores case
+<p>Some restrictions: There must be exactly one <tt>ENTRY</tt> and one
+<tt>READ</tt> command; the <tt>ENTRY</tt> command, all <tt>MACRO</tt>
+commands, and certain <tt>FUNCTION</tt> commands (see next subsection's
+description of <tt>call.type$</tt>) must precede the <tt>READ</tt> command;
+and the <tt>READ</tt> command must precede the four that manipulate the
+entries and produce output.</p>
+<p>Also it's best (but not essential) to leave at least one blank line
+between commands and to leave no blank lines within a command; this helps
+recover from any syntax errors you make.</p>
+<p>You must enclose each argument of every command in braces. Look at the
+standard-style documentation for syntactic issues not described in this
+section. Here are the ten commands:</p>
+  <dt><tt><strong>ENTRY</strong></tt></dt>
+    <dd><p>Declares the fields and entry variables. It has three arguments,
+      each a (possibly empty) list of variable names. The three lists are of:
+      fields, integer entry variables, and string entry variables. There is
+      an additional field that</p>
+    </dd>
+    <dd><p>automatically declares, <tt>crossref</tt>, used for cross
+      referencing. And there is an additional string entry variable
+      automatically declared, <tt>sort.key$</tt>, used by the <tt>SORT</tt>
+      command. Each of these variables has a value for each entry on the
+      list.</p>
+    </dd>
+  <dt><strong><tt>EXECUTE</tt></strong></dt>
+    <dd>Executes a single function. It has one argument, the function
+    name.</dd>
+  <dt><strong><tt>FUNCTION</tt></strong></dt>
+    <dd>Defines a new function. It has two arguments; the first is the
+      function's name and the second is its definition. You must define a
+      function before using it; recursive functions are thus illegal.</dd>
+  <dt><strong><tt>INTEGERS</tt></strong></dt>
+    <dd>Declares global integer variables. It has one argument, a list of
+      variable names. There are two such automatically-declared variables,
+      <tt>entry.max$</tt> and <tt>global.max$</tt>, used for limiting the
+      lengths of string variables. You may have any number of these commands,
+      but a variable's declaration must precede its use.</dd>
+  <dt><tt><strong>ITERATE</strong></tt></dt>
+    <dd>Executes a single function, once for each entry in the list, in the
+      list's current order (initially the list is in citation order, but the
+      <tt>SORT</tt> command may change this). It has one argument, the
+      function name.</dd>
+  <dt><strong><tt>MACRO</tt></strong></dt>
+    <dd>Defines a string macro. It has two arguments; the first is the
+      macro's name, which is treated like any other variable or function
+      name, and the second is its definition, which must be
+      double-quote-delimited. You must have one for each three-letter month
+      abbreviation; in addition, you should have one for common journal
+      names. The user's database may override any definition you define using
+      this command. If you want to define a string the user can't touch, use
+      the <tt>FUNCTION</tt> command, which has a compatible syntax.</dd>
+  <dt><strong><tt>READ</tt></strong></dt>
+    <dd>Dredges up from the database file the field values for each entry in
+      the list. It has no arguments. If a database entry doesn't have a value
+      for a field (and probably no database entry will have a value for every
+      field), that field variable is marked as missing for the entry.</dd>
+  <dt><tt><strong>REVERSE</strong></tt></dt>
+    <dd>Exactly the same as the <tt>ITERATE</tt> command except that it
+      executes the function on the entry list in reverse order.</dd>
+  <dt><tt><strong>SORT</strong></tt></dt>
+    <dd>Sorts the entry list using the values of the string entry variable
+      <tt>sort.key$</tt>. It has no arguments.</dd>
+  <dt><tt><strong>STRINGS</strong></tt></dt>
+    <dd><p>Declares global string variables. It has one argument, a list of
+      variable names. You may have any number of these commands, but a
+      variable's declaration must precede its use.</p>
+    </dd>
+<h3>5.3 The built-in functions</h3>
+<p>Before we get to the built-in functions, a few words about some other
+built-in objects. There is one built-in string entry variable,
+<tt>sort.key$</tt>, which the style program must set if the style is to do
+sorting. There is one built-in field, <tt>crossref</tt>, used for the cross
+referencing feature described in Section&nbsp;4. And there are two built-in
+integer global variables, <tt>entry.max$</tt> and <tt>global.max$</tt>, which
+are set by default to some internal constants; you should truncate strings to
+these lengths before you assign to string variables, so as to not generate
+any warning messages.</p>
+<p>There are currently 37 built-in functions. Every built-in function with a
+letter in its name ends with a `<tt>$</tt>'. In what follows, ``first'',
+``second'', and so on refer to the order popped. A ``literal'' is an element
+on the stack, and it will be either an integer value, a string value, a
+variable or function name, or a special value denoting a missing field. If
+any popped literal has an incorrect type,</p>
+<p>complains and pushes the integer 0 or the null string, depending on
+whether the function was supposed to push an integer or string.</p>
+  <dt><strong><tt>&gt;</tt></strong></dt>
+    <dd>Pops the top two (integer) literals, compares them, and pushes the
+      integer 1 if the second is greater than the first, 0 otherwise.</dd>
+  <dt><strong><tt>&lt;</tt></strong></dt>
+    <dd>Analogous.</dd>
+  <dt><tt><strong>=</strong></tt></dt>
+    <dd>Pops the top two (both integer or both string) literals, compares
+      them, and pushes the integer 1 if they're equal, 0 otherwise.</dd>
+  <dt><strong><tt>+</tt></strong></dt>
+    <dd>Pops the top two (integer) literals and pushes their sum.</dd>
+  <dt><tt><strong>-</strong></tt></dt>
+    <dd>Pops the top two (integer) literals and pushes their difference (the
+      first subtracted from the second).</dd>
+  <dt><strong><tt>*</tt></strong></dt>
+    <dd>Pops the top two (string) literals, concatenates them (in reverse
+      order, that is, the order in which pushed), and pushes the resulting
+      string.</dd>
+  <dt><strong><tt>:=</tt></strong></dt>
+    <dd>Pops the top two literals and assigns to the first (which must be a
+      global or entry variable) the value of the second.</dd>
+  <dt><tt><strong>add.period$</strong></tt></dt>
+    <dd>Pops the top (string) literal, adds a `<tt>.</tt>' to it if the last
+      non`<tt>}</tt>' character isn't a `<tt>.</tt>', `<tt>?</tt>', or
+      `<tt>!</tt>', and pushes this resulting string.</dd>
+  <dt><strong><tt>call.type$</tt></strong></dt>
+    <dd>Executes the function whose name is the entry type of an entry. For
+      example if an entry is of type <tt>book</tt>, this function executes
+      the <tt>book</tt> function. When given as an argument to the
+      <tt>ITERATE</tt> command, <tt>call.type$</tt> actually produces the
+      output for the entries. For an entry with an unknown type, it executes
+      the function <tt>default.type</tt>. Thus you should define (before the
+      <tt>READ</tt> command) one function for each standard entry type as
+      well as a <tt>default.type</tt> function.</dd>
+  <dt><tt><strong>$</strong></tt></dt>
+    <dd>Pops the top two (string) literals; it changes the case of the second
+      according to the specifications of the first, as follows. (Note: The
+      word `letters' in the next sentence refers only to those at
+      brace-level&nbsp;0, the top-most brace level; no other characters are
+      changed, except perhaps for ``special characters'', described in
+      Section&nbsp;4.) If the first literal is the string&nbsp;`<tt>t</tt>',
+      it converts to lower case all letters except the very first character
+      in the string, which it leaves alone, and except the first character
+      following any colon and then nonnull white space, which it also leaves
+      alone; if it's the string&nbsp;`<tt>l</tt>', it converts all letters to
+      lower case; and if it's the string&nbsp;`<tt>u</tt>', it converts all
+      letters to upper case. It then pushes this resulting string. If either
+      type is incorrect, it complains and pushes the null string; however, if
+      both types are correct but the specification string (i.e., the first
+      string) isn't one of the legal ones, it merely pushes the second back
+      onto the stack, after complaining. (Another note: It ignores case
+      differences in the specification string; for example, the strings
+      <tt>t</tt> and <tt>T</tt> are equivalent for the purposes of this
+      built-in function.)</dd>
+  <dt><tt><strong>$</strong></tt></dt>
+    <dd>Pops the top (string) literal, makes sure it's a single character,
+      converts it to the corresponding ASCII integer, and pushes this
+    integer.</dd>
+  <dt><strong><tt>cite$</tt></strong></dt>
+    <dd>Pushes the string that was the <code>\cite</code>-command argument
+      for this entry.</dd>
+  <dt><strong><tt>duplicate$</tt></strong></dt>
+    <dd>Pops the top literal from the stack and pushes two copies of it.</dd>
+  <dt><strong><tt>empty$</tt></strong></dt>
+    <dd>Pops the top literal and pushes the integer 1 if it's a missing field
+      or a string having no non-white-space characters, 0 otherwise.</dd>
+  <dt><strong><tt>$</tt></strong></dt>
+    <dd>Pops the top three literals (they are a string, an integer, and a
+      string literal). The last string literal represents a name list (each
+      name corresponding to a person), the integer literal specifies which
+      name to pick from this list, and the first string literal specifies how
+      to format this name, as explained in the next subsection. Finally, this
+      function pushes the formatted name.</dd>
+  <dt><tt><strong>if$</strong></tt></dt>
+    <dd>Pops the top three literals (they are two function literals and an
+      integer literal, in that order); if the integer is greater than 0, it
+      executes the second literal, else it executes the first.</dd>
+  <dt><tt><strong>$</strong></tt></dt>
+    <dd>Pops the top (integer) literal, interpreted as the ASCII integer
+      value of a single character, converts it to the corresponding
+      single-character string, and pushes this string.</dd>
+  <dt><strong><tt>$</tt></strong></dt>
+    <dd>Pops the top (integer) literal, converts it to its (unique) string
+      equivalent, and pushes this string.</dd>
+  <dt><strong><tt>missing$</tt></strong></dt>
+    <dd>Pops the top literal and pushes the integer 1 if it's a missing
+      field, 0&nbsp;otherwise.</dd>
+  <dt><strong><tt>newline$</tt></strong></dt>
+    <dd>Writes onto the <tt>bbl</tt> file what's accumulated in the output
+      buffer. It writes a blank line if and only if the output buffer is
+      empty. Since <tt>write$</tt> does reasonable line breaking, you should
+      use this function only when you want a blank line or an explicit line
+      break.</dd>
+  <dt><tt><strong>num.names$</strong></tt></dt>
+    <dd>Pops the top (string) literal and pushes the number of names the
+      string represents--one plus the number of occurrences of the substring
+      ``and'' (ignoring case differences) surrounded by nonnull white-space
+      at the top brace level.</dd>
+  <dt><strong><tt>pop$</tt></strong></dt>
+    <dd>Pops the top of the stack but doesn't print it; this gets rid of an
+      unwanted stack literal.</dd>
+  <dt><strong><tt>preamble$</tt></strong></dt>
+    <dd>Pushes onto the stack the concatenation of all the <tt>@PREAMBLE</tt>
+      strings read from the database files.</dd>
+  <dt><strong><tt>purify$</tt></strong></dt>
+    <dd>Pops the top (string) literal, removes nonalphanumeric characters
+      except for white-space characters and hyphens and ties (these all get
+      converted to a space), removes certain alphabetic characters contained
+      in the control sequences associated with a ``special character'', and
+      pushes the resulting string.</dd>
+  <dt><strong><tt>quote$</tt></strong></dt>
+    <dd>Pushes the string consisting of the double-quote character.</dd>
+  <dt><tt><strong>skip$</strong></tt></dt>
+    <dd>Is a no-op.</dd>
+  <dt><strong><tt>stack$</tt></strong></dt>
+    <dd>Pops and prints the whole stack; it's meant to be used for style
+      designers while debugging.</dd>
+  <dt><tt><strong>substring$</strong></tt></dt>
+    <dd>Pops the top three literals (they are the two integers literals
+      <i>len</i> and <i>start</i>, and a string literal, in that order). It
+      pushes the substring of the (at most) <i>len</i> consecutive characters
+      starting at the <i>start</i>th character (assuming 1-based indexing) if
+      <i>start</i> is positive, and ending at the<i> start</i>th character
+      from the end if <i>start</i> is negative (where the first character
+      from the end is the last character).</dd>
+  <dt><tt><strong>swap$</strong></tt></dt>
+    <dd>Swaps the top two literals on the stack.</dd>
+  <dt><strong><tt>text.length$</tt></strong></dt>
+    <dd>Pops the top (string) literal, and pushes the number of text
+      characters it contains, where an accented character (more precisely, a
+      ``special character'', defined in Section&nbsp;4) counts as a single
+      text character, even if it's missing its matching right brace, and
+      where braces don't count as text characters.</dd>
+  <dt><strong><tt>text.prefix$</tt></strong></dt>
+    <dd>Pops the top two literals (the integer literal <i>len</i> and a
+      string literal, in that order). It pushes the substring of the (at
+      most) <i>len</i> consecutive text characters starting from the
+      beginning of the string. This function is similar to
+      <tt>substring$</tt>, but this one considers a ``special character'',
+      even if it's missing its matching right brace, to be a single text
+      character (rather than however many ASCII characters it actually
+      comprises), and this function doesn't consider braces to be text
+      characters; furthermore, this function appends any needed matching
+      right braces.</dd>
+  <dt><tt><strong>top$</strong></tt></dt>
+    <dd>Pops and prints the top of the stack on the terminal and log file.
+      It's useful for debugging.</dd>
+  <dt><strong><tt>type$</tt></strong></dt>
+    <dd>Pushes the current entry's type (book, article, etc.), but pushes the
+      null string if the type is either unknown or undefined.</dd>
+  <dt><tt><strong>warning$</strong></tt></dt>
+    <dd>Pops the top (string) literal and prints it following a warning
+      message. This also increments a count of the number of warning messages
+      issued.</dd>
+  <dt><strong><tt>while$</tt></strong></dt>
+    <dd>Pops the top two (function) literals, and keeps executing the second
+      as long as the (integer) literal left on the stack by executing the
+      first is greater than 0.</dd>
+  <dt><strong><tt>width$</tt></strong></dt>
+    <dd>Pops the top (string) literal and pushes the integer that represents
+      its width in some relative units (currently, hundredths of a point, as
+      specified by the June 1987 version of the  font; the only white-space
+      character with nonzero width is the space). This function takes the
+      literal literally; that is, it assumes each character in the string is
+      to be printed as is, regardless of whether the character has a special
+      meaning to TEX, except that ``special characters'' (even without their
+      right braces) are handled specially. This is meant to be used for
+      comparing widths of label strings.</dd>
+  <dt><strong><tt>write$</tt></strong></dt>
+    <dd><p>Pops the top (string) literal and writes it on the output buffer
+      (which will result in stuff being written onto the <tt>bbl</tt> file
+      when the buffer fills up).</p>
+    </dd>
+<p>Note that the built-in functions <tt>while$</tt> and <tt>if$</tt> require
+two function literals on the stack. You get them there either by immediately
+preceding the name of a function by a single quote, or, if you don't feel
+like defining a new function with the <tt>FUNCTION</tt> command, by simply
+giving its definition (that is, giving what would be the second argument to
+the <tt>FUNCTION</tt> command, including the surrounding braces). For example
+the following function fragment appends the character `<tt>a</tt>' if the
+string variable named <tt>label</tt> is nonnull:</p>
+<pre>    .  .  .
+    label "" =
+      'skip$
+      { label "a" * 'label := }
+    if$
+    .  .  .</pre>
+<p>A function whose name you quote needn't be built in like <tt>skip$</tt>
+above--it may, for example, be a field name or a function you've defined
+<h3>5.4 Name formatting</h3>
+<p>What's in a name? Section&nbsp;4 pretty much describes this. Each name
+consists of four parts: First, von, Last, and Jr; each consists of a list of
+name-tokens, and any list but Last's may be empty for a nonnull name. This
+subsection describes the format string you must supply to the built-in
+function <tt>$</tt>.</p>
+<p>Let's look at an example of a very long name. Suppose a database
+entry&nbsp;[<a href="bthack.html#prime-number-theorem">1</a>] has the
+<pre>  author = "Charles Louis Xavier Joseph de la Vall{\'e}e Poussin"</pre>
+<p>and suppose you want this formatted ``last name comma initials''. If you
+use the format string</p>
+<pre>    "{vv~}{ll}{, jj}{, f}?"</pre>
+<p>will produce</p>
+<pre>    de~la Vall{\'e}e~Poussin, C.~L. X.~J?</pre>
+<p>as the formatted string.</p>
+<p>Let's look at this example in detail. There are four brace-level&nbsp;1
+<i>pieces</i> to this format string, one for each part of a name. If the
+corresponding part of a name isn't present (the Jr part for this name),
+everything in that piece is ignored. Anything at brace-level&nbsp;0 is output
+verbatim (the presumed typo `<tt>?</tt>' for this name is at
+brace-level&nbsp;0), but you probably won't use this feature much.</p>
+<p>Within each piece a double letter tells to use whole tokens, and a single
+letter, to abbreviate them (these letters must be at brace-level&nbsp;1);
+everything else within the piece is used verbatim (well, almost
+everything--read on). The tie at the end of the von part (in
+<code>{vv~}</code>) is a discretionary tie-- will output a tie at that point
+if it thinks there's a need for one; otherwise it will output a space. If you
+really, really, want a tie there, regardless of what thinks, use two of them
+(only one will be output); that is, use <code>{vv~~}</code>. A tie is
+discretionary only if it's the last character of the piece; anywhere else
+it's treated as an ordinary character.</p>
+<p>puts default strings <i>between</i> tokens of a name part: For whole
+tokens it uses either a space or a tie, depending on which one it thinks is
+best, and for abbreviated tokens it uses a period followed by either a space
+or a tie. However it doesn't use this default string after the last token in
+a list; hence there's no period following the `J' for our example. You should
+have used</p>
+<pre>    "{vv~}{ll}{, jj}{, f.}" to get to produce the same formatted string but with the question mark replaced by a period. Note that the period should go inside the First-name piece, rather than where the question mark was, in case a name has no First part.</pre>
+<p>If you want to override 's default between-token strings, you must
+explicitly specify a string. For example suppose you want a label to contain
+the first letter from each token in the von and Last parts, with no spaces;
+you should use the format string</p>
+<pre>    "{v{}}{l{}}"</pre>
+<p>so that will produce `<tt>dlVP</tt>' as the formatted string. You must
+give a string for each piece whose default you want overridden (the example
+here uses the null string for both pieces), and this string must immediately
+follow either the single or double letter for the piece. You may not have any
+other letters at brace-level&nbsp;1 in the format string.</p>
+  <dt>1</dt>
+    <dd>Charles Louis Xavier&nbsp;Joseph de&nbsp;la Vallée&nbsp;Poussin.<br>
+      A strong form of the prime number theorem, 19th century.</dd>
+  <dt><a name="texbook"></a>2</dt>
+    <dd>Donald&nbsp;E. Knuth.<br>
+      <em>The TEXbook</em>.<br>
+      Addison-Wesley, 1984.</dd>
+  <dt><a name="latex"></a>3</dt>
+    <dd>Leslie Lamport.<br>
+      L<sup>A</sup>TEX: <em>A Document Preparation System</em>.<br>
+      Addison-Wesley, 1986.</dd>
+  <dt><a name="btxdoc"></a>4</dt>
+    <dd>Oren Patashnik.<br>
+      ing.<br>
+      Documentation for general users, 8&nbsp;February 1988.</dd>
+  <dt><a name="strunk-and-white"></a>5</dt>
+    <dd>William Strunk, Jr. and E.&nbsp;B. White.<br>
+      <em>The Elements of Style</em>.<br>
+      Macmillan, third edition, 1979.</dd>
+  <dt><a name="scribe"></a>6</dt>
+    <dd>Unilogic, Ltd., Pittsburgh.<br>
+      <em>Scribe Document Production System User Manual</em>, April 1984.<br>
+      Chapter twelve and appendices E8 through E10 deal with
+    bibliographies.</dd>
+  <dt><a name="van-leunen"></a>7</dt>
+    <dd><p>Mary-Claire van Leunen.<br>
+      <em>A Handbook for Scholars</em>.<br>
+      Knopf, 1979.</p>
+    </dd>
+<h3><a name="SECTION00070000000000000000"></a>About this document ...</h3>
+<p>This document was generated using the <a
+translator Version 2002-1 (1.68)</p>
+<p>Copyright © 1993, 1994, 1995, 1996, <a
+href="">Nikos Drakos</a>, Computer
+Based Learning Unit, University of Leeds.<br>
+Copyright © 1997, 1998, 1999, <a
+href="">Ross Moore</a>, Mathematics
+Department, Macquarie University, Sydney.</p>
+<p>The command line arguments were:<br>
+<strong>latex2html</strong> <tt>-no_subdir -split 0 -show_section_numbers
+<p>The translation was initiated by root on 2002-12-22</p>

Propchange: incubator/ooo/ooo-site/trunk/content/bibliographic/bthack.html
    svn:eol-style = native

Added: incubator/ooo/ooo-site/trunk/content/bibliographic/bthack.pdf
Binary file - no diff available.

Propchange: incubator/ooo/ooo-site/trunk/content/bibliographic/bthack.pdf
    svn:mime-type = application/pdf

View raw message