[Bibulus-dev] A short guide to code navigation

[Thomas Widmann]

Hi,

since I sometimes find it difficult to navigate the code (and I've
written most of it myself), here's a brief guide to how the modules
fit together.

The main module is Bibulus.pm.  When a new object is created, first of
all new() is called.  The cite() commands are also in here, as is
getbib() which the user will call to get the bibliography.  This will
generate some labels and sort the entries, and it will then call
genbib().  This function will print the bibliography header and then
loop over all the entries, calling formatentry().

This function is located in Bibulus/formatentry.pm.  It sets up a few
things, crucially $self->{CURR} which is the current line.  It first
calls the l_ functions (see below) on all the elements and then sorts
the elements based on the l_ output.  Then it loops over the elements,
calling punctuation functions and formatting functions.  As a concrete
example, if an entry consisted of the elements <author>, <title> and
<year>, the function calls would be as follows: f_author, po_author,
pr_title, f_title, po_title, pr_year, f_year.

The locations functions (l_...()) are placed in Bibulus/location.pm.
Each of them just returns a number, and it's up to them whether they
want to check any parameters.

The punctuation functions (pr_...() and po_...()) are placed in
Bibulus/punctuation.pm.  The pr_ functions are called before the
element they're named after, and the po_ functions afterwards.  If
they don't do anything, standard punctuation (normally ', ') will be
used.  I've also moved some other functions here, mainly the ones
dealing with punctuation and outputting.

The formatting functions (f_...()) are located in Bibulus/
formatting.pm.  Basically each f_ function should call outputtext()
(defined in punctuation.pm) to output text.  Some of them call some
other functions also defined here.  If the formatting functions need
to do anything that might be influenced by language or output module,
they should call the relevant functions.

The language support is defined in several files.  The main support is
defined in Bibulus/language.pm, but this should not be of great
interest.  More important to understand is Bibulus/general.pm, which
provides fall-back functions and words.  For each language an array of
texts ($self->{LANGTEXT}{language}) exists (words like 'of',
'January', 'Cologne'), but the functions themselves can also be
overridden.  For instance, to print "volume 2 of The Art of CP", the
function volume() in general.pm is normally used, but the various
language modules can override this.

The same is true for formatting: Plain text support is defined in
Bibulus/primitives.pm, but most of these are redefined by the output
modules (LaTeX/LaTeX.pm and HTML/HTML.pm).

I hope this made some sense.  Please ask me to clarify if not!

/Thomas
-- 
Thomas Widmann          Bye-bye to BibTeX: join the Bibulus project now!
address@hidden                                <http://www.bibulus.org>
Glasgow, Scotland, EU     <http://savannah.nongnu.org/projects/bibulus/>