BBlog/man/man1/BBlog.1

.Dd $Mdocdate: July 26 2023 $
.Dt BBLOG 2.3
.Os
.Sh NAME
.Nm BBlog
.Nd LaTeX bibliography parser
.Sh SYNOPSIS
.Nm
.Bk -words
.Op Fl c Ar conf_file
.Op Fl d Ar database_file
.Op Fl e Ar engine
.Op Fl a Ar aux_file
.Op Fl A Ar aux_command
.Op Fl f Ar format
.Op Fl F Ar filter_name:filter
.Op Fl r Ar ref_map
.Op Fl o Ar order
.Op Fl b Ar output
.Ek
.Pp
.Nm
.Bk -words
.Fl v
.Ek
.Sh DESCRIPTION
.Nm
generates bibliographies for LaTeX documents.
.Pp
.Nm
reads a list of bibliography items from a LaTeX .aux file read from a file or from stdin if no input file is specified.
.Pp
The bibliography is output to a file or to stdout if no output file is specified.
.Pp
The bibliography entries are contained in a database.
.Nm
is bundled with several engines" for reading the following types of databases:
.Bl -bullet
.It
.Sy sqlite :
sqlite3 databases (see
.Sx BBlog-sqlite Ns (7))
.El
.Pp
.Sh COMMAND-LINE OPTIONS
.Bl -tag -width Ds
.It Fl c Ar conf_file
Configuration file (default: '').
.It Fl d Ar database_file
Database (default: '').
.It Fl e Ar engine
The engine to use to read the database (default: 'sqlite').
.It Fl a Ar aux_file
LaTeX .aux file, supports bash globbing (default: '*.aux').
.It Fl A Ar aux_command
In the .aux file, each entry should be written as the argument of a LaTeX command, specified through this option (default: '\\citation{').
.It Fl f Ar format
Format of the bibliography entries (default: '\\bibitem[%citeref%]{%token%}%n%%author% - {\it %title%}, %journal%, %year%.%n%').
.It Fl F Ar filter_name:filter
Define a filter (this option can be specified more than once). Filters can be used in the format string in order to automatically change database entries (see FILTERS).
.It Fl r Ar ref_map
A ref_map is a file containing a sequence of
.Sx sed Ns (1)
commands which is used to translate the document citerefs into database citerefs (see REF_MAP).
.It Fl o Ar order
Order in which to display the entries, either 'alphabetical' (order by author) or 'appearance' (in order of citation in text) (default: 'alphabetical')
.It Fl b Ar output
Output file (default: stdout)
.It Fl v
Print version and exit.
.El
.Sh CONFIGURATION FILE
The options described above can also be specified in a configuration file. The options specified on the command line have precedence over those given in the configuration file. The configuration file is a list of key/value pairs, in the following format:
.D1 key: value
The possible keys are
.Bl -bullet -offset Ds
.It
.Sy database
.It
.Sy engine
.It
.Sy aux
.It
.Sy aux_cmd
.It
.Sy format
.It
.Sy filter
.It
.Sy ref_map
.It
.Sy order
.It
.Sy out_file
.It
.Sy extra
.El
.Pp
In addition to the command-line options, extra bibliography entries can be provided in the conf file. This is done through the 'extra' key. The value of 'extra' should be of the form
.Pp
.D1 order_tag:citeref:token:content
.Pp
where
.Bl -tag -width Ds
.It Sx order_tag
a string that is compared with the 'prauth' of other entries to determine where the extra entry should be placed: e.g. in 'alphabetical' mode, if 'order_tag' is "Doe1996" and there are two other entries with prauth "Doe1990" and "Fred1967", then the extra entry will be placed between "Doe1990" and "Fred1967". If the ordering mode is "appearance", then this entry is ignored.
.It Sx citeref
the citeref for the extra entry.
.It Sx token
the token for the extra entry. If the token appears in another entry, then the appropriate steps are taken to make it unique (see TOKEN REPETITIONS).
.It Sx content
the text to be printed to the bibliography, which may contain the '%token%' and '%citeref%' macros (see FORMAT). Since the token may be replaced if it is a duplicate, it is safer to use the '%token%' macro rather than writing it explicitly in 'content'.
.El
.Sh ENGINE
An engine is shell script that defines functions to read a database. These functions take a list of references as an input, and, for each reference, return a collection of key/value pairs. The format string (see FORMAT) can reference the keys in order to construct the entry from the associated values.
.Pp
One of the entries must be the citeref of the entry and its key must be 'citeref' (or else the ref_map will not work).
.Pp
A more thorough discussion of the format of engines and instructions on writing custom engines is provided below in the CUSTOM ENGINES section.
.Sh FORMAT
The format string specifies how the entries of the bibliography should be typeset. It is a string of characters, in which database entries can be inserted by writing the appropriate key, sandwiched between '%' characters. For instance '%title%' is replaced by the value associated to the 'title' key.
.Pp
In addition, a filter can be added to any key, for instance '%title:tfilter%' is replaced by the value associated to the 'title' key after going through the filter 'tfilter' defined in the 'filter' entry (see FILTER).
.Pp
The format string can also contain conditional statements, in the format '|field?text|'. When a conditional statement is encountered,
.Nm
checks whether the field is non-empty, and replaces it with 'text' if it is, while it ignores 'text' if the field is empty. For example, '|link?\\url{%link%}|' is expanded to '\\url{%link%}' if '%link%' is non empty, and is ignored if '%link%' is empty.
.Pp
.Sx Warning :
Conditional statements cannot be nested.
.Pp
Newline characters can be inserted using '%n%'. For every reference, the format string is read, '%' characters are replaced by the appropriate database entry, and the output is written to the output file.
.Pp
Note that the format string may not contain newline characters.
.Sh FILTER
Filters can be used to automatically format database entries to suit the style of a particular document. For example, if the names of the authors is given as 'first_name last_name' in the database, but the desired format only retains the first initial of the first_name, then a filter that maps 'first_name last_name' to 'first_initial last_name' can be used.
.Pp
Each filter must be given a name, which can be referenced inside '%...%' commands. When the filter is defined, its name is specified by
.D1 filter:name_of_the_filter: expression_of_the_filter
.Pp
The expression of a filter is a
.Sx sed Ns (1)
script. Note that the
.Sx sed Ns (1)
command is called with the '-r' option, so extended regexps should be used.
.Pp
The following line defines a filter, 'authfilter', that maps a 'first_name middle_name last_name,...' entry to a 'first_initial.middle_initial. last_name,...' entry:
.Pp
.D1 filter:authfilter: s/([A-Z])[^, ]* /\1. /g; s/ ([^ ,]*),/_\1,_/g; s/ ([^ ,]*)$/_\1/g; s/ //g; s/_/ /g;
.Pp
This filter can then be used by setting the format to
.Pp
.D1 %author:authfilter% - {\it %title%}, %journal%, %year%.%n%
.Pp
.Sh REF_MAP
Ref_maps can be useful when the citerefs in the LaTeX document are different from those in the database (e.g. when writing papers in collaboration with someone who uses a different convention for their citerefs). In order to automatically translate the citerefs in the document to ones the database can read, a
.Sx sed Ns (1)
script that performs the translation can be specified. This
.Sx sed Ns (1)
script is called a 'ref_map'.
.Pp
For example, to translate 'doe11' to 'Do11', use
.D1 s/^doe11$/Do11/
.Pp
Since ref_maps are
.Sx sed Ns (1)
scripts, they can use regexps. Note that the '-r' command line switch is used, so extended regexps should be used.
.Pp
.Sh CUSTOM ENGINES
(See the sqlite.sh engine for an example). Custom engines are shell scripts that define two functions:
.Bl -bullet -offset Ds
.It
fetch_BBlog_entries_alpha
.It
fetch_BBlog_entries_appearance
.El
.Pp
which read the .aux file, and output a list of key/value pairs for each reference, respectively in alphabetical order and in order of appearance in the document.
.Pp
In addition, if a ref_map is specified, then the citeref should be translated accordingly before being passed to the database. The 'map_citeref' function should be used to handle the translation.
.Pp
The output of each function should be written to stdout. For each reference, a list of key/value pairs in the format 'key="value"' should be printed, with no empty lines. Different references must be separated by a single empty line.
.Pp
Each key/value entry should be formatted as a bash variable assignment, in particular special characters should be escaped and quotes should be used where needed. A function to escape some common special characters is provided, and can be called by passing the input string to the stdin of 'escape_string'.
.Pp
Engines are stored in /usr/share/BBlog/engines/ by default (the path can be changed through the 'enginedir' variable, which can also be set when installing
.Nm
using its Makefile, through the ENGINEDIR variable).
.Sh TOKEN REPETITIONS
If multiple references that share the same token are cited within the same document, then
.Nm
automatically adds a letter (from 'b' to 'z') at the end of non-unique tokens, in order of appearance.
.Sh AUTHORS
.Nm
was written by Ian Jauslin.
.Sh COPYRIGHT
copyright Ian Jauslin 2015-2023
.Sh SEE ALSO
.Sx BBlog-sqlite Ns (7)