Dear all,
Jurgen was not kidding when he said the syntax of the bib modules is
somewhat cryptic....and the documentation is a bit sparse(;-))
So here are a few notes that may serve as a base for a fuller documentation
effort. Input greatly welcome, especially in the section marked as FIXME
between dotted lines.
--
Here is what I gathered from looking at the natbib and jurabib modules:
A bib module has (may have) three sections:
1. CiteEngineType
2. CiteEngine
3. CiteFormat
The purpose of CiteEngineType (see natbib.module, where the types are
authoryear and numerical) is to allow switching among the different
different citation styles offered by the bibliographic package the module
implements. For biblatex, then, a "CiteEngine" is equivalent to a biblatex
"citation style" (as implemented in a .cbx file). Biblatex has 28 standard
styles, hence a full biblatex module would have 28 CiteEngines. Support of
additional, non-standard styles would require additional CiteEngines (and
preferably a separate module, I guess)
Every CiteEngine has its own "CiteEngine" section listing the available
citation commands. Roughly speaking, the CiteEngine section has citation
styles' "prototypes" as in a .h file of C-style programming. It simply
lists the allowed styles and their parameters. No actual behavior is
specified, though. This is the goal of the CiteFormat section.
Every CiteEngine has a CiteFormat section, where the results of using one
of the citation commands listed in the corresponding CiteEngine section is
specified. This is the most substantial section, where both the appearance
of a citation in the LyX window and in the XHTML output are specified.
---------------------------------------------------------------------------------------------------------------------------------------------
FIXME: I am not clear on this distinction between text vs. XHTML output. I
do not see any separation between different kinds of outputs in the module.
---------------------------------------------------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------------------------------------------------------------------------
FIXME: I am not clear where, if at all, the LaTeX code corresponding to the
chosen citation command is specified. I guess it happens in
GuiCitation.cpp? Or perhaps in BiblioInfo.cpp? Truth is, I haven't
understood yet how those classes (and perhaps more) and the module(s)
interact.
---------------------------------------------------------------------------------------------------------------------------------------------
At its most basic, the CiteEngine section will have, for every citation
command, a substitution pattern indicating what should replace the command
in the LyX and XHTML output
---------------------------------------------------------------------------------------------------------------------------------------------
FIXME: the customization manual, p. 44 and 45, indicate that the CiteEngine
section should have a line for every bibtex *type* (article, book, etc),
not for every bibtex *command* (cite, citealp, etc). I am not sure if this
is a possible alternate behavior or if reflects earlier functionalities.
The definitions in stdciteformats.inc suggest the former. But then, what
exactly is allowed in CiteFormat?
---------------------------------------------------------------------------------------------------------------------------------------------
The citation commands' substitution patterns (may) use a simple macro
language with the following syntax forms:
1. !token expansion
means "token" is a macro and will be replace by "expansion" in all
subsequent patterns
2. %fieldName%
allows the replacement of the bibtex field "fieldName" with its value.
---------------------------------------------------------------------------------------------------------------------------------------------
FIXME: the customization manual says that BibTeX *keys* may be replaced
with their values. I find this confusing, as a bibtex key is usually
understood to refer to the unique citation identifier, not to the name of
the citation fields.
Moreover, the above definition implies that "fieldName" can only range over
bibtex fieldnames. However, the following definition in jurabib.module:
!startlink {!<a href='#LyXCite-%clean:key%'>!}
uses the clause%clean:key% which is obviously not a bibtex field name (I
think). I guess it is a cleaned up version of the bibtext key? There are
other values for "fieldName" present in the bib modules, the last one
being particularly cryptic:
- %textbefore%
- %textafter%
- %key%
- %nextkey%
- %bibentry%
- %dialog%
---------------------------------------------------------------------------------------------------------------------------------------------
3. {%fieldName% [[if-clause]][[else-clause]]}
if "fieldName" exists, it replaces it with "if-value," otherwise it
replaces it with "else-value".
4. !token {!<HtmlTag>!}
Replaces "token with "HtmlTag", but only in case of HTML output
---------------------------------------------------------------------------------------------------------------------------------------------
FIXME: Where is it decided to output HTML instead of plain text?
---------------------------------------------------------------------------------------------------------------------------------------------
5. __token translatedBit
Replaces "token" with the "translatedBit"
---------------------------------------------------------------------------------------------------------------------------------------------
FIXME: I am really confused about this clause form:
First, because the documentation says it is not a macro, even though there
is a substitution going on.
Second, they are called "translatable bits", but who does the translation?
In other words, if I want a biblatex module for language X, do I write a
new BibLatex-X.module with the various strings in language X (and in it it,
I perhaps simply import the bibtlatex.module and redefine the
translations? Or are the translations stored somewhere else, and indexed
accordingly?
---------------------------------------------------------------------------------------------------------------------------------------------
Thanks for the help.
Cheers,
Stefano
--
__________________________________________________
Stefano Franchi
stefano.fran...@gmail.com <stef...@tamu.edu>
http://stefano.cleinias.org
