User’s Guide to the Camel Citator^{∗}

Frank G. Bennett, Jr.^{†}

November 29, 1995

Abstract

This is the core documentation for Camel, a L^{A}TEX macro package that drastically simplifies the typesetting of citations and bibliographies in a wide variety of styles and formats. Camel is similar in look and feel to standard BibTEX, but introduces a number of long-desired enhancements. When the document is printed, Camel allows the generation of subdivided bibliographies, separate bibliographies for each subdivision of a larger work, in-footnote cross-referenced citations, bibliographies indexed to the pages where citations to the relevant work occur, and much else. This is the only fully supported bibliography package for L^{A}TEX that provides full support for legal citations. The package also provides genuinely helpful error messages and an extremely simple syntax for adding details like page numbers and the like to citation tags. Camel provides the logical engine and skeleton macros that make these things possible; a separate style package is required to actually typeset documents. For an example of a working style package, see law.dtx in the camel subdirectory on CTAN.

Contents

1 Introduction 1 1.1 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2 BibTEX features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.3 Processing documents . . . . . . . . . . . . . . . . . . . . . . . . . 7

2 Notes for Implementors 9 2.1 Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.2 The .cst file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.3 Toggles and hooks for the .cit file . . . . . . . . . . . . . . . . . . 10

2.3.1 Citation history . . . . . . . . . . . . . . . . . . . . . . . . . 10 2.3.2 Formatting toggles . . . . . . . . . . . . . . . . . . . . . . . 10 2.3.3 typefaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.3.4 Citation details . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.3.5 Bridges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.3.6 Pinpoint printing . . . . . . . . . . . . . . . . . . . . . . . . 12

∗This file is version number 1.0m. The documentation was last revised on 95/06/24.

†The text and source code contained in this file are \begin{matrix}c \\ ◯ \end{matrix} 1992–1995 by Frank G. Bennett, Jr.

This file can be freely distributed; the sole condition of use is that acknowledgement to the author be made in any published work produced using Camel. The author wishes to thank Pedro Aphalo, Steve Bellovin, George Greenwade and Boris Pevzner and David Rhead for their helpful comments on versions of LexITEX, the predecessor to Camel. In addition, David Rhead provided a mass of information on bibliographic conventions, which was used in shaping the options supported by this package. Gratitude is also owed to Marcia Elliot and Yoshiko Makino, LL.B. finalists in the Law Department of the School of Oriental and African Studies in 1993 and 1994 respectively, who prepared extended essays using early releases of LexITEX.

2.4 The .cit file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 2.5 The .bst file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

2.5.1 Entry types . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.5.2 About cross-referencing . . . . . . . . . . . . . . . . . . . . 14 “Now comes the fun part.”

—Donald Knuth^{1}.

Preface to release 1.0

Welcome to Camel, a comprehensive bibliography manager developed as a prototype citation engine for the L^{A}TEX3 project. The Camel engine offers a highly flexible yet straightforward syntax for entering citation keys into a L^{A}TEX document. The Camel engine is designed to support a wide range of citation styles. Documents prepared for Camel can be converted into virtually any supported bibliography or citation style, usually by editing only a few toggles at the top of the document.^{2}

Within the L^{A}TEX3 project, an extensive survey of bibliographic styles was carried out by David Rhead. Pedro Aphalo, Task Coordinator for bibliographic support on the L^{A}TEX3 Project, first proposed adopting a unified syntax for all bibliographic styles. Camel itself is the brainchild of Frank Bennett, and is based upon his earlier work on the LexITEX style engine for legal materials. This package completely supercedes LexITEX, and that earlier style package will no longer be supported. The new package should be referred to as “the Camel citator”.^{3}

The core Camel package provides hooks for the development of style options that satisfy all bibliographic requirements that have come to the attention of the L^{A}TEX3 bibliography team. The foundation has been laid, but much work remains to be done in drafting Camel modules to meet all known bibliographic requirements in all fields (and in all languages) for which L^{A}TEX is used. This work will involve the drafting or modification of .bst files in the reverse polish notation used by BibTEX, and of Camel style modules written in TEX. If you want to contribute to a project that will dramatically enhance the utility of L^{A}TEX as an author’s productivity tool, get involved! The developers’ email addresses are as follows:

• Frank Bennett: fb@soas.ac.uk.

   • Pedro Aphalo: aphalo@cc.joensuu.fi.
   • David Rhead: David Rhead@vme.ccc.nottingham.ac.uk.

A programmer’s reference guide for drafting Camel styles is included in this manual. Don’t delay—start coding today.

1<undefined:  knuth> .

2This is potentially exciting (he said), but as of this writing only one module — law.dtx, the legal citation module used for beta-testing the Camel engine — exists. Some followers of Camel development have expressed serious interest in developing other modules, however, so a claim to broadening support for this package is legitimate.

3Why Camel? I can offer several reasons, users may take their pick. The style operates by gathering citation details that it carries with it through the desert of plain text, until the bibliography engine reaches its oasis at document’s end. Alternatively, in his daily work the author uses the multi-lingual enchancement of Emacs, which is called “Mule”. It’s nice for one critter to have the company of another in the stable. A third arbitrary explanation is that the Japanese word for “camel” is rakuda. These syllables, with a different intonation, mean “dead easy”. Since the design goal of Camel is to make bibliography management as easy, as fool-proof and as robust as possible, this cross-lingual pun seems fitting.

1 Introduction

This guide explains the use of the Camel Citator. It covers all commands available in the style. This should be the only user manual that you need to prepare a document for use with any Camel bibliography style. The package provides eight commands, listed in the table at the bottom of this page. The opening commands may be combined in a variety of ways, but a typical document heading might look like this:

      \documentclass{article}
      \usepackage{camel}
      \citationsubject{english}{Materials in English}
      \citationsubject{german}{Materials in German}
      \begin{document}
      \citationstyle{law}
      \citationdata{gorp,slush,fodder}
      \forcefootnotes

You should be careful to decide on the subject classification, if any, that you wish to apply to your citations, before you begin your writing. With that in hand, you can begin entering \source commands into the document, adjusting the style parameters at print time. A detailed description of command usage follows. Throughout this guide, it is assumed that the reader has a general familiarity with BibTEX and its use in preparing bibliographies with standard-issue L^{A}TEX. If you need to learn more about BibTEX, a number of excellent sources of information are available.^{4} The treatment given to the programming language tends to be quite brief, but you should not be put off by this; the language is, in fact, quite simple to use, and the Camel programming library makes things even easier.

1.1 Commands

\citationstyle The \citationstyle command is used to tell both BibTEX and the Camel engine how your citations should be formatted; its argument is the name of a Camel module (contained in a .cst, a .cit and a .bst file) such as ‘law’. In this

Camel commands

4<undefined:  latex-book> ; <undefined:  latex-companion> ; <undefined:

oren-user> and <undefined:  oren-hackers> .

\citationsubject[⟨options⟩]{⟨nickname⟩}{⟨heading text⟩} optional  preamble \citationstyle{⟨style package name⟩} required doc top \citationdata{⟨bib1,bib2… ⟩}  alternative doc top \bibliographymanager{⟨product name⟩}  alternative doc top \forcefootnotes  optional  doc top \newinterword{⟨nickname⟩}{⟨text⟩}  optional  doc top \printbibliography{⟨nickname⟩}  optional  anywhere \source[⟨options⟩]{⟨nickname⟩}[⟨page numbers⟩]  n/a  anywhere

respect, it is similar to a “document class”, but for citations instead of whole documents. This declaration may be make more than once.^{5}

\citationdata This command is used to indicate the .bib files from which citation entries should be drawn. As in the \bibliography command of standard L^{A}TEX, the \citationdata command takes one option, which is a comma-separated list of bibliographies for use in the documents. Each refers to a .bib file, each of which should be in the path of your local BibTEX.

\bibliographymanager While we hope that you find BibTEX the most satisfactory means of formatting your citations, you might prefer to use some other software product for the separate task of managing a large citation database. Camel has been designed so that it can be used with a number of such utilities. If you are using an external bibiliography manager, you should declare the name of the package at the top of the document using the \bibliographymanager command. Supported managers, and their corresponding nicknames for this command, are:

• Reference Manager (referencemanager)

• Papyrus (papyrus)

• ProCite (procite)

• EndNote (endnote)

The details on how to join external bibliography managers with Camel are below at page 8.

If you use the \bibliographymanager command, you should not use the \citationdata command. This is not felt to be a serious limitation; if you use a bibliography manager, you might as well put all of your citations into it anyway, and use it as the sole source of citations in your documents.

\citationsubject You may wish to produce a bibliography classified into subheadings by subject or by type of material. To do this, place a set of \citationsubject commands at the top of your document, or after a \printbibliography command. Each command takes two mandatory arguments and one optional argument. The first mandatory argument indicates the nickname that you will use in your document to attach a citation to the category. The second is the section heading that you wish to see displayed for that section of the bibliography.

The optional argument may be used for two purposes. First, you may want to further divide your bibliography into sub-subheadings. You can specify a such a subcategory by putting a 2 as the optional argument to the \citationsubject command. Otherwise, a first-level header is used. Where the \printbibliography command is issued, the parts and sub-parts of the bibiliography will be produced in the order in which they were declared.

For some types of citation, you may wish to produce a table that shows more detail about citations made. With Camel, simply add an optional argument to the \citationsubject command applicable to your desired table which includes an o= argument of three letters (giving the extension of the raw data output file), and an i= argument of three letters (giving the extension of the makeindexprocessed input file). Optionally, you may also include arguments of p or P. With p, the output file will be passed the page or section numbers given in pinpoint arguments to the \source command. With P, index-style page references to the main text are turned on. With or without the P or p,^{6} the export file should be processed with makeindex using Camel’s own camel.ist file to produce the import file. This table-creation feature exists principally for typesetting tables of statutes.

5This feature (support for multiple citation styles in a single document) will be added after the release of BibTEX 1.0.

\forcefootnotes If you are preparing a document that is to be, or may be, prepared with citations in footnotes at the bottom of the page, you can save yourself some typing (and make it easier to produce the same document in other formats) by using the \forcefootnotes command at the top of the document. In some styles this command has no effect since, for example, a footnote containing only “[2]” would look rather peculiar.

\newinterword In a string citation, you may want to use a connecting word that is not already in Camel’s internal list. You can add a word to this list with the \newinterword command. This command takes two mandatory arguments. The first is the nickname you wish to give to the word and its associated punctuation. The second is the text to be inserted when you use the new connecting word between two \source commands.

The connecting word may appear either at the beginning of a citation string (as the argument to a != option in the first \source command of a string), or in the middle, between two citations. Two special characters are used to control the appearance of the word in these two positions. A leading punctuation mark should be preceded by a _character. This will suppress such a punctuation mark, and the space following it, if the connecting word is used as a prefix to an initial citation in a string. The ^character should precede the first word of the phrase associated with the connecting word, and that character should be capitalized. The first character of the phrase will then be forced to lower case if the connecting word is used between two \source commands.

The following examples may be useful for guidance:

   • \newinterword{cf}{_; ^C.f.~}
   • \newinterword{see-generally}{_. ^See generally\ }

\printbibliography Place a \printbibliography command in your document wherever you would like the bibliography to appear. If no \citationsubject commands are used at the top of the document, \printbibliography{all} will produce a full bibliography of all references made in the document up to that point. If

\citationsubject has been used, then \printbibliography{all} will produce

the same bibliography, but classified by subject, with the headers specified in the \citationsubject commands at the top of the document.

You may also specify a subject to the \printbibliography command, instead of all. This will produce a bibliography formatted as requested in the \citationsubject command. Note that, if the i= and o= options are used with \citationsubject, makeindex must be used to generate the input file that will be expected for that subject. Note also that such external tables will be ignored by \printbibliography{all} where citation subjects are used.

\source The most common command for Camel users is the \source command, which replaces the \cite command of standard L^{A}TEX. It is used to identify the citation in the .bib data files, and to provide a logical description of any ‘fine-tuning’ of the citation form that the user might desire. Because it is frequently used, and must be accessible to authors with more interest in the content of what they are writing than the inner workings of L^{A}TEX, much effort has gone into making the command as simple to use as possible.

6The syntax of these options is the same as for options to the \source command, discussed above.

Options

The valid options that may be placed inside the first set of square braces are shown below.

Single character options

a — Supress printing of author’s name in the document. t — Suppress printing of the title in the document. l — Force automatically generated abbreviations to lower case. n — Suppress printing of the citation in the document (equivalent to \nocite in

standard L^{A}TEX). f — Force the full form of the citation to be printed in the document. h — Suppress automated footnote generation and the use of interwords for the cur-

rent and following citations. This option should not be used in the middle of a string of citations linked with interwords.

String options

s= — Associate the citation with the specified subject. This option can be freely specified, but only has significance when a classified bibliography is being produced. When these subject tags are being used for that purpose, they must be declared at the top of the document, and a given source must be associated with the same subject throughout the document; specifying a different subject from that used in the first use of the citation will produce an error message from L^{A}TEX.

v= — Give a volume number for use in the citation. BOOK entries in a BibTEX database may be given a volume number. Such citations are assumed to be multi-volume works, and a volume number should be supplied when citing them; the volume number given in a BOOK entry itself ignored, and an error message will be produced if an explicit volume number is not given using this option.

!= — Precede the citation with the interword given in the argument.

These options may be entered in the option braces in any order, with the single requirement that a comma must end a string option if it is followed by another option.

The number of possible citation forms that can be generated using these command options is very large, and varies from one style to another. The best way of familiarizing yourself with them is to finish reading the next section of this guide, and then do a little experimentation with the various options. This will serve you much better than a verbose set of illustrations here, which would not stick in the memory, would be difficult to use as a reference, and could not in any case cover all of the possibilities.

The following citations are all valid:

   • \source[ats=school]{ucla}
   • \source[av=8,t]{harvard}
   • \source[s=town,nat]{oxford}

A string of citations applying to a particular statement may be entered as follows:

• \source[⟨options⟩]{⟨nickname⟩}[⟨page numbers⟩] ⟨interword⟩ \source[⟨options⟩]{⟨nickname⟩}[⟨page numbers⟩]

Keys

The key given in the squiggly braces should correspond to the key that identifies the entry in the BibTEX or other database that you are using. If you have a series of citations to make, and do not need to give separate options to any of them, you can enter them as a comma-delimited string, in the following manner:

     \source[s=stooges]{joe,curly,moe}

Pinpoints

For most citations, pinpoint references are simply typed between the second pair of square braces, using normal punctuation marks ( , & - ). Spacing is irrelevant, so long as the punctuation marks are entered. A valid simple pinpoint citation might look as follows:

     \source{major}[2, 7, 9 & 23]

In some very special situations, Camel needs more information to handle pinpoint references correctly. Suppose you are entering a citation for a statute, and you intend to produce a table showing where references to each cited section of the statute are made in the text. If your citation includes references to more than one section of the statute, Camel will produce a table entry for each cited section automatically. But what if you are citing a range of sections? Camel cannot know whether the range is continuous, or has gaps in it where provisions have been repealed. You therefore need to tell Camel explicitly about each section number—but you don’t want the numbers to be printed in the text. To feed citation numbers to the table, but suppress printing in the document, separate the numbers to “hidden” from the rest with a “fence” in the form of the | character. A typical citation of this kind might look like this:

     \source{SaleofGoodsAct}[19-25 | 20, 21, 22, 23, 24]

There are two other situations, also related only to the production of tables, where special markings may need to be included in the pinpointing string. These are (a) where you want material to appear only in the text, and (b) where you want material to appear only in the table. The first case may arise where you are citing subsections of a statute. In this situation, you can enclose in ^characters any text that you want to withhold from the table. A simple citation of this kind might look as follows:

     \source{VehicleCode}[23(A)^(3)(a)(i)^]

Where material should appear only in the table, enclose that pinpoint material in _characters. This might be necessary where, for example, you are citing two subsections of the same statute. An example might look as follows:

     \source{LawofPropertyAct}[70(1)(f) & _70(1)_(g)]

Finally, there is one more feature that applies only to ‘parallel citations’ to law cases. If a law case to which you are referring is reported in more than one location (see below), and you want to give a pinpoint to each location, you can do so by using the the = sign between the pinpoint strings. For example:

     \source{bloggvkermit}[20-25 = 125-26 ]

If more parallel pinpoints are given than exist in the BibTEX entry for the case nicknames bloggvkermit, the extra pinpoints will be ignored. Similarly, if you give fewer pinpoints than there are parallels in the BibTEX entry, the portions of the entry with no matching pinpoints will be omitted. No fuss, no muss.

1.2 BibTEX features

A number of enhancements for processing BibTEX entries have been incorporated into the Camel BibTEX programmer’s library. These enhancements are drawn upon by the law.bst style, and should also be used by subsequent Camel style modules. These features are described briefly here. Please see the BibTEX documentation for more information on the format of BibTEX entries et cetera.

Cases

A new entry type, @CASE, has been added. This entry type should be used for reported law cases. Although citation forms vary widely between jurisdictions, Camel bases the formatting of the citation on the information contained in the citation, rather than a tag indicating the jurisdiction.

A result of this approach is that there are no ‘required’ fields in the usual sense that BibTEX will complain if something is missing. Instead, is a set of ‘core’ fields for each of three different formatting styles. For someone familiar with legal resources, this is actually quite intuitively straightforward.

For reported U.S. law cases, the core fields are title, volume, journal, pages and year. In addition, you may wish to specify court.^{7} Procedural histories may not be represented in the BibTEX entry.

For reported Commonwealth cases, use number instead of volume. The effect of this will be to place the year at the front of the citation in square braces, with the number and journal following it. Again, you may specify court optionally.

For cases reported in ephemeral media such as newspapers, leave out volume and number, and give the full date in the year field instead (see below for the formatting of dates). The formatting of the citation will adjust accordingly.^{8}

7This is not yet implemented, but can be and should be.

8I’m not sure whether this works with parallels yet. If it doesn’t but you need it to, let me know and I’ll fix it.

For cases reported in jurisdictions such as Japan that refer to cases by date

rather than title, use casedate, court, journal, volume, pages and year. Op-

tionally, you may also wish to include divno and division, to specify the exact identity of the deciding court.

Statutes

Support for statutes is still in its infancy. You need, at minimum, to enter

title, year and jurisdiction. Supported jurisdictions are japan, singapore
and england.

Dates

The entry of dates has been considerably simplified in Camel BibTEX entries. Always use the year field (or, if appropriate, the casedate field). Months may be entered as numbers or as a three-character string. The following date forms are all valid:

      year = {10 jun 1995},
      year = {jun 10 1995},
      year = {jun 1995},
      year = {1995},
      year = {10/06/95},

Parallel citations

For @CASE entries, it is possible to enter multiple citations in a single BibTEX entry using a short form of citation in a field called cites, separating entries with a = character.^{9} There are several valid syntaxes for this field, which closely follow the citation format used in the Blue Book for the relevant sources. They are:

      cites = {[1995] 1 All ER 25 = [1995] 2 WLR 125},
      cites = {123 Cal.3d 237 (1995) = 124 S.W.2d 235 (1995)},

You can create an arbitrary number of parallel citations in this way.^{10} Be sure to read the notes on pinpointing, above, for details on how to specify pinpoint references to parallel citations.

1.3 Processing documents

Ordinary processing

For a simple document containing no cross-references other than those produced by Camel, printing requires one run of L^{A}TEX, one run of BibTEX, and a second run of L^{A}TEX. Because Camel absorbs all citation information at the start of

the document (at the point of the \citationdata or \bibliographymanager

commands), there is no need for the third L^{A}TEX run required in the standard L^{A}TEX setup. You may, however, need additional runs of L^{A}TEX to resolve other cross-references in the document, or to work out misspellings and other errors.

9It actually does work. <undefined:  halsall-v-brizell> .

10Cross-references are complex to format, but they work correctly. <undefined:

halsall-v-brizell> . In a competition for speed and accuracy between typists equipped with L^{A}TEX/Camel and with WordPerfect, who do you reckon would win?

Producing tables

When the o= and i= options are used for one or more declared citation subjects, those subjects will be excluded from the bibliography. Instead, Camel will write an external table file according to the specifications given in the \citationsubject command. Any such files must then be processed into properly formatted lists using makeindex before they will appear in the printed document.^{11} On a UNIX or DOS system you would type the following for a table declared with the export extension .atb and the input extension .art:

     makeindex -s camel.ist -o ⟨file name⟩.art ⟨file name⟩.atb

If the subject associated with this table is article, the table can then be placed in the document for the next L^{A}TEX run using the command:

   • \printcitationtable{article}.

When the option p is used with the \citationsubject command and the i= and o= options, the table will include any section or other numbers given as optional arguments to \source commands in the document. Because makeindex sorts alphabetically, not numerically, the section numbers may be out of their proper order in the makeindex-processed file. This must be corrected by hand.

11The documentation for makeindex will explain how it should be set up for your system. On a UNIX or DOS installation, the basic requirements are that the makeindex program be in your search path, and that the appropriate environment variable (usually indexstyle) be set—this tells makeindex where to find the style files that tell it exactly how to format the finished table lists.

2 Notes for Implementors

2.1 Getting started

The purpose of this section is to provide style designers with all of the information required to write a new bibliography style from scratch, drawing on the powerful facilities available in BibTEX and the Camel style engine. Before you start, you should have a sound knowledge of BibTEX primitives, and of the programmer’s function library contained in the file camel.dtx. A bibliography style consists of a .bst file, a .cst file and a .cit file. The .bst file should produce entries suitable for digestion by Camel for all of the BibTEX entry types supported by the style.

The modules of the Camel system work together in an integrated fashion to format citations. Raw citation details are kept in .bib databases. The function of the Camel system is to massage those details into formatted citations, and include them in appropriate locations in typeset pages. When a document invoking the Camel package encounters a \citationstyle command, the relevant .cst and .cit files are loaded. A corresponding \bibstyle entry is also written on the .aux file. A \citationdata command causes a relevant \bibdata command to be written there as well. If a \bibliographymanager declaration is used instead, a \bibdata entry calling on the file camel.bib is written to .aux. When a \source command is encountered during processing, code contained in camel.sty writes a \citation entry for that citation on the .aux file. In this way, an orthodox set of entries and files for use with BibTEX is generated.

If an external bibliography manager is used, the file camel.bib must be converted into a valid .bib file, using whatever tools for finding and replacing key entries the database manager has to offer.

BibTEX must then be run on the document. This reads the entries on the .aux file, opens the .bib databases, reads them, and writes the result of its ruminations on a .bbl file. At this point, the operation of Camel diverges sharply from that of conventional L^{A}TEX bibliography tools. With Camel, BibTEX is used to generate \lexibib entries on the .bbl file. Such entries parse the citation into logical typesetting units, but the typefaces used within the units, and the punctuation that appears between them, is not determined by BibTEX. The tasks of punctuation and typeface selection are carried out on the second run of L^{A}TEX on the document, using the details specified in the .cit file for the Camel citaton style being used.

It is worth spending some time pondering this programming flow; there are good reasons for spreading the formatting work over a number of different modules in this way, and it is important to understand the design before embarking on the drafting of a style.

2.2 The .cst file

The .cst file should contain, at least, the following macros:

\@law@print: This is the macro that actually prints the citations in the document and in the bibliography. Its structure is discussed below in the commented code listing of the default \@law@print command, which draws on most of the conditional handles provided by Camel.

\@law@wordlist: This is a list macro consisting of paired interword nicknames and corresponding punctuation/text sets. Possible changes you may wish to make to this file are discussed in the commented code description of this macro.

Additional macros (including re-definitions of the macros contained in the Camel engine) may be included in the .cst file. Be sure to document your work, however; Camel is among the more complex packages written for use with TEX, and documentation is essential if problems that arise are to be sorted out quickly and efficiently.

Concerning the \@law@wordlist macro, it is best to examine the existing macro in law.dtx, and read the user documentation on the \newinterword command. With this information, you should be able to make any changes you require in the behaviour of the list to suit your new style. You should not omit items from the list—this is important to maintain compatibility between styles. You may want to add to the list, and this is welcomed—drop a note to Frank Bennett on fb@soas.ac.uk to assure that your new addition is incorporated into the law.dtx list, which is used as a model, so others will include it in their styles too.

Drafting the \@law@print macro may be difficult to approach at first. If you examine the example in the law.dtx file, you may be somewhat intimidated by the size and complexity of the macro listed there. But in fact for most styles this macro should be reasonably simple to write; the law.dtx example is complex because it automates a very complex set of style rules applying to legal materials.

Essentially, what \@law@print does is print a citation in a particular form according to a set of conditions that can be recognized from toggles in effect when the macro is run by the Camel engine. The toggles that may be drawn upon are described here. For further information, study the example in law.dtx—bearing in mind that your own macro will probably be simpler to draft.

2.3 Toggles and hooks for the .cit file

2.3.1 Citation history

\if@law@firstuseofcite This is true during the first expansion of a citation nickname in the text.

\if@justabove This is set to true where (a) the author, title, source, page and citation trailer are identical in the last citation used in a footnote and in the current citation, (b) the last citation used in a footnote was the only citation in that footnote, and (c) a pinpoint was not used in the previous citation or, if there was such a pinpoint, a pinpoint is also used in the current citation.

\if@l@quiteexact  This is set to true where (a) \@law@justabove is set true and (b) a pinpoint

was used in both citations, and (c) the pinpoints match exactly.

2.3.2 Formatting toggles

\if@law@intextcite This is set true by the h option to the \source command. Use it to select a

special in-text form for the citation.

\if@law@multipages This is set true if more than one pinpoint reference is used (i.e. any of , & or

- occur in the pinpoint argument).

\if@law@printcite If this is true the citation should print. Otherwise it should not. It should

also trigger suppression of footnote forcing.

\if@law@printauthor If this is true the name of the author prints.

\if@law@printtitle If this is true the title of the work prints.

\if@law@longcite If this is true the citation should be printed in its full form. This is set true by the f option to the \source command.

2.3.3 typefaces

\@ltok@authormainface This is the typeface set in the .cit file for author names. It, and all other \@ltok@

control strings are token registers that must be expanded using \the.

\@ltok@authoroptionface This is the typeface selected by enclosing text in the author portion of the citation within \\ commands in the current citation’s type (i.e. as defined in its

\newcitestyle entry).

\@ltok@titlemainface The typeface used for the title portion of the citation. \@ltok@titleoptionface The alternative \\ typeface within the title argument to \lexibib. \@ltok@citefirstmainface The typeface used for the source portion of the citation. \@ltok@citefirstoptionface The alternative for the source portion of the citation.

\@law@firstslash These two commands should be defined as follows in your \@law@print com- \@law@secondslash mand before citation elements are expanded. This could be done within Camel

itself, but this gives you a little more hands-on control in style design maybe.

     \def\@law@firstslash{\begingroup\def\\{\@law@secondslash}%
     \the\ltokspecialface}%
     \def\@law@secondslash{\endgroup\def\\{\@law@firstslash}}%
     \def\\{\@law@firstslash}%

2.3.4 Citation details

\@ltok@whereitsat This actually contains the text that is used to flag either a note or a page number (i.e. {\ note\ } or {\ page\ }). This is used only where citation crossreferencing is required.

\@ltok@stylename This stores the citation type used to declare the citation with \lexibib. This is mainly used for internal purposes by Camel, but if you’re printing a style or proof sheet, or are just trying to debug a style, you may have a use for it.

\@ltok@nickname This stores the nickname of the citation.

\@ltok@author This stores the author portion of the citation.

\@ltok@name This stores the title portion of the citation. \@ltok@citefirst This stores the source portion of the citation. \@ltok@citepage This stores the page number (not the pinpoint!) of the citation. \@ltok@citelast This stores the citation trailer.

\@ltok@pageorfootno This stores either the page or the footnote number at which the citation first occurred.

2.3.5 Bridges

\@ltok@atot This contains the punctuation bridge, declared in the .cit file for the current citation type, that is to be placed between the author and the title elements of the citation.

\@ltok@ttocone This contains the bridge that is to be placed between the title and the source. \@ltok@conetop This contains the (singular) bridge that goes between the source and the page

number.

\@ltok@conetopplural This contains the alternative plural bridge that goes between the source and the page number.

\@ltok@ptop This contains the bridge that goes between a page reference giving the location

of an article, for example, and the pinpoint reference.

\@ltok@ptoctwo This contains the bridge that goes between any page numbers and the citation

trailer.

\@ltok@atbridge This contains the bridge that goes between an abbreviated citation (i.e. Id. or

somesuch) and a pinpoint.

\@ltok@atbridgeplural This contains the plural bridge for abbreviated citations.

2.3.6 Pinpoint printing

\@law@barkill The pinpoint information is contained in the token register \@ltok@argtwo. To print the pinpoint, you should always use the following form, which will induce the correct behaviour of the string expansion engine within Camel.

     \@law@barkill\the\@ltok@argtwo\relax

2.4 The .cit file

The .cit file should contain instances of the \newcitestyle command and associated arguments. This defines a Camel style instance for each of the entry types supported by the style’s .bst file. If you find it necessary to add a new entry type to the style defined in the .bst file for your style, you must also define a Camel style instance in the .cit file applying to this new entry type.

The arguments to the \newcitestyle command have the functions described in the following footnoted illustration:

     \newcitestyle{article^{a}}%
      {rsirsr^{b}A^{c}}%
      {[a],\ ^{d}[t],\ ^{d} [c]\ ^{d} [p],\ ^{d} (pl),\ ^{d} [rp]\ ^{d} [e]:[id]\ at~^{d}
     (pl)\ at~^{d} [xrf]}%
      {6}^{e}%
     {{#1}^{f} {#2}^{f} {#3}^{f} {#4}^{f} {#5}^{f} {(#6)}^{f} }%

aThis gives the name of the citation template to be generated.

bThe first part of this list of arguments consists always of exactly six letters: the first three pairs set the main and alternative typefaces for the author, title and firstcite-part portions of the citation. r, s, b and i select roman, small caps, boldface and italic type. These letter flags are not case sensitive. The alternative typefaces may then be specially selected in the text arguments to a citation using \\...\\.

cThe last letter in this list sets the classification of citations declared with the resulting style macro. a, b, c and s will classify all citations generated by this citation template as being to articles, books, cases or statutes, respectively. This letter flag is not case sensitive.

dThese are the citation bridges that will be placed between the portions of the citation indicated. Two bridges, singular and plural, are given between [p] (page) and

[rp] (reference page), and between [id] (id. or supra) and [xrf] (cross-reference). eThis argument states how many arguments the finished citation template will

accept. It must be a number between 1 and 6.

f Six pairs of matched braces must appear inside this argument. Any other than the first (which represents the citation nickname) may be left empty, but the bridges must of course take this into account. The number of arguments inserted here must correspond with the number stated on the line above.

2.5 The .bst file

2.5.1 Entry types

Most of the work in drafting a new style is in writing entry type functions for inclusions in the .bst file. This is, inevitably, an arduous task, because of the number of possibilities that must be covered. The task is made easier, however, by the .bst file programming library contained in the file camel.dtx. This library provides a set of functions for the manipulation of fields pushed onto the stack in the entry type functions themselves. This approach increases the transparency of your code, because you can see in the entry type function itself exactly what fields are being used, and what logical and formatting operations are being carried out on them.

Using the library is highly recommended. If you find that you require functions that are not presently available in the library, you can make your solutions available to others by adhering to a few design guidelines, and passing the function on to fb@soas.ac.uk for inclusion in the Camel distribution. The guidelines are actually quite simple. No library function should directly manipulate a field, but should instead expect to find the field on the stack when it is invoked. No library function should make assumptions about the setting of variables; any parameters should also be passed to the stack before the library function is invoked. When finished, a library function should always leave a fixed number of items on the stack, in a fixed order. And a library function should not pass data to subsequent functions in the form of variables. Finally, a function should be documented concerning (a) the number of items it expects to find on the stack, and in what order, (b) the number of items it leaves on the stack, and in what order, and (c) the effect of any toggle strings that may be fed to the function.

You may find it necessary, in drafting a function, to divide its operation into sub-functions. As between sub-functions, the ban on passing data through variables need not be followed, so long as the set of functions adheres to the rule.

2.5.2 About cross-referencing

About cross-referencing, Oren Patashnik wrote:

Now come the cross-referencing functions (these are invoked because one entry in the database file(s) cross-references another, by giving the other entry’s database key in a crossref field). This feature allows one or more titled things that are part of a larger titled thing to crossreference the larger thing. These styles allow for five posibilities:

1. an article may cross-reference an article;

2. a cross-reference to a book may be made in an entry for:

(a) a book;

(b) an inbook; or

(c) an incollection; and

3. an inproceedings may cross-reference a proceedings.

Each of these is explained in more detail later.

This is the authoritative statement on the proper use of cross-referencing within a .bib file. The further comments I have to offer here are a non-authoritative gloss, but do accurately reflect the assumptions I made in writing the .bst code for the

law.dtx file.

article: A cross-reference from one article entry to another may be used for special issues of a journal, such as those dedicated to a single topic. The referenced entry should include all details relevant to the issue as a whole, including volume, journal and booktitle (this last for the name or topic description of a special issue), and type (this defaults to “Special issue”).

book: This cross-reference is not recognized by the law.dtx style. It could logically be used for a series, but this is little trouble to type into the original @book entry itself, and a series is not something that should appear separately on the reference list.

inbook: This is used for cross-referencing a chapter or other subdivision within a work by a single author to that work.

incollection: This is used for cross-referencing a work by multiple authors. The typeface conventions used in the Blue Book style differ for inbook and incollection citations, as defined here, so this distinction should be honored in building a database.

inproceedings: This is used only cross-referencing articles appearing to a proceedings volume to that volume.