Return-Path: X-Original-To: apmail-incubator-ooo-commits-archive@minotaur.apache.org Delivered-To: apmail-incubator-ooo-commits-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id A22B797CA for ; Sun, 25 Sep 2011 19:39:56 +0000 (UTC) Received: (qmail 28994 invoked by uid 500); 25 Sep 2011 19:39:56 -0000 Delivered-To: apmail-incubator-ooo-commits-archive@incubator.apache.org Received: (qmail 28906 invoked by uid 500); 25 Sep 2011 19:39:56 -0000 Mailing-List: contact ooo-commits-help@incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: ooo-dev@incubator.apache.org Delivered-To: mailing list ooo-commits@incubator.apache.org Received: (qmail 28891 invoked by uid 99); 25 Sep 2011 19:39:56 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Sun, 25 Sep 2011 19:39:56 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Sun, 25 Sep 2011 19:39:34 +0000 Received: from eris.apache.org (localhost [127.0.0.1]) by eris.apache.org (Postfix) with ESMTP id 62C012388B46; Sun, 25 Sep 2011 19:39:03 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: svn commit: r1175536 [7/11] - /incubator/ooo/ooo-site/trunk/content/bibliographic/ Date: Sun, 25 Sep 2011 19:39:01 -0000 To: ooo-commits@incubator.apache.org From: kschenk@apache.org X-Mailer: svnmailer-1.0.8-patched Message-Id: <20110925193903.62C012388B46@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Added: incubator/ooo/ooo-site/trunk/content/bibliographic/btxdoc.html URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/bibliographic/btxdoc.html?rev=1175536&view=auto ============================================================================== --- incubator/ooo/ooo-site/trunk/content/bibliographic/btxdoc.html (added) +++ incubator/ooo/ooo-site/trunk/content/bibliographic/btxdoc.html Sun Sep 25 19:38:58 2011 @@ -0,0 +1,1029 @@ + + + + +

BiB-T_EXing

Oren Patashnik

February 8, 1988

1. Overview

[This document will be expanded when BibTeX +version 1.00 comes out. Please report typos, omissions, +inaccuracies, and especially unclear explanations to me +(patashnik@SCORE.STANFORD.EDU). Suggestions for improvements are +wanted and welcome.]

This documentation, for BibTeX version 0.99b, is +meant for general BibTeX users; bibliography-style designers should +read this document and then read “Designing BibTeX +Styles” [3], which is meant for just them.

This document has three parts: Section 2 +describes the differences between versions 0.98i and 0.99b of +BibTeX and between the corresponding versions of the standard +styles; Section 3 updates Appendix B.2 of the L +"1">^AT_EX book [2]; and Section 4 +gives some general and specific tips that aren’t documented +elsewhere. It’s assumed throughout that you’re familiar +with the relevant sections of the L"1">^A +T_EX book.

This documentation also serves as sample input +to help BibTeX implementors get it running. For most documents, +this one included, you produce the reference list by: running L +"1">^AT_EX on the document (to produce the +aux file(s)), then running BibTeX (to produce the bbl file), then L +"1">^AT_EX twice more (first to find the +information in the bbl file and then to get +the forward references correct). In very rare circumstances you may +need an extra BibTeX/L "1">^AT_EX +run.

BibTeX version 0.99b should be used with L +"1">^AT_EX version 2.09, for which the +closed bibliography format is the default; to get the open format, +use the optional document style openbib (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).]

Note: BibTeX 0.99b is not compatible with the +old style files; nor is BibTeX 0.98i compatible with the new ones +(the new BibTeX, however, is compatible with old database +files).

Note for implementors: BibTeX provides +logical-area names TEXINPUTS: for bibliography-style files and +TEXBIB: for database files it can’t +otherwise find.

2. Changes

This section describes the differences between +BibTeX 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.

2.1 New BibTeX features

The following list explains BibTeX’s new +features and how to use them.

1. With the single command +‘\nocite{*}’ you can now include in the reference list +every entry in the database files, without having to explicitly +\cite or \nocite each entry. Giving this command, in essence, +\nocites all the enties in the database, in database order, at the +very spot in your document where you give the command.

2. You can now have as a field value (or an +@STRING definition) the concatenation of several strings. For +example if you’ve defined

@STRING( WGA = " World Gnus Almanac" )

then it’s easy to produce nearly-identical +title fields for different entries:

"2">@BOOK(almanac-66,

title = 1966 # WGA,

. . .

"2">@BOOK(almanac-67,

title = 1967 # WGA,

and so on. Or, you could have a field +like

month = "1~" # jan,

which would come out something like +‘1~January’ or ‘1~Jan.’ in the bbl file, +depending on how your bibliography style defines the + jan 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 ‘#’, surrounded by optional spaces or + newlines, between each successive pair of + strings.

3. BibTeX has a new cross-referencing feature, +explained by an example. Suppose you say \cite{no-gnats} in your +document, and suppose you have these two entries in your database +file:

"2">@INPROCEEDINGS(no-gnats,

crossref = "gg-proceedings",

author = "Rocky Gneisser",

title = "No Gnats Are Taken for +Granite",

pages = "133-139")

. . .

"2">@PROCEEDINGS(gg-proceedings,

editor = "Gerald Ford and Jimmy +Carter",

title = "The Gnats and Gnus 1988 +Proceedings",

booktitle = "The Gnats and Gnus 1988 +Proceedings")

Two things happen. First, the special crossref +field tells BibTeXthat the no-gnats entry should inherit any fields +it’s missing from the entry it cross references, +gg-proceedings. In this case it in inherits the two fields editor +and booktitle. Note that, in the standard styles at least, the +booktitle field is irrelevant for the PROCEEDINGS entry type. The +booktitle field appears here in the gg-proceedings 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 booktitle field need only appear once.

The second thing that happens: BibTeX +automatically puts the entry gg-proceedings +into the reference list if it’s cross referenced by two or +more entries that you \cite or \nocite, even +if you don’t \cite or \nocite the +gg-proceedings entry itself. So gg-proceedings will automatically +appear on the reference list if one other entry besides no-gnats +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 BibTeX’s cross +referencing, which is still allowed. Thus, having a field +like

note = "Jones \cite{jones-proof} improves the +result"

is not affected by the new feature.

4. BibTeX now handles accented characters. For +example if you have an entry with the two fields

author = "Kurt G{\"o}del",

year = 1931,

and if you’re using the alpha bibliography +style, then BibTeX will construct the label [Gö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 {\"o} or {\"{o}} 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 {G{\"{o}}del} nor {G\"{o}del} 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 3.2 of the "3">L"1">^A +"3">T_EX book. This feature behaves similarly for +“accents” you might define; we’ll see an example +shortly. For the purposes of counting letters in labels, BibTeX +considers everything contained inside the braces as a single +letter.

5. BibTeX also handles hyphenated names. For +example if you have an entry with

author = "Jean-Paul Sartre",

and if you’re using the abbrv style, then +the result is ‘J.-P. Sartre’.

6. There’s now an @PREAMBLE command for +the database files. This command’s syntax is just like +@STRING’s, except that there is no name +or equals-sign, just the string. Here’s an +example:

@PREAMBLE{ "\newcommand{\noopsort}[1]{} +"

# "\newcommand{\singleletter}[1]{#1} " +}

(note the use of concatenation here, too). The +standard styles output whatever information you give this command +(L "1">^AT_EX macros most likely) directly +to the bbl file. We’ll look at one possible use of this +command, based on the \noopsort command just defined.

The issue here is sorting (alphabetizing). +BibTeX does a pretty good job, but occasionally weird circumstances +conspire to confuse BibTeX: 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 1 to appear just before +volume 2 in your reference list. Further suppose that +there’s now a second edition of volume 1, which came out +in 1973, say, but that there’s still just one edition of +volume 2, which came out in 1971. Since the plain standard +style sorts by author and then year, it will place volume 2 +first (because its edition came out two years earlier) unless you +help BibTeX. You can do this by using the year fields below for the +two volumes:

year = "{\noopsort{a}}1973"

. . .

year = "{\noopsort{b}}1971"

According to the definition of \noopsort, +"3">L"1">^A "3">T_EX will print +nothing but the true year for these fields. But BibTeX will be +perfectly happy pretending that \noopsort specifies some fancy +accent that’s supposed to adorn the ‘a’ and +the ‘b’; thus when BibTeX sorts it will pretend +that ‘a1973’ and ‘b1971’ are the real +years, and since ‘a’ comes before ‘b’, +it will place volume 1 before volume 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 {\noopsort{1968a}}1973 and {\noopsort{1968b}}1971, 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 1 appeared).

There is a limit to the number of @PREAMBLE +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 2).

7. BibTeX’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.)

8. BibTeX no longer does case conversion for +file names; this will make BibTeX easier to install on Unix +systems, for example.

9. It’s now easier to add code for +processing a command-line aux-file +name.

2.2 Changes to the standard styles

This section describes changes to the standard +styles (plain, unsrt, alpha, abbrv) that +affect ordinary users. Changes that affect style designers appear +in the document “Designing BibTeX +Styles” [3].

1. In general, sorting is now by +“author”, then year, then title—the old versions +didn’t use the year field. (The alpha +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.

2. Many unnecessary ties (~) have been removed. +L "1">^AT_EX thus will produce slightly +fewer ‘Underfull \hbox’ messages when it’s formatting the +reference list.

3. Emphasizing ({\em ...}) +has replaced italicizing ({\it ...}). This will almost never result +in a difference between the old output and the new.

4. The alpha style now uses +a superscripted ‘’ instead of + a ‘*’ 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 ‘’ by redefining + the \etalchar command that the + alpha style writes onto the bbl file (just preceding the \thebibliography environment); use L + "1">^A T_EX’s \renewcommand inside a database @PREAMBLE command, described in the previous + subsection’s + item 6.

5. The abbrv style now uses +‘Mar.’ and ‘Sept.’for those months rather +than ‘March’ and ‘Sep.’

6. The standard styles use BibTeX’s new +cross-referencing feature by giving a \cite 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 (1) an INPROCEEDINGS (or +CONFERENCE, which is the same) cross references a PROCEEDINGS; when (2) a BOOK, +(3) an INBOOK, or (4) an + INCOLLECTION cross references a + BOOK (in these cases, the + cross-referencing entry is a single volume in a multi-volume + work); and when (5) an ARTICLE cross references an + ARTICLE (in this case, the cross-referenced entry is really a + journal, but there’s no JOURNAL entry type; this will + result in warning messages about an empty author and + title for the journal—you should + just ignore these + warnings).

7. The MASTERSTHESIS and +PHDTHESIS entry types now take an optional +type 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

type = "{Ph.D.} dissertation"

in your database entry.

8. Similarly, the INBOOK and INCOLLECTION entry types now take an optional type field, +allowing ‘section 1.2’ instead of the default +‘chapter 1.2’. You get this by +putting

chapter = "1.2",

type = "Section"

in your database entry.

9. The BOOKLET, + MASTERSTHESIS, and TECHREPORT entry types now format their title + fields as if they were ARTICLE titles + rather than BOOK titles.

10. The PROCEEDINGS and +INPROCEEDINGS entry types now use the address +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 publisher or organization +field.

11. The BOOK, INBOOK, +INCOLLECTION, and PROCEEDINGS entry types now +allow either volume or number (but not both), +rather than just volume.

12. The INCOLLECTION entry +type now allows a series and an edition +field.

13. The INPROCEEDINGS and +PROCEEDINGS entry types now allow either a +volume or number, and also a series field.

14. The UNPUBLISHED entry +type now outputs, in one block, the note field followed by the date +information.

15. The MANUAL entry type +now prints out the organization in the first block if the author +field is empty.

16. The MISC entry type now +issues a warning if all the optional fields are empty (that is, if +the entire entry is empty).

3. The Entries

This section is simply a corrected version of +Appendix B.2 of the "3">L"1">^A +"3">T_EX book [2], Ó 1986, by Addison-Wesley. The basic scheme is +the same, only a few details have changed.

3.1 Entry Types

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 BibTeX provides enough +entry types to handle almost any reference reasonably well.

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:

required 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.

optional 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.

ignored The field is ignored. BibTeX +ignores any field that is not required or optional, so you can +include any fields you want in a bib file +entry. It’s a good idea to put all relevant information about +a reference in its bib 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 abstract field in the paper’s bib file entry. The +bib 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 BibTeX 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 Leunen [4] for use in the Scribe +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 bib file, the entry-type name is preceded by an @ +character.

article An article from a journal or +magazine. Required fields: author, title, +journal, year. Optional fields: + volume, number, pages, month, note.

book A book with an explicit publisher. +Required fields: author or editor, title, +publisher, year. Optional fields: volume or +number, series, address, edition, + month, note.

booklet A work that is printed and bound, +but without a named publisher or sponsoring institution. Required +field: title. Optional fields: author, howpublished, + address, month, year, note.

conference The same as INPROCEEDINGS, +included for Scribe compatibility.

inbook A part of a book, which may be a +chapter (or section or whatever) and/or a range of pages. Required +fields: author or editor, title, chapter +and/or pages, publisher, year. Optional +fields: volume or number, series, type, +address, edition, month, +note.

incollection A part of a book having its +own title. Required fields: author, title, +booktitle, publisher, year. Optional fields: +editor, volume or number, series, type, +chapter, pages, address, edition, month, +note.

inproceedings An article in a conference +proceedings. Required fields: author, title, +booktitle, year. Optional fields: + editor, volume or number, series, pages, address, month, + organization, publisher, note.

manual Technical documentation. Required +field: title. Optional fields: author, organization, + address, edition, + month, year, note.

mastersthesis A Master’s thesis. +Required fields: author, title, school, +year. Optional fields: type, address, month, note.

misc Use this type when nothing else +fits. Required fields: none. Optional fields: author, + title, howpublished, month, year, note.

phdthesis A PhD thesis. Required fields: +author, title, school, year. Optional fields: +type, address, month, note.

proceedings The proceedings of a +conference. Required fields: title, year. +Optional fields: editor, volume or number, +series, address, month, organization, +publisher, note.

techreport A report published by a school +or other institution, usually numbered within a series. Required +fields: author, title, institution, year. +Optional fields: type, number, address, month, +note.

unpublished A document having an author +and title, but not formally published. Required fields: author, +title, note. Optional fields: month, +year.

In addition to the fields listed above, each +entry type also has an optional key field, +used in some styles for alphabetizing, for cross referencing, or +for forming a \bibitem label. You should +include a key field for any entry whose “author” +information is missing; the “author” information is +usually the author field, but for some entry +types it can be the editor or even the organization field +(Section 4 describes this in more detail). Do not confuse the +key field with the key that appears in the \cite command and at the +beginning of the database entry; this field is named +“key” only for compatibility with +Scribe.

3.2 Fields

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.

address Usually the address of the +publisher or other type of institution. For major publishing +houses, van Leunen recommends omitting the information +entirely. For small publishers, on the other hand, you can help the +reader by giving the complete address.

annote An annotation. It is not used by +the standard bibliography styles, but may be used by others that +produce an annotated bibliography.

author The name(s) of the author(s), in +the format described in the "3">L"1">^A +"3">T_EX book.

booktitle Title of a book, part of which +is being cited. See the "3">L"1">^A +"3">T_EX book for how to type titles. For book +entries, use the title field instead.

chapter A chapter (or section or +whatever) number.

crossref The database key of the entry +being cross referenced.

edition 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.

editor Name(s) of editor(s), typed as +indicated in the "3">L"1">^A "3">T_EX +book. If there is also an author field, then the editor field gives +the editor of the book or collection in which the reference +appears.

howpublished How something strange has +been published. The first word should be capitalized.

institution The sponsoring institution of +a technical report.

journal A journal name. Abbreviations are +provided for many journals; see the Local Guide.

key Used for alphabetizing, cross +referencing, and creating a label when the “author” +information (described in Section 4) is missing. This field +should not be confused with the key that appears in the \cite +command and at the beginning of the database entry.

month 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 "3">L"1">^A +"3">T_EX book.

note Any additional information that can +help the reader. The first word should be capitalized.

number 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.

organization The organization that +sponsors a conference or that publishes a manual.

pages One or more page numbers or range +of numbers, such as 42–111 or + 7,41,73–97 or 43+ (the ‘+’ in + this last example indicates pages following that don’t + form a simple range). To make it easier to maintain + Scribe-compatible databases, the standard styles + convert a single dash (as in 7-33) to the double dash used in + T_EX to denote number ranges (as in 7–33).

publisher The publisher’s +name.

school The name of the school where a +thesis was written.

series 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 or +multi-volume set in which the book is published.

title The work’s title, typed as +explained in the L"1">^A T_EX book.

type The type of a technical +report—for example, “Research Note”.

volume The volume of a journal or +multivolume book.

year The year of publication or, for an +unpublished work, the year it was written. Generally it should +consist of four numerals, such as 1984, although the standard +styles can handle any year whose last four nonpunctuation +characters are numerals, such as ‘(about +1984)’.

4. Helpful Hints

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 +style—journal says you must use style and that’s + that. If you have a choice, however, I strongly recommend that + you choose something like the plain + standard style. Such a style, van Leunen [4] argues + convincingly, encourages better writing than the + alternatives—more concrete, more vivid.

The Chicago Manual of Style [1], 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 Chicago +Manual contains, right in the middle of page 401, this +anachronism: “The chief disadvantage of [a style like plain] +is that additions or deletions cannot be made after the manuscript +is typed without changing numbers in both text references and +list.” "3">L"1">^A "3">T_EX, +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 al., 1983b)’ might be half a page later than the one +for ‘(Aho et 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 BibTeXwith the standard styles +(although many of them hold for nonstandard styles, too).

1. With BibTeX’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 Local +Guide to see what tools are available on your system.

2. 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).

3. 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 publisher field, rather than putting it in the + address field. Or sometimes, difficult + entries work best when you make judicious use of the + note field.

4. Don’t take the warning messages too +seriously. Sometimes, for instance, the year appears in the title, +as in The 1966 World Gnus Almanac. In this case it’s +best to omit the year field and to ignore BibTeX’s warning +message.

5. If you have too many names to list in an +author or editor field, you can end the list +with “and others”; the standard styles appropriately +append an “et al.”

6. In general, if you want to keep BibTeX 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.

7. For Scribe compatibility, the database +files allow an @COMMENT command; it’s +not really needed because BibTeX allows in the database files any +comment that’s not within an entry. If you want to comment +out an entry, simply remove the ‘@’ character preceding the entry +type.

8. 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 +@STRING commands in their own database file and to list this +database file as an argument to L +"1">^AT_EX’s \bibliography command +(but you should list this argument before the ones that specify +real database entries).

9. 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 month +field is usually the best place. For example

month = jul # "~4,"

will probably produce just what you +want.

10. If you’re using the unsrt style +(references are listed in order of citation) along with the +\nocite{*} feature (all entries in the +database are included), the placement of the \nocite{*} command within your document file will +determine the reference order. According to the rule given in +Section 2.1: 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 \cite or \nocite will occur in citation order, +and the remaining database entries will be in database +order.

11. 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 address field.

12. The MASTERSTHESIS and +PHDTHESIS entry types are so named for +Scribe compatibility; MINORTHESIS and +MAJORTHESIS probably would have been better +names. Keep this in mind when trying to classify a non-U.S. +thesis.

13. 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.

author = "Donald E. Knuth"

. . .

author = "D. E. Knuth"

There are two possibilities. You could +(1) simply leave them as is, or (2) 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 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

author = "D[onald] E. Knuth"

This avoids the pitfalls of the previous two +solutions, since BibTeX 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] E. +Knuth’ looks ugly—but in this case I think the increase +in accuracy outweighs the loss in aesthetics.

14. "3">L"1">^A +"3">T_EX’s comment character ‘%’ is +not a comment character in the database files.

15. 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 author field. However: For the BOOK and INBOOK entry +types it’s the author field, but if there’s no author +then it’s the editor field; for the +MANUAL entry type it’s the + author field, but if there’s no + author then it’s the organization field; and for the + PROCEEDINGS entry type it’s the editor field, but if + there’s no editor then it’s the organization + field.

16. When creating a label, the alpha style uses +the “author” information described above, but with a +slight change—for the MANUAL and PROCEEDINGS entry types, the +key field takes precedence over the organization field. +Here’s a situation where this is useful.

organization = "The Association for Computing +Machinery",

key = "ACM"

Without the key field, the +alpha style would make a label from the first three letters of +information in the organization field; alpha knows to strip off the +‘The ’, but it would still form a label like +‘[Ass86]’, which, however intriguing, is uninformative. +Including the key field, as above, would yield the better label +‘[ACM86]’.

You won’t always need the key field to +override the organization, though: With

organization = "Unilogic, Ltd.",

for instance, the alpha style would form the +perfectly reasonable label ‘[Uni86]’.

17. Section 2.1 discusses accented +characters. To BibTeX, 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

author = "\AA{ke} {Jos{\'{e}} {\'{E}douard} +G{\"o}del"

there are just two special characters, +‘{\'{E}douard}’ and ‘{\"o}’ (the same would +be true if the pair of double quotes delimiting the field were +braces instead). In general, BibTeX will not do any processing of a +T_EX or "3">L"1">^A "3">T_EX +control sequence inside a special character, but it will +process other characters. Thus a style that converts all titles to +lower case would convert

The {\TeX BOOK\NOOP} Experience

The {\TeX book\NOOP} experience

(the ‘The’ is +still capitalized because it’s the first word of the +title).

This special-character scheme is useful for +handling accented characters, for getting BibTeX’s +alphabetizing to do what you want, and, since BibTeX counts an +entire special character as just one letter, for stuffing extra +characters inside labels. The file XAMPL.BIB +distributed with BibTeXgives examples of all three +uses.

18. This final item of the section describes +BibTeX’s names (which appear in the author or + editor field) in slightly more detail + than what appears in Appendix B of the + L"1">^A T_EX 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 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 Hansen’s name +should be typed

"Brinch Hansen, Per"

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

"Per Brinch Hansen"

instead, BibTeX would (erroneously) think +“Brinch” were a First-part token, just as +“Paul” is a First-part token in “John Paul +Jones”, so this erroneous form would have two First tokens +and one Last token.

Here’s another example:

"Charles Louis Xavier Joseph de la Vall{\'e}e +Poussin"

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.

In general, it’s a von token if the first +letter at brace-level 0 is in lower case. Since technically +everything in a “special character” is at +brace-level 0, you can trick BibTeX into thinking that a token +is or is not a von token by prepending a dummy special character +whose first letter past the "3">T_EX control sequence +is in the desired case, upper or lower.

To summarize, BibTeX allows three possible forms +for the name:

"First von Last"

"von Last, First"

"von Last, Jr, First"

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.

References

[1] The Chicago Manual of Style, pages +400–401. University of Chicago Press, thirteenth edition, +1982.

[2] Leslie Lamport. L +"1">^AT_EX: A Document Preparation +System. Addison-Wesley, 1986.

[3] Oren Patashnik. Designing BibTeX styles. The +part of BibTeX’s documentation that’s not meant for +general users, 8 February 1988.

[4] Mary-Claire van Leunen. A Handbook for +Scholars. Knopf, 1979.

+ + + + Propchange: incubator/ooo/ooo-site/trunk/content/bibliographic/btxdoc.html ------------------------------------------------------------------------------ svn:eol-style = native Added: incubator/ooo/ooo-site/trunk/content/bibliographic/btxdoc_html_4f4e0c11.png URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/bibliographic/btxdoc_html_4f4e0c11.png?rev=1175536&view=auto ============================================================================== Binary file - no diff available. Propchange: incubator/ooo/ooo-site/trunk/content/bibliographic/btxdoc_html_4f4e0c11.png ------------------------------------------------------------------------------ svn:mime-type = image/png Added: incubator/ooo/ooo-site/trunk/content/bibliographic/btxdoc_html_7359fea5.png URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/bibliographic/btxdoc_html_7359fea5.png?rev=1175536&view=auto ============================================================================== Binary file - no diff available. Propchange: incubator/ooo/ooo-site/trunk/content/bibliographic/btxdoc_html_7359fea5.png ------------------------------------------------------------------------------ svn:mime-type = image/png Added: incubator/ooo/ooo-site/trunk/content/bibliographic/btxdoc_html_m6b4cff24.png URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/bibliographic/btxdoc_html_m6b4cff24.png?rev=1175536&view=auto ============================================================================== Binary file - no diff available. Propchange: incubator/ooo/ooo-site/trunk/content/bibliographic/btxdoc_html_m6b4cff24.png ------------------------------------------------------------------------------ svn:mime-type = image/png Added: incubator/ooo/ooo-site/trunk/content/bibliographic/citation-prefix.png URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/bibliographic/citation-prefix.png?rev=1175536&view=auto ============================================================================== Binary file - no diff available. Propchange: incubator/ooo/ooo-site/trunk/content/bibliographic/citation-prefix.png ------------------------------------------------------------------------------ svn:mime-type = image/png Added: incubator/ooo/ooo-site/trunk/content/bibliographic/components.html URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/bibliographic/components.html?rev=1175536&view=auto ============================================================================== --- incubator/ooo/ooo-site/trunk/content/bibliographic/components.html (added) +++ incubator/ooo/ooo-site/trunk/content/bibliographic/components.html Sun Sep 25 19:38:58 2011 @@ -0,0 +1,105 @@ + + + + + + Bibliographic Project Major Component Overview + + + + + + + + + + + + + + + + + + + + + +

Last Modified 2006-September-27
Overview of Project Components + + ----------------------------------------------------------- + + The diagram on the right shows the + major functional components of the proposed bibliographic system + - + + Bibliographic Data + + Bibliographic data import and export to common formats. + Internet database and catalog searching and importing. + Database Selection and Management. + Bibliographic data entry, editing, browsing and + searching. + Copying data between documents' internal Bibliographic data + and the database(s). + + + Screen presentation and + handling of Bibliographic material + + Visual marking, display of context menus, display + options. + + + Insertion of citation marker (footnote / endnote or + in-text) and selection of citation options. + + + Insertion of bibliographic tables and selection of + options. + + + The automatic selection of initial, subsequent and Ibid + citation forms. + + + Bibliographic Style management + and presentation + + Selection of bibiographic style. + Definition of bibliographic style (MLA APA, ASA, etc.) + Selection of bibliographic style options. + Loading and saving bibliographic style definitions. + Bibliographic Citation formating. + Bibliographic table formating. + + + Document saving and + loading + + A new bibliographic data file + will be included with the document save file package that + will contain the additional bibliographic data in the richer + and more comprehensive MODS complaint format. + + + + + +	+ +
The diagram below sketchout alternative arrangments for + the relationship between the WordProcessor and the Bibliographic + Module (the basic bibliographic + API's). + + See a discussion + of the scheme represented in the diagram below. +
+

+ + Propchange: incubator/ooo/ooo-site/trunk/content/bibliographic/components.html ------------------------------------------------------------------------------ svn:eol-style = native Added: incubator/ooo/ooo-site/trunk/content/bibliographic/datasourcescreen.jpeg URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/bibliographic/datasourcescreen.jpeg?rev=1175536&view=auto ============================================================================== Binary file - no diff available. Propchange: incubator/ooo/ooo-site/trunk/content/bibliographic/datasourcescreen.jpeg ------------------------------------------------------------------------------ svn:mime-type = application/octet-stream Added: incubator/ooo/ooo-site/trunk/content/bibliographic/deficiencies.html URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/bibliographic/deficiencies.html?rev=1175536&view=auto ============================================================================== --- incubator/ooo/ooo-site/trunk/content/bibliographic/deficiencies.html (added) +++ incubator/ooo/ooo-site/trunk/content/bibliographic/deficiencies.html Sun Sep 25 19:38:58 2011 @@ -0,0 +1,320 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

User requirements and current deficienciesÂ

+ +

Last modified 2006 March 23

+ +

General requirements

+ +

OpenOffice needs -

Enhancements to the bibliographic database and internal data structure; + fields need to be able to handle larger texts eg multiple authors; the + data structure need to be compatible to new standards; it needs to + support more complex data structures such as a author table liked to + bibliographic records.
Provision for document style support, which includes page formatting + and citation method and bibliographic formats. (eg MLA specifies page + formatting and citation types for technical papers and student + essays.)
Build a method for building document style descriptions and importing + and exporting these.
Provide import and export facilities for bibliographic data in common + formats.
Support for the full range of common citation styles. In-text and + footnote / endnote methods and Footnote symbols.
A much better bibliographic data entry, edit, and browsing facilities. + Similar to high-end commercial applications such as Endnote.
Ability store and directly access bibliographic data on a database. + Ability to interact with other bibliographic databases.
Ability to directly query reference sources via the internet and add + responses to bibliographic records.

+ +

Deficiencies needing correction

+ +

1. The Bibliographic referencing needs to support the +footnote citation style (commonly used in the Humanities, and particularly in +History) such as defined in the Chicago Manual of Style. Eg
+------------

+ +

+
34. T.M. Charles-Edwards,"Honour and Status in Some Irish and + Welsh Prose Tales.", Eriu, xxxvi, 1978.
+

+ +

Currently citation key is currently defined as fixed character string +called the âshort nameâ eg [DWILSON:2000] which the user enters when the +bibliographic reference is entered. The field selection and formatting +facility available for the bibliographic table (and other index and tables) +needs to be able to format the footnote citation string.
+
+2a. There needs to provision for defining citations and references with +different treatment for first and subsequent uses of the citation. There is a +tedious and fault prone aspects of the footnote / endnote citation method - +the maintenance the Initial and Subsequent citations in the correct order as +one edits the text. It is not difficult when editing to move a piece of text +and have as result the Initial Citation reference coming after the Subsequent +reference.
+
+2b.Then there is the issue of support for treating repeating footnote +references such as the use of - 24. ibid.
+
+3a. Endnote citations are only partially supported. Citations can be marked +by numbers and this enables the use of the endnote method of citation. As the +Bibliographic table can function as the endnote citations placed at the end +of the chapter of the document. However the Chicago Manual of Style specifies +different formats for footnote / endnote citations and the bibliographic +table (citation use Initials & Surname, Bibliography Table uses Surname +& Initials). Currently only one format can be defined.

+ +

3b. There needs to be an option to place the endnotes an a user selectable +location. Currently there are only two options availalbe at the end of the +document or at the end of each section. The reason this needs to be make more +flexable is that style manuals specify different locations. For example the +formatting guidelines for APA and Chicago style submissions specify the +following order for the sections in a document:

APA Style: title page; abstract; text; references; appendixes; author note; footnotes/endnotes; tables; figure captions; figures

Chicago Style (back matter): Appendix; Endnotes; Glossary; Bibliography; Index; Colophon

+ +

See issue number 37679 for +details.

+ +

4a. Chicago Manual of Style requires repeated author names in the +Bibliographic Tables to be indicated by a three-em dash eg.

+ +

+
Dickens, Charles. A Tale of Two Cities (London:Penguin Books, + 2000)
+ âââ Nicholas Nickelby, (London: + Penguin Books, 1956)
+ âââ Oliver Twist, (New York, + Random House,1965)
+

+ +

The bibliographic table generator should do this.
+
+4b. Associated with bibliographic table generation is special sorting rules. +Provision needs to be made for these. (as so well discussed in D. E. Knuth. +Sorting and Searching. Example: how to sort âMujahid Usamah Bin +Ladinâ ; â bin â is always ignored in sorting.)

+ +

Another sorting issue - When used to create a list of references for an +APA style paper, the references need to be sorted by (Author, Date) sequence, +which is straightforward enough, but references without an identifiable +author (such as a web page) need to be listed by the title of the article and +alphabatized in the list accordingly.
+
+5. There is a need to support more that one document style. The current +facilities support only one document style. The table definitions for +bibliographic table can be manually modified to support a particular citation +style. But the modified style can not be save, or selected. (Saving the +document table formats as templates is possible, but this is not the most +convenient way of dealing with citation styles.)
+
+6. There should be provision for Footnote symbols. The Chicago Manual of +Style stipulates that when Endnotes and Footnotes are both used, the Endnotes +are consecutively numbered (1,2,3 ...) and the footnotes referenced by +symbols. The series they suggest are -

+ + + + + + + + + + + + + +

As more symbols are needed they are doubled and + trebled -

+ +

+6a. At present there are two loosely coupled bibliographic facilities. One is +the old StarOffice 5.2 Bibliographic database (dbase format) It has a simple +reference insertion process. When an database bibliographic entry is dragged +onto a document, a dialog box opens which allows the fields required for the +entry to be selected. This process can be configured for only one citation +format in one citation style - eg book reference for MLA - and it does not +support character formatting of fields, such as italic or underlining.
+
+6b. The other facility in new in OpenOffice. It stores bibliographic data +within the document. The data is entered through 'Insert >Indexes and +Tables> Bibliographic Entry' function, and bibliographic tables can be +generated from it. There is no capacity for this in-document bibliographic +data to be imported or exported (other than hacking them out of the save +file).
+
+6c. There is no provision to enable the transfer of data between the internal +document storage and the dbase Bibliographic database.

+ +

6d. Currently no link is maintained between the database and the inserted +citation. If the database reference is changed, currently the citations +refering to that reference have to be manually re-inserted or manually +corrected. A link to the bibliographic citation source (such as the database) +must be made, and an 'citation update for source' command created. See issue +44189.

+ +

+7. The only import / export facilities available for bibliographic data is +via the dbase Bibliographic database by copying the table and pasting in into +another one and saving it as dbase, CSV or text. The same method can be used +to import. This is hardly convenient. Nor is there any provision to import or +export bibliographic data using any of the common formats â Endnotes, +bibtex, Ovid, Medline, Refer, isifile, etc.
+
+8. The data model used for the bibliographic database is based upon BibTeX. +This has several limitations, it only supports a few document types and does +not properly support new media types. A MODS compatible data model is +preferable.

+ +

"MODS - Metadata Object +Description Schema. The Library of Congress' Network Development and MARC +Standards Office, with interested experts, has developed a schema for a +bibliographic element set that may be used for a variety of purposes, and +particularly for library applications. As an XML schema, the "Metadata Object +Description Schema" (MODS) is intended to be able to carry selected data from +existing MARC 21 records as well as to enable the creation of original +resource description records. It includes a subset of MARC fields and uses +language-based tags rather than numeric ones, in some cases regrouping +elements from the MARC 21 bibliographic format. MODS is expressed using the +XML schema language."

+ +

9. The dbase bibliographic database has field size restrictions which are +too small for most situations.
+
+10. There should be option to select a document style that applies to the +whole document. Some styles such as MLAâs Research Paper defines line +spacing, margins and headings.
+
+11. If a user is expected to conform to a document style, there is no support +to assist a user to maintain this style. It would be useful to have some +function that could save the user from accidently modifing a setting that +violates the style.

+ +

We could achieve this adding an option that would allow a user to switch +on a 'Strictly Enforce Style (Y/N)' flag. The idea is that it would prevent +the user from modifying the document style aspects defined by the selected +Document Style. This could also make the OOo word processor easier to use as +many of the functions would be grayed-out or not shown. The user would not be +so bewildered with choice. The user could at any time turn off 'Strictly +Enforce Style' and have access to all settings.

+ +

I envisage this function with working with a 'Select Document Style' +option which would select the bibliographic format style, but could include +all the elments that make up a document style guide. Margins, text size +spacing, order of document components etc.

+ +

12. There is no support for types of citations with a style, of the type +-

+ +

If I quote a document(book/journal/article etc.) without a page it looks +like

+ +

"This method is very reliable (AUTHOR YEAR)"
+f.e. "This method is very reliable (BASLER 2003)

+ +

"But AUTHOR (YEAR) showed that..."
+f.e. "But WILSON(2002) showed that this method is not very reliable."
+If a page or some pages are quoted (direct or indirect) it must look like
+"'This method is very reliable' (AUTHOR YEAR:12)"
+f.e. "'This method is very reliable' (BASLER 2003:12)"

+ +

"'This method is very reliable' (BASLER 2003:12 ff.)"

+ +

"AUTHOR (YEAR:12) stated 'This method is very reliable.'"
+f.e. "BASLER (2003:12) stated 'This method is very reliable.'"

+ +

"BASLER (2003:12 f.) concludes that this method is very reliable.'"

+ +

Some comments on that:
+1. The AUTHOR(s) must be in small capitals (as every person everywhere in the +text - a requirement in some European countries).
+2. One author: "AUTHOR 2003" Two authors: "AUTHOR1 & AUTHOR2 2003" Three +or more: "AUTHOR1 ET AL. 2003"

+ +

If there are more than one publication of an author in the same year it +must look like:
+"BASLER 2003a" and "BASLER 2003b" a.s.o.
+In the bibliography the above example would look like
+BASLER, M. (YEAR): Book title. City1 et al.

+ +

BASLER, M. & D. WILSON (YEAR): Book title. City1 et al. or BASLER, M. +D., WILSON, A. NONAME & B. NONAME (YEAR): Book title. City1 et al.

+ +

Note that in the bibliography index ALL authors including their initials +must be stated, in the text citations only the first, followed by "ET AL."

+ + Propchange: incubator/ooo/ooo-site/trunk/content/bibliographic/deficiencies.html ------------------------------------------------------------------------------ svn:eol-style = native Added: incubator/ooo/ooo-site/trunk/content/bibliographic/deficiencies.pdf URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/bibliographic/deficiencies.pdf?rev=1175536&view=auto ============================================================================== Binary file - no diff available. Propchange: incubator/ooo/ooo-site/trunk/content/bibliographic/deficiencies.pdf ------------------------------------------------------------------------------ svn:mime-type = application/pdf

BiB-TEXing

Oren Patashnik

February 8, 1988

Overview of Project Components

User requirements and current deficienciesÂ

General requirements

Deficiencies needing correction

BiB-T_EXing