% Generated by Sphinx.
\def\sphinxdocclass{report}
\documentclass[letterpaper,10pt,english]{sphinxmanual}
\usepackage[utf8]{inputenc}
\DeclareUnicodeCharacter{00A0}{\nobreakspace}
\usepackage{cmap}
\usepackage[T1]{fontenc}
\usepackage{babel}
\usepackage{times}
\usepackage[Bjarne]{fncychap}
\usepackage{longtable}
\usepackage{sphinx}
\usepackage{multirow}
\DeclareUnicodeCharacter{672C}{X}


\title{Bibulous Documentation}
\date{May 14, 2014}
\release{1.2}
\author{Bibulous developers}
\newcommand{\sphinxlogo}{\includegraphics{banner.pdf}\par}
\renewcommand{\releasename}{Release}
\makeindex

\makeatletter
\def\PYG@reset{\let\PYG@it=\relax \let\PYG@bf=\relax%
    \let\PYG@ul=\relax \let\PYG@tc=\relax%
    \let\PYG@bc=\relax \let\PYG@ff=\relax}
\def\PYG@tok#1{\csname PYG@tok@#1\endcsname}
\def\PYG@toks#1+{\ifx\relax#1\empty\else%
    \PYG@tok{#1}\expandafter\PYG@toks\fi}
\def\PYG@do#1{\PYG@bc{\PYG@tc{\PYG@ul{%
    \PYG@it{\PYG@bf{\PYG@ff{#1}}}}}}}
\def\PYG#1#2{\PYG@reset\PYG@toks#1+\relax+\PYG@do{#2}}

\expandafter\def\csname PYG@tok@gd\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.63,0.00,0.00}{##1}}}
\expandafter\def\csname PYG@tok@gu\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.50,0.00,0.50}{##1}}}
\expandafter\def\csname PYG@tok@gt\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.25,0.82}{##1}}}
\expandafter\def\csname PYG@tok@gs\endcsname{\let\PYG@bf=\textbf}
\expandafter\def\csname PYG@tok@gr\endcsname{\def\PYG@tc##1{\textcolor[rgb]{1.00,0.00,0.00}{##1}}}
\expandafter\def\csname PYG@tok@cm\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}}
\expandafter\def\csname PYG@tok@vg\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@m\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@mh\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@cs\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}\def\PYG@bc##1{\setlength{\fboxsep}{0pt}\colorbox[rgb]{1.00,0.94,0.94}{\strut ##1}}}
\expandafter\def\csname PYG@tok@ge\endcsname{\let\PYG@it=\textit}
\expandafter\def\csname PYG@tok@vc\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@il\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@go\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.19,0.19,0.19}{##1}}}
\expandafter\def\csname PYG@tok@cp\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@gi\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.63,0.00}{##1}}}
\expandafter\def\csname PYG@tok@gh\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.00,0.50}{##1}}}
\expandafter\def\csname PYG@tok@ni\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.84,0.33,0.22}{##1}}}
\expandafter\def\csname PYG@tok@nl\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.13,0.44}{##1}}}
\expandafter\def\csname PYG@tok@nn\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.05,0.52,0.71}{##1}}}
\expandafter\def\csname PYG@tok@no\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.38,0.68,0.84}{##1}}}
\expandafter\def\csname PYG@tok@na\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@nb\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@nc\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.05,0.52,0.71}{##1}}}
\expandafter\def\csname PYG@tok@nd\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.33,0.33,0.33}{##1}}}
\expandafter\def\csname PYG@tok@ne\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@nf\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.02,0.16,0.49}{##1}}}
\expandafter\def\csname PYG@tok@si\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.44,0.63,0.82}{##1}}}
\expandafter\def\csname PYG@tok@s2\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@vi\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@nt\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.02,0.16,0.45}{##1}}}
\expandafter\def\csname PYG@tok@nv\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@s1\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@gp\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.78,0.36,0.04}{##1}}}
\expandafter\def\csname PYG@tok@sh\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@ow\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@sx\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.78,0.36,0.04}{##1}}}
\expandafter\def\csname PYG@tok@bp\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@c1\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}}
\expandafter\def\csname PYG@tok@kc\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@c\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}}
\expandafter\def\csname PYG@tok@mf\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@err\endcsname{\def\PYG@bc##1{\setlength{\fboxsep}{0pt}\fcolorbox[rgb]{1.00,0.00,0.00}{1,1,1}{\strut ##1}}}
\expandafter\def\csname PYG@tok@kd\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@ss\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.32,0.47,0.09}{##1}}}
\expandafter\def\csname PYG@tok@sr\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.14,0.33,0.53}{##1}}}
\expandafter\def\csname PYG@tok@mo\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@mi\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@kn\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@o\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.40,0.40,0.40}{##1}}}
\expandafter\def\csname PYG@tok@kr\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@s\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@kp\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@w\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.73,0.73}{##1}}}
\expandafter\def\csname PYG@tok@kt\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.56,0.13,0.00}{##1}}}
\expandafter\def\csname PYG@tok@sc\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@sb\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@k\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@se\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@sd\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}

\def\PYGZbs{\char`\\}
\def\PYGZus{\char`\_}
\def\PYGZob{\char`\{}
\def\PYGZcb{\char`\}}
\def\PYGZca{\char`\^}
\def\PYGZam{\char`\&}
\def\PYGZlt{\char`\<}
\def\PYGZgt{\char`\>}
\def\PYGZsh{\char`\#}
\def\PYGZpc{\char`\%}
\def\PYGZdl{\char`\$}
\def\PYGZti{\char`\~}
% for compatibility with earlier versions
\def\PYGZat{@}
\def\PYGZlb{[}
\def\PYGZrb{]}
\makeatother

\begin{document}

\maketitle
\tableofcontents
\phantomsection\label{index::doc}


Contents:


\chapter{Getting started}
\label{getting_started:bibulous-documentation}\label{getting_started:getting-started}\label{getting_started::doc}
For general users, all that is needed is place the main \code{bibulous.py} file into the Python path and to tell LaTeX to use Bibulous rather than BibTeX as their bibliography engine. For users interested in using the auxiliary command \code{bibulous\_authorextract.py}, this file must also be in the Python path, and must be in the same directory as the main file. It is also possible to tell any LaTeX front-end to use Bibulous in place of BibTeX. For Kile, Texmaker, TeXStudio, TeXworks, and Lyx (on Linux) and WinEdt (on Windows), instructions for doing this are given below.

Once you bibliography engine is set to Bibulous, remember that the filename within the \code{\textbackslash{}bibliography\{...\}} command in your \code{*.tex} files must point to a Bibulous-format bibliography style template (\code{.bst} file) and not a BibTeX one.


\section{Kile: replacing BibTeX with Bibulous}
\label{getting_started:kile-replacing-bibtex-with-bibulous}\begin{enumerate}
\item {} 
In Kile, go to the menu bar and select \code{Settings} \textgreater{} \code{Configure Kile}. Select \code{Tools} \textgreater{} \code{Build} and choose \code{BibTeX} from the \code{Select a tool} menu (see the figure). To the right of the menu, after you select \code{BibTeX} you should see ``Choose a configuration for the tool BibTeX''. Below the drop-down menu, select the button ``New'' and type in the name \code{Bibulous} (or whatever you prefer to call your new tool). Below, in the \code{General} tab, type in the location of the \code{bibulous.py} file. And in the \code{Options} field, type \code{\%dir\_base/\%S.aux}.

\end{enumerate}

\includegraphics[width=0.490\linewidth]{screenshot_for_kile_instructions.png}

\includegraphics[width=0.490\linewidth]{screenshot_for_kile_instructions2.png}

That should be it. In case your default setup is different, you can also check the \code{Advanced} tab settings and verify that they are as shown in the second figure. (That is, \code{Source extension} is set to \code{aux}, and \code{Target extension} is set to \code{bbl}.)
\begin{enumerate}
\setcounter{enumi}{1}
\item {} 
Note that the following variables are accessible in Kile's \code{Options} field:

\begin{Verbatim}[commandchars=\\\{\}]
\PYGZpc{}source = filename (i.e. filename with suffix but not path)
\PYGZpc{}S = filename without suffix (and without path)
\PYGZpc{}dir\PYGZus{}base = source file directory (source file's path without the filename)
\PYGZpc{}dir\PYGZus{}target = target file directory (source file's path without the filename)
\end{Verbatim}

\end{enumerate}


\section{Modifying WinEdt5 to replace BibTeX with Bibulous}
\label{getting_started:modifying-winedt5-to-replace-bibtex-with-bibulous}\begin{enumerate}
\item {} 
Go to the menu \code{Options} \textgreater{} \code{Execution Modes}. In the \code{Console Applications} menu on the left hand side, select \code{BibTeX}. Then replace the three \code{Command Line} fields with the ones shown in the figure, replacing the example file paths with the ones correct for your installation of Python and \code{bibulous.py}.

\end{enumerate}

\includegraphics[width=0.490\linewidth]{original_Winedt5_setup.png}

\includegraphics[width=0.490\linewidth]{modified_Winedt5_setup.png}
\begin{enumerate}
\setcounter{enumi}{1}
\item {} 
Note that the following are definitions of WinEdt registers:

\begin{Verbatim}[commandchars=\\\{\}]
\PYGZpc{}f = full path of active file (= \PYGZpc{}p/\PYGZpc{}n.\PYGZpc{}t)
\PYGZpc{}n = name of the active file
\PYGZpc{}p = the path of the active file
\PYGZpc{}t = the extension of the active file
\PYGZpc{}q = the path relative to the main file (i.e. for subdirectories)
\PYGZpc{}b = WinEdt's local working directory (not the tex file directory)
\PYGZpc{}B = path to the WinEdt executable file
\end{Verbatim}

\end{enumerate}


\section{Modifying Texmaker to replace BibTeX with Bibulous}
\label{getting_started:modifying-texmaker-to-replace-bibtex-with-bibulous}
On the main menu bar, select \code{Options} then \code{Configure Texmaker}. In the \code{Bib(la)tex} field, replace \code{bibtex \%.aux} with the location of your \code{bibulous.py} file, followed by \code{\%.aux}. The following figures show the configuration window before and after the change:

\includegraphics[width=0.490\linewidth]{original_texmaker_setup.png}

\includegraphics[width=0.490\linewidth]{modified_texmaker_setup.png}

(The example shows the location of the \code{bibulous.py} file as \code{/home/repos/bibulous/bibulous.py}, but you need to replace it with the appropriate location on your own system.)


\section{Modifying TeXStudio to replace BibTeX with Bibulous}
\label{getting_started:modifying-texstudio-to-replace-bibtex-with-bibulous}
On the main menu bar, select \code{Options} then \code{Configure TeXStudio}, and then the \code{Commands} tab. In the \code{BibTeX} field, replace \code{bibtex \%.aux} with the location of your \code{bibulous.py} file, followed by \code{\%.aux}. The following figures show the configuration window before and after the change:

\includegraphics[width=0.490\linewidth]{original_texstudio_setup.png}

\includegraphics[width=0.490\linewidth]{modified_texstudio_setup.png}

(The example shows the location of the \code{bibulous.py} file as \code{/home/repos/bibulous/bibulous.py}, but you need to replace it with the appropriate location on your own system.)


\section{Modifying TeXworks to replace BibTeX with Bibulous}
\label{getting_started:modifying-texworks-to-replace-bibtex-with-bibulous}
On the main menu bar, select \code{Edit} then \code{Preferences...}, and then the \code{Typesetting} tab. In the \code{Paths for TeX and related programs} list, insert a new entry to give the path to your \code{bibulous.py} program. (This is the highlighted entry in the figure shown below.) In the \code{Processing tools} list, double-click on \code{BibTeX}. This brings up a new dialog window. In that window, remove \code{bibtex} from the \code{Program} field and replace it with \code{bibulous.py}. The following figures show the configuration windows before and after the change:

\includegraphics[width=0.490\linewidth]{original_texworks_setup.png}

\includegraphics[width=0.490\linewidth]{modified_texworks_setup.png}

(The example shows the location of the \code{bibulous.py} file as \code{/home/repos/bibulous/bibulous.py}, but you need to replace it with the appropriate location on your own system.)


\section{Modifying LyX to replace BibTeX with Bibulous}
\label{getting_started:modifying-lyx-to-replace-bibtex-with-bibulous}
On the main menu bar, select \code{Tools} then \code{Preferences}, and then expand the \code{Output} dropdown list and click on the \code{LaTeX} field. In the \code{Bibliography generation} section of the resulting dialog, change \code{Processor} to \code{Custom} and in the \code{Command} field insert the full path to your \code{bibulous.py} program. The following figures show the configuration windows before and after the change:

\includegraphics[width=0.490\linewidth]{original_lyx_setup.png}

\includegraphics[width=0.490\linewidth]{modified_lyx_setup.png}

(The example shows the location of the \code{bibulous.py} file as \code{/home/repos/bibulous/bibulous.py}, but you need to replace it with the appropriate location on your own system.)


\chapter{Guidelines for writing bibliography style templates}
\label{guidelines_for_writing_style_templates:guidelines-for-writing-bibliography-style-templates}\label{guidelines_for_writing_style_templates::doc}

\section{Syntax}
\label{guidelines_for_writing_style_templates:syntax}\begin{enumerate}
\item {} 
Comments begin with \code{\#}, following the Python convention.

\item {} 
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 \code{TEMPLATES:}.

\item {} 
The \code{TEMPLATES} section of the file contains template definitions for formatting references. The \code{SPECIAL-TEMPLATES} section contains definitions for creating variables within each database entry. The \code{OPTIONS} section contains definitions for various keywords that can be used to modify program behavior. The \code{VARIABLES} section contains user definitions for new variables to be made available. The difference between these definitions and those in \code{SPECIAL-TEMPLATES} is that the ones provided in the \code{VARIABLES} section are in-line Python code, whereas the former use templates. Finally, the \code{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 \emph{Python API} section below.

\item {} 
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.

\item {} 
An ellipsis \code{...} 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.

\item {} 
An ellipsis in the middle of a line indicates an ``implicit loop''. For details, see the \emph{Examples for namelist formatting} section below.

\item {} 
Inside the \code{TEMPLATES} section, all of the variable definitions are intended to map to a database entrytype name. For example:

\begin{Verbatim}[commandchars=\\\{\}]
article = \PYGZlt{}au\PYGZgt{}, {}`{}`\PYGZlt{}title\PYGZgt{},'' \PYGZlt{}journal\PYGZgt{}, \PYGZlt{}volume\PYGZgt{}, \PYGZlt{}startpage\PYGZgt{}--\PYGZlt{}endpage\PYGZgt{} (\PYGZlt{}year\PYGZgt{}).
\end{Verbatim}

Here the \code{article} entrytype will be typeset so that the list of authors (\code{\textless{}au\textgreater{}}) 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.

\item {} 
A variable is indicated by angle brackets, as \code{\textless{}var\textgreater{}} and represents the contents of a field found within the bibliography database. Thus, when typesetting the bibliography, Bibulous will replace the variable \code{\textless{}authorlist\textgreater{}} with the string stored in the \code{authorlist} field of the current entry being formatted. An example list of typical variables one might use is:
\begin{quote}

\code{\textless{}au\textgreater{}}, \code{\textless{}booktitle\textgreater{}}, \code{\textless{}chapter\textgreater{}}, \code{\textless{}edition\textgreater{}}, \code{\textless{}ed\textgreater{}}, \code{\textless{}eid\textgreater{}}, \code{\textless{}endpage\textgreater{}}, \code{\textless{}institution\textgreater{}}, \code{\textless{}journal\textgreater{}}, \code{\textless{}nationality\textgreater{}}, \code{\textless{}note\textgreater{}}, \code{\textless{}number\textgreater{}}, \code{\textless{}organization\textgreater{}}, \code{\textless{}publisher\textgreater{}}, \code{\textless{}school\textgreater{}}, \code{\textless{}series\textgreater{}}, \code{\textless{}startpage\textgreater{}}, \code{\textless{}title\textgreater{}}, \code{\textless{}version\textgreater{}}, \code{\textless{}volume\textgreater{}}, \code{\textless{}year\textgreater{}}.
\end{quote}

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

\item {} 
Any variable placed within square brackets \code{{[}{]}} 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 \code{\textbar{}} is present within the square brackets, it indicates an ``elseif'' clause. That is, if the template is \code{{[}\textless{}var1\textgreater{}\textbar{}\textless{}var2\textgreater{} and \textless{}var3\textgreater{}{]}}, then the code will look for \code{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 \code{var2} and \code{var3}. If both are defined, then the original template \code{{[}\textless{}var1\textgreater{}\textbar{}\textless{}var2\textgreater{} and \textless{}var3\textgreater{}{]}} is replaced with \code{\textless{}var2\textgreater{} and \textless{}var3\textgreater{}} (i.e. removing the square brackets) and proceeds to replace the two variables with their corresponding fields. If either one of \code{var2} or \code{var3} is undefined in the entry, then the entire optional {[}...{]} portion of the template is skipped.

\item {} 
If the \code{\textbar{}} symbol is used to create an empty last cell, as in \code{{[}\textless{}var1\textgreater{}\textbar{}\textless{}var2\textgreater{}\textbar{}{]}}, 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, \code{{[}\textless{}note\textgreater{}\textbar{}{]}} has the same meaning as simply \code{\textless{}note\textgreater{}} does.

\item {} 
Nesting of \code{{[}{]}} brackets is allowed, but the syntax becomes computationally expensive to parse, so that these structures should be used sparingly:

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

\item {} 
In the \code{TEMPLATES} section of the file, if an entrytype format definition contains only another entrytype name on the right hand side of the \code{=}, i.e.:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{inbook} \PYG{o}{=} \PYG{n}{incollection}
\end{Verbatim}

then this means that the existing \code{incollection} template should be copied for use with \code{inbook} entrytypes. (Note that \code{incollection} should be defined above this line in order for this to work.)

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

\item {} 
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:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{inbook} \PYG{o}{=} \PYG{n}{incollection}
\end{Verbatim}

then the \code{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: \code{comment} and \code{preamble}.

\item {} 
A user wanting a localized form of quotation should use \code{\textbackslash{}enquote\{\textless{}title\textgreater{}\}} rather than \code{{}`{}`\textless{}title\textgreater{}'{'}}, and add \code{\textbackslash{}usepackage\{csquotes\}} to the preamble of the LaTeX document.

\item {} 
In the \code{OPTIONS} section of the file are the formatting options. None of these definitions are required. The complete list is given in the \emph{Options keywords} section below, together with explanations of each.

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

\begin{Verbatim}[commandchars=\\\{\}]
group = [\PYGZlt{}organization\PYGZgt{}\textbar{}\PYGZlt{}institution\PYGZgt{}\textbar{}\PYGZlt{}corporation\PYGZgt{}\textbar{}]
\end{Verbatim}

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

Another example usage would be the following::

\begin{Verbatim}[commandchars=\\\{\}]
author = [\PYGZlt{}author-en\PYGZgt{}\textbar{}\PYGZlt{}author-jp\PYGZgt{}\textbar{}]
\end{Verbatim}

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

\item {} 
The order in which any definitions are placed within the special templates is important. For example, if a user has \code{au = \textless{}authorlist.format\_authorlist()\textgreater{}} and then below that defines \code{authorlist = \textless{}author.to\_namelist()\textgreater{}}, then the code will issue an error stating that \code{authorlist} is not defined when attempting to create the \code{au} variable. Since the definition for \code{au} assumes the presence of the \code{authorlist} variable, the latter definition must be placed above it.

\end{enumerate}


\section{Default Fields}
\label{guidelines_for_writing_style_templates:default-fields}
A complete of the existing default fields is::

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{au}
\PYG{n}{authorlist}
\PYG{n}{citealnum}
\PYG{n}{citealpha}
\PYG{n}{citekey}
\PYG{n}{citenum}
\PYG{n}{ed}
\PYG{n}{editorlist}
\end{Verbatim}

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 these six default special templates are::

\begin{Verbatim}[commandchars=\\\{\}]
authorlist = \PYGZlt{}author.to\PYGZus{}namelist()\PYGZgt{}
editorlist = \PYGZlt{}editor.to\PYGZus{}namelist()\PYGZgt{}
citelabel = \PYGZlt{}citenum\PYGZgt{}
sortkey = \PYGZlt{}citenum\PYGZgt{}
au = \PYGZlt{}authorlist.format\PYGZus{}authorlist()\PYGZgt{}
ed = \PYGZlt{}editorlist.format\PYGZus{}editorlist()\PYGZgt{}
\end{Verbatim}

Note that the ordering of definitions is important. The following summarizes what these definitions are used for.

Also, in addition to these default fields, there are also two special variables defined, \code{citealpha} and \code{citealnum}, that can be accessed as \code{\textless{}citealpha\textgreater{}} and \code{\textless{}citealnum\textgreater{}} within any template. The first, \code{\textless{}citealpha\textgreater{}}, is designed to reproduce the citation label style used by BibTeX's \code{alpha} style. For example, \code{GKP94} is the \code{alpha}--style citation label for the book \emph{Concrete Mathematics}, 2nd Edition, by Ronald L. Graham, Donald E. Knuth, and Oren Patashnik (1994). The second variable \code{\textless{}citealnum\textgreater{}} 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 \emph{et al.} would have the label ``G2'' if preceded by, say, \emph{Introduction to Fourier Optics} by Joseph W. Goodman (1968), since the latter, being published earlier, would be placed earlier in the sorted list.

\textbf{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 \code{.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 \code{minauthors} option keyword. The maximum number of allowed authors is set by the \code{maxauthors} option keyword.

\textbf{authorlist} creates a list of dictionaries (one dictionary for each author name found within the database entry's \code{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 \code{\textless{}authorlist.0.first\textgreater{} \textless{}authorlist.0.last\textgreater{}}. To access the middle name(s) of the second author, use \code{\textless{}authorlist.1.middle\textgreater{}}.

\textbf{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 \code{citealnum} of ``B'' followed by its order number. If ``Yogi Bear'' were another first-author name in the list, then ``Yogi Bear'' would receive \code{citealnum = B1} while ``Bugs Bunny'' would receive \code{citealnum = B2}.

\textbf{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 \code{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 \code{alpha} style for citation labels can use \code{citelabel == \textless{}citealpha\textgreater{}} in the SPECIAL-TEMPLATES section of the file.

\textbf{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 \code{\textless{}citenum\textgreater{}}. The number used here for the label indicates the order in which the entry was cited.

\textbf{ed} follows the same basic structure as \code{au}, but uses the \code{maxeditors} and \code{mineditors} keywords.

\textbf{editorlist} behaves exactly as \code{authorlist} but derives its list of names from the database entry's \code{editor} field rather than \code{author} field.

\textbf{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 \code{\textless{}citenum\textgreater{}} variable.


\subsection{Operators}
\label{guidelines_for_writing_style_templates:operators}
One can use the ``dot'' operator inside a variable name, as in \code{\textless{}authorname.0.last.initial()\textgreater{}'{'} to perform any one of five functions: a explicit numerical index (the {}`{}`0} shown here, listed as the \code{.\#} operator below), an implicit numerical index (using \code{.n} or \code{.N}, for which see section \emph{Examples for namelist formatting} below for details), a range index (listed as the \code{\#\#:\#\#} operator below), a dictionary lookup (the \code{last} used here), or the application of an operator (in this case, the \code{.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).

The complete list of operators available is::

\begin{Verbatim}[commandchars=\\\{\}]
.\PYGZsh{}
.\PYGZsh{}\PYGZsh{}:\PYGZsh{}\PYGZsh{}
.compress()
.format\PYGZus{}authorlist()
.format\PYGZus{}editorlist()
.frenchinitial()
.if\PYGZus{}singular(var1,var2,var3)
.if\PYGZus{}length\PYGZus{}equals(var1,number,var2,var3)
.if\PYGZus{}length\PYGZus{}less\PYGZus{}than(var1,number,var2,var3)
.if\PYGZus{}length\PYGZus{}more\PYGZus{}than(var1,number,var2,var3)
.initial()
.lower()
.monthabbrev()
.monthname()
.n
.N
.ordinal()
.purify()
.replace(old,new)
.sentence\PYGZus{}case()
.tie()
.to\PYGZus{}namelist()
.uniquify(arg)
.upper()
.zfill(num)
\end{Verbatim}

The function of each operator is summarized below.

\textbf{.\#} An explicit numerical index, i.e., select the \#th element of the operand.

\textbf{.\#\#:\#\#} A range index, i.e., select the \#\#th through \#\#th elements of the operand. For example, for a bibliography entry whose database file contains \code{title = \{Impossibility\}}, a template variable of the form \code{\textless{}title.0:2\textgreater{}} will return \code{Imp}, and \code{\textless{}title.3:5\textgreater{}} will return \code{oss}. The first character of the operand thus has an index \code{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 \code{-1}, and the third to last by \code{-3}, so that in the example above, \code{\textless{}title.-3:-1\textgreater{}} will return \code{ity}.

\textbf{.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:

\begin{Verbatim}[commandchars=\\\{\}]
\PYGZlt{}authorlist.0.first\PYGZgt{}\PYGZlt{}authorlist.0.middle.initial().compress()\PYGZgt{} \PYGZlt{}authorlist.0.last\PYGZgt{}
\end{Verbatim}

Without the \code{.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.

\textbf{.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: \code{etal\_message}, \code{maxauthors}, \code{minauthors}, \code{namelist\_format}, \code{period\_after\_initial}, \code{terse\_inits}, \code{use\_firstname\_initials}, \code{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 \emph{Example definitions for namelist formatting} section below.

\textbf{.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: \code{etal\_message}, \code{maxeditors}, \code{mineditors}, \code{namelist\_format}, \code{period\_after\_initial}, \code{terse\_inits}, \code{use\_firstname\_initials}, \code{use\_name\_ties}. (The difference with the \code{.format\_authorlist()} operator is that it uses \code{maxeditors} and \code{mineditors} rather than \code{maxauthors} and \code{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 \emph{Example definitions for namelist formatting} section below.

\textbf{.frenchinitial()} is an alternative form of the \code{.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.

\textbf{.if\_singular(var1,var2,var3)} is an operator which inserts \code{var2} if \code{var1} has only one element, but \code{var3} if \code{var1} has more than one element. Here \code{var1} is assumed to be a list-type of variable, and \code{var2} and \code{var3} are assumed to be either fields present within the database entry or variables defined in the \code{SPECIAL-TEMPLATES} section of the file.

\textbf{.if\_length\_equals(var1,number,var2,var3)}

\textbf{.if\_length\_less\_than(var1,number,var2,var3)}

\textbf{.if\_length\_more\_than(var1,number,var2,var3)}

\textbf{.initial()} will truncate the string to its first letter. Note that if a name begins with a LaTeX markup character, such as \code{\{\textbackslash{}'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 \code{.initial()} operator to the name \code{\{\textbackslash{}v\{Z\}\}ukauskas} will produce the initialized form ``Ž''.

\textbf{.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 \code{au} contains \code{\{\textbackslash{}AA\}} then the operator will first convert this to the letter Å and then reduce it to the lower case å.

\textbf{.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 \code{month = 11}, and the template has the form \code{\textless{}month.monthabbrev()\textgreater{}}, then the template will be replaced with ``Nov'' for the default locale. For users with locale ``Japan'', this same operator will return ``11月''.

\textbf{.monthname()} behaves much like \code{.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 \code{month = 3}, and the template has the form \code{\textless{}month.monthname()\textgreater{}}, then the template variable will be replaced with ``March'' for the default locale. For users with locale ``Norway'', this same operator will return ``Mars''.

\textbf{.n} See the \emph{Examples for namelist formatting} below

\textbf{.N} {[}Not currently supported{]}

\textbf{.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!)

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

\textbf{.replace(old,new)} will replace the substring \code{old} with \code{new} wherever it finds \code{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 \code{.replace(J. W. Tukey,\textbackslash{}textbf\{J. W. Tukey\})} will work. Note that whitespace is preserved here. Thus, \code{.replace(J. W. Tukey, \textbackslash{}textbf\{J. W. Tukey\})} will add a space in front of \code{\textbackslash{}textbf\{J. W. Tukey\}}. Also, Bibulous will not allow the use of \code{\textless{}}, \code{\textgreater{}}, \code{\textbar{}}, or \code{)} characters in the two arguments of the operator.

\textbf{.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 \code{title = \{Understanding Bohmian mechanics\}} and the template has the form \code{\textless{}title.sentence\_case()\textgreater{}}, then the template variable will be replaced with ``Understanding bohmian mechanics''. However, if the entry has \code{title = \{Understanding \{B\}ohmian mechanics\}}, the result will be ``Understanding \{B\}ohmian mechanics''.

\textbf{.tie()} replaces any spaces with an unbreakable space. Thus, ``R. M. A.'' becomes ``R.\textasciitilde{}M.\textasciitilde{}A.''. An example use of this operator would be the following template::

\begin{Verbatim}[commandchars=\\\{\}]
authorname = [\PYGZlt{}authorlist.n.first.initial()\PYGZgt{}.\PYGZti{}][\PYGZlt{}authorlist.n.middle.initial().tie()\PYGZgt{}. ]...
             [\PYGZlt{}authorlist.n.prefix\PYGZgt{}\PYGZti{}]\PYGZlt{}authorlist.n.last\PYGZgt{}[, \PYGZlt{}authorlist.n.suffix\PYGZgt{}]
\end{Verbatim}

\textbf{.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).

\textbf{.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 \code{citelabel = \textless{}authorlist.0.last\textgreater{}\textless{}year\textgreater{}} will produce the same citation label for both entries. Thus, we can rename this as \code{citetemp = \textless{}authorlist.0.last\textgreater{}\textless{}year\textgreater{}} and then define \code{citelabel = \textless{}citetemp.uniquify(a)\textgreater{}} 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.

\textbf{.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 \code{au} contains \code{\{\textbackslash{}aa\}} then the operator will first convert this to the letter å and then raise it to the upper case Å.

\textbf{.zfill(num)} appends zeros to the front of its argument, where \code{num} indicates the desired final length of the string. For example, if the field \code{vol} contains the number \code{11}, then calling \code{\textless{}vol.zfill(3)\textgreater{}} produces the result \code{011}.


\section{Options keywords}
\label{guidelines_for_writing_style_templates:options-keywords}
A complete list of existing options keywords, together with their default definitions, is::

\begin{Verbatim}[commandchars=\\\{\}]
allow\PYGZus{}scripts = False
autocomplete\PYGZus{}doi = True
backrefs = False
backrefstyle = none
bibitemsep = None
case\PYGZus{}sensitive\PYGZus{}field\PYGZus{}names = False
edmsg1 = , ed.
edmsg2 = , eds
etal\PYGZus{}message = , \PYGZbs{}\PYGZbs{}textit\PYGZob{}et al.\PYGZcb{}
maxauthors = 9
maxeditors = 5
minauthors = 9
mineditors = 5
name\PYGZus{}separator = and
namelist\PYGZus{}format = first\PYGZus{}name\PYGZus{}first
period\PYGZus{}after\PYGZus{}initial = True
procspie\PYGZus{}as\PYGZus{}journal = False
sort\PYGZus{}case = True
terse\PYGZus{}inits = False
undefstr = ???
use\PYGZus{}abbrevs = True
use\PYGZus{}citeextract = True
use\PYGZus{}firstname\PYGZus{}initials = True
use\PYGZus{}name\PYGZus{}ties = False
\end{Verbatim}

Each of the keywords is summarized below.

\textbf{allow\_scripts} {[}default value: False{]} tells Bibulous whether to allow the evaluation of Python code in the VARIABLES and DEFINITIONS sections of \code{.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 \code{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.

\textbf{autocomplete\_doi} {[}default value: True{]} tells Bibulous whether to add \code{http://dx.doi.org/} to the front of the \code{doi} field if the front is missing. This allows the \code{\textless{}doi\textgreater{}} variable to be used as a complete URL, even when the prefix is missing in the database field.

\textbf{backrefs} {[}default value: False{]} THIS KEYWORD IS NOT YET IMPLEMENTED

\textbf{backrefstyle} {[}default value: none{]} THIS KEYWORD IS NOT YET IMPLEMENTED

\textbf{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 \code{bibitemsep = 0pt}.

\textbf{case\_sensitive\_field\_names} {[}default value: False{]} tells Bibulous whether to consider, for example, a field named ``Author'' as being distinct from ``author''.

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

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

\textbf{etal\_message} {[}default value: , \textbackslash{}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 \code{maxauthors} keyword).

\textbf{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 \code{minauthors} and the \code{etal\_message} is appended to the result. (This keyword is only used within the \code{.format\_namelist()} operator.)

\textbf{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 \code{mineditors} and the \code{etal\_message} is appended to the result. (This keyword is only used within the \code{.format\_namelist()} operator.)

\textbf{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 \code{.format\_namelist()} operator.)

\textbf{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 \code{.format\_namelist()} operator.)

\textbf{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 \code{Bugs Bunny and Porky Pig}, using the separator \code{and} allows Bibulous to determine that there are two separate people, \code{Bugs Bunny} and \code{Porky Pig}. If the option keyword has an empty field (\emph{i.e.} it is written as \code{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.

\textbf{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 \code{namelist\_format = first\_name\_first} then the individual names will appear in the order ``firstname middle prefix last, suffix''. If \code{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 \code{.format\_namelist()} operator.)

\textbf{period\_after\_initial} {[}default value: True{]} tells the \code{.format\_namelist()} operator whether to place a period after each initial of an individual's name. Thus, if \code{period\_after\_initial = True}, a name will appear as ``R. M. A. Azzam'', but if \code{False} will appear as ``R M A Azzam''. (This keyword is only used within the \code{.format\_namelist()} operator.)

\textbf{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.

\textbf{sort\_case} {[}default value: True{]} informs Bibulous whether or not to use case-sensitive sorting of reference keys.

\textbf{terse\_inits} {[}default value: False{]} tells the \code{.format\_namelist()} operator whether to compress together the initials of an individual's name. Thus, if \code{terse\_inits = True}, a name will appear as ``RMA Azzam'', but if \code{False} will appear as ``R. M. A. Azzam''. (This keyword is only used within the \code{.format\_namelist()} operator.)

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

\textbf{use\_abbrevs} {[}default value: True{]} tells Bibulous whether or not to use the abbreviations defined in the bibliography database. (Used for debugging.)

\textbf{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 \code{.aux} file.

\textbf{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 \code{.format\_namelist()} operator.)

\textbf{use\_name\_ties} {[}default value: False{]} Whether or not to replace spaces with unbreakable spaces (i.e. ``R. M. A. Azzam'' or ``R.\textasciitilde{}M.\textasciitilde{}A. Azzam'') inside names in the name list. (This keyword is only used within the \code{.format\_namelist()} operator.)


\section{Implicit loops and examples for namelist formatting}
\label{guidelines_for_writing_style_templates:implicit-loops-and-examples-for-namelist-formatting}
The following code provides an example usage of implicit indexing within an implicit loop structure::

\begin{Verbatim}[commandchars=\\\{\}]
authorlist = \PYGZlt{}author.to\PYGZus{}namelist()\PYGZgt{}
editorlist = \PYGZlt{}editor.to\PYGZus{}namelist()\PYGZgt{}
authorname.n = [\PYGZlt{}authorlist.n.first.initial()\PYGZgt{}. ][\PYGZlt{}authorlist.n.middle.initial()\PYGZgt{}. ]...
               [\PYGZlt{}authorlist.n.prefix\PYGZgt{} ]\PYGZlt{}authorlist.n.last\PYGZgt{}[, \PYGZlt{}authorlist.n.suffix\PYGZgt{}]
au = \PYGZlt{}authorname.0\PYGZgt{}, ...,\PYGZob{} and \PYGZcb{}\PYGZlt{}authorname.9\PYGZgt{}
editorname.n = [\PYGZlt{}editorlist.n.first.initial()\PYGZgt{}. ][\PYGZlt{}editorlist.n.middle.initial()\PYGZgt{}. ]...
               [\PYGZlt{}editorlist.n.prefix\PYGZgt{} ]\PYGZlt{}editorlist.n.last\PYGZgt{}[, \PYGZlt{}editorlist.n.suffix\PYGZgt{}]
ed = \PYGZlt{}editorname.0\PYGZgt{}, ...,\PYGZob{} and \PYGZcb{}\PYGZlt{}editorname.2\PYGZgt{}
\end{Verbatim}

Here the \code{authorlist} and \code{editorlist} definitions create namelist variables from the \code{author} and \code{editor} fields in the entry (if they exist). Next, the implicitly-indexed \code{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 \code{ed} template than the \code{au} one, as it has a smaller number of allowed names. The \code{ed} template has the definition:

\begin{Verbatim}[commandchars=\\\{\}]
\PYGZlt{}editorname.0\PYGZgt{}, ...,\PYGZob{} and \PYGZcb{}\PYGZlt{}editorname.2\PYGZgt{}
\end{Verbatim}

which simplifies to \code{\textless{}editorname.0\textgreater{}} when there is only one editor in the database entry, and:

\begin{Verbatim}[commandchars=\\\{\}]
\PYGZlt{}editorname.0\PYGZgt{} and \PYGZlt{}editorname.1\PYGZgt{}
\end{Verbatim}

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

\begin{Verbatim}[commandchars=\\\{\}]
\PYGZlt{}editorname.0\PYGZgt{}, \PYGZlt{}editorname.1\PYGZgt{}, and \PYGZlt{}editorname.2\PYGZgt{}
\end{Verbatim}

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 \code{\{ 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 \emph{et al.} construction when there more than this number of names, so that the result becomes:

\begin{Verbatim}[commandchars=\\\{\}]
\PYGZlt{}editorname.0\PYGZgt{}, \PYGZlt{}editorname.1\PYGZgt{}, \PYGZlt{}editorname.2\PYGZgt{}, \PYGZbs{}textit\PYGZob{}et al.\PYGZcb{}
\end{Verbatim}

where the form of the string \code{\textbackslash{}textit\{, et. al\}} is specified by the \code{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 \code{editorname} to complete building out the template. The latter template is defined as:

\begin{Verbatim}[commandchars=\\\{\}]
editorname.n = [\PYGZlt{}editorlist.n.first.initial()\PYGZgt{}. ][\PYGZlt{}editorlist.n.middle.initial()\PYGZgt{}. ]...
               [\PYGZlt{}editorlist.n.prefix\PYGZgt{} ]\PYGZlt{}editorlist.n.last\PYGZgt{}[, \PYGZlt{}editorlist.n.suffix\PYGZgt{}]
\end{Verbatim}

so that a template variable of the form {\color{red}\bfseries{}{}`{}`}\textless{}editorname.0\textgreater{}'' is replaced with:

\begin{Verbatim}[commandchars=\\\{\}]
[\PYGZlt{}editorlist.0.first.initial()\PYGZgt{}. ][\PYGZlt{}editorlist.0.middle.initial()\PYGZgt{}. ]...
[\PYGZlt{}editorlist.0.prefix\PYGZgt{} ]\PYGZlt{}editorlist.0.last\PYGZgt{}[, \PYGZlt{}editorlist.0.suffix\PYGZgt{}]
\end{Verbatim}

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

\begin{Verbatim}[commandchars=\\\{\}]
[\PYGZlt{}editorlist.0.first.initial()\PYGZgt{}. ][\PYGZlt{}editorlist.0.middle.initial()\PYGZgt{}. ]...
[\PYGZlt{}editorlist.0.prefix\PYGZgt{} ]\PYGZlt{}editorlist.0.last\PYGZgt{}[, \PYGZlt{}editorlist.0.suffix\PYGZgt{}] and ...
[\PYGZlt{}editorlist.1.first.initial()\PYGZgt{}. ][\PYGZlt{}editorlist.1.middle.initial()\PYGZgt{}. ]...
[\PYGZlt{}editorlist.1.prefix\PYGZgt{} ]\PYGZlt{}editorlist.1.last\PYGZgt{}[, \PYGZlt{}editorlist.1.suffix\PYGZgt{}]
\end{Verbatim}

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

Note that implicit loop structures only work when they comprise the \emph{entire} template. That is, a template such as \code{au = \textless{}authorname.0\textgreater{}, ...,\{ and \}\textless{}authorname.6\textgreater{}} works fine, whereas the template \code{au = {[}\textless{}authorname.0\textgreater{}, ...,\{ and \}\textless{}authorname.6\textgreater{}{]}} uses the \code{{[}} as part of each entry in the loop, and the \code{{]}} as part of the final entry, so that the final result is a malformed template. (The left and right square brackets are no longer matched.)


\section{Python API}
\label{guidelines_for_writing_style_templates:python-api}
Bibulous also provides to users an extensible Python interface allowing users to directly manipulate Bibulous' internal data structures. These use the \code{VARIABLES} and \code{DEFINITIONS} sections of the file, as shown below. For the \code{{}`VARIABLES} section, a variable name is defined (the first example below defines the variable \code{year\_bce}, while the second example below defines \code{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 \code{VARIABLES} section can then be accessed as a template variable (i.e. \code{\textless{}year\_bce\textgreater{}}) within the \code{TEMPLATES} section of the file. Two example uses are shown below.

To allow Bibulous to read the \code{VARIABLES} and \code{DEFINITIONS} sections of the file, users must set the option keyword \code{allow\_scripts} to True.

\textbf{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 \code{yearstyle} that allows users to switch between one style (BC/AD) and the other (BCE/CE). This keyword is accessed by placing \code{options} as an argument to the \code{format\_yearstyle()} function defining the variable \code{year\_bce}. Inside the function, it can then check the options dictionary for the \code{yearstyle} keyword and determine which convention to use.

The \code{format\_yearstyle()} function itself is straightforward. It first checks whether the entry has a \code{year} field. If not, then it returns \code{None}, indicating that the function's result is undefined. If it finds a \code{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 \code{year} fields as \code{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:

\begin{Verbatim}[commandchars=\\\{\}]
OPTIONS:
allow\PYGZus{}scripts = True
yearstyle = BCE/CE

VARIABLES:
year\PYGZus{}bce = format\PYGZus{}yearstyle(entry, options)

DEFINITIONS:
\PYGZsh{}\PYGZsh{} NOTE! Only Unix-style line endings are allowed here.
def format\PYGZus{}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'])

    \PYGZsh{}\PYGZsh{} First check that the year string is an integer. If not an integer, then just return
    \PYGZsh{}\PYGZsh{} the field itself.
    if not str\PYGZus{}is\PYGZus{}integer(entry['year']):
        return(entry['year'])

    yearnum = int(entry['year'])

    if (yearnum \PYGZlt{} 0):
        if (options['yearstyle'] == 'BCE/CE'):
            suffix = 'BCE'
        else:
            suffix = 'BC'
        \PYGZsh{}\PYGZsh{} 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)
\end{Verbatim}

\textbf{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:

\begin{Verbatim}[commandchars=\\\{\}]
@article\PYGZob{}stewart,
title = \PYGZob{}Interview with Walter Stewart\PYGZcb{},
author = \PYGZob{}Doug Stewart\PYGZcb{},
journal = \PYGZob{}Omni\PYGZcb{},
year = \PYGZob{}1989\PYGZcb{},
volume = \PYGZob{}11\PYGZcb{},
number = \PYGZob{}5\PYGZcb{},
pages = \PYGZob{}64--66, 87--92, 94\PYGZcb{}
\PYGZcb{}
\end{Verbatim}

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 \code{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 \code{allow\_scripts} must be set to true. Next, a new \code{pagerange} variable is defined, so that it can be accessed in the \code{TEMPLATES} section of the file as \code{\textless{}pagerange\textgreater{}}. The variable is defined as the return value of the function \code{format\_pagerange()} given in the \code{DEFINITIONS} section. The defined function first checks to see if there is a \code{pages} field defined in the entry. If not, then it returns None, so that the \code{pagerange} variable will also be undefined. If it finds the \code{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 \code{endpage} variable (generated by default by Bibulous from the \code{pages} field). If present, then the function returns a startpage--endpage pair. If \code{endpage} is not present, then it returns only the \code{startpage} variable.

Example:

\begin{Verbatim}[commandchars=\\\{\}]
OPTIONS:
allow\PYGZus{}scripts = True

VARIABLES:
pagerange = format\PYGZus{}pagerange(entry, options)

DEFINITIONS:
def format\PYGZus{}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'])
\end{Verbatim}


\chapter{Instructions on how to report a bug to the Bibulous development team}
\label{instructions_for_reporting_bugs:instructions-on-how-to-report-a-bug-to-the-bibulous-development-team}\label{instructions_for_reporting_bugs::doc}

\section{Where to report a bug}
\label{instructions_for_reporting_bugs:where-to-report-a-bug}
Send an email to the \code{users\_mailing\_list}. Once it's confirmed as a bug, someone, possibly you, can enter it into the issue tracker. (Or if you're pretty sure about the bug, go ahead and post directly to the developers mailing list, \code{developers\_mailing\_list}. But if you're not sure, it's better to post to {[}\code{users mailing list}{]} first; someone there can tell you whether the behavior you encountered is expected or not.)


\section{How to report a bug}
\label{instructions_for_reporting_bugs:how-to-report-a-bug}
First, make sure it's a bug. If Bibulous does not behave the way you expect, look in the documentation and mailing list archives for evidence that it should behave the way you expect. If the documentation and archives do not contain enough information to tell you whether the behavior is a bug or is expected behavior, go ahead and ask on the users mailing list first \code{users\_mailing\_list}. Also check that you are running the most recent version of Bibulous. It may be that the bug has already been fixed.

Once you've established that it's a bug, the most important thing you can do is come up with a simple description and reproduction recipe. For example, if the bug, as you initially found it, involves five files over ten commits, try to make it happen with just one file and one commit. The simpler the reproduction recipe, the more likely a developer is to successfully reproduce the bug and fix it.

When you write up the reproduction recipe, don't just write a prose description of what you did to make the bug happen. Instead, give a copy of the exact series of commands you ran, and their output. Use cut-and-paste to do this. If there are files involved, be sure to include the names of the files, and even their content if you think it might be relevant. The very best thing is to package your reproduction recipe as a script, that helps a lot.

In addition to the reproduction recipe, we'll also need a complete description of the environment in which you reproduced the bug. That means:
\begin{itemize}
\item {} 
Your operating system

\item {} 
The Python version you are running under.

\item {} 
The release and/or revision of Bibulous.

\item {} 
Anything else that could possibly be relevant. Err on the side of too much information, rather than too little.

\end{itemize}

Once you have all this, you're ready to write the report. Start out with a clear description of what the bug is. That is, say how you expected Bibulous to behave, and contrast that with how it actually behaved. While the bug may seem obvious to you, it may not be so obvious to someone else, so it's best to avoid a guessing game. Follow that with the environment description, and the reproduction recipe. If you also want to include speculation as to the cause, and even suggest how the code may be modified to fix the bug, that's great.

Post all of this information to the developers mailing list, \code{developers\_mailing\_list}, or if you have already been there and been asked to file an issue, then go to the Issue Tracker and follow the instructions there.

Thanks! It's a lot of work to file an effective bug report, but a good report can save hours of a developer's time, and make the bug much more likely to get fixed.


\chapter{Developer guide}
\label{developer_guide::doc}\label{developer_guide:developer-guide}

\section{Guidelines and notes for Python coding style}
\label{developer_guide:guidelines-and-notes-for-python-coding-style}\begin{enumerate}
\item {} 
Note that one can mix 8-bit Python strings (ASCII text) with UTF-8 encoded text as long as the 8-bit string contains only ASCII characters.

\item {} 
Keep in mind when running into Unicode errors: reading a line of text from a file produces a line of bytes and not characters. To decode the bytes into a string of characters, you need to know the encoding.

\item {} 
There are a couple of minor points where the Bibulous coding standards deviates from Python's PEP8:
\begin{enumerate}
\item {} 
A line width of 120 is the standard (not 80).

\item {} 
In general, statements that evaluate to a boolean are placed within parentheses (i.e. \code{if (a \textless{} b):} rather than \code{if a \textless{} b:}).

\end{enumerate}

\item {} 
Many developers prefer to spread out code among a large number of small files, but Bibulous is currently organized in a single large file. This is partly because there is no large block of code that fits by itself so that a separate file makes sense. (Parsing of \code{.bib} files, for example, only requires a couple hundred lines.

\end{enumerate}


\section{Overall project strategy and code structure}
\label{developer_guide:overall-project-strategy-and-code-structure}
The basic function of BibTeX is to accept an \code{.aux} file as input and to produce a \code{.bbl} file as output. The \code{aux} file contains all of the citation information as well as the filenames for the bibliography database file (\code{.bib}) and the style file (\code{.bst}).

The basic program flow is as follows:
\begin{enumerate}
\item {} 
Read the \code{.aux} file and get the names of the bibliography databases (\code{.bib} files), the style templates (\code{.bst} files) to use, together with the entire set of citations.

\item {} 
Read in the Bibulous style template file as a dictionary (\code{bstdict}).

\item {} 
If the \code{use\_citeextract} keyword is set to True, and if an ``extracted'' database file exists, then compare the citations in the extracted database against those in the \code{.aux} file. If there are any differences, then re-extract the database. Otherwise, use the extracted database rather than the full one specified in the \code{.aux} file.

\item {} 
Read in all of the bibliography database files into one long dictionary (\code{bibdata}), replacing any abbreviations with their full form. In an ``extracted'' database, all entries are parsed, whereas in any other type of database file, only those entries whose keywords are found in the citation list are actually parsed. All other entries have their data saved as unparsed strings. Cross-referenced data is \emph{not} yet inserted at this point. That is delayed until the time of writing the BBL file in order to speed up parsing. It is only then that the cross-referenced entries have their data parsed into dictionary form.

\item {} 
Now that all the information is collected, we can generate the \code{.bbl} file. Create the list of sortkeys, then go through each corresponding citation key in turn, and find the corresponding entry key in \code{bibdata}. If there is crossref data, then fill in missing values here. Also create the ``special variables'' here. Finally, from the entry type, select a template from \code{bstdict} and begin inserting the variables one-by-one into the template.

\end{enumerate}

Because the \code{.bib} file is highly structured, it is straightforward to write a parser by hand in Python: the \code{parse\_bibfile()} method converts the \code{.bib} file contents into a Python dictionary (the \code{Bibdata} class' \code{bibdata}). The \code{.aux} file is even easier to parse, and the \code{parse\_auxfile()} method converts the citation information into the \code{Bibdata} class' \code{citedict} dictionary.

The \code{Bibdata} class thus holds all relevant information needed to operate on a bibliography and generate the output LaTeX-formatted \code{.bbl} file.


\section{Parsing BIB files}
\label{developer_guide:parsing-bib-files}

\subsection{parse\_bibfile()}
\label{developer_guide:parse-bibfile}
The strategy for \code{parse\_bibfile()} is to find each individual bibliography entry, determine its entry type, and save all of the text between the entry's opening and closing braces as one long string, to be passed to \code{parse\_bibentry()} for further parsing. To gather the entry data string, we first look for a line that starts with \code{@}. On that line, we look for a string after the \code{@} followed by \code{\{}, where the string gives the entry type. After we know the entry type, we look for the corresponding closing brace. If we don't find it on the same line, then we read in the next line, and so forth, concatenating all of the lines into one long ``entry string'' until we encounter the corresponding closing brace. Once we have this extended ``entry string'' we feed it to \code{parse\_bibentry()} to generate the bibliography data. Once we have come to the end of a given entry, we continue reading down the file looking for the next `@' and so on.

Although this approach effectively means that we have to pass twice through the same data, dealing with brace-matching can otherwise become a mess for the BibTeX format, since it allows nested delimiters, is not directly compatible with regular expressions.


\subsection{parse\_bibentry()}
\label{developer_guide:parse-bibentry}
Because \code{parse\_bibfile()} has already split the data by individual entry, \code{parse\_bibentry()} only needs to worry about parsing a single entry, and there are five possible formats for the entry string passed to the function:
\begin{enumerate}
\item {} 
If the entrytype is a \code{comment}, then skip everything, adding nothing to the database dictionary.

\item {} 
If the entrytype is a \code{preamble}, then treat the entire entry contents as a single fieldvalue. Append the string onto the \code{preamble} value in the \code{bibdata} dictionary.

\item {} 
If the entrytype is a \code{acronym}, then get the entrykey and copy it into the \code{name} field. The remainder of the string is a single field value (the full form of the acronym); copy that into the \code{description} field.

\item {} 
If the entrytype is a \code{string} (i.e. an abbreviation), then there is no entrykey. Get the fieldname (abbreviation key), and the remainder of the string is a single field value (the full form of the abbreviated string). Add this key-value pair to the \code{abbrevs} dictionary.

\item {} 
If the entry is any other type, then get the entrykey, and the remainder of the string is a \emph{series} of field-value pairs.

\end{enumerate}

Once it determines which of these four options to use, \code{parse\_bibentry()} extracts the entry key (if present), it locates each individual field and separates out the string corresponding to the key-value pair for each field. It does not actually \emph{parse} the individual fields. For that, it loops over each field with a call to \code{parse\_bibfield()} to extract the field key-value pairs.


\subsection{parse\_bibfield()}
\label{developer_guide:parse-bibfield}
\code{parse\_bibfield()} is the workhorse function of the BIB parsing. And because of BibTeX's method for allowing concatenation, use of abbreviation keys, and use of two different types of delimiters (\code{"..."} or \code{\{...\}}), this function is a little messy. However, for the format of a given field, there are four parsing possibilities:
\begin{enumerate}
\item {} 
If the field begins with a double quote \code{"} then scan until you find the next unnested \code{"}. Add that to the result string. If the ending \code{"} is followed by a comma, then the field is done; return the result string. If the ending is followed by a \code{\#} then expect another field string. Scan for it and append it to the current result string.

\item {} 
If the field begins with \code{\{} then scan until you resolve the brace level. This should be followed by a comma, since no concatenation is allowed for brace-delimited fields. Otherwise issue a syntax error warning.

\item {} 
If the field begins with a \code{\#} (concatenation operator) then skip whitespace to the next character set, where you should expect a quote-delimited field. Append that to the current result string.

\item {} 
If the field begins with anything else, then the substring up until the first whitespace character represents an abbreviation key. Locate it and substitute it in. If you don't find the key in the \code{abbrevs} dictionary, give a warning and continue on.

\end{enumerate}


\section{Parsing AUX files}
\label{developer_guide:parsing-aux-files}
The \code{.aux} file contains the filenames of the \code{.bib} database file and the \code{.bst} style template file, as well as the citations. The \code{get\_bibfilenames()} method scans through the \code{.aux} file and locates a line with \code{\textbackslash{}bibdata\{...\}} which contains a filename or a comma-delimited list of filenames, giving the database files. Another line with \code{\textbackslash{}bibstyle\{...\}} gives the filename or comma-delimited list of filenames for style templates. The filenames obtained are saved into the \code{filedict} attribute -- a dictionary whose keys are the file extensions \code{aux}, \code{bbl}, \code{bib}, \code{bst}, or \code{tex}.

The \code{parse\_auxfile()} method makes a second pass through the \code{.aux} file, this time looking for the citation information. (Auxiliary files are generally quite small, so taking multiple passes through them costs very little time.) Each line with \code{\textbackslash{}citation\{...\}} contains a citation key or comma-delimited list of citation keys -- each one is added into the citation dictionary (\code{citedict}), with a value corresponding to the citation order.


\section{Parsing BST files}
\label{developer_guide:parsing-bst-files}
Parsing a \code{.bst} file basically involves looking for one of several syntactical structures.
\begin{enumerate}
\item {} 
First, any \code{\#} present in a line indicates a comment. All text following the \code{\#} are ignored.

\item {} 
Any line containing all capital letters and ending in \code{:} indicates a section header. The sections recognized are: \code{TEMPLATES}, \code{SPECIAL-TEMPLATES}, \code{OPTIONS}, \code{VARIABLES}, and \code{DEFINITIONS}. The first three sections (\code{TEMPLATES}, \code{SPECIAL-TEMPLATES}, and \code{OPTIONS}) use template syntax, while the last two ( \code{VARIABLES} and \code{DEFINITIONS}) use Python syntax.

\item {} 
In the TEMPLATES, SPECIAL-TEMPLATES, or OPTIONS sections of the file, any line ending in an ellipsis (\code{...}) means that the following line is a continuation. Thus, the following line is appended to the current one.

\item {} 
For each \code{var = definition} pair found in the \code{VARIABLES} section of the file, the code creates a new entry in the \code{user\_variables} dictionary, with value equal to the given definition.

\item {} 
For each \code{entrytype = template} pair found in the \code{TEMPLATES} section of the file, the code creates a corresponding entry in \code{bstdict}, with the key given by the \code{entrytype} and value given by the \code{template}. The code next examines the template definition to see if it contains a nested options block. If so, it adds it to the list of nested templates.

\item {} 
For each \code{keyword = value} pair found in the \code{OPTIONS} section of the file, the code creates a new entry in the \code{options} dictionary, with the dictionary key being the keyword itself, and the value copied from the right hand side of the option definition.

\item {} 
For each \code{var = definition} pair found in the \code{SPECIAL-TEMPLATES} section of the file, the code has to do a little more work than elsewhere. First it creates a new entry in the \code{specials} dictionary, with the dictionary key given by the \code{var}, and the value given by the \code{definition}. It then appens the key to the \code{specials\_list}. (Since a dictionary is not ordered, we need an order-preserving means of iterating through the list of specials to make sure that one can always be defined before another that depends on it.) Next it examines the template definition to see if it contains a nested options block. If so, it adds it to the list of nested templates. It also looks to see if there is an ellipsis representing an implicit loop. If so, it adds the template key to the list of ``looped templates''. Finally it looks to see if the template's key represents an inmplicitly-indexed variable. If so, it adds the key to the list of implicitly indexed variables.

\end{enumerate}

Once the initial parsing is done, there are several steps in which it analyzes the results:
\begin{enumerate}
\item {} 
Iterating through each of the regular templates, the code looks to see if any of the templates are defined as copies of other templates, as, for example, \code{inbook = incollection}. If it finds this kind of definition, then it copies the template from the one (\code{incollection} here) to the other (\code{inbook} here).

\item {} 
The code looks at the functions defined in the \code{DEFINITIONS} section of the file. If the \code{allow\_scripts} keyword is set to True, then it goes ahead and evaluates these function definitions so that they will be available during the process of formatting bibliography entries.

\item {} 
Finally, the code passes each template definition through the \code{validate\_templatestr()} function to validate that the template has proper syntax.

\end{enumerate}


\section{Writing the BBL file}
\label{developer_guide:writing-the-bbl-file}
Now that all the information is available to Bibulous, we can begin writing the output BBL file. First we write a few lines to the preamble, including the \code{preamble} string obtained from the \code{.bib} database files. Then, for each citation key we found in the \code{.aux} file, we
\begin{enumerate}
\item {} 
Insert any cross-reference data from any other database entries into the current one.

\item {} 
Define all of the ``special variables'', including the \code{sortkey} and \code{citelabel}, as fields within the current entry.

\end{enumerate}

Now that we have all of the sortkeys, we generate the \code{citation\_list} --- the thing we iterate through one by one to format the references in order. At each iteration, we call \code{format\_bibitem()}, which does the following:
\begin{enumerate}
\item {} 
Write the line \code{\textbackslash{}bibitem{[}citelabel{]}\{citekey\}} into the \code{.bbl} file.

\item {} 
Import the template corresponding to the current entry's \code{entrytype}.

\item {} 
If there are any user-deefined variables (from the \code{VARIABLES} section of the file), then evaluate those variables now, so that they can be used inside the template.

\item {} 
For each option block in the template, go through and determine how to ``simplify'' the block. This amounts to locating the first cell in each block that has a defined value, and then replacing the \code{{[}...{]}} square-bracket-delimited block with its contents. At this point the template variables are still there; only the square brackets have been dropped.

\item {} 
Now that the optional pieces are all gone, go through each template variable and replace it with the corresponding field from the database entry.

\item {} 
If there are any nested \code{\textbackslash{}textit\{...\textbackslash{}textit\{...\}...\}} operators in the result, replace odd-level operators with \code{\textbackslash{}textup\{...\}} in order to get the right behavior of flipping between italics and regular font.

\item {} 
If there are any nested \code{\textbackslash{}textbf\{...\textbackslash{}textbf\{...\}...\}} operators in the result, replace odd-level operators with \code{\textbackslash{}textup\{...\}} in order to get the right behavior of flipping between bold and regular weight.

\item {} 
If there are any nested quotation marks in the result, then re-order them according to the American standard. This means having double-quotation-marks at the outermost level, single-quotation-marks inside that, then double inside that, single inside that, and so on. This is messy and difficult code, and so users should always be recommended to use the \code{\textbackslash{}enquote\{...\}} LaTeX operator instead of manually-implemented quotation marks.

\end{enumerate}


\section{Name formatting}
\label{developer_guide:name-formatting}
One of the more complex tasks needed for parsing BIB files is to resolve the elements of name lists (typically saved in the \code{author} and \code{editor} fields). In order to know how these should be inserted into a template, it is necessary to know which parts of a given person's name correspond to the first name, the middle name(s), the ``prefix'' (or ``von part''), the last name (or ``surname''), and the ``suffix'' (such as ``Jr.'' or ``III''). These five pieces or each person's name are saved as a dictionary, so that a bibliography entry with five authors is represented in \code{\textless{}authorlist\textgreater{}} as a list of five dictionaries, and each dictionary having keys \code{first}, \code{middle}, \code{prefix}, \code{last}, and \code{suffix}.

In order to speed up parsing times, the actual mapping of the \code{author} or \code{editor} fields to \code{authorlist} or \code{editorlist} is not done until the loop over citation keys performed while writing out the BBL file. The function that product the list-of-dicts parsing result is \code{namestr\_to\_namedict(namestr)}.

The default formatting of a namelist into a string to be inserted into the template is performed by \code{format\_namelist()}.


\subsection{create\_namelist()}
\label{developer_guide:create-namelist}
A BibTeX ``name'' field can consist of three different formats of names:
\begin{enumerate}
\item {} 
A space-separated list: \code{{[}firstname middlenames suffix lastname{]}}

\item {} 
A two-element comma-separated list: \code{{[}prefix lastname, firstname middlenames{]}}

\item {} 
A three-element comma-separated list: \code{{[}prefix lastname, suffix, firstname middlenames{]}}

\end{enumerate}

So, an easy way to separate these three categories is by counting the number of commas that appear. The trickiest part here is that although we can use \code{and} as a name separator, we are only allowed to do so if \code{and} occurs at the top brace level.

In addition, in order to make name parsing more flexible for nonstandard names, Bibulous adds two more name formats to this list:
\begin{enumerate}
\setcounter{enumi}{3}
\item {} 
A four-element comma-separated list: \code{{[}firstname, middlenames, prefix, lastname{]}}

\item {} 
A five-element comma-separated list: \code{{[}firstname, middlenames, prefix, lastname, suffix{]}}

\end{enumerate}

For each name in the field, we parse the name tokens into a dictionary. We then compile all of the dictionaries into a list, ordered by the appearance of the names in the input field.


\subsection{format\_namelist()}
\label{developer_guide:format-namelist}
Given a namelist (list of dictionaries), we glue the name elements together into a single string, incorporating all of the format options selected by the user in the template file. This includes calls to \code{namedict\_to\_formatted\_namestr()}, and to \code{initialize\_name()} if converting any name tokens to initials.


\section{Generating sortkeys}
\label{developer_guide:generating-sortkeys}
If the user's style template file selects the citation order to be \code{citenum} or \code{none}, then creating the ordered citation list is as simple as listing the citation keys in order of their citation appearance, which was recorded as the value in the citation dictionary. If the user instead chooses the citation order to be \code{citekey}, then all that is needed is to sort the citation keys alphabetically. Similar operations follow for the various citation order options, but the difficult lies in correctly sorting in the presence of non-ASCII languages, and especially in the presence of LaTeX markup of non-ASCII names. For a citation sorting order that requires using author names, any LaTeX markup needs to be converted to its Unicode equivalent prior to sorting. Using unicode allows the sorting to be done with any input languages, and allows the sorting order to be locale-dependent.

\code{create\_citation\_list()} is the highest-level function for generating the citation list. For each citation key, it calls \code{generate\_sortkey()}, which is the workhorse function for including all of the various options when generating the key to use for sorting the list. A key part of the function is a call to \code{purify\_string()}, which removes unnecessary LaTeX markup elements and then calls \code{latex\_to\_utf8()} to convert LaTeX-markup non-ASCII characters to Unicode. It is only after all of these conversions that the final sorting is performed and the sorted citation list returned.


\section{Testing}
\label{developer_guide:testing}
The suite of regression tests for Bibulous consist of various template definitions and database entries designed to test individual features of the program. The basic approach of the tests is as follows:
\begin{enumerate}
\item {} 
Once a change is made to the code (to fix a bug or add functionality), the developer also adds an entry to the \code{test/test1.bib} file, where the entry's ``entrytype'' is named in such a way to give an indication of what the test is for. For example, the entry in the BIB file may be defined with:

\begin{Verbatim}[commandchars=\\\{\}]
@initialize1\PYGZob{}...
\end{Verbatim}

where the developer provides an \code{author} field in the entry where one or more authors have names which are difficult to for generating initials correctly. The developer should also include at least a 1-line comment about the purpose of the entry as well. To make everything easy to find, use the entrytype as the entry's key as well. Thus, the example above would use:

\begin{Verbatim}[commandchars=\\\{\}]
@initialize1\PYGZob{}initialize1, ...
\end{Verbatim}

\item {} 
If the above new entry is something which can be checked with normal options settings, then the developer should add a corresponding line in the BST file defining how that new entrytype (i.e. \code{initialize1}) should be formatted. If \emph{different} options settings are needed, then a new BST file is needed. Only a minimalist file is generally needed: the file can, for example, contain one line defining a new entrytype and one line to define the new option setting. You can define all of the other options if you want, but these are redundant and introduce a number of unnecessary ``overwriting option value...'' warning messages.

\item {} 
Next, the developer should add a line \code{\textbackslash{}citation\{entrytype\}} to the AUX file where the \code{entrytype} is the key given in the new entry of the BIB file you just put in (e.g. \code{initialize1}). This is the same as the entrytype to keep everything consistent.

\item {} 
Next, the developer needs to add two lines to the \code{test1\_target.bbl} file to say what the formatted result should look like. Take a look at other lines to get a feel for how these should look, and take in consideration the form of the template just added to the BST file.

\item {} 
Finally, run \code{bibulous\_test.py} to check the result. This script will load the modified BIB and BST files and will write out several formatted BBL file \code{test1.bbl} etc. It will then run a \code{diff} program on the output file versus the target BBL file to see if there are any differences between the target and actual output BBL files.

\end{enumerate}


\section{Generating the documentation}
\label{developer_guide:generating-the-documentation}
The documentation is written in reStructuredText (RST) and converted to HTML using Sphinx. Sphinx can also use LaTeX to convert the HTML files into a PDF.

From the bibulous repository \code{doc/} subfolder, run \code{make html} to generate the HTML documentation. The result can be found in \code{doc/\_build/html/}, with \code{index.html} as the main file. To generate the PDF documentation, run \code{make latexpdf} from the \code{doc/} subfolder, with the result found at \code{doc/\_build/latex/Bibulous.pdf}.

While the documentation is saved in the \code{doc/} folder on the main branch, this is not automatically converted into viewable, linked HTML on GitHub. To achieve that requires pushing the updated docs into the \code{gh-pages} branch. One way of doing this is the following. Make a local copy of the main branch's \code{doc/} folder. Switch to the \code{gh-pages} branch (i.e. \code{git checkout gh-pages}) and replace everything there with the locally-copied \code{doc/} folder contents. Then update: \code{git add -A} and \code{git push origin gh-pages}. And switch back to the main branch, \code{git checkout master}.


\section{Miscellaneous notes}
\label{developer_guide:miscellaneous-notes}
The code includes two different variables, \code{citekey} and \code{entrykey} which for any given entry are always identical. So it would appear that they are redundant. But the keys in the \code{citedict} dictionary, and the keys specifying each entry in the database, belong to different sets. That is, the list of entry keys can be from every entry in the database, even entries that were not cited. The list of citation keys, however, contains only those keys that were cited, and so can be a much smaller list.


\chapter{Examples}
\label{examples::doc}\label{examples:examples}

\section{Example 1}
\label{examples:example-1}
The following example is taken from a question posted at \code{http://tex.stackexchange.com/questions/147675/bibtex-scientific-style-with-pages-at-the-end}, where the desired bibliography format is given as:

\includegraphics[width=0.500\linewidth]{example1a.png}

With Bibulous, we can easily provide templates that provide the formatting that the OP asks for:

\begin{Verbatim}[commandchars=\\\{\}]
TEMPLATES:
article = \PYGZbs{}textit\PYGZob{}\PYGZlt{}au\PYGZgt{}\PYGZcb{} \PYGZlt{}title\PYGZgt{} // \PYGZlt{}journal\PYGZgt{} -- \PYGZlt{}year\PYGZgt{}. -- Vol.\PYGZti{}\PYGZlt{}volume\PYGZgt{}. P.\PYGZti{}[\PYGZlt{}startpage\PYGZgt{} -- \PYGZlt{}endpage\PYGZgt{}\textbar{}\PYGZlt{}startpage\PYGZgt{}\textbar{}\PYGZlt{}eid\PYGZgt{}\textbar{}].
book = \PYGZbs{}textit\PYGZob{}\PYGZlt{}au\PYGZgt{}\PYGZcb{} \PYGZlt{}title\PYGZgt{}. [Ch.\PYGZti{}\PYGZlt{}chapter\PYGZgt{}. ]-- \PYGZlt{}address\PYGZgt{}: \PYGZlt{}publisher\PYGZgt{}, \PYGZlt{}year\PYGZgt{}.[ -- \PYGZlt{}startpage\PYGZgt{}\PYGZti{}p.]
inbook = \PYGZbs{}textit\PYGZob{}\PYGZlt{}au\PYGZgt{}\PYGZcb{} \PYGZlt{}title\PYGZgt{} // \PYGZlt{}booktitle\PYGZgt{}[ / Ed. by \PYGZlt{}ed.if\PYGZus{}singular(editorlist, nothing, etal\PYGZus{}message)\PYGZgt{}]. -- \PYGZlt{}address\PYGZgt{}: ...
         \PYGZlt{}publisher\PYGZgt{}, \PYGZlt{}year\PYGZgt{}.[ -- P.\PYGZti{}\PYGZlt{}startpage\PYGZgt{} -- \PYGZlt{}endpage\PYGZgt{}\textbar{} -- P.\PYGZti{}\PYGZlt{}startpage\PYGZgt{}\textbar{} -- P.\PYGZti{}\PYGZlt{}eid\PYGZgt{}\textbar{}].
inproceedings = \PYGZbs{}textit\PYGZob{}\PYGZlt{}au\PYGZgt{}\PYGZcb{} \PYGZlt{}title\PYGZgt{} // \PYGZlt{}booktitle\PYGZgt{}[ / Ed. by \PYGZlt{}ed.if\PYGZus{}singular(editorlist, nothing, etal\PYGZus{}message)\PYGZgt{}]. -- ...
                \PYGZlt{}publisher\PYGZgt{}, \PYGZlt{}address\PYGZgt{}, \PYGZlt{}year\PYGZgt{}. -- P.\PYGZti{}[\PYGZlt{}startpage\PYGZgt{} -- \PYGZlt{}endpage\PYGZgt{}\textbar{}\PYGZlt{}startpage\PYGZgt{}\textbar{}\PYGZlt{}eid\PYGZgt{}\textbar{}].

SPECIAL-TEMPLATES:
authorlist = \PYGZlt{}author.to\PYGZus{}namelist()\PYGZgt{}
editorlist = \PYGZlt{}editor.to\PYGZus{}namelist()\PYGZgt{}
authorname.n = [\PYGZlt{}authorlist.n.prefix\PYGZgt{} ]\PYGZlt{}authorlist.n.last\PYGZgt{}[ \PYGZlt{}authorlist.n.first.initial()\PYGZgt{}.][ \PYGZlt{}authorlist.n.middle.initial()\PYGZgt{}.][,  \PYGZlt{}authorlist.n.suffix\PYGZgt{}.]
au = \PYGZlt{}authorname.0\PYGZgt{}, ..., \PYGZlt{}authorname.9\PYGZgt{}
ed = [\PYGZlt{}editorlist.0.first.initial()\PYGZgt{}. ][ \PYGZlt{}editorlist.0.middle.initial()\PYGZgt{}. ][\PYGZlt{}editorlist.0.prefix\PYGZgt{} ]\PYGZlt{}editorlist.0.last\PYGZgt{}[,  \PYGZlt{}editorlist.0.suffix\PYGZgt{}.]

OPTIONS:
nothing = \PYGZob{}\PYGZcb{}
\end{Verbatim}

so that if we use this template together with the following database file:

\begin{Verbatim}[commandchars=\\\{\}]
@article\PYGZob{}Holzwarth,
    author = \PYGZob{}G. Holzwarth and G. Eckart\PYGZcb{},
    title = \PYGZob{}Fluid-dynamical approximation for finite Fermi systems\PYGZcb{},
    journal = \PYGZob{}Nucl. Phys.\PYGZcb{},
    year = 1979,
    volume = \PYGZob{}A325\PYGZcb{},
    pages = \PYGZob{}1-30\PYGZcb{}
\PYGZcb{}
@book\PYGZob{}Bertsch,
    author = \PYGZob{}G. F. Bertsch and R. A. Broglia\PYGZcb{},
    title = \PYGZob{}Oscillations in finite quantum systems\PYGZcb{},
    chapter = 6,
    address = \PYGZob{}Cambridge\PYGZcb{},
    publisher = \PYGZob{}Cambridge University\PYGZcb{},
    year = 1994,
    pages = 150
\PYGZcb{}
@inbook\PYGZob{}Woude,
    author = \PYGZob{}A. \PYGZob{}Van der Woude\PYGZcb{}\PYGZcb{},
    title = \PYGZob{}The electric giant resonances\PYGZcb{},
    booktitle = \PYGZob{}Electric and magnetic giant resonances in nuclei\PYGZcb{},
    editor = \PYGZob{}J. Speth\PYGZcb{},
    address = \PYGZob{}Singapore\PYGZcb{},
    publisher = \PYGZob{}World Scientific P.C.\PYGZcb{},
    year = 1991,
    pages = \PYGZob{}99-232\PYGZcb{}
\PYGZcb{}
@inproceedings\PYGZob{}Smolanzuk,
    author = \PYGZob{}R. Smolanzuk and J. Skalski and A. Sobiczewski\PYGZcb{},
    title = \PYGZob{}Masses and half-life of superheavy elements\PYGZcb{},
    booktitle = \PYGZob{}Proc.\PYGZbs{} of the International Workshop 24 on Gross Properties of Nuclei and Nuclear Excitations\PYGZcb{},
    editor = \PYGZob{}H. Feldmeier and others\PYGZcb{},
    address = \PYGZob{}Darmstadt\PYGZcb{},
    publisher = \PYGZob{}GSI\PYGZcb{},
    year = 1996,
    pages = \PYGZob{}35-42\PYGZcb{}
\PYGZcb{}
\end{Verbatim}

then we get the formatted result shown below

\includegraphics[width=0.600\linewidth]{example1b.png}


\bigskip\hrule{}\bigskip



\section{Example 2}
\label{examples:example-2}
The next example is taken from the bibliography style found in: Dimitri Mihalas and James Binney, \_Galactic Astronomy: Structure and {\color{red}\bfseries{}Kinematics\_}, 2nd ed. (W. H. Freeman, New York, 1981). A snapshot from the the book's bibliography looks like

\includegraphics[width=0.600\linewidth]{example2a.png}

To produce this style, we can define the following templates:

\begin{Verbatim}[commandchars=\\\{\}]
TEMPLATES:
article = \PYGZlt{}au\PYGZgt{} \PYGZlt{}year\PYGZgt{}. \PYGZbs{}textit\PYGZob{}\PYGZlt{}journal\PYGZgt{}\PYGZcb{} \PYGZbs{}textbf\PYGZob{}\PYGZlt{}volume\PYGZgt{}\PYGZcb{}:\PYGZlt{}pages\PYGZgt{}.
book = [\PYGZlt{}au\PYGZgt{}\textbar{}\PYGZlt{}ed.if\PYGZus{}singular(editorlist, eds\PYGZus{}msg1, eds\PYGZus{}msg2)\PYGZgt{}\textbar{}]. \PYGZlt{}year\PYGZgt{}. \PYGZbs{}textit\PYGZob{}\PYGZlt{}title\PYGZgt{}\PYGZcb{}. (\PYGZlt{}address\PYGZgt{}: \PYGZlt{}publisher\PYGZgt{}).
proceedings = book
phdthesis = \PYGZlt{}au\PYGZgt{} \PYGZlt{}year\PYGZgt{}. Ph.D. Thesis, \PYGZlt{}university\PYGZgt{}.


SPECIAL-TEMPLATES:
authorlist = \PYGZlt{}author.to\PYGZus{}namelist()\PYGZgt{}
editorlist = \PYGZlt{}editor.to\PYGZus{}namelist()\PYGZgt{}
authorname.n = [\PYGZlt{}authorlist.n.prefix\PYGZgt{} ]\PYGZlt{}authorlist.n.last\PYGZgt{}[, \PYGZlt{}authorlist.n.first.initial()\PYGZgt{}.][ \PYGZlt{}authorlist.n.middle.initial()\PYGZgt{}.][,  \PYGZlt{}authorlist.n.suffix\PYGZgt{}.]
au = \PYGZlt{}authorname.0\PYGZgt{}, ...,\PYGZob{} and \PYGZcb{}\PYGZlt{}authorname.9\PYGZgt{}
editorname.n = [\PYGZlt{}editorlist.n.prefix\PYGZgt{} ]\PYGZlt{}editorlist.n.last\PYGZgt{}[, \PYGZlt{}editorlist.n.first.initial()\PYGZgt{}.][ \PYGZlt{}editorlist.n.middle.initial()\PYGZgt{}.][,  \PYGZlt{}editorlist.n.suffix\PYGZgt{}.]
ed = \PYGZlt{}editorname.0\PYGZgt{}, ...,\PYGZob{} and \PYGZcb{}\PYGZlt{}editorname.5\PYGZgt{}
authorlabel = [\PYGZlt{}authorlist.0.prefix\PYGZgt{}\textbar{}\PYGZlt{}authorlist.0.last\PYGZgt{}]
editorlabel = [\PYGZlt{}editorlist.0.prefix\PYGZgt{}\textbar{}\PYGZlt{}editorlist.0.last\PYGZgt{}]
sortkey = [\PYGZlt{}authorlabel\PYGZgt{}\PYGZlt{}year.zfill(4)\PYGZgt{}\textbar{}\PYGZlt{}editorlabel\PYGZgt{}\PYGZlt{}year\PYGZgt{}]
citelabel = (\PYGZlt{}citealnum\PYGZgt{})


OPTIONS:
eds\PYGZus{}msg1 = \PYGZob{} \PYGZcb{}(ed.)
eds\PYGZus{}msg2 = \PYGZob{} \PYGZcb{}(eds.)
use\PYGZus{}citeextract = True
\end{Verbatim}

so that with the following database file:

\begin{Verbatim}[commandchars=\\\{\}]
@book\PYGZob{}Blaauw1965,
    editor = \PYGZob{}A. Blaauw and M. Schmidt\PYGZcb{},
    title = \PYGZob{}Galactic Structure\PYGZcb{},
    address = \PYGZob{}Chicago\PYGZcb{},
    publisher = \PYGZob{}University of Chicago Press\PYGZcb{},
    year = 1965
\PYGZcb{}
@article\PYGZob{}Bok1977,
    author = \PYGZob{}B. J. Bok\PYGZcb{},
    journal = \PYGZob{}Publ. Astron. Soc. Pacific\PYGZcb{},
    year = 1977,
    volume = 89,
    pages = 597
\PYGZcb{}
@phdthesis\PYGZob{}Bosma1978,
    author = \PYGZob{}A. Bosma\PYGZcb{},
    university = \PYGZob{}University of Groningen, Netherlands\PYGZcb{},
    year = 1978
\PYGZcb{}
@article\PYGZob{}Burke1957,
    author = \PYGZob{}B. F. Burke\PYGZcb{},
    journal = \PYGZob{}Astron. J.\PYGZcb{},
    year = 1957,
    volume = 62,
    pages = 90
\PYGZcb{}
@article\PYGZob{}Burton1970,
    author = \PYGZob{}W. B. Burton\PYGZcb{},
    journal = \PYGZob{}Astron. and Astrophys.\PYGZcb{},
    year = 1970,
    volume = 10,
    pages = 76
\PYGZcb{}
@article\PYGZob{}Burton1972,
    author = \PYGZob{}W. B. Burton\PYGZcb{},
    journal = \PYGZob{}Astron. and Astrophys.\PYGZcb{},
    year = 1972,
    volume = 19,
    pages = 51
\PYGZcb{}
@article\PYGZob{}Burton1976,
    author = \PYGZob{}W. B. Burton\PYGZcb{},
    journal = \PYGZob{}Ann. Rev. Astron. and Astrophys.\PYGZcb{},
    year = 1976,
    volume = 14,
    pages = 275
\PYGZcb{}
@article\PYGZob{}Burton1978,
    author = \PYGZob{}W. B. Burton and M. A. Gordon\PYGZcb{},
    journal = \PYGZob{}Astron. and Astrophys.\PYGZcb{},
    year = 1978,
    volume = 63,
    pages = 7
\PYGZcb{}
@book\PYGZob{}Chiu1970,
    editor = \PYGZob{}H.-Y. Chiu and A. Muriel\PYGZcb{},
    title = \PYGZob{}Galactic Astronomy\PYGZcb{},
    year = 1970,
    address = \PYGZob{}New York\PYGZcb{},
    publisher = \PYGZob{}Gordon and Breach\PYGZcb{}
\PYGZcb{}
@article\PYGZob{}Cohen1976,
    author = \PYGZob{}R. J. Cohen and R. D. Davies\PYGZcb{},
    journal = \PYGZob{}Mon. Not. Roy. Astron. Soc.\PYGZcb{},
    year = 1976,
    volume = 175,
    pages = 1
\PYGZcb{}
@article\PYGZob{}Dickman1978,
    author = \PYGZob{}R. L. Dickman\PYGZcb{},
    journal = \PYGZob{}Astrophys. J. Supp.\PYGZcb{},
    year = 1978,
    volume = 37,
    pages = 407
\PYGZcb{}
@article\PYGZob{}Emerson1978,
    author = \PYGZob{}D. T. Emerson\PYGZcb{},
    journal = \PYGZob{}Astron. and Astrophys.\PYGZcb{},
    year = 1978,
    volume = 63,
    pages = \PYGZob{}L29\PYGZcb{},
\PYGZcb{}
@proceedings\PYGZob{}Fichtel1977,
    editor = \PYGZob{}C. E. Fichtel and F. W. Stecker\PYGZcb{},
    title = \PYGZob{}The Structure and Content of the Galaxy and Galactic Gamma Rays\PYGZcb{},
    address = \PYGZob{}Washington, D.C.\PYGZcb{},
    publisher = \PYGZob{}NASA\PYGZcb{},
    year = 1977
\PYGZcb{}
\end{Verbatim}

we get the following formatted result

\includegraphics[width=0.600\linewidth]{example2b.png}


\bigskip\hrule{}\bigskip



\section{Example 3}
\label{examples:example-3}
The next example illustrates the style used by the Optical Society of America (OSA) for their journals. The following formatted bibliography

\includegraphics[width=0.600\linewidth]{example3.png}

is obtained using the template

\begin{Verbatim}[commandchars=\\\{\}]
TEMPLATES:
article = \PYGZlt{}au\PYGZgt{}, \PYGZbs{}enquote\PYGZob{}[\PYGZbs{}href\PYGZob{}\PYGZlt{}url\PYGZgt{}\PYGZcb{}\PYGZob{}\PYGZlt{}title\PYGZgt{}\PYGZcb{}\textbar{}\PYGZbs{}href\PYGZob{}\PYGZlt{}doi\PYGZgt{}\PYGZcb{}\PYGZob{}\PYGZlt{}title\PYGZgt{}\PYGZcb{}\textbar{}\PYGZlt{}title\PYGZgt{}],\PYGZcb{} \PYGZlt{}journal\PYGZgt{} \PYGZbs{}textbf\PYGZob{}\PYGZlt{}volume\PYGZgt{}\PYGZcb{},\PYGZob{} \PYGZcb{}...
        [\PYGZlt{}startpage\PYGZgt{}--\PYGZlt{}endpage\PYGZgt{}\textbar{}\PYGZlt{}startpage\PYGZgt{}\textbar{}\PYGZlt{}eid\PYGZgt{}\textbar{}] (\PYGZlt{}year\PYGZgt{}).[ \PYGZlt{}note\PYGZgt{}]
book = [\PYGZlt{}au\PYGZgt{}\textbar{}\PYGZlt{}ed\PYGZgt{}\textbar{}\PYGZlt{}organization\PYGZgt{}\textbar{}\PYGZlt{}institution\PYGZgt{}\textbar{}], \PYGZbs{}textit\PYGZob{}\PYGZlt{}title\PYGZgt{}\PYGZcb{}[, \PYGZlt{}edition.ordinal()\PYGZgt{}\PYGZti{}ed.][, vol.\PYGZti{}\PYGZlt{}volume\PYGZgt{}]\PYGZob{} \PYGZcb{}...
        (\PYGZlt{}publisher\PYGZgt{}, \PYGZlt{}year\PYGZgt{})[ Chap.\PYGZti{}\PYGZlt{}chapter\PYGZgt{}][, pp.\PYGZti{}\PYGZlt{}startpage\PYGZgt{}--\PYGZlt{}endpage\PYGZgt{}\textbar{}, p.\PYGZti{}\PYGZlt{}startpage\PYGZgt{}].[ \PYGZlt{}note\PYGZgt{}]
endnote = \PYGZlt{}note\PYGZgt{}
inbook = incollection
incollection = \PYGZlt{}au\PYGZgt{}, \PYGZbs{}enquote\PYGZob{}\PYGZlt{}title\PYGZgt{},\PYGZcb{} in \PYGZbs{}textit\PYGZob{}\PYGZlt{}booktitle\PYGZgt{}\PYGZcb{}, [vol.\PYGZti{}\PYGZlt{}volume\PYGZgt{}, ][\PYGZlt{}edition.ordinal()\PYGZgt{}\PYGZti{}ed., ]...
        [\PYGZlt{}ed\PYGZgt{}, ][\PYGZlt{}series\PYGZgt{}, ][Chap.\PYGZti{}\PYGZlt{}chapter\PYGZgt{}, ][pp.\PYGZti{}\PYGZlt{}startpage\PYGZgt{}--\PYGZlt{}endpage\PYGZgt{}\textbar{}p.\PYGZti{}\PYGZlt{}startpage\PYGZgt{}\textbar{}\PYGZlt{}eid\PYGZgt{}\textbar{}] (\PYGZlt{}publisher\PYGZgt{}, \PYGZlt{}year\PYGZgt{}).[ \PYGZlt{}note\PYGZgt{}]
inproceedings = \PYGZlt{}au\PYGZgt{}, \PYGZbs{}enquote\PYGZob{}\PYGZlt{}title\PYGZgt{},\PYGZcb{} in \PYGZbs{}textit\PYGZob{}\PYGZlt{}booktitle\PYGZgt{}\PYGZcb{}[, \PYGZlt{}ed\PYGZgt{}][, in \PYGZlt{}series\PYGZgt{}][ \PYGZbs{}textbf\PYGZob{}\PYGZlt{}volume\PYGZgt{}\PYGZcb{}]...
        [, pp.\PYGZti{}\PYGZlt{}startpage\PYGZgt{}--\PYGZlt{}endpage\PYGZgt{}\textbar{}, p.\PYGZti{}\PYGZlt{}startpage\PYGZgt{}\textbar{}, \PYGZlt{}eid\PYGZgt{}] (\PYGZlt{}year\PYGZgt{}).[ \PYGZlt{}note\PYGZgt{}]
manual = [\PYGZlt{}au\PYGZgt{}\textbar{}\PYGZlt{}ed\PYGZgt{}\textbar{}\PYGZlt{}organization\PYGZgt{}\textbar{}\PYGZlt{}institution\PYGZgt{}\textbar{}], \PYGZbs{}textit\PYGZob{}\PYGZlt{}title\PYGZgt{}\PYGZcb{}[, vol.\PYGZti{}\PYGZlt{}volume\PYGZgt{}]...
        [, \PYGZlt{}edition.ordinal()\PYGZgt{}\PYGZti{}ed.\textbar{}, ver.\PYGZti{}\PYGZlt{}version\PYGZgt{}][, \PYGZlt{}ed\PYGZgt{}] (\PYGZlt{}organization\PYGZgt{}, \PYGZlt{}year\PYGZgt{})[, Chap.\PYGZti{}\PYGZlt{}chapter\PYGZgt{}]...
        [, pp.\PYGZti{}\PYGZlt{}startpage\PYGZgt{}--\PYGZlt{}endpage\PYGZgt{}\textbar{}, p.\PYGZti{}\PYGZlt{}startpage\PYGZgt{}].[ \PYGZlt{}note\PYGZgt{}]
mastersthesis = \PYGZlt{}au\PYGZgt{}, \PYGZbs{}enquote\PYGZob{}\PYGZlt{}title\PYGZgt{},\PYGZcb{} M.S. dissertation (\PYGZlt{}school\PYGZgt{}, \PYGZlt{}year\PYGZgt{}).[ \PYGZlt{}note\PYGZgt{}]
misc = [\PYGZlt{}au\PYGZgt{}, ][\PYGZbs{}enquote\PYGZob{}\PYGZlt{}title\PYGZgt{}\PYGZcb{}][ (\PYGZlt{}organization\PYGZgt{}, \PYGZlt{}year\PYGZgt{})\textbar{} (\PYGZlt{}year\PYGZgt{})].[ \PYGZlt{}note\PYGZgt{}][ (url: \PYGZbs{}url\PYGZob{}\PYGZlt{}url\PYGZgt{}\PYGZcb{})]
patent = \PYGZlt{}au\PYGZgt{}, \PYGZbs{}enquote\PYGZob{}\PYGZlt{}title\PYGZgt{},\PYGZcb{} \PYGZlt{}nationality\PYGZgt{} patent \PYGZlt{}number\PYGZgt{} (\PYGZlt{}year\PYGZgt{}).[ \PYGZlt{}note\PYGZgt{}]
phdthesis = \PYGZlt{}au\PYGZgt{}, \PYGZbs{}enquote\PYGZob{}\PYGZlt{}title\PYGZgt{},\PYGZcb{} Ph.D. dissertation (\PYGZlt{}school\PYGZgt{}, \PYGZlt{}year\PYGZgt{}).[ \PYGZlt{}note\PYGZgt{}]
poster = \PYGZlt{}au\PYGZgt{}, \PYGZbs{}enquote\PYGZob{}\PYGZlt{}title\PYGZgt{}\PYGZcb{}, poster [presented at \PYGZlt{}conference\PYGZgt{}]([\PYGZlt{}month\PYGZgt{} ]\PYGZlt{}year\PYGZgt{}).[ \PYGZlt{}note\PYGZgt{}]
presentation = \PYGZlt{}au\PYGZgt{}, \PYGZbs{}enquote\PYGZob{}\PYGZlt{}title\PYGZgt{}\PYGZcb{}, presentation [presented at \PYGZlt{}conference\PYGZgt{}]([\PYGZlt{}month\PYGZgt{} ]\PYGZlt{}year\PYGZgt{}).[ \PYGZlt{}note\PYGZgt{}]
proceedings = \PYGZlt{}ed\PYGZgt{}, \PYGZbs{}textit\PYGZob{}\PYGZlt{}title\PYGZgt{}\PYGZcb{}, [vol.\PYGZti{}\PYGZlt{}volume\PYGZgt{}][, \PYGZlt{}edition.ordinal()\PYGZgt{}\PYGZti{}ed.] (\PYGZlt{}year\PYGZgt{}).[ \PYGZlt{}note\PYGZgt{}]
techreport = [\PYGZlt{}au\PYGZgt{}\textbar{}\PYGZlt{}ed\PYGZgt{}\textbar{}\PYGZlt{}organization\PYGZgt{}\textbar{}\PYGZlt{}institution\PYGZgt{}\textbar{}], \PYGZbs{}enquote\PYGZob{}\PYGZlt{}title\PYGZgt{},\PYGZcb{} \PYGZlt{}institution\PYGZgt{}, Tech. Rep. \PYGZlt{}number\PYGZgt{} (\PYGZlt{}year\PYGZgt{}).[ \PYGZlt{}note\PYGZgt{}]
website = \PYGZbs{}href\PYGZob{}[\PYGZlt{}url\PYGZgt{}\textbar{}\PYGZlt{}doi\PYGZgt{}]\PYGZcb{}\PYGZob{}[\PYGZlt{}url\PYGZgt{}\textbar{}\PYGZlt{}doi\PYGZgt{}]\PYGZcb{}

SPECIAL-TEMPLATES:
sortkey = \PYGZlt{}citenum.zfill(2)\PYGZgt{}              \PYGZsh{}\PYGZsh{} order the reference list in the same order as the citations were given in
citelabel = \PYGZlt{}citenum\PYGZgt{}.                    \PYGZsh{}\PYGZsh{} use numeric reference labels

OPTIONS:
maxauthors = 25                           \PYGZsh{}\PYGZsh{} if more than 25 authors, then use "et al." format (only applied when using the default "\PYGZlt{}au\PYGZgt{}" variable)
minauthors = 9                            \PYGZsh{}\PYGZsh{} if "maxauthors" is exceeded, then display only the first "minauthors" and et al. (only applied when using the default "\PYGZlt{}au\PYGZgt{}" variable)
maxeditors = 5                            \PYGZsh{}\PYGZsh{} if more than 5 editors, then use "et al." format (only applied when using the default "\PYGZlt{}ed\PYGZgt{}" variable)
mineditors = 5                            \PYGZsh{}\PYGZsh{} if "maxeditors" is exceeded, then display only the first "mineditors" and et al. (only applied when using the default "\PYGZlt{}ed\PYGZgt{}" variable)
procspie\PYGZus{}as\PYGZus{}journal = True                \PYGZsh{}\PYGZsh{} treat SPIE conference proceedings like a journal, with journal name 'Proc. SPIE'
sort\PYGZus{}case = False                         \PYGZsh{}\PYGZsh{} whether to use case-sensitive citation sorting (default is False)
use\PYGZus{}abbrevs = True                        \PYGZsh{}\PYGZsh{} whether to use the abbreviation strings (mainly useful for debugging)
french\PYGZus{}initials = False                   \PYGZsh{}\PYGZsh{} whether to use French initials (i.e. Jean-Paul -\PYGZgt{} J.-P. and not J., also Philippe -\PYGZgt{} Ph. not P.)
bibitemsep = 0pt                          \PYGZsh{}\PYGZsh{} the extra vertical separation between each bibliography entry. Defining this option *overrides* LaTeX's existing definition for \PYGZbs{}bibitemsep.
etal\PYGZus{}message = , \PYGZbs{}textit\PYGZob{}et\PYGZti{}al.\PYGZcb{}          \PYGZsh{}\PYGZsh{} what text to place at the end of an authorlist when there are too many
edmsg1 = , ed.                            \PYGZsh{}\PYGZsh{} the label to use after the editor namelist when only one editor is present
edmsg2 = , eds                            \PYGZsh{}\PYGZsh{} the label to use after the editor namelist when multiple editors are present

\PYGZsh{}\PYGZsh{} The remaining exceptions below are really for users rather than for the journal. Maybe put these someplace else?
undefstr = ???                            \PYGZsh{}\PYGZsh{} what string to replace undefined required fields with
replace\PYGZus{}newlines = True                   \PYGZsh{}\PYGZsh{} whether to replace newline characters inside fields with spaces
allow\PYGZus{}scripts = False                     \PYGZsh{}\PYGZsh{} whether to allow user scripts in BST files
case\PYGZus{}sensitive\PYGZus{}field\PYGZus{}names = False        \PYGZsh{}\PYGZsh{} whether to allow field names to be case sensitive (i.e. so that "BOOK" will not be the same entrytype as "book")
use\PYGZus{}citeextract = True                    \PYGZsh{}\PYGZsh{} whether to automatically perform citation extraction each time Bibulous is run
name\PYGZus{}separator = and                      \PYGZsh{}\PYGZsh{} the string used to separate names in a BibTeX-format field of names

VARIABLES:

DEFINITIONS:
\end{Verbatim}

and the database file

\begin{Verbatim}[commandchars=\\\{\}]
@String\PYGZob{}ol       = \PYGZob{}Opt. Lett.\PYGZcb{}\PYGZcb{}
@String\PYGZob{}procspie = \PYGZob{}Proc. SPIE\PYGZcb{}\PYGZcb{}

@Article\PYGZob{}Tkaczyk2012,
  title = \PYGZob{}Vectorial laws of refraction and reflection using the cross product and dot product\PYGZcb{},
  author = \PYGZob{}Eric R. Tkaczyk\PYGZcb{},
  journal = ol,
  volume = \PYGZob{}37\PYGZcb{},
  year = \PYGZob{}2012\PYGZcb{},
  pages = \PYGZob{}972--974\PYGZcb{},
  doi = \PYGZob{}http://dx.doi.org/10.1364/OL.37.000972\PYGZcb{}
\PYGZcb{}

@Book\PYGZob{}Smith-1992,
  title = \PYGZob{}Modern Lens Design: A Resource Manual\PYGZcb{},
  year = \PYGZob{}1992\PYGZcb{},
  address = \PYGZob{}New York\PYGZcb{},
  author = \PYGZob{}Warren J. Smith\PYGZcb{},
  publisher = \PYGZob{}McGraw-Hill\PYGZcb{}
\PYGZcb{}

@Inbook\PYGZob{}Silverman1998,
  title = \PYGZob{}Optical detection theory\PYGZcb{},
  author = \PYGZob{}Mark Silverman\PYGZcb{},
  pages = \PYGZob{}139--159\PYGZcb{},
  publisher = \PYGZob{}Princeton University Press\PYGZcb{},
  year = \PYGZob{}1998\PYGZcb{},
  booktitle = \PYGZob{}Probing the Atom: Interactions of Coupled States, Fast Beams, and Loose Electrons\PYGZcb{},
  chapter = \PYGZob{}6\PYGZcb{}
\PYGZcb{}

@Incollection\PYGZob{}Feynman1987,
  title = \PYGZob{}Negative probability\PYGZcb{},
  author = \PYGZob{}Richard P. Feynman\PYGZcb{},
  booktitle = \PYGZob{}Quantum Implications --- Essays in Honour of \PYGZob{}D\PYGZcb{}avid Bohm\PYGZcb{},
  publisher = \PYGZob{}Routledge \PYGZbs{}\PYGZam{} Kegan Paul\PYGZcb{},
  year = \PYGZob{}1987\PYGZcb{},
  pages = \PYGZob{}235--248\PYGZcb{},
  editor = \PYGZob{}B. J. Hiley and F. D. Peat\PYGZcb{}
\PYGZcb{}

@Inproceedings\PYGZob{}Descour1995a,
  title = \PYGZob{}Nonscanning no-moving-parts imaging spectrometer\PYGZcb{},
  author = \PYGZob{}Michael R. Descour and Eustace L. Dereniak\PYGZcb{},
  booktitle = \PYGZob{}Imaging Spectrometry\PYGZcb{},
  year = \PYGZob{}1995\PYGZcb{},
  pages = \PYGZob{}48--64\PYGZcb{},
  series = procspie,
  volume = \PYGZob{}2480\PYGZcb{},
  crossref = \PYGZob{}ProcSPIE2480\PYGZcb{}
\PYGZcb{}

@Manual\PYGZob{}CGAL2006,
  title = \PYGZob{}CGAL user and reference manual\PYGZcb{},
  year = \PYGZob{}2006\PYGZcb{},
  month = \PYGZob{}July\PYGZcb{},
  organization = \PYGZob{}CGAL Project\PYGZcb{}
\PYGZcb{}

@Mastersthesis\PYGZob{}RimmerDiss,
  title = \PYGZob{}Optical aberration coefficients\PYGZcb{},
  author = \PYGZob{}Matthew Peter Rimmer\PYGZcb{},
  school = \PYGZob{}University of Rochester\PYGZcb{},
  year = \PYGZob{}1963\PYGZcb{}
\PYGZcb{}

@Misc\PYGZob{}Knuth1992,
  title = \PYGZob{}Convolution polynomials\PYGZcb{},
  author = \PYGZob{}Donald E. Knuth\PYGZcb{},
  year = \PYGZob{}1992\PYGZcb{},
  url = \PYGZob{}http://arxiv.org/pdf/math/9207221.pdf\PYGZcb{}
\PYGZcb{}

@Patent\PYGZob{}Bayer1976,
  title = \PYGZob{}Color imaging array\PYGZcb{},
  author = \PYGZob{}Bryce E. Bayer\PYGZcb{},
  number = \PYGZob{}3971065\PYGZcb{},
  year = \PYGZob{}1976\PYGZcb{},
  yearfiled = \PYGZob{}1975\PYGZcb{},
  assignee = \PYGZob{}Eastman Kodak Company\PYGZcb{},
  nationality = \PYGZob{}USA\PYGZcb{}
\PYGZcb{}

@Phdthesis\PYGZob{}BroglieDiss,
  title = \PYGZob{}On the theory of quanta\PYGZcb{},
  author = \PYGZob{}Louis-Victor de Broglie\PYGZcb{},
  school = \PYGZob{}University of Paris\PYGZcb{},
  year = \PYGZob{}1925\PYGZcb{},
  note = \PYGZob{}A translation by A. F. Kracklauer of the original, Recherches sur la th\PYGZob{}\PYGZbs{}'e\PYGZcb{}orie des quanta, (Ann. de Phys., 10th series, v. III, Jan-Feb 1925).\PYGZcb{}
\PYGZcb{}

@Poster\PYGZob{}Jacquemart2012,
  title = \PYGZob{}The next HITRAN edition: description of new parameters and formats\PYGZcb{},
  author = \PYGZob{}David Jacquemart and Laurence S. Rothman\PYGZcb{},
  address = \PYGZob{}[location unknown]\PYGZcb{},
  year = \PYGZob{}2012\PYGZcb{}
\PYGZcb{}

@Presentation\PYGZob{}Boyd2006,
  title = \PYGZob{}Convex optimization - class slides\PYGZcb{},
  author = \PYGZob{}Stephen Boyd and Lieven Vandenberghe\PYGZcb{},
  year = \PYGZob{}2006\PYGZcb{}
\PYGZcb{}

@Proceedings\PYGZob{}ProcSPIE4480,
  title = \PYGZob{}Imaging Spectrometry VII\PYGZcb{},
  year = \PYGZob{}2002\PYGZcb{},
  editor = \PYGZob{}Michael R. Descour\PYGZcb{},
  series = procspie,
  volume = \PYGZob{}4480\PYGZcb{}
\PYGZcb{}

@Techreport\PYGZob{}Bohannon2009,
  title = \PYGZob{}Can people distinguish p\PYGZob{}\PYGZbs{}\PYGZca{}a\PYGZcb{}t\PYGZob{}\PYGZbs{}'e\PYGZcb{} from dog food?\PYGZcb{},
  author = \PYGZob{}John Bohannon and Robin Goldstein and Alexis Herschkowitsch\PYGZcb{},
  institution = \PYGZob{}American Association of Wine Economists\PYGZcb{},
  year = \PYGZob{}2009\PYGZcb{},
  number = \PYGZob{}51757\PYGZcb{},
  month = \PYGZob{}April\PYGZcb{}
\PYGZcb{}

@Website\PYGZob{}Zemax,
  url = \PYGZob{}www.zemax.com\PYGZcb{},
  organization = \PYGZob{}ZEMAX Development Corp.\PYGZcb{}
\PYGZcb{}
\end{Verbatim}


\bigskip\hrule{}\bigskip



\section{Example 4}
\label{examples:example-4}
The next example illustrates the style used by the society SPIE for their journals. The following formatted bibliography

\includegraphics[width=0.600\linewidth]{example4.png}

is obtained using the template

\begin{Verbatim}[commandchars=\\\{\}]
TEMPLATES:
article = \PYGZlt{}au\PYGZgt{}, \PYGZbs{}enquote\PYGZob{}\PYGZlt{}title\PYGZgt{},\PYGZcb{} [\PYGZbs{}href\PYGZob{}\PYGZlt{}url\PYGZgt{}\PYGZcb{}\PYGZob{}\PYGZbs{}textit\PYGZob{}\PYGZlt{}journal\PYGZgt{}\PYGZcb{}\PYGZcb{}\textbar{}\PYGZbs{}href\PYGZob{}\PYGZlt{}doi\PYGZgt{}\PYGZcb{}\PYGZob{}\PYGZbs{}textit\PYGZob{}\PYGZlt{}journal\PYGZgt{}\PYGZcb{}\PYGZcb{}\textbar{}\PYGZbs{}textit\PYGZob{}\PYGZlt{}journal\PYGZgt{}\PYGZcb{}]\PYGZob{} \PYGZcb{}...
        \PYGZbs{}textbf\PYGZob{}\PYGZlt{}volume\PYGZgt{}\PYGZcb{}(\PYGZlt{}number\PYGZgt{}), [\PYGZlt{}startpage\PYGZgt{}--\PYGZlt{}endpage\PYGZgt{}\textbar{}\PYGZlt{}startpage\PYGZgt{}\textbar{}\PYGZlt{}eid\PYGZgt{}\textbar{}] (\PYGZlt{}year\PYGZgt{}).[ \PYGZlt{}note\PYGZgt{}]
book = [\PYGZlt{}au\PYGZgt{}\textbar{}\PYGZlt{}ed\PYGZgt{}\textbar{}\PYGZlt{}organization\PYGZgt{}\textbar{}\PYGZlt{}institution\PYGZgt{}\textbar{}], \PYGZbs{}textit\PYGZob{}\PYGZlt{}title\PYGZgt{}\PYGZcb{}[, \PYGZlt{}edition.ordinal()\PYGZgt{}\PYGZti{}ed.][, vol.\PYGZti{}\PYGZlt{}volume\PYGZgt{}]\PYGZob{} \PYGZcb{}...
        \PYGZlt{}publisher\PYGZgt{}, \PYGZlt{}address\PYGZgt{} (\PYGZlt{}year\PYGZgt{})[ Chap.\PYGZti{}\PYGZlt{}chapter\PYGZgt{}][, pp.\PYGZti{}\PYGZlt{}startpage\PYGZgt{}--\PYGZlt{}endpage\PYGZgt{}\textbar{}, p.\PYGZti{}\PYGZlt{}startpage\PYGZgt{}].[ \PYGZlt{}note\PYGZgt{}]
endnote = Warning (entry \PYGZlt{}citekey\PYGZgt{}): Opt.\PYGZbs{} Eng.\PYGZbs{} does not allow endnotes.
inbook = incollection
incollection = \PYGZlt{}au\PYGZgt{}, \PYGZbs{}enquote\PYGZob{}\PYGZlt{}title\PYGZgt{},\PYGZcb{} in \PYGZbs{}textit\PYGZob{}\PYGZlt{}booktitle\PYGZgt{}\PYGZcb{}, [vol.\PYGZti{}\PYGZlt{}volume\PYGZgt{}, ][\PYGZlt{}edition.ordinal()\PYGZgt{}\PYGZti{}ed., ]...
        [\PYGZlt{}ed\PYGZgt{}, ][\PYGZlt{}series\PYGZgt{}, ][Chap.\PYGZti{}\PYGZlt{}chapter\PYGZgt{}, ][pp.\PYGZti{}\PYGZlt{}startpage\PYGZgt{}--\PYGZlt{}endpage\PYGZgt{}\textbar{}p.\PYGZti{}\PYGZlt{}startpage\PYGZgt{}\textbar{}\PYGZlt{}eid\PYGZgt{}\textbar{}] (\PYGZlt{}publisher\PYGZgt{}, \PYGZlt{}year\PYGZgt{}).[ \PYGZlt{}note\PYGZgt{}]
inproceedings = \PYGZlt{}au\PYGZgt{}, \PYGZbs{}enquote\PYGZob{}\PYGZlt{}title\PYGZgt{},\PYGZcb{} in \PYGZbs{}textit\PYGZob{}\PYGZlt{}booktitle\PYGZgt{}\PYGZcb{}[, \PYGZlt{}ed\PYGZgt{}][, in \PYGZlt{}series\PYGZgt{}][ \PYGZbs{}textbf\PYGZob{}\PYGZlt{}volume\PYGZgt{}\PYGZcb{}]...
        [, pp.\PYGZti{}\PYGZlt{}startpage\PYGZgt{}--\PYGZlt{}endpage\PYGZgt{}\textbar{}, p.\PYGZti{}\PYGZlt{}startpage\PYGZgt{}\textbar{}, \PYGZlt{}eid\PYGZgt{}] (\PYGZlt{}year\PYGZgt{}).[ \PYGZlt{}note\PYGZgt{}]
manual = [\PYGZlt{}au\PYGZgt{}\textbar{}\PYGZlt{}ed\PYGZgt{}\textbar{}\PYGZlt{}organization\PYGZgt{}\textbar{}\PYGZlt{}institution\PYGZgt{}\textbar{}], \PYGZbs{}textit\PYGZob{}\PYGZlt{}title\PYGZgt{}\PYGZcb{}[, vol.\PYGZti{}\PYGZlt{}volume\PYGZgt{}]...
        [, \PYGZlt{}edition.ordinal()\PYGZgt{}\PYGZti{}ed.\textbar{}, ver.\PYGZti{}\PYGZlt{}version\PYGZgt{}][, \PYGZlt{}ed\PYGZgt{}] (\PYGZlt{}organization\PYGZgt{}, \PYGZlt{}year\PYGZgt{})[, Chap.\PYGZti{}\PYGZlt{}chapter\PYGZgt{}]...
        [, pp.\PYGZti{}\PYGZlt{}startpage\PYGZgt{}--\PYGZlt{}endpage\PYGZgt{}\textbar{}, p.\PYGZti{}\PYGZlt{}startpage\PYGZgt{}].[ \PYGZlt{}note\PYGZgt{}]
mastersthesis = \PYGZlt{}au\PYGZgt{}, \PYGZbs{}enquote\PYGZob{}\PYGZlt{}title\PYGZgt{},\PYGZcb{} M.S. dissertation (\PYGZlt{}school\PYGZgt{}, \PYGZlt{}year\PYGZgt{}).[ \PYGZlt{}note\PYGZgt{}]
misc = [\PYGZlt{}au\PYGZgt{}, ][\PYGZbs{}enquote\PYGZob{}\PYGZlt{}title\PYGZgt{}\PYGZcb{}][ (\PYGZlt{}organization\PYGZgt{}, \PYGZlt{}year\PYGZgt{})\textbar{} (\PYGZlt{}year\PYGZgt{})].[ \PYGZlt{}note\PYGZgt{}][ (url: \PYGZbs{}url\PYGZob{}\PYGZlt{}url\PYGZgt{}\PYGZcb{})]
patent = \PYGZlt{}au\PYGZgt{}, \PYGZbs{}enquote\PYGZob{}\PYGZlt{}title\PYGZgt{},\PYGZcb{} \PYGZlt{}nationality\PYGZgt{} patent \PYGZlt{}number\PYGZgt{} (\PYGZlt{}year\PYGZgt{}).[ \PYGZlt{}note\PYGZgt{}]
phdthesis = \PYGZlt{}au\PYGZgt{}, \PYGZbs{}enquote\PYGZob{}\PYGZlt{}title\PYGZgt{},\PYGZcb{} Ph.D. dissertation (\PYGZlt{}school\PYGZgt{}, \PYGZlt{}year\PYGZgt{}).[ \PYGZlt{}note\PYGZgt{}]
poster = \PYGZlt{}au\PYGZgt{}, \PYGZbs{}enquote\PYGZob{}\PYGZlt{}title\PYGZgt{}\PYGZcb{}, poster [presented at \PYGZlt{}conference\PYGZgt{}]([\PYGZlt{}month\PYGZgt{} ]\PYGZlt{}year\PYGZgt{}).[ \PYGZlt{}note\PYGZgt{}]
presentation = \PYGZlt{}au\PYGZgt{}, \PYGZbs{}enquote\PYGZob{}\PYGZlt{}title\PYGZgt{}\PYGZcb{}, presentation [presented at \PYGZlt{}conference\PYGZgt{}]([\PYGZlt{}month\PYGZgt{} ]\PYGZlt{}year\PYGZgt{}).[ \PYGZlt{}note\PYGZgt{}]
proceedings = \PYGZlt{}ed\PYGZgt{}, \PYGZbs{}textit\PYGZob{}\PYGZlt{}title\PYGZgt{}\PYGZcb{}, [vol.\PYGZti{}\PYGZlt{}volume\PYGZgt{}][, \PYGZlt{}edition.ordinal()\PYGZgt{}\PYGZti{}ed.] (\PYGZlt{}year\PYGZgt{}).[ \PYGZlt{}note\PYGZgt{}]
techreport = [\PYGZlt{}au\PYGZgt{}\textbar{}\PYGZlt{}ed\PYGZgt{}\textbar{}\PYGZlt{}organization\PYGZgt{}\textbar{}\PYGZlt{}institution\PYGZgt{}\textbar{}], \PYGZbs{}enquote\PYGZob{}\PYGZlt{}title\PYGZgt{},\PYGZcb{} \PYGZlt{}institution\PYGZgt{}, \PYGZlt{}number\PYGZgt{} (\PYGZlt{}year\PYGZgt{}).[ \PYGZlt{}note\PYGZgt{}]
website = \PYGZbs{}href\PYGZob{}[\PYGZlt{}url\PYGZgt{}\textbar{}\PYGZlt{}doi\PYGZgt{}]\PYGZcb{}\PYGZob{}[\PYGZlt{}url\PYGZgt{}\textbar{}\PYGZlt{}doi\PYGZgt{}]\PYGZcb{}

SPECIAL-TEMPLATES:
sortkey = \PYGZlt{}citenum.zfill(2)\PYGZgt{}              \PYGZsh{}\PYGZsh{} order the reference list in the same order as the citations were given in
citelabel = \PYGZlt{}citenum\PYGZgt{}                     \PYGZsh{}\PYGZsh{} use numeric reference labels

OPTIONS:
maxauthors = 3                            \PYGZsh{}\PYGZsh{} if more than 3 authors, then use "et al." format (only applied when using the default "\PYGZlt{}au\PYGZgt{}" variable)
minauthors = 1                            \PYGZsh{}\PYGZsh{} if "maxauthors" is exceeded, then display only the first "minauthors" and et al. (only applied when using the default "\PYGZlt{}au\PYGZgt{}" variable)
maxeditors = 3                            \PYGZsh{}\PYGZsh{} if more than 3 editors, then use "et al." format (only applied when using the default "\PYGZlt{}ed\PYGZgt{}" variable)
mineditors = 1                            \PYGZsh{}\PYGZsh{} if "maxeditors" is exceeded, then display only the first "mineditors" and et al. (only applied when using the default "\PYGZlt{}ed\PYGZgt{}" variable)
procspie\PYGZus{}as\PYGZus{}journal = False               \PYGZsh{}\PYGZsh{} treat SPIE conference proceedings like a journal, with journal name 'Proc. SPIE'
sort\PYGZus{}case = False                         \PYGZsh{}\PYGZsh{} whether to use case-sensitive citation sorting (default is False)
use\PYGZus{}abbrevs = True                        \PYGZsh{}\PYGZsh{} whether to use the abbreviation strings (mainly useful for debugging)
bibitemsep = 0pt                          \PYGZsh{}\PYGZsh{} the extra vertical separation between each bibliography entry. Defining this option *overrides* LaTeX's existing definition for \PYGZbs{}bibitemsep.
etal\PYGZus{}message = , \PYGZbs{}textit\PYGZob{}et\PYGZti{}al.\PYGZcb{}          \PYGZsh{}\PYGZsh{} what text to place at the end of an authorlist when there are too many
edmsg1 = , ed.                            \PYGZsh{}\PYGZsh{} the label to use after the editor namelist when only one editor is present
edmsg2 = , eds                            \PYGZsh{}\PYGZsh{} the label to use after the editor namelist when multiple editors are present

\PYGZsh{}\PYGZsh{} The remaining exceptions below are really for users rather than for the journal. Maybe put these someplace else?
undefstr = ???                            \PYGZsh{}\PYGZsh{} what string to replace undefined required fields with
replace\PYGZus{}newlines = True                   \PYGZsh{}\PYGZsh{} whether to replace newline characters inside fields with spaces
allow\PYGZus{}scripts = False                     \PYGZsh{}\PYGZsh{} whether to allow user scripts in BST files
case\PYGZus{}sensitive\PYGZus{}field\PYGZus{}names = False        \PYGZsh{}\PYGZsh{} whether to allow field names to be case sensitive (i.e. "BOOK" will not be the same entrytype as "book")
name\PYGZus{}separator = and                      \PYGZsh{}\PYGZsh{} the string used to separate names in a BibTeX-format field of names

VARIABLES:

DEFINITIONS:
\end{Verbatim}

and the database file

\begin{Verbatim}[commandchars=\\\{\}]
@String\PYGZob{}ol       = \PYGZob{}Opt. Lett.\PYGZcb{}\PYGZcb{}
@String\PYGZob{}procspie = \PYGZob{}Proc. SPIE\PYGZcb{}\PYGZcb{}

@Article\PYGZob{}Tkaczyk2012,
  title = \PYGZob{}Vectorial laws of refraction and reflection using the cross product and dot product\PYGZcb{},
  author = \PYGZob{}Eric R. Tkaczyk\PYGZcb{},
  journal = ol,
  volume = \PYGZob{}37\PYGZcb{},
  number = \PYGZob{}5\PYGZcb{},
  year = \PYGZob{}2012\PYGZcb{},
  pages = \PYGZob{}972--974\PYGZcb{},
  doi = \PYGZob{}http://dx.doi.org/10.1364/OL.37.000972\PYGZcb{}
\PYGZcb{}

@Book\PYGZob{}Smith-1992,
  title = \PYGZob{}Modern Lens Design: A Resource Manual\PYGZcb{},
  year = \PYGZob{}1992\PYGZcb{},
  address = \PYGZob{}New York\PYGZcb{},
  author = \PYGZob{}Warren J. Smith\PYGZcb{},
  publisher = \PYGZob{}McGraw-Hill\PYGZcb{}
\PYGZcb{}

@Inbook\PYGZob{}Silverman1998,
  title = \PYGZob{}Optical detection theory\PYGZcb{},
  author = \PYGZob{}Mark Silverman\PYGZcb{},
  pages = \PYGZob{}139--159\PYGZcb{},
  publisher = \PYGZob{}Princeton University Press\PYGZcb{},
  year = \PYGZob{}1998\PYGZcb{},
  booktitle = \PYGZob{}Probing the Atom: Interactions of Coupled States, Fast Beams, and Loose Electrons\PYGZcb{},
  chapter = \PYGZob{}6\PYGZcb{}
\PYGZcb{}

@Incollection\PYGZob{}Feynman1987,
  title = \PYGZob{}Negative probability\PYGZcb{},
  author = \PYGZob{}Richard P. Feynman\PYGZcb{},
  booktitle = \PYGZob{}Quantum Implications --- Essays in Honour of \PYGZob{}D\PYGZcb{}avid Bohm\PYGZcb{},
  publisher = \PYGZob{}Routledge \PYGZbs{}\PYGZam{} Kegan Paul\PYGZcb{},
  year = \PYGZob{}1987\PYGZcb{},
  pages = \PYGZob{}235--248\PYGZcb{},
  editor = \PYGZob{}B. J. Hiley and F. D. Peat\PYGZcb{}
\PYGZcb{}

@Inproceedings\PYGZob{}Descour1995a,
  title = \PYGZob{}Nonscanning no-moving-parts imaging spectrometer\PYGZcb{},
  author = \PYGZob{}Michael R. Descour and Eustace L. Dereniak\PYGZcb{},
  booktitle = \PYGZob{}Imaging Spectrometry\PYGZcb{},
  year = \PYGZob{}1995\PYGZcb{},
  pages = \PYGZob{}48--64\PYGZcb{},
  series = procspie,
  volume = \PYGZob{}2480\PYGZcb{},
  crossref = \PYGZob{}ProcSPIE2480\PYGZcb{}
\PYGZcb{}

@Manual\PYGZob{}CGAL2006,
  title = \PYGZob{}CGAL user and reference manual\PYGZcb{},
  year = \PYGZob{}2006\PYGZcb{},
  month = \PYGZob{}July\PYGZcb{},
  organization = \PYGZob{}CGAL Project\PYGZcb{}
\PYGZcb{}

@Mastersthesis\PYGZob{}RimmerDiss,
  title = \PYGZob{}Optical aberration coefficients\PYGZcb{},
  author = \PYGZob{}Matthew Peter Rimmer\PYGZcb{},
  school = \PYGZob{}University of Rochester\PYGZcb{},
  year = \PYGZob{}1963\PYGZcb{}
\PYGZcb{}

@Misc\PYGZob{}Knuth1992,
  title = \PYGZob{}Convolution polynomials\PYGZcb{},
  author = \PYGZob{}Donald E. Knuth\PYGZcb{},
  year = \PYGZob{}1992\PYGZcb{},
  url = \PYGZob{}http://arxiv.org/pdf/math/9207221.pdf\PYGZcb{}
\PYGZcb{}

@Patent\PYGZob{}Bayer1976,
  title = \PYGZob{}Color imaging array\PYGZcb{},
  author = \PYGZob{}Bryce E. Bayer\PYGZcb{},
  number = \PYGZob{}3971065\PYGZcb{},
  year = \PYGZob{}1976\PYGZcb{},
  yearfiled = \PYGZob{}1975\PYGZcb{},
  assignee = \PYGZob{}Eastman Kodak Company\PYGZcb{},
  nationality = \PYGZob{}USA\PYGZcb{}
\PYGZcb{}

@Phdthesis\PYGZob{}BroglieDiss,
  title = \PYGZob{}On the theory of quanta\PYGZcb{},
  author = \PYGZob{}Louis-Victor de Broglie\PYGZcb{},
  school = \PYGZob{}University of Paris\PYGZcb{},
  year = \PYGZob{}1925\PYGZcb{},
  note = \PYGZob{}A translation by A. F. Kracklauer of the original, Recherches sur la th\PYGZob{}\PYGZbs{}'e\PYGZcb{}orie des quanta, (Ann. de Phys., 10th series, v. III, Jan-Feb 1925).\PYGZcb{}
\PYGZcb{}

@Poster\PYGZob{}Jacquemart2012,
  title = \PYGZob{}The next HITRAN edition: description of new parameters and formats\PYGZcb{},
  author = \PYGZob{}David Jacquemart and Laurence S. Rothman\PYGZcb{},
  address = \PYGZob{}[location unknown]\PYGZcb{},
  year = \PYGZob{}2012\PYGZcb{}
\PYGZcb{}

@Presentation\PYGZob{}Boyd2006,
  title = \PYGZob{}Convex optimization - class slides\PYGZcb{},
  author = \PYGZob{}Stephen Boyd and Lieven Vandenberghe\PYGZcb{},
  year = \PYGZob{}2006\PYGZcb{}
\PYGZcb{}

@Proceedings\PYGZob{}ProcSPIE4480,
  title = \PYGZob{}Imaging Spectrometry VII\PYGZcb{},
  year = \PYGZob{}2002\PYGZcb{},
  editor = \PYGZob{}Michael R. Descour\PYGZcb{},
  series = procspie,
  volume = \PYGZob{}4480\PYGZcb{}
\PYGZcb{}

@Techreport\PYGZob{}Bohannon2009,
  title = \PYGZob{}Can people distinguish p\PYGZob{}\PYGZbs{}\PYGZca{}a\PYGZcb{}t\PYGZob{}\PYGZbs{}'e\PYGZcb{} from dog food?\PYGZcb{},
  author = \PYGZob{}John Bohannon and Robin Goldstein and Alexis Herschkowitsch\PYGZcb{},
  institution = \PYGZob{}American Association of Wine Economists\PYGZcb{},
  year = \PYGZob{}2009\PYGZcb{},
  number = \PYGZob{}51757\PYGZcb{},
  month = \PYGZob{}April\PYGZcb{}
\PYGZcb{}

@Website\PYGZob{}Zemax,
  url = \PYGZob{}www.zemax.com\PYGZcb{},
  organization = \PYGZob{}ZEMAX Development Corp.\PYGZcb{}
\PYGZcb{}
\end{Verbatim}


\bigskip\hrule{}\bigskip



\section{Example 5}
\label{examples:example-5}
The following example is taken from a question posted at \code{http://tex.stackexchange.com/questions/160737/bold-labels-and-more-with-custom-bibtex-bst-and-author-year}, where an answer to the original poster's question is given as

\includegraphics[width=0.600\linewidth]{example5a.png}

That is the reference list entries should have the author list in bold, journal articles should have their title quoted using German-style quotation marks, and editor lists should be given in small caps. The first answerer to the OP's question gives an example database file

\begin{Verbatim}[commandchars=\\\{\}]
@BOOK\PYGZob{}ko,
   title = \PYGZob{}Wissenschaftlich schreiben leicht gemacht\PYGZcb{},
   publisher = \PYGZob{}Haupt\PYGZcb{},
   year = \PYGZob{}2011\PYGZcb{},
   author = \PYGZob{}Kornmeier, M.\PYGZcb{},
   number = \PYGZob{}3154\PYGZcb{},
   series = \PYGZob{}UTB\PYGZcb{},
   address = \PYGZob{}Bern\PYGZcb{},
   edition = \PYGZob{}4\PYGZcb{},
   subtitle = \PYGZob{}für Bachelor, Master und Dissertation\PYGZcb{}
\PYGZcb{}

@BOOK\PYGZob{}nial,
   title = \PYGZob{}Wissenschaftliche Arbeiten schreiben mit Word 2010\PYGZcb{},
   publisher = \PYGZob{}Addison Wesley\PYGZcb{},
   year = \PYGZob{}2011\PYGZcb{},
   author = \PYGZob{}Nicol, N. and Albrecht, R.\PYGZcb{},
   address = \PYGZob{}München\PYGZcb{},
   edition = \PYGZob{}7\PYGZcb{}
\PYGZcb{}

@ARTICLE\PYGZob{}shome,
   author = \PYGZob{}Scholz, S. and Menzl, S.\PYGZcb{},
   title = \PYGZob{}Alle Wege führen nach Rom\PYGZcb{},
   journal = \PYGZob{}Medizin Produkte Journal\PYGZcb{},
   year = \PYGZob{}2011\PYGZcb{},
   volume = \PYGZob{}18\PYGZcb{},
   pages = \PYGZob{}243-254\PYGZcb{},
   subtitle = \PYGZob{}ein Vergleich der regulatorischen Anforderungen und Medizinprodukte
   in Europa und den USA\PYGZcb{},
   issue = \PYGZob{}4\PYGZcb{}
\PYGZcb{}

@INBOOK\PYGZob{}shu,
   author = \PYGZob{}Schulz, C.\PYGZcb{},
   title = \PYGZob{}Corporate Finance für den Mittelstand\PYGZcb{},
   booktitle = \PYGZob{}Praxishandbuch Firmenkundengeschäft\PYGZcb{},
   year = \PYGZob{}2010\PYGZcb{},
   editor = \PYGZob{}Hilse, J. and Netzel, W and Simmert, D.B.\PYGZcb{},
   booksubtitle = \PYGZob{}Geschäftsfelder Risikomanagement Marketing\PYGZcb{},
   publisher = \PYGZob{}Gabler\PYGZcb{},
   pages = \PYGZob{}97-107\PYGZcb{},
   location = \PYGZob{}Wiesbaden\PYGZcb{}
\PYGZcb{}
\end{Verbatim}

that makes use of separate formatting instructions for titles and subtitles, so that an appropriate style template is

\begin{Verbatim}[commandchars=\\\{\}]
TEMPLATES:
article = \PYGZbs{}textbf\PYGZob{}\PYGZlt{}au\PYGZgt{}:\PYGZcb{} \PYGZbs{}enquote\PYGZob{}\PYGZlt{}title\PYGZgt{}\PYGZcb{}, in: \PYGZbs{}textit\PYGZob{}\PYGZlt{}journal\PYGZgt{}\PYGZcb{} \PYGZbs{}textbf\PYGZob{}\PYGZlt{}volume\PYGZgt{}\PYGZcb{} (\PYGZlt{}year\PYGZgt{}), \PYGZlt{}issue\PYGZgt{} [S.\PYGZti{}\PYGZlt{}startpage\PYGZgt{}--\PYGZlt{}endpage\PYGZgt{}\textbar{}S.\PYGZti{}\PYGZlt{}startpage\PYGZgt{}\textbar{}\PYGZlt{}eid\PYGZgt{}\textbar{}] (\PYGZlt{}year\PYGZgt{}).[ \PYGZlt{}note\PYGZgt{}]
book = [\PYGZbs{}textbf\PYGZob{}\PYGZlt{}au\PYGZgt{}:\PYGZcb{}\textbar{}\PYGZbs{}textbf\PYGZob{}\PYGZlt{}ed\PYGZgt{}\PYGZcb{} (Ed.) \PYGZbs{}textbf\PYGZob{}:\PYGZcb{}\textbar{}\PYGZlt{}organization\PYGZgt{}\textbar{}\PYGZlt{}institution\PYGZgt{}\textbar{}], \PYGZbs{}textit\PYGZob{}\PYGZlt{}title\PYGZgt{}\PYGZcb{}[, \PYGZlt{}edition\PYGZgt{}\PYGZti{}Aufl.][, (\PYGZlt{}series\PYGZgt{}; \PYGZlt{}number\PYGZgt{})][, \PYGZlt{}address\PYGZgt{}] u.a.: \PYGZlt{}publisher\PYGZgt{} \PYGZlt{}year\PYGZgt{}.[ \PYGZlt{}note\PYGZgt{}]
inbook = \PYGZbs{}textbf\PYGZob{}\PYGZlt{}au\PYGZgt{}:\PYGZcb{} \PYGZbs{}enquote\PYGZob{}\PYGZlt{}title\PYGZgt{}\PYGZcb{}, in: [\PYGZlt{}ed.upper()\PYGZgt{} (Ed.): ]\PYGZbs{}textit\PYGZob{}\PYGZlt{}booktitle\PYGZgt{}\PYGZcb{}[\PYGZbs{}textit\PYGZob{}: \PYGZlt{}booksubtitle\PYGZgt{}\PYGZcb{}], \PYGZlt{}location\PYGZgt{} u.a.: \PYGZlt{}publisher\PYGZgt{} \PYGZlt{}year\PYGZgt{}, [S.\PYGZti{}\PYGZlt{}startpage\PYGZgt{}--\PYGZlt{}endpage\PYGZgt{}\textbar{}S.\PYGZti{}\PYGZlt{}eid\PYGZgt{}\textbar{}].[ \PYGZlt{}note\PYGZgt{}]

SPECIAL-TEMPLATES:
citelabel = \PYGZlt{}citenum\PYGZgt{}
sortkey = \PYGZlt{}citenum\PYGZgt{}
\end{Verbatim}

producing the formatted result

\includegraphics[width=0.600\linewidth]{example5b.png}


\bigskip\hrule{}\bigskip



\section{Example 6}
\label{examples:example-6}
The following example is taken from a question posted at \code{http://tex.stackexchange.com/questions/147932/peerage-titles-in-the-author-field-in-bibtex}. The question's answerer responds with a Biblatex solution, in which \code{nameaddon} and \code{shortauthor} fields are added to the \code{*.bib} database file, as in

\begin{Verbatim}[commandchars=\\\{\}]
@article\PYGZob{}Rayleigh1892,
    author = \PYGZob{}Strutt, John William\PYGZcb{},
    journal = \PYGZob{}Philosophical Magazine\PYGZcb{},
    nameaddon = \PYGZob{}3rd Baron Rayleigh\PYGZcb{},
    pages = \PYGZob{}481-502\PYGZcb{},
    shortauthor = \PYGZob{}Rayleigh\PYGZcb{},
    title = \PYGZob{}On the influence of obstacles arranged in rectangular order upon the properties of a medium\PYGZcb{},
    volume = \PYGZob{}34\PYGZcb{},
    year = \PYGZob{}1892\PYGZcb{}
\PYGZcb{}
\end{Verbatim}

The formatting template makes use of these additional fields, and provides a citation label using the \code{shortauthor} field's first three characters followed by the last two characters in the \code{year} field:

\begin{Verbatim}[commandchars=\\\{\}]
TEMPLATES:
article = \PYGZlt{}au\PYGZgt{}[ (\PYGZlt{}nameaddon\PYGZgt{})], \PYGZbs{}enquote\PYGZob{}\PYGZlt{}title\PYGZgt{}\PYGZcb{}. In: \PYGZbs{}textit\PYGZob{}\PYGZlt{}journal\PYGZgt{}\PYGZcb{} \PYGZlt{}volume\PYGZgt{} (\PYGZlt{}year\PYGZgt{}), [pp.\PYGZti{}\PYGZlt{}startpage\PYGZgt{}--\PYGZlt{}endpage\PYGZgt{}\textbar{}p.\PYGZti{}\PYGZlt{}startpage\PYGZgt{}\textbar{}\PYGZlt{}eid\PYGZgt{}\textbar{}].[ \PYGZlt{}note\PYGZgt{}]

SPECIAL-TEMPLATES:
authorlist = \PYGZlt{}author.to\PYGZus{}namelist()\PYGZgt{}
editorlist = \PYGZlt{}editor.to\PYGZus{}namelist()\PYGZgt{}
authorname.n = [\PYGZlt{}authorlist.n.first\PYGZgt{} ][\PYGZlt{}authorlist.n.middle\PYGZgt{} ][\PYGZlt{}authorlist.n.prefix\PYGZgt{} ]\PYGZlt{}authorlist.n.last\PYGZgt{}[, \PYGZlt{}authorlist.n.suffix\PYGZgt{}]
au = \PYGZlt{}authorname.0\PYGZgt{}; ...; \PYGZlt{}authorname.9\PYGZgt{}
citelabel = [\PYGZlt{}shortauthor.0:2\PYGZgt{}\PYGZlt{}year.2:3\PYGZgt{}\textbar{}\PYGZlt{}authorlist.0.last.0:2\PYGZgt{}\PYGZlt{}year.2:3\PYGZgt{}\textbar{}]
sortkey = \PYGZlt{}authorlist.0.last\PYGZgt{}
\end{Verbatim}

The formatted result looks like

\includegraphics[width=0.600\linewidth]{example6.png}


\bigskip\hrule{}\bigskip



\section{Example 7}
\label{examples:example-7}
The following example is taken from a question posted at \code{http://tex.stackexchange.com/questions/145038/some-citation-numbers-in-bold-others-not/168233\#168233}, where the OP asks if there is a way to have some citations given in \textbf{bold} font. This can be achieved with a user-defined script, as shown below. With tha database file

\begin{Verbatim}[commandchars=\\\{\}]
@Article\PYGZob{}refA,
  title = \PYGZob{}Can quantum-mechanical description of physical reality be considered complete?\PYGZcb{},
  author = \PYGZob{}A. Einstein and B. Podolsky and N. Rosen\PYGZcb{},
  journal = \PYGZob{}Phys.\PYGZbs{} Rev.\PYGZcb{},
  volume = \PYGZob{}47\PYGZcb{},
  year = \PYGZob{}1935\PYGZcb{},
  pages = \PYGZob{}777--780\PYGZcb{}
\PYGZcb{}

@Book\PYGZob{}refB,
  title = \PYGZob{}Probability Theory: The Logic of Science\PYGZcb{},
  year = \PYGZob{}2003\PYGZcb{},
  author = \PYGZob{}E. T. Jaynes\PYGZcb{},
  publisher = \PYGZob{}Cambridge University Press\PYGZcb{}
\PYGZcb{}

@Incollection\PYGZob{}refC,
  title = \PYGZob{}On the present status of the radiation problem\PYGZcb{},
  author = \PYGZob{}Albert Einstein\PYGZcb{},
  booktitle = \PYGZob{}The Collected Papers of Albert Einstein\PYGZcb{},
  publisher = \PYGZob{}Princeton University Press\PYGZcb{},
  year = \PYGZob{}1989\PYGZcb{},
  pages = \PYGZob{}357--375\PYGZcb{},
  volume = \PYGZob{}2\PYGZcb{}
\PYGZcb{}

@Mastersthesis\PYGZob{}refD,
  title = \PYGZob{}Optical aberration coefficients\PYGZcb{},
  author = \PYGZob{}Matthew Peter Rimmer\PYGZcb{},
  school = \PYGZob{}University of Rochester\PYGZcb{},
  year = \PYGZob{}1963\PYGZcb{}
\PYGZcb{}

@Phdthesis\PYGZob{}refBOLD,
  title = \PYGZob{}On the theory of quanta\PYGZcb{},
  author = \PYGZob{}Louis-Victor de Broglie\PYGZcb{},
  school = \PYGZob{}University of Paris\PYGZcb{},
  year = \PYGZob{}1925\PYGZcb{}
\PYGZcb{}
\end{Verbatim}

and the style template file

\begin{Verbatim}[commandchars=\\\{\}]
TEMPLATES:
article = \PYGZlt{}au\PYGZgt{}, \PYGZbs{}enquote\PYGZob{}\PYGZlt{}title\PYGZgt{},\PYGZcb{} \PYGZbs{}textit\PYGZob{}\PYGZlt{}journal\PYGZgt{}\PYGZcb{} \PYGZbs{}textbf\PYGZob{}\PYGZlt{}volume\PYGZgt{}\PYGZcb{},\PYGZob{} \PYGZcb{}...
          [\PYGZlt{}startpage\PYGZgt{}--\PYGZlt{}endpage\PYGZgt{}\textbar{}\PYGZlt{}startpage\PYGZgt{}\textbar{}\PYGZlt{}eid\PYGZgt{}\textbar{}] (\PYGZlt{}year\PYGZgt{}).
book = \PYGZlt{}au\PYGZgt{}, \PYGZbs{}textit\PYGZob{}\PYGZlt{}title\PYGZgt{}\PYGZcb{} (\PYGZlt{}publisher\PYGZgt{}, \PYGZlt{}year\PYGZgt{}).
incollection = \PYGZlt{}au\PYGZgt{}, \PYGZbs{}enquote\PYGZob{}\PYGZlt{}title\PYGZgt{},\PYGZcb{} in \PYGZbs{}textit\PYGZob{}\PYGZlt{}booktitle\PYGZgt{}\PYGZcb{}, [Chap.\PYGZti{}\PYGZlt{}chapter\PYGZgt{}, ]...
        [pp.\PYGZti{}\PYGZlt{}startpage\PYGZgt{}--\PYGZlt{}endpage\PYGZgt{}\textbar{}p.\PYGZti{}\PYGZlt{}startpage\PYGZgt{}\textbar{}\PYGZlt{}eid\PYGZgt{}\textbar{}] (\PYGZlt{}publisher\PYGZgt{}, \PYGZlt{}year\PYGZgt{}).
mastersthesis = \PYGZlt{}au\PYGZgt{}, \PYGZbs{}enquote\PYGZob{}\PYGZlt{}title\PYGZgt{},\PYGZcb{} M.S. dissertation (\PYGZlt{}school\PYGZgt{}, \PYGZlt{}year\PYGZgt{}).
phdthesis = \PYGZlt{}au\PYGZgt{}, \PYGZbs{}enquote\PYGZob{}\PYGZlt{}title\PYGZgt{},\PYGZcb{} Ph.D. dissertation (\PYGZlt{}school\PYGZgt{}, \PYGZlt{}year\PYGZgt{}).

SPECIAL-TEMPLATES:
authorlist = \PYGZlt{}author.to\PYGZus{}namelist()\PYGZgt{}
editorlist = \PYGZlt{}editor.to\PYGZus{}namelist()\PYGZgt{}
au = \PYGZlt{}authorlist.format\PYGZus{}authorlist()\PYGZgt{}
ed = \PYGZlt{}editorlist.format\PYGZus{}editorlist()\PYGZgt{}

OPTIONS:
allow\PYGZus{}scripts = True         \PYGZsh{}\PYGZsh{} whether to allow user scripts in BST files

VARIABLES:
citelabel = create\PYGZus{}citelabel(entry, options)

DEFINITIONS:
def create\PYGZus{}citelabel(entry, options):
    numnames = len(entry['authorlist'])
    if (numnames == 0): return(entry['citenum'])
    foundit = False
    for name in entry['authorlist']:
        if (name['last'] == 'Broglie') and (name['prefix'] == 'de'):
            foundit = True
            break
    if foundit:
        return(r'\PYGZbs{}textbf\PYGZob{}' + entry['citenum'] + '\PYGZcb{}')
    else:
        return(entry['citenum'])
\end{Verbatim}

we can make use of a simple main \code{.tex} file

\begin{Verbatim}[commandchars=\\\{\}]
\PYGZbs{}documentclass\PYGZob{}article\PYGZcb{}
\PYGZbs{}usepackage\PYGZob{}cite\PYGZcb{}
\PYGZpc{}\PYGZbs{}makeatletter
\PYGZpc{}   \PYGZbs{}renewcommand\PYGZob{}\PYGZbs{}@biblabel\PYGZcb{}[1]\PYGZob{}\PYGZsh{}1.\PYGZcb{}
\PYGZpc{}\PYGZbs{}makeatother
\PYGZbs{}begin\PYGZob{}document\PYGZcb{}

Some text where I cite papers, where I want to highlight all publications by de Broglie\PYGZti{}\PYGZbs{}cite\PYGZob{}refA, refB, refC, refBOLD, refD\PYGZcb{}. 
It would be nice for the citations to to appear sorted like [1-3,\PYGZob{}\PYGZbs{}textbf 4\PYGZcb{},5].

\PYGZbs{}bibliography\PYGZob{}example7\PYGZcb{}
\PYGZbs{}bibliographystyle\PYGZob{}example7\PYGZcb{}

\PYGZbs{}end\PYGZob{}document\PYGZcb{}
\end{Verbatim}

to produce a formatted result

\includegraphics[width=0.600\linewidth]{example7.png}


\bigskip\hrule{}\bigskip



\section{Example 8}
\label{examples:example-8}
The following example is taken from a question posted at \code{http://tex.stackexchange.com/questions/169300/modify-plain-bst-file/172828\#172828}, where the OP asks for a way to customize the formatted reference list so that the first line contains the author names and date, while the second and subsequent lines are given a hanging indent. This can be achieved with the following setup. With the database file

\begin{Verbatim}[commandchars=\\\{\}]
@article\PYGZob{}Abrahams1986,
  title = \PYGZob{}Scaling description of the dielectric function near the mobility edge\PYGZcb{},
  author = \PYGZob{}Abrahams, Elihu and Lee, P. A.\PYGZcb{},
  journal = \PYGZob{}Phys. Rev. B\PYGZcb{},
  volume = \PYGZob{}33\PYGZcb{},
  issue = \PYGZob{}2\PYGZcb{},
  pages = \PYGZob{}683--689\PYGZcb{},
  year = \PYGZob{}1986\PYGZcb{},
  month = \PYGZob{}1\PYGZcb{},
  publisher = \PYGZob{}American Physical Society\PYGZcb{},
  url = \PYGZob{}http://link.aps.org/doi/10.1103/PhysRevB.33.683\PYGZcb{}
\PYGZcb{}

@book\PYGZob{}Nakayama2003,
  title = \PYGZob{}Fractal Concepts in Condensed Matter Physics\PYGZcb{},
  series = \PYGZob{}Springer Series in Solid-State Sciences\PYGZcb{},
  volume = \PYGZob{}140\PYGZcb{},
  author = \PYGZob{}Nakayama, Tsuneyoshi and Yakubo, Kousuke\PYGZcb{},
  address = \PYGZob{}New York\PYGZcb{},
  publisher = \PYGZob{}Springer\PYGZcb{},
  issn = \PYGZob{}0171-1873\PYGZcb{},
  year = \PYGZob{}2003\PYGZcb{}
\PYGZcb{}

@article\PYGZob{}Chalker1988,
  title = \PYGZob{}Scaling, diffusion, and the integer quantized Hall effect\PYGZcb{},
  author = \PYGZob{}Chalker, J. T. and Daniell, G. J.\PYGZcb{},
  journal = \PYGZob{}Phys. Rev. Lett.\PYGZcb{},
  volume = \PYGZob{}61\PYGZcb{},
  issue = \PYGZob{}5\PYGZcb{},
  pages = \PYGZob{}593--596\PYGZcb{},
  year = \PYGZob{}1988\PYGZcb{},
  month = \PYGZob{}8\PYGZcb{},
  publisher = \PYGZob{}American Physical Society\PYGZcb{},
  url = \PYGZob{}http://link.aps.org/doi/10.1103/PhysRevLett.61.593\PYGZcb{}
\PYGZcb{}

@article\PYGZob{}Chalker1990,
  journal = \PYGZob{}Physica A: Statistical Mechanics and its Applications\PYGZcb{},
  volume = \PYGZob{}167\PYGZcb{}, 
  issue = \PYGZob{}1\PYGZcb{},
  month = \PYGZob{}8\PYGZcb{},
  year = \PYGZob{}1990\PYGZcb{},
  day = \PYGZob{}1\PYGZcb{},
  pages = \PYGZob{}253-258\PYGZcb{},
  title = \PYGZob{}Scaling and eigenfunction correlations near a mobility edge\PYGZcb{},
  author = \PYGZob{}J. T. Chalker\PYGZcb{}
\PYGZcb{}

@article\PYGZob{}Pook1991,
  year = \PYGZob{}1991\PYGZcb{},
  issn = \PYGZob{}0722-3277\PYGZcb{},
  journal = \PYGZob{}Zeitschrift für Physik B Condensed Matter\PYGZcb{},
  volume = \PYGZob{}82\PYGZcb{},
  number = \PYGZob{}2\PYGZcb{},
  title = \PYGZob{}Multifractality and scaling in disordered mesoscopic systems\PYGZcb{},
  url = \PYGZob{}http://dx.doi.org/10.1007/BF01324339\PYGZcb{},
  publisher = \PYGZob{}Springer-Verlag\PYGZcb{},
  author = \PYGZob{}Pook, Werner and Janßen, Martin\PYGZcb{},
  pages = \PYGZob{}295-298\PYGZcb{}
\PYGZcb{}
\end{Verbatim}

and the style template file

\begin{Verbatim}[commandchars=\\\{\}]
TEMPLATES:
article = \PYGZbs{}textbf\PYGZob{}\PYGZlt{}au\PYGZgt{}, (\PYGZlt{}year\PYGZgt{}[-\PYGZlt{}month.monthabbrev()\PYGZgt{}[-\PYGZlt{}day\PYGZgt{}]]):\PYGZcb{}\PYGZbs{}\PYGZbs{} [\PYGZbs{}href\PYGZob{}\PYGZlt{}url\PYGZgt{}\PYGZcb{}\PYGZob{}\PYGZlt{}title\PYGZgt{}\PYGZcb{}\textbar{}\PYGZbs{}href\PYGZob{}\PYGZlt{}doi\PYGZgt{}\PYGZcb{}\PYGZob{}\PYGZlt{}title\PYGZgt{}\PYGZcb{}\textbar{}\PYGZlt{}title\PYGZgt{}\textbar{}], \PYGZbs{}textit\PYGZob{}\PYGZlt{}journal\PYGZgt{}\PYGZcb{} \PYGZbs{}textit\PYGZob{}\PYGZlt{}volume\PYGZgt{}\PYGZcb{}([\PYGZlt{}number\PYGZgt{}\textbar{}\PYGZlt{}issue\PYGZgt{}\textbar{}]), [\PYGZlt{}startpage\PYGZgt{}--\PYGZlt{}endpage\PYGZgt{}\textbar{}\PYGZlt{}startpage\PYGZgt{}\textbar{}\PYGZlt{}eid\PYGZgt{}\textbar{}].
book = \PYGZbs{}textbf\PYGZob{}[\PYGZlt{}au\PYGZgt{}\textbar{}\PYGZlt{}ed\PYGZgt{}\textbar{}], (\PYGZlt{}year\PYGZgt{}[-\PYGZlt{}month.monthabbrev()\PYGZgt{}[-\PYGZlt{}day\PYGZgt{}]]):\PYGZcb{}\PYGZbs{}\PYGZbs{} \PYGZbs{}textit\PYGZob{}\PYGZlt{}title\PYGZgt{}\PYGZcb{}[, \PYGZlt{}edition\PYGZus{}ordinal\PYGZgt{}\PYGZti{}ed.][, \PYGZlt{}series\PYGZgt{}][ \PYGZlt{}issn\PYGZgt{}], \PYGZlt{}address\PYGZgt{}: \PYGZlt{}publisher\PYGZgt{}.

SPECIAL-TEMPLATES:
authorlist = \PYGZlt{}author.to\PYGZus{}namelist()\PYGZgt{}
editorlist = \PYGZlt{}editor.to\PYGZus{}namelist()\PYGZgt{}
authorname.n = [\PYGZlt{}authorlist.n.prefix\PYGZgt{} ]\PYGZlt{}authorlist.n.last\PYGZgt{}, \PYGZlt{}authorlist.n.first.initial()\PYGZgt{}.[ \PYGZlt{}authorlist.n.middle.initial()\PYGZgt{}.][, \PYGZlt{}authorlist.n.suffix\PYGZgt{}.]
au = \PYGZlt{}authorname.0\PYGZgt{}, ...\PYGZob{} \PYGZbs{}\PYGZam{} \PYGZcb{}\PYGZlt{}authorname.9\PYGZgt{}
editorname.n = [\PYGZlt{}authorlist.n.prefix\PYGZgt{} ]\PYGZlt{}authorlist.n.last\PYGZgt{}, \PYGZlt{}authorlist.n.first.initial()\PYGZgt{}.[ \PYGZlt{}authorlist.n.middle.initial()\PYGZgt{}.][, \PYGZlt{}authorlist.n.suffix\PYGZgt{}.]
ed = \PYGZlt{}editorname.0\PYGZgt{}, ...\PYGZob{} \PYGZbs{}\PYGZam{} \PYGZcb{}\PYGZlt{}editorname.5\PYGZgt{}
citelabel = \PYGZlt{}authorlist.0.last\PYGZgt{}-\PYGZlt{}year\PYGZgt{}
sortkey = \PYGZlt{}citelabel\PYGZgt{}
\end{Verbatim}

we can make use of a simple main \code{.tex} file

\begin{Verbatim}[commandchars=\\\{\}]
\PYGZbs{}documentclass\PYGZob{}article\PYGZcb{}
\PYGZbs{}usepackage[T1]\PYGZob{}fontenc\PYGZcb{}
\PYGZbs{}usepackage[utf8]\PYGZob{}inputenc\PYGZcb{}
\PYGZbs{}usepackage[paper=letterpaper, text=\PYGZob{}5.8in,8.5in\PYGZcb{},centering]\PYGZob{}geometry\PYGZcb{}
\PYGZbs{}usepackage[colorlinks=True,urlcolor=blue,citecolor=black,breaklinks=true]\PYGZob{}hyperref\PYGZcb{}
\PYGZbs{}usepackage\PYGZob{}enumitem\PYGZcb{}
\PYGZbs{}makeatletter
   \PYGZbs{}renewcommand\PYGZob{}\PYGZbs{}@biblabel\PYGZcb{}[1]\PYGZob{}\PYGZcb{}
   \PYGZbs{}renewenvironment\PYGZob{}thebibliography\PYGZcb{}[1]
      \PYGZob{}\PYGZbs{}section*\PYGZob{}\PYGZbs{}refname\PYGZcb{}\PYGZpc{}
         \PYGZbs{}@mkboth\PYGZob{}\PYGZbs{}MakeUppercase\PYGZbs{}refname\PYGZcb{}\PYGZob{}\PYGZbs{}MakeUppercase\PYGZbs{}refname\PYGZcb{}\PYGZpc{}
         \PYGZbs{}begin\PYGZob{}enumerate\PYGZcb{}[label=\PYGZob{}\PYGZcb{},itemindent=*,leftmargin=3em]
         \PYGZbs{}@openbib@code
         \PYGZbs{}sloppy
         \PYGZbs{}clubpenalty4000
         \PYGZbs{}@clubpenalty \PYGZbs{}clubpenalty
         \PYGZbs{}widowpenalty4000
         \PYGZbs{}sfcode{}`\PYGZbs{}.\PYGZbs{}@m\PYGZcb{}
         \PYGZob{}\PYGZbs{}def\PYGZbs{}@noitemerr
            \PYGZob{}\PYGZbs{}@latex@warning\PYGZob{}Empty {}`thebibliography' environment\PYGZcb{}\PYGZcb{}\PYGZpc{}
      \PYGZbs{}end\PYGZob{}enumerate\PYGZcb{}\PYGZcb{}
\PYGZbs{}makeatother

\PYGZbs{}begin\PYGZob{}document\PYGZcb{}

\PYGZob{}\PYGZbs{}noindent\PYGZcb{}Citations: \PYGZbs{}cite\PYGZob{}Abrahams1986,Nakayama2003,Chalker1988,Chalker1990,Pook1991\PYGZcb{}

\PYGZbs{}bibliography\PYGZob{}example8\PYGZcb{}
\PYGZbs{}bibliographystyle\PYGZob{}example8\PYGZcb{}

\PYGZbs{}end\PYGZob{}document\PYGZcb{}
\end{Verbatim}

to produce a formatted result

\includegraphics[width=0.600\linewidth]{example8.png}


\bigskip\hrule{}\bigskip



\section{Example 9}
\label{examples:example-9}
The following example is taken from a question posted at \code{http://tex.stackexchange.com/questions/172444/suppress-month-and-day-for-journal-articles-and-maintain-for-a-newspaper-article}, where the OP asks for a way to create a reference list in which newspaper articles have the month and day of publication shown while journal articles do not. The cleanest way of implementing this in Bibulous is simply to use a different entrytype for newspaper articles and journal articles, as shown below. For this example, we have a database file

\begin{Verbatim}[commandchars=\\\{\}]
@newsarticle\PYGZob{}test1,
  title = \PYGZob{}Ideas \PYGZbs{}\PYGZam{} trends; politics of the web: \PYGZob{}Meet\PYGZcb{}, greet, segregate, meet again\PYGZcb{},
  url = \PYGZob{}http://www.nytimes.com/2004/01/25/weekinreview/ideas-trends-politics-of-the-web-meet-greet-segregate-meet-again.html\PYGZcb{},
  urldate = \PYGZob{}2014-01-14\PYGZcb{},
  journal = \PYGZob{}New York Times\PYGZcb{},
  author = \PYGZob{}Harmon, Amy\PYGZcb{},
  day = \PYGZob{}1\PYGZcb{},
  month = jan,
  year = \PYGZob{}2004\PYGZcb{}
\PYGZcb{}

@article\PYGZob{}test2,
  title = \PYGZob{}Social movement networks virtual and real\PYGZcb{},
  volume = \PYGZob{}3\PYGZcb{},
  issn = \PYGZob{}1369-118X\PYGZcb{},
  url = \PYGZob{}http://www.tandfonline.com/doi/abs/10.1080/13691180051033333\PYGZcb{},
  doi = \PYGZob{}10.1080/13691180051033333\PYGZcb{},
  number = \PYGZob{}3\PYGZcb{},
  urldate = \PYGZob{}2013-05-31\PYGZcb{},
  journal = \PYGZob{}Information, Communication \PYGZbs{}\PYGZam{} Society\PYGZcb{},
  author = \PYGZob{}Diani, Mario\PYGZcb{},
  month = jan,
  year = \PYGZob{}2000\PYGZcb{},
  pages = \PYGZob{}386--401\PYGZcb{}
\PYGZcb{}
\end{Verbatim}

and a style template file

\begin{Verbatim}[commandchars=\\\{\}]
TEMPLATES:
article = \PYGZlt{}au\PYGZgt{} (\PYGZlt{}year\PYGZgt{}). \PYGZlt{}title\PYGZgt{}. \PYGZbs{}textit\PYGZob{}\PYGZlt{}journal\PYGZgt{}\PYGZcb{} \PYGZbs{}textit\PYGZob{}\PYGZlt{}volume\PYGZgt{}\PYGZcb{}(\PYGZlt{}number\PYGZgt{}),\PYGZob{} \PYGZcb{}...
          [\PYGZlt{}startpage\PYGZgt{}--\PYGZlt{}endpage\PYGZgt{}\textbar{}\PYGZlt{}startpage\PYGZgt{}\textbar{}\PYGZlt{}eid\PYGZgt{}\textbar{}].[ doi:\PYGZbs{}url\PYGZob{}\PYGZlt{}doi\PYGZgt{}\PYGZcb{}\textbar{} url:\PYGZbs{}url\PYGZob{}\PYGZlt{}url\PYGZgt{}\PYGZcb{}]
newsarticle = \PYGZlt{}au\PYGZgt{} (\PYGZlt{}year\PYGZgt{}[, \PYGZlt{}month.monthname()\PYGZgt{}[ \PYGZlt{}day\PYGZgt{}]]). \PYGZlt{}title\PYGZgt{}. \PYGZbs{}textit\PYGZob{}\PYGZlt{}journal\PYGZgt{}\PYGZcb{}. Retrieved \PYGZlt{}urldate\PYGZgt{}, from \PYGZbs{}url\PYGZob{}\PYGZlt{}url\PYGZgt{}\PYGZcb{}.

SPECIAL-TEMPLATES:
authorlist = \PYGZlt{}author.to\PYGZus{}namelist()\PYGZgt{}
editorlist = \PYGZlt{}editor.to\PYGZus{}namelist()\PYGZgt{}
au = \PYGZlt{}authorlist.format\PYGZus{}authorlist()\PYGZgt{}
ed = \PYGZlt{}editorlist.format\PYGZus{}editorlist()\PYGZgt{}
citelabel = (\PYGZlt{}authorlist.0.last\PYGZgt{}, \PYGZlt{}year\PYGZgt{})

OPTIONS:
namelist\PYGZus{}format = last\PYGZus{}name\PYGZus{}first
\end{Verbatim}

that when comiled by the main \code{.tex} file

\begin{Verbatim}[commandchars=\\\{\}]
\PYGZbs{}documentclass\PYGZob{}article\PYGZcb{}
\PYGZbs{}usepackage[paper=letterpaper, text=\PYGZob{}6.2in,8.5in\PYGZcb{},centering]\PYGZob{}geometry\PYGZcb{}
\PYGZbs{}usepackage[colorlinks=True,urlcolor=blue,citecolor=black,breaklinks=true]\PYGZob{}hyperref\PYGZcb{}

\PYGZbs{}makeatletter
   \PYGZbs{}renewcommand\PYGZob{}\PYGZbs{}@biblabel\PYGZcb{}[1]\PYGZob{}\PYGZcb{}
   \PYGZbs{}renewcommand\PYGZob{}\PYGZbs{}@cite\PYGZcb{}[2]\PYGZob{}\PYGZob{}\PYGZsh{}1\PYGZbs{}if@tempswa , \PYGZsh{}2\PYGZbs{}fi\PYGZcb{}\PYGZcb{}
\PYGZbs{}makeatother

\PYGZbs{}begin\PYGZob{}document\PYGZcb{}

Lorem \PYGZbs{}cite\PYGZob{}test1\PYGZcb{} ipsum \PYGZbs{}cite\PYGZob{}test2\PYGZcb{}.

\PYGZbs{}bibliography\PYGZob{}example9\PYGZcb{}
\PYGZbs{}bibliographystyle\PYGZob{}example9\PYGZcb{}

\PYGZbs{}end\PYGZob{}document\PYGZcb{}
\end{Verbatim}

produces the formatted result

\includegraphics[width=0.600\linewidth]{example9.png}


\bigskip\hrule{}\bigskip



\section{Example ?}
\label{examples:example}
This follows an online question posted at \code{http://tex.stackexchange.com/questions/961/bibtex-style-that-groups-by-author}.


\chapter{Bibulous Overview}
\label{index:bibulous-overview}
Bibulous is a drop-in replacement for BibTeX that makes use of style templates instead of BibTeX's BST language. The code is written in Python and, like BibTeX itself, is open source.

Bibulous developed out of frustration with the complexity of creating bibliography styles using BibTeX's obscure language, and also from the realization that because bibliographies are highly structured, one should be able to specify them simply and flexibly using a template approach. There should be no need to learn a new language just to build a bibliography style, and specifying a style should take only a matter of minutes.

Bibulous incorporates this template approach, and at the same time implements many of the modern enhancements to BibTeX, such as the ability to work with languages other than English, better support for allowing non-standard bibliography entry types, increased options for author name formatting, and more. And one can use the same basic structures and LaTeX commands to generating each of: a bibliography, a glossary, an annotated bibliography, a list of acronyms and symbols, and more, by specifying a different style template for each case.

Bibulous' “style template” files allow a user to visualize the entire bibliography format structure in a concise way within a single page of text. Moreover, the template is structured with its own Python-like mini-language, intended to allow uses to create flexible formatting instructions quickly and easily. The example below illustrates the simplicity of the format.

The project website, with complete documentation, can be found at \code{http://nzhagen.github.io/bibulous/}. The complete sourcecode for the project can be found at \code{https://github.com/nzhagen/bibulous}.


\section{Installation}
\label{index:installation}
Installing using pip::

\begin{Verbatim}[commandchars=\\\{\}]
pip install bibulous
\end{Verbatim}

Instructions for installing Bibulous, and for seamlessly integrating it into your normal LaTeX workflow, are given in the \code{INSTALL.rst} file. Users can also consult the user guide (\code{user\_guide.rst}) for further information and tutorials. A \code{FAQ} page is also available.


\section{Example}
\label{index:example}
For a very simple bibliography, consisting of only journal articles and books, a complete style template file may consist of just two lines::

\begin{Verbatim}[commandchars=\\\{\}]
article = \PYGZlt{}au\PYGZgt{}, \PYGZbs{}enquote\PYGZob{}\PYGZlt{}title\PYGZgt{},\PYGZcb{} \PYGZbs{}textit\PYGZob{}\PYGZlt{}journal\PYGZgt{}\PYGZcb{} \PYGZbs{}textbf\PYGZob{}\PYGZlt{}volume\PYGZgt{}\PYGZcb{}: ...
             [\PYGZlt{}startpage\PYGZgt{}--\PYGZlt{}endpage\PYGZgt{}\textbar{}\PYGZlt{}startpage\PYGZgt{}\textbar{}\PYGZlt{}eid\PYGZgt{}\textbar{}] (\PYGZlt{}year\PYGZgt{}).[ \PYGZlt{}note\PYGZgt{}]
book = [\PYGZlt{}au\PYGZgt{}\textbar{}\PYGZlt{}ed\PYGZgt{}\textbar{}], \PYGZbs{}textit\PYGZob{}\PYGZlt{}title\PYGZgt{}\PYGZcb{} (\PYGZlt{}publisher\PYGZgt{}, \PYGZlt{}year\PYGZgt{})...
             [, pp.\PYGZti{}\PYGZlt{}startpage\PYGZgt{}--\PYGZlt{}endpage\PYGZgt{}].[ \PYGZlt{}note\PYGZgt{}]
\end{Verbatim}

The \code{\textless{}variable\textgreater{}} notation indicates that the corresponding bibliography entry's field is to be inserted into the template there. The \code{{[}...\textbar{}...{]}} notation behaves similar to an if...elseif... statement, checking whether a given field is defined within the bibliography entry. If not defined, then it attempts to implement the instruction in the block following the next \code{\textbar{}} character.

We can read the above article template as indicating the following structure for LaTeX-formatting the cited entry in the bibliography (\code{.bib} file). For articles, we first insert the list of author names (formatted according to the default form), followed by a comma. If no \code{author} field was found in the bibliography entry, then insert \code{???} to indicate a missing required field. Next insert a quoted title, followed by an italicized journal name, and a boldface volume number (all of these are required fields). Next, if the \code{pages} field was found in the entry's database, then parse the start and end page numbers and insert them here. If the \code{pages} field indicates that there was only one page, then use that instead. Or if the \code{pages} field is not present, then check to see if the \code{eid} is defined, and use it instead. However, if none of these three possibilities are available, then insert the “missing field” indicator, \code{???}. Finally, put the year inside parentheses, and if the \code{note} field is defined in the entry, then add that to the end (following the period). If \code{note} is not defined, then just ignore it.

One can read the book template similarly, and find that it has different required and optional fields. The simplicity of the format allows one to customize databases to suit any use. For example, to use a bibliography entrytype \code{本} instead of \code{book}, then all that is necessary is to go into the template file and change \code{book} to \code{本}. If a user wishes to add a new field, such as \code{translator}, then if it has been added to the \code{.bib} database file, then all that is needed is to add some text to the template, such as \code{(\textless{}translator\textgreater{}, trans.)} to insert the field into every bibliography entry that has \code{translator} defined for that entrytype.


\section{Developers}
\label{index:developers}
Bibulous is a new project, and so it has until now been a solo effort. Anyone interested in helping out is welcome to join; just send an email to the developers mailing list and we will try to help you get involved and show you the ropes. And, this being the maintainer's first open source project, any suggestions by experienced developers are welcome.

Guidelines for developers are given in \code{developer\_guide.rst}, and includes an overview of the project's strategy and overall code structure. Note that a bug tracking system has not yet been set up for the project. HTML-based documentation is provided at \code{bibulous/doc/\_build/html/index.html}, and a corresponding PDF file at \code{bibulous/doc/\_build/latex/Bibulous.pdf}. The \code{setup.py} and \code{MANIFEST.in} files provided in the repository base directory are used to create a Python package using the \code{disutils} distribution utilities module.


\section{License}
\label{index:license}
Bibulous is released under the MIT/X11 license, meaning that it is free and open source, and that it can be used without restriction in other programs, commercial or not. The full license is given in the file \code{LICENSE.txt}.


\section{Indices and tables}
\label{index:indices-and-tables}
The link below provides an index to the source code for all functions contained in the Bibulous project.
\begin{itemize}
\item {} 
\emph{genindex}

\item {} 
\emph{search}

\end{itemize}

\begin{longtable}{ll}
\hline
\endfirsthead

\multicolumn{2}{c}%
{{\textsf{\tablename\ \thetable{} -- continued from previous page}}} \\
\hline
\endhead

\hline \multicolumn{2}{|r|}{{\textsf{Continued on next page}}} \\ \hline
\endfoot

\endlastfoot

\end{longtable}




\renewcommand{\indexname}{Index}
\printindex
\end{document}
