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