Guidelines for writing bibliography style templates
***************************************************

Syntax
======

#. Comments begin with ``#``, following the Python convention.

#. Each template file can have as many as five sections. None of the sections are required to be in the file, but any definitions in the file must be placed inside a section header so that the code knows how to deal with the definition. The four possible section headers are: TEMPLATES, SPECIAL-TEMPLATES, OPTIONS, VARIABLES, DEFINITIONS. And note that a section header is always placed by itself on a line and has a colon appended to it, as in ``TEMPLATES:``.

#. The ``TEMPLATES`` section of the file contains template definitions for formatting references. The ``SPECIAL-TEMPLATES`` section contains definitions for creating variables within each database entry. The ``OPTIONS`` section contains definitions for various keywords that can be used to modify program behavior. The ``VARIABLES`` section contains user definitions for new variables to be made available. The difference between these definitions and those in ``SPECIAL-TEMPLATES`` is that the ones provided in the ``VARIABLES`` section are in-line Python code, whereas the former use templates. Finally, the ``DEFINITIONS`` section of the file contains Python-executable code that can then make functionality available in the form of template variables. (An example is provided in the *Python API* section below.

#. All variable definitions within the TEMPLATES, SPECIAL-TEMPLATES, and OPTIONS sections use the variable name followed by whitespace, an equals sign, more whitespace, and then the definition itself. Thus the [whitespace+=+whitespace] expression is the delimiter between variable and definition, and is required syntax.

#. An ellipsis ``...`` at the end of a line indicates a line continuation. All whitespace following the ellipsis, and all whitespace preceding text on the next line, is removed from the resulting connected text.

#. An ellipsis in the middle of a line indicates an "implicit loop". For details, see the *Examples for namelist formatting* section below.

#. Inside the ``TEMPLATES`` section, all of the variable definitions are intended to map to a database entrytype name. For example::

      article = <au>, ``<title>,'' <journal>, <volume>, <startpage>--<endpage> (<year>).

   Here the ``article`` entrytype will be typeset so that the list of authors (``<au>``) is followed by the article title in double quotes, the journal name in standard font (i.e. not italics), the volume number, the page range, and the year.

#. A variable is indicated by angle brackets, as ``<var>`` and represents the contents of a field found within the bibliography database. Thus, when typesetting the bibliography, Bibulous will replace the variable ``<authorlist>`` with the string stored in the ``authorlist`` field of the current entry being formatted. An example list of typical variables one might use is:

      ``<au>``, ``<booktitle>``, ``<chapter>``, ``<edition>``, ``<ed>``, ``<eid>``, ``<endpage>``, ``<institution>``, ``<journal>``, ``<nationality>``, ``<note>``, ``<number>``, ``<organization>``, ``<publisher>``, ``<school>``, ``<series>``, ``<startpage>``, ``<title>``, ``<version>``, ``<volume>``, ``<year>``.

   This list is actually freely extensible. A user can add any additional variables needed, so that if a ``video`` field is used in a ``.bib`` database file, then this can be used within a formatted reference simply by placing ``<video>`` into the template wherever the information needs to be inserted.

#. Any variable placed within square brackets ``[]`` indicate that it is an optional variable --- it is not required that the database have that entry. While required entries that are not defined in the BibTeX database file (.bib file) are replaced with '???', and undefined optional variables are simply skipped. If a ``|`` is present within the square brackets, it indicates an "elseif" clause. That is, if the template is ``[<var1>|<var2> and <var3>]``, then the code will look for ``var1`` as a field within the current database entry being formatted. If it does not find the entry, then it will try the next block, where it finds the two variables ``var2`` and ``var3``. If both are defined, then the original template ``[<var1>|<var2> and <var3>]`` is replaced with ``<var2> and <var3>`` (i.e. removing the square brackets) and proceeds to replace the two variables with their corresponding fields. If either one of ``var2`` or ``var3`` is undefined in the entry, then the entire optional (bracketed) portion of the template is skipped.

#. If the ``|`` symbol is used to create an empty last cell, as in ``[<var1>|<var2>|]``, this indicates that while the individual cells within the optional block are themselves optional, it is required to have at least _one_ among the cells to be defined. Thus, ``[<note>|]`` has the same meaning as simply ``<note>`` does.

#. Nesting of ``[]`` brackets is allowed, but the syntax becomes computationally expensive to parse, so that these structures should be used sparingly.

#. Users that need to use ``[``, ``]``, ``#``, ``<``, ``>``, or ``|`` symbols as formatting elements within the reference list can implement them using some custom LaTeX-markup commands: ``{\makeopenbracket}``, ``{\makeclosebracket}``, ``{\makehashsign}``, ``{\makelessthan}``, ``{\makegreaterthan}``, ``{\makeverticalbar}``, or ``{\makeellipsis}``. Note that the curly brackets used in each case are required.

#. In the ``TEMPLATES`` section of the file, if an entrytype format definition contains only another entrytype name on the right hand side of the ``=``, i.e.::

       inbook = incollection

   then this means that the existing ``incollection`` template should be copied for use with ``inbook`` entrytypes.

#. Note that several fields are defined by default which are *not* directly from the bibliography database. These are ``au``, ``authorlist``, ``citekey``, ``citenum``, ``ed``, ``editorlist``, ``endpage``, and ``startpage``. These fields are derived from the original database file, but have been reformatted. See the *Default Fields* section below.

#. Although the entrytype template definitions listed below are in alphabetical order, that can be put in any desired order within the file. The exception to this rule is that if a definition consists of, for example::

      inbook = incollection

   then the ``incollection`` template must already be defined. Also note that two entrytype names are special and so cannot be used on the left hand side of the equals sign here: ``comment`` and ``preamble``.

#. A user wanting a localized form of quotation should use ``\enquote{<title>}`` rather than ````<title>''``, and add ``\usepackage{csquotes}`` to the preamble of the LaTeX document.

#. In the ``OPTIONS`` section of the file are the formatting options. None of these definitions are required. The complete list is given in the *Options keywords* section below, together with explanations of each.

#. The ``SPECIAL-TEMPLATES`` section is where users can define their own fields that get generated for every database entry evaluated. For example, the variable definition::

      group = [<organization>|<institution>|<corporation>|]

   in the ``SPECIAL-TEMPLATES`` section will create a ``group`` field that can be used as the variable ``<group>`` within the regular ``TEMPLATES`` section of the file. This effectively allows users to create a shortcut. Where they could write out ``[<organization>|<institution>|<corporation>|]`` inside each template that needs this structure, the special template definition allows them to replace each instance with a simple ``<group>``.

   Another example usage would be the following::

      author = [<author-en>|<author-jp>|]

   where the ``author`` field is actually redefined to include not only the *existing* author field, but also the fields ``author-en`` or ``author-jp``. That is, if the ``author`` field is missing in the database entry (the field matching the thing on the left hand side), the code next searches for the ``author-en`` field. If it finds it, then it will create an ``author`` field that contains a copy of the ``author-en``'s field's contents. If the ``author-en`` is also missing, the code next searches for ``author-jp`` and uses that fields contents to create the missing ``author`` field. This is a convenient way of grouping different variable names in order to simplify templates.

#. The order in which any definitions are placed within the special templates is important. For example, if a user has ``au = <authorlist.format_authorlist()>`` and then below that defines ``authorlist = <author.to_namelist()>``, then the code will issue an error stating that ``authorlist`` is not defined when attempting to create the ``au`` variable. Since the definition for ``au`` assumes the presence of the ``authorlist`` variable, the latter definition must be placed above it.

Default Fields
==============

A complete list of the existing default fields is:::

    au
    authorlist
    citealnum
    citealpha
    citekey
    citenum
    ed
    editorlist
    sortkey
    sortnum

Each of these default fields are defined as "special templates". If a user defines a special template with the same name as one of the above, then the default is overwritten with the user's version. The definitions of the default special templates are:::

    authorlist = <author.to_namelist()>
    editorlist = <editor.to_namelist()>
    citealnum = ?
    citelabel = <citenum>
    sortkey = <citenum>
    au = <authorlist.format_authorlist()>
    ed = <editorlist.format_editorlist()>

Note that the ordering of definitions is important (that is, if ``citelabel`` uses ``authorlist`` in its definition, then the latter has to appear before it in the list of special templates, so that it is defined by the time that ``citelabel`` needs to be defined). The following summarizes what these definitions are used for.

Also, in addition to these default fields, there are also four special variables defined, ``citealpha``, ``citealnum``, ``citenum``, and ``sortnum``. These can be accessed as ``<citealpha>``, ``<citealnum>``, ``<citenum>``, and ``<sortnum>`` within any template. The first, ``<citealpha>``, is designed to reproduce the citation label style used by BibTeX's ``alpha`` style. For example, ``GKP94`` is the ``alpha``--style citation label for the book *Concrete Mathematics*, 2nd Edition, by Ronald L. Graham, Donald E. Knuth, and Oren Patashnik (1994). The second variable ``<citealnum>`` is a variant of this that creates a citation label from the first letter of the author's last name, followed by an integer indicating its place in the sorted bibliography. Thus the book by Graham *et al.* would have the label "G2" if preceded by, say, *Introduction to Fourier Optics* by Joseph W. Goodman (1968), since the latter, being published earlier, would be placed earlier in the sorted list. ``<citenum>`` is simply the numerical order in which the reference was cited in the text (starting at 1 with the first citation). ``<sortnum>`` is the numerical order in which the citation appears in the reference list. If the reference list is sorted alphabetically, for example, then ``sortnum`` will generally be different from ``citenum``.

**au** is the string representing the formatted list of author names. In the default definition shown above, the name list is a standard form, and so simply uses the ``.format_authorlist()`` operator. Generally, this operator creates name lists that have the form "firstauthor" for only one author, "firstauthor and secondauthor" if only two authors, "firstauthor, secondauthor, ..., and lastauthor" if more than two authors but less than the maximum, and "firstauthor, secondauthor, ..., minauthor, et al." if more than the maximum allowed number of authors. Which author in the list is "minauthor" is defined using the ``minauthors`` option keyword. The maximum number of allowed authors is set by the ``maxauthors`` option keyword.

**authorlist** creates a list of dictionaries (one dictionary for each author name found within the database entry's ``author`` field). Each name dictionary has keys "first", "middle", "prefix", "last", and "suffix", where each of these keys is optional except for "last". Thus, a user can access the first and last name of the first author in the database entry using ``<authorlist.0.first> <authorlist.0.last>``. To access the middle name(s) of the second author, use ``<authorlist.1.middle>``.

**citealnum** is a field generated by taking the first letter of the first author's last name, and appending to it the citation sort order number within all entries sharing that prefix. Thus "Bugs Bunny" would have a ``citealnum`` of "B" followed by its order number. If "Yogi Bear" were another first-author name in the list, then "Yogi Bear" would receive ``citealnum = B1`` while "Bugs Bunny" would receive ``citealnum = B2``.

**citealpha** is a field generated according to BibTeX's classic "alpha" style. That is, it takes the first three letters of the author's last name if there is only one author. If multiple authors, it takes the initials of the author last names, for up to the first three authors. If no author is present, then it looks for the first three letters of the ``organization`` field. Finally, the three-letter alphabetical label is followed by the last two digits of the publication year. Thus, any user wishing to use BibTeX's classic ``alpha`` style for citation labels can use ``citelabel = <citealpha>`` in the SPECIAL-TEMPLATES section of the file.

**citelabel** is the thing that appears at the front of the formatted reference, and is identical to the citation label used in the manuscript to point to the item in the reference list. In technical journal articles, this is typically just a number, as in the default definition ``<citenum>``. The number used here for the label indicates the order in which the entry was cited.

**ed** follows the same basic structure as ``au``, but uses the ``maxeditors`` and ``mineditors`` keywords.

**editorlist** behaves exactly as ``authorlist`` but derives its list of names from the database entry's ``editor`` field rather than ``author`` field.

**sortkey** is the string used to sort the entry within the reference list. For technical journal articles, what is generally wanted is just the citation order, as indicated by the ``<citenum>`` variable.

Operators
---------

One can use the "dot" operator inside a variable name, as in ``<authorname.0.last.initial()>'' to perform any one of five functions: a explicit numerical index (the ``0`` shown here, listed as the ``.#`` operator below), an implicit numerical index (using ``.n`` or ``.N``, for which see section *Examples for namelist formatting* below for details), a range index (listed as the ``##:##`` operator below), a dictionary lookup (the ``last`` used here), or the application of an operator (in this case, the ``.initial()`` operator which is used to reduce a name to its initial). A numerical index must apply to a list-type of variable, and a key index must apply to a dict-type of variable (i.e. a dictionary). Note that, due to limitations of the parser, it is not allowed for ``<.>`` angle-bracketed variables to be placed within other angle-bracketed variables. Thus, function arguments take variable names with their angle brackets removed.

The complete list of operators available is:::

    .#
    .##:##
    .compress()
    .format_authorlist()
    .format_editorlist()
    .frenchinitial()
    .if_len_equals(var1,number,var2,var3)
    ..    .if_len_less_than(var1,number,var2,var3)
    ..    .if_len_more_than(var1,number,var2,var3)
    .if_str_equal(test_str,then_var,else_var)
    .if_singular(var1,var2,var3)
    .initial()
	.len()
    .lower()
    .monthabbrev()
    .monthname()
    .n
    .N
    .null()
    .ordinal()
    .purify()
    .replace(old,new)
    .sentence_case()
    .tie()
    .to_namelist()
    .uniquify(arg)
    .upper()
    .zfill(num)

The function of each operator is summarized below.

**.#** An explicit numerical index, i.e., select the #th element of the operand.

**.##:##** A range index, i.e., select the ##th through ##th elements of the operand. For example, for a bibliography entry whose database file contains ``title = {Impossibility}``, a template variable of the form ``<title.0:2>`` will return ``Imp``, and ``<title.3:5>`` will return ``oss``. The first character of the operand thus has an index ``0``. Indexing from the end of the operand can be done using negative number indices. For example, the last character of the operand can be indexed by ``-1``, and the third to last by ``-3``, so that in the example above, ``<title.-3:-1>`` will return ``ity``.

**.compress()** removes any whitespace found within the string. This is useful for generating namelists where the format requires "tight" spacing. An example would be "RMA Azzam", where the three initials are grouped together without spacing. And example template for generating this type of name would be::

    <authorlist.0.first><authorlist.0.middle.initial().compress()> <authorlist.0.last>

Without the ``.compress()`` operator, the name would come out as "RM A Azzam", since the two middle name initials "M" and "A" are spaced apart from one another by default.

**.format_authorlist()** operates on a list of dictionaries type of variable (a namelist), and uses the keyword-based default formatting scheme to create a formatted string of names. The complete list keywords that it looks for is: ``etal_message``, ``maxauthors``, ``minauthors``, ``namelist_format``, ``period_after_initial``, ``terse_inits``, ``use_firstname_initials``, ``use_name_ties``. The default formatter, while fast, is not very flexible, so that users looking for more customizability will want to make use of Bibulous' implicit-index and implicit-loop based definitions. See the *Example definitions for namelist formatting* section below.

**.format_editorlist()** operates on a list of dictionaries type of variable (a namelist), and uses the keyword-based default formatting scheme to create a formatted string of names.  The complete list keywords that looks for is: ``etal_message``, ``maxeditors``, ``mineditors``, ``namelist_format``, ``period_after_initial``, ``terse_inits``, ``use_firstname_initials``, ``use_name_ties``. (The difference with the ``.format_authorlist()`` operator is that it uses ``maxeditors`` and ``mineditors`` rather than ``maxauthors`` and ``minauthors``) The default formatter, while fast, is not very flexible, so that users looking for more customizability will want to make use of Bibulous' implicit-index and implicit-loop based definitions. See the *Example definitions for namelist formatting* section below.

**.frenchinitial()** is an alternative form of the ``.initial()`` operator that has slightly different behavior. If a name begins with one of the digraphs "Ch", "Gn", "Ll", "Ph", "Ss", or "Th", then the initial will truncate the name after the digraph instead of after the first letter.

**.if_str_equal(test_str,then_var,else_var)** inserts ``then_var`` if the string to be operated on is equal to ``test_str``, else it inserts the string ``else_var``.

**.if_singular(var,res1,res2)** inserts ``res1`` if ``var`` has only one element, but ``res2`` if ``var`` has more than one element. Here ``var`` is assumed to be a list-type of variable. An example usage is the following: ``[<ed.if_singular(editorlist, option.edmsg1), option.edmsg2)>, ]``. This form appends the contents of the ``edmsg1`` option variable to the end of the ``ed`` variable if the ``editorlist`` variable contains only one element (is singular). If ``editorlist`` has more than one element, then the contents of the ``edmsg2`` variable is appended instead. (This could potentially be a null string.)

**.if_num_equals(var,number,res1,res2)** appends ``res1`` if ``var`` equals ``number``, but otherwise appends ``var2``.

.. **.if_less_than(var,number,res1,res2)** appends ``res1`` if ``var`` is less than ``number``, but otherwise appends ``res2``.

.. **.if_more_than(var,number,res1,res2)** appends ``res1`` if ``var`` is more than ``number``, but otherwise appends ``res2``.

**.initial()** will truncate the string to its first letter. Note that if a name begins with a LaTeX markup character, such as ``{\'E}``, then the operator will convert the input string to its best attempt at a Unicode-equivalent (without character markup) prior to performing the truncation. Thus, applying the ``.initial()`` operator to the name ``{\v{Z}}ukauskas`` will produce the initialized form "Ž".

**.len()** returns the number of elements in a list variable (to the left of the operator dot).

**.lower()** reduces all letters in its argument to lower case. If any LaTeX markup letters exist in the argument, then they will be converted to Unicode equivalents first before applying the operator. Thus, if the field ``au`` contains ``{\AA}`` then the operator will first convert this to the letter Å and then reduce it to the lower case å.

**.monthabbrev()** assumes that the input field is a number from 1 to 12, and converts the numerical input into the abbreviated month according to the user's current locale. If the system cannot determine the user's locale, the operator will default to using the American English locale, which replaces the numerical field operated on with one of "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", or "Dec" according to the field's value. Thus, if the bibliography database entry has a field ``month = 11``, and the template has the form ``<month.monthabbrev()>``, then the template will be replaced with "Nov" for the default locale. For users with locale "Japan", this same operator will return "11月".

**.monthname()** behaves much like ``.monthabbrev()`` but rather than using an abbreviated form for the month's name, it uses the full form. Thus if the bibliography database entry has a field ``month = 3``, and the template has the form ``<month.monthname()>``, then the template variable will be replaced with "March" for the default locale. For users with locale "Norway", this same operator will return "Mars".

**.n** See the *Examples for namelist formatting* below

**.N** [Not currently supported]

**.null()** returns an undefined variable, forcing the string to be evaluated as "undefined".

**.ordinal()** creates an "ordinal" from a numerical field. Thus, if the field operated on is "1", "2", "3", or "4", then the operator will replace the template with "1st", "2nd", "3rd" or "4th". Any number above 4 simply has "th" appended to the end of it. Currently Bibulous does not support non-English locales for this function. (Anyone having suggestions of how this may be implemented without too much fuss should contact us!)

**.purify()** attempts to convert its argument into a string without LaTeX-markup for foreign characters. Thus, if the entry contains ``title = {{\AA}land}`` then a template variable of the form ``<title.purify()>`` will produce the result ``Åland``. This can be useful when having to use ``substr_replace()`` and other functions where the markup may cause matching problems.

**.replace(old,new)** will replace the substring ``old`` with ``new`` wherever it finds ``old`` within the string it is applied to. For example, if a user wants to make the name "J. W. Tukey" bold everywhere it appears in a reference, then ``.replace(J. W. Tukey,\textbf{J. W. Tukey})`` will work. Note that whitespace is preserved here. Thus, ``.replace(J. W. Tukey, \textbf{J. W. Tukey})`` will add a space in front of ``\textbf{J. W. Tukey}``. Also, Bibulous will not allow the use of ``<``, ``>``, ``|``, or ``)`` characters in the two arguments of the operator.

**.sentence_case()** reduces the lower case any characters in the field, except for the initial letter and any letters protected within a pair of curly braces. For example, if the database entry has ``title = {Understanding Bohmian mechanics}`` and the template has the form ``<title.sentence_case()>``, then the template variable will be replaced with "Understanding bohmian mechanics". However, if the entry has ``title = {Understanding {B}ohmian mechanics}``, the result will be "Understanding {B}ohmian mechanics".

**.tie()** replaces any spaces with an unbreakable space. Thus, "R. M. A." becomes "R.~M.~A.". An example use of this operator would be the following template:::

    authorname = [<authorlist.n.first.initial()>.~][<authorlist.n.middle.initial().tie()>. ]...
                 [<authorlist.n.prefix>~]<authorlist.n.last>[, <authorlist.n.suffix>]

**.to_namelist()** parses the field (assumed to be a BibTeX-format "and"-delimited list of names) into a Bibulous-format namelist (i.e. a list of dictionaries).

**.uniquify(arg)** appends a letter character (if arg=``a``) or a number (if arg=``1``) to the end of the field to make it unique relative to the same field in every other cited entry. For example, if two authors have the name "Smith" and published a paper in the year 2000, then the template ``citelabel = <authorlist.0.last><year>`` will produce the same citation label for both entries. Thus, we can rename this as ``citetemp = <authorlist.0.last><year>`` and then define ``citelabel = <citetemp.uniquify(a)>`` to generate unique labels. For this example, the first citation will have the label "Smith2000" and the second "Smith2000a". If a third citation shares the same name and year, then it will be given the unique label "Smith2000b", and so on.

**.upper()** raises all letters in its argument to upper case. If any LaTeX markup letters exist in the argument, then they will be converted to Unicode equivalents first before applying the operator. Thus, if the field ``au`` contains ``{\aa}`` then the operator will first convert this to the letter å and then raise it to the upper case Å.

**.zfill(num)** appends zeros to the front of its argument, where ``num`` indicates the desired final length of the string. For example, if the field ``vol`` contains the number ``11``, then calling ``<vol.zfill(3)>`` produces the result ``011``.

Options keywords
================

A complete list of existing options keywords, together with their default definitions, is:::

    allow_scripts = False
    autocomplete_doi = True
    backrefs = False
    backrefstyle = none
    bibitemsep = None
    case_sensitive_field_names = False
    edmsg1 = , ed.
    edmsg2 = , eds
    etal_message = , \\textit{et al.}
    maxauthors = 9
    maxeditors = 5
    minauthors = 9
    mineditors = 5
    name_separator = and
    namelist_format = first_name_first
    period_after_initial = True
    procspie_as_journal = False
    sort_case = True
    sort_order = forward
    terse_inits = False
    undefstr = ???
    use_abbrevs = True
    use_citeextract = True
    use_firstname_initials = True
    use_name_ties = False

Each of the keywords is summarized below.

**allow_scripts** [default value: False] tells Bibulous whether to allow the evaluation of Python code in the VARIABLES and DEFINITIONS sections of ``.bst`` files. It is important for users to realize that evaluating external code in this way is a security risk, and so they should not set ``allow_scripts = True`` when inserting code that they do not trust. However, as an additional security precaution, Bibulous prevents most security-sensitive operations from being used within its Python API.

**autocomplete_doi** [default value: True] tells Bibulous whether to add ``http://dx.doi.org/`` to the front of the ``doi`` field if the front is missing. This allows the ``<doi>`` variable to be used as a complete URL, even when the prefix is missing in the database field.

**backrefs** [default value: False] THIS KEYWORD IS NOT YET IMPLEMENTED

**backrefstyle** [default value: none] THIS KEYWORD IS NOT YET IMPLEMENTED

**bibitemsep** [default value: None] provides users a means to change the amount of vertical separation that LaTeX sets between entries in the reference list. For example, users wanting a more compact list can define ``bibitemsep = 0pt``.

**case_sensitive_field_names** [default value: False] tells Bibulous whether to consider, for example, a field named "Author" as being distinct from "author".

**edmsg1** [default value: , ed.] provides a string to use after a list of editor names, for the case when only one editor is present.

**edmsg2** [default value: , eds] provides a string to use after a list of editor names, for the case when multiple editors are present.

**etal_message** [default value: , \\textit{et al.}] provides a string to use after a truncated namelist (for example, when the number of authors exceeds the value given by the ``maxauthors`` keyword).

**maxauthors** [default value: 9] provides the maximum number of allowed names in the formatted list of authors. If the number of names is more than this, then the list of names is truncated to ``minauthors`` and the ``etal_message`` is appended to the result. (This keyword is only used within the ``.format_namelist()`` operator.)

**maxeditors** [default value: 5] provides the maximum number of allowed names in the formatted list of editors. If the number of names is more than this, then the list of names is truncated to ``mineditors`` and the ``etal_message`` is appended to the result. (This keyword is only used within the ``.format_namelist()`` operator.)

**minauthors** [default value: 9] provides the minimum number of author names to use when truncating an overlength author name list. (This keyword is only used within the ``.format_namelist()`` operator.)

**mineditors** [default value: 5] provides the minimum number of editor names to use when truncating an overlength author name list. (This keyword is only used within the ``.format_namelist()`` operator.)

**name_separator** [default value: and] informs Bibulous how to separate the individual names in a BibTeX-format field of names. For example, with a BibTeX-format field of ``Bugs Bunny and Porky Pig``, using the separator ``and`` allows Bibulous to determine that there are two separate people, ``Bugs Bunny`` and ``Porky Pig``. If the option keyword has an empty field (*i.e.* it is written as ``name_separator =``, with nothing on the right hand side of the equals) then it is assumed that the intended separator is a space character. This is useful for alphabets (such as Chinese and Japanese) that often work without spaces.

**namelist_format** [default value: first_name_first, allowed values: {first_name_first, last_name_first}] defines how the formatted list of names should appear. If ``namelist_format = first_name_first`` then the individual names will appear in the order "firstname middle prefix last, suffix". If ``namelist_format = last_name_first`` then the individual names will appear in the order "prefix last, firstname middle, suffix". (This keyword is only used within the ``.format_namelist()`` operator.)

**period_after_initial** [default value: True] tells the ``.format_namelist()`` operator whether to place a period after each initial of an individual's name. Thus, if ``period_after_initial = True``, a name will appear as "R. M. A. Azzam", but if ``False`` will appear as "R M A Azzam". (This keyword is only used within the ``.format_namelist()`` operator.)

**procspie_as_journal** [default value: False] The "Proceedings of SPIE" are treated as special by the journals of the Optical Society of America. That is, they format these proceedings (and only these) in the same way that they do journal articles. Thus, a special keyword is required to allow this behavior.

**sort_case** [default value: True] informs Bibulous whether or not to use case-sensitive sorting of reference keys.

**sort_order** [default value: forward] whether to sort in increasing order (``forward``) or decreasing order (``reverse``).

**terse_inits** [default value: False] tells the ``.format_namelist()`` operator whether to compress together the initials of an individual's name. Thus, if ``terse_inits = True``, a name will appear as "RMA Azzam", but if ``False`` will appear as "R. M. A. Azzam". (This keyword is only used within the ``.format_namelist()`` operator.)

**undefstr** [default value: ???] informs Bibulous what kind of warning message to print when a required field is missing in the database entry.

**use_abbrevs** [default value: True] tells Bibulous whether or not to use the abbreviations defined in the bibliography database. (Used for debugging.)

**use_citeextract** [default value: True] tells Bibulous whether to perform "citation extraction", which creates a small database of only the cited items from among the complete database provided in the ``.aux`` file.

**use_firstname_initials** [default value: True] Whether or not to initialize the first names of authors in the formatted authors list. (This keyword is only used within the ``.format_namelist()`` operator.)

**use_name_ties** [default value: False] Whether or not to replace spaces with unbreakable spaces (i.e. "R. M. A. Azzam" or "R.~M.~A. Azzam") inside names in the name list. (This keyword is only used within the ``.format_namelist()`` operator.)


Implicit loops and examples for namelist formatting
===================================================

The following code provides an example usage of implicit indexing within an implicit loop structure:::

    authorlist = <author.to_namelist()>
    editorlist = <editor.to_namelist()>
    authorname.n = [<authorlist.n.first.initial()>. ][<authorlist.n.middle.initial()>. ]...
                   [<authorlist.n.prefix> ]<authorlist.n.last>[, <authorlist.n.suffix>]
    au = <authorname.0>, ...,{ and }<authorname.9>
    editorname.n = [<editorlist.n.first.initial()>. ][<editorlist.n.middle.initial()>. ]...
                   [<editorlist.n.prefix> ]<editorlist.n.last>[, <editorlist.n.suffix>]
    ed = <editorname.0>, ...,{ and }<editorname.2>

Here the ``authorlist`` and ``editorlist`` definitions create namelist variables from the ``author`` and ``editor`` fields in the entry (if they exist). Next, the implicitly-indexed ``authorname.n`` cannot operate except within an implicit loop, and so we should describe that first. It is easier to describe the functionality of the ``ed`` template than the ``au`` one, as it has a smaller number of allowed names. The ``ed`` template has the definition::

    <editorname.0>, ...,{ and }<editorname.2>

which simplifies to ``<editorname.0>`` when there is only one editor in the database entry, and::

    <editorname.0> and <editorname.1>

when there are only two. Here the separator `` and `` comes from the ``{ and }`` placed at the right hand side of the implicit loop. For three editors, the implicit loop expands the template to::

    <editorname.0>, <editorname.1>, and <editorname.2>

where this time the comma alone is used as the first delimiter, as it is outside the enclosed braces. For the final element, both the comma and the ``{ and }`` at the right hand side of the implicit loop are used as the final delimiter. Since the template does not specify the format for more than three editor names, the code builds an *et al.* construction when there more than this number of names, so that the result becomes::

    <editorname.0>, <editorname.1>, <editorname.2>, \textit{et al.}

where the form of the string ``\textit{, et. al}`` is specified by the ``etal_message`` keyword option.

Thus, the implicit loop has filled out a unique template based on the number of editors it finds within the database entry. The next step is to use the implicitly-indexed ``editorname`` to complete building out the template. The latter template is defined as::

    editorname.n = [<editorlist.n.first.initial()>. ][<editorlist.n.middle.initial()>. ]...
                   [<editorlist.n.prefix> ]<editorlist.n.last>[, <editorlist.n.suffix>]

so that a template variable of the form ``<editorname.0>'' is replaced with::

    [<editorlist.0.first.initial()>. ][<editorlist.0.middle.initial()>. ]...
    [<editorlist.0.prefix> ]<editorlist.0.last>[, <editorlist.0.suffix>]

That is, the implicit index ``.n`` is everywhere replaced with the explicit index ``0``. For the case of a database entry containing two editor names, the final template will thus have the form::

    [<editorlist.0.first.initial()>. ][<editorlist.0.middle.initial()>. ]...
    [<editorlist.0.prefix> ]<editorlist.0.last>[, <editorlist.0.suffix>] and ...
    [<editorlist.1.first.initial()>. ][<editorlist.1.middle.initial()>. ]...
    [<editorlist.1.prefix> ]<editorlist.1.last>[, <editorlist.1.suffix>]

With this template now complete, the code begins to evaluate the entry and replace the individual variables with their corresponding database fields.

Python API
==========

Bibulous also provides to users an extensible Python interface allowing users to directly manipulate Bibulous' internal data structures. These use the ``VARIABLES`` and ``DEFINITIONS`` sections of the file, as shown below. For the ```VARIABLES`` section, a variable name is defined (the first example below defines the variable ``year_bce``, while the second example below defines ``pagerange``). On the right hand side of the definition, however, is a Python function call. This is different from the other sections of the BST file, which use template syntax. Any variable defined in this way within the ``VARIABLES`` section can then be accessed as a template variable (i.e. ``<year_bce>``) within the ``TEMPLATES`` section of the file. Two example uses are shown below.

To allow Bibulous to read the ``VARIABLES`` and ``DEFINITIONS`` sections of the file, users must set the option keyword ``allow_scripts`` to True.

**First example: a custom yearstyle**. For a bibliography containing works from authors dating from before year 0, a common approach is to append "BC" to the year number, and for positive-numbered years, appending "AD". More recently, the convention has been to append "BCE" and "CE" rather than "BC" and "AD". The example defines an option keyword ``yearstyle`` that allows users to switch between one style (BC/AD) and the other (BCE/CE). This keyword is accessed by placing ``options`` as an argument to the ``format_yearstyle()`` function defining the variable ``year_bce``. Inside the function, it can then check the options dictionary for the ``yearstyle`` keyword and determine which convention to use.

The ``format_yearstyle()`` function itself is straightforward. It first checks whether the entry has a ``year`` field. If not, then it returns ``None``, indicating that the function's result is undefined. If it finds a ``year`` field, then it checks to see whether it corresponds to an integer. If not, then it returns the field as-is. (Perhaps a user defines his ``year`` fields as ``45 BCE`` with the BCE already written out inside the field?) If it finds an integer value, then it determines which style to use (BC/AD or BCE/CE). If the year number is negative then it appends "BC" or "BCE to the end. If the year number is positive then it appends "AD" or "CE to the end, depending on the convention chosen.

Example::

    OPTIONS:
    allow_scripts = True
    yearstyle = BCE/CE

    VARIABLES:
    year_bce = format_yearstyle(entry, options)

    DEFINITIONS:
    ## NOTE! Only Unix-style line endings are allowed here.
    def format_yearstyle(entry, options):
        '''
        Append "BC or "AD" to "year", depending on whether the year is positive or negative.
        If the option "yearstyle" is set to "BCE/CE", then use "BCE" and "CE" instead of "BC"
        and "AD".
        '''

        if ('year' not in entry):
            return(options['undefstr'])

        ## First check that the year string is an integer. If not an integer, then just return
        ## the field itself.
        if not str_is_integer(entry['year']):
            return(entry['year'])

        yearnum = int(entry['year'])

        if (yearnum < 0):
            if (options['yearstyle'] == 'BCE/CE'):
                suffix = 'BCE'
            else:
                suffix = 'BC'
            ## The "[1:]" here removes the minus sign.
            result = str(yearnum)[1:] + ' ' + suffix
        elif (yearnum == 0):
            result = str(yearnum)
        else:
            if (options['yearstyle'] == 'BCE/CE'):
                suffix = 'CE'
            else:
                suffix = 'AD'
            result = str(yearnum) + ' ' + suffix

        return(result)

**Second example: a custom pagestyle**. For a bibliography containing works from magazines, it is not uncommon to find articles with large gaps in page numbers. Here is an example bibliography database entry::

    @article{stewart,
    title = {Interview with Walter Stewart},
    author = {Doug Stewart},
    journal = {Omni},
    year = {1989},
    volume = {11},
    number = {5},
    pages = {64--66, 87--92, 94}
    }

where we can see that the article was broken into three sections in order to fit the editors' formatting requirements. Many bibliography styles require a starting and ending page, but these are misleading when the article is broken across pages in this way. Thus, a user may want to have the option that if a comma is found within the ``pages`` field of an entry then it should be displayed as-is. If no comma is found, then it simply returns the standard startpage--endpage pair.

To make this work, first the option ``allow_scripts`` must be set to true. Next, a new ``pagerange`` variable is defined, so that it can be accessed in the ``TEMPLATES`` section of the file as ``<pagerange>``. The variable is defined as the return value of the function ``format_pagerange()`` given in the ``DEFINITIONS`` section. The defined function first checks to see if there is a ``pages`` field defined in the entry. If not, then it returns None, so that the ``pagerange`` variable will also be undefined. If it finds the ``pages`` field, it looks to see if there is a comma present. If so, it returns the field as-is. If not, it looks for the ``endpage`` variable (generated by default by Bibulous from the ``pages`` field). If present, then the function returns a startpage--endpage pair. If ``endpage`` is not present, then it returns only the ``startpage`` variable.

Example::

    OPTIONS:
    allow_scripts = True

    VARIABLES:
    pagerange = format_pagerange(entry, options)

    DEFINITIONS:
    def format_pagerange(entry, options):
        '''
        If the "pages" field is comma-delimited, then return the pages field as-is. Otherwise
        return the standard startpage--endpage range.
        '''

        if not ('pages' in entry):
            return(None)
        elif (',' in entry['pages']):
            return(entry['pages'])
        elif ('endpage' in entry):
            return(entry['startpage']--entry['endpage'])
        else:
            return(entry['startpage'])
