Bibulous — A drop-in BIBTEX replacement
Contents
1. Tool 100 820 12 000 BIBTEX 0 112sec 0 117sec 1 01 sec Bibulous 0 190sec 1 667sec 41sec Biber 1 115sec 9 05lsec 17 5min 5 Comparison with existing bibliography engines Bibulous not only provides easy customization for users but does so with minimal compromises in speed and without requiring a compiler for installing It is written in Python and has no external dependencies it requires only Python s standard library making it highly portable and easy to install since Python is widely available on all modern platforms And although it is slower than BIBTEX it is considerably faster than Biber To demonstrate processing speeds each of the three back end processors were run on three bibliog raphy databases inside Bibulous regression testing suite one containing 12000 entries another with 820 entries and a third with 100 entries Using a stan dard desktop computer running all three processors on these databases produces the timing results shown in Table 1 While the comparison is not entirely fair since Biber is doing more work especially by build ing hash codes for every author in every entry the results show that Biber s expanded capabilities have come at a significant sacrifice in speed Biblatex and Biber are quickly replacing BIBTEX as the standard tools of choice for ATEX bibliogra Nathan Hagen phy processors as they provide much needed func tionality that BIBTEX does not support for larger da2. else None for_english_audience if options document_language English else None Figure 4 Template file for the multi language bibliography example mathematics markup within keys and labels even though ATEX itself currently cannot handle this Another example of Bibulous versatility in deal ing with multiple languages is that of an audience switch The following example is adapted from a query made online 4 For a single database file that can be used inside both English language and Japanese language publications an English language format should allow Japanese entries in the bibliogra phy with author names in both kanji and romanized characters Titles should also be given in this dual form but sometimes with an English translation pro vided English language citations should appear as normal In a Japanese language publication how ever the Japanese entries should have the author title etc in Japanese form without roman letters or English Here is an example database entry collection Tsuruta2006 address_ja HR address_romaji Tokyo author_ja H EEX author_en Tadao Tsuruta publisher_ja JX 3 257 av Ay publisher_en Shin gijutsu Communications title_ja DED S Y title_romaji Hikari no empitsu title_en Pencil of light volume 7 year 2006 The corresponding style template file is shown in Fig 4 The
3. fault the relevant database entries from the main bib files are extracted and placed to gether into a single usually small database This speeds up program execution when operat ing with a large main database but a relatively TUGboat Volume 34 2013 No 3 small number of citations 4 Bibulous provides an authorextract command that creates a bib file containing only those in which the given author s name is referenced This can be useful for writing a CV 5 Bibulous sentence_case operator is almost identical to BIBTX s change case command but works with Unicode 6 Bibulous provides a Python API to its own inter nal data structures allowing users to extend or customize the program as they desire by placing function definitions within style files 6 Comments Rather than providing a detailed explanation of us age the aim here has been to introduce Bibulous to IATRX users and to showcase some of its strengths These include 1 using the simplicity and power of style templates to specify and customize bibliographies 2 implementing a fully Unicode compliant pro gram without serious memory limitations The examples provided in the sections above show how these traits can be used to provide a powerful backend bibliography processor However a range of functionality remains that is important for users but is not readily accessible through Bibulous alone Tasks such as advanced citation labelling the c
4. we have to convert from using italics for titles to using quotation marks around a hyperlinked text if a url or doi field is provided in the entry from using boldface to standard typeface for the volume and adding an issue number in parentheses The inproceedings style uses the same format for hyperlinked titles and adds the ability to format fields such as booktitle and series and provides a separate list of editors For BIBTEX modifying an existing style file to achieve these changes would be a daunting task for a casual user Biblatex has succeeded in making this much easier but with templates it can be easier still The other major change in going from Fig 1 to Fig 2 is in the special template definitions where we can find several new constructions The first is a dot operator placed after a variable inside the angle brackets This can be used to apply an in dex as in the case of a list or a dictionary type of variable or an operator as in to_namelist or initial An index can be ezplicit as in lt authorlist 0 gt which indicates taking the zeroth element of the list type variable authorlist or im plicit as in editorname n For an implicit index the construction lt editorname 0 gt used in conjunc Nathan Hagen tion with the variable definition for editorname n indicates that all instances of the implicit index n in the template should be replaced with the explicit index 0 Finally an ellipsis oc
5. In addition to style templates Bibulous also implements many of the modern enhancements to BIBTEX such as the ability to work smoothly with languages other than English better support for non standard bibliography structures and heterogeneous databases and increased formatting options among others Moreover one can use the same framework to generate any of a bibliography glossary nomen clature list of symbols and or more by specifying a different style template for each case 2 Template example A short example illustrates how templates work For a simple bibliography consisting of only journal arti cles and books a complete style file may consist of just a few lines as shown in Figure 1 Angle brack ets indicate a template variable which can be a a variable e g lt year gt that maps to a field e g year in the database entry b a special variable that is generated by the program e g lt au gt is gen Nathan Hagen TUGboat Volume 34 2013 No 3 erated by formatting the database entry s author field into a list of names or c a variable that is defined by the user within the template s variable definitions Each variable represents a string to be inserted into the template at that point so that for a database entry with year 1988 a template containing lt year gt is replaced with 1988 The same procedure follows for each variable found within the template definition An
6. a fully Japanese style template A lt H gt lt i gt lt gt with a corresponding example database file entry OA LIK 1906 mig Cert aa 24 ho 4 1906 The important feature here is that Bibulous does not need to know anything about the languages used in the database the template or the tex file It only needs to be able to convert the symbols to Unicode so that it can match any symbol from one file to that in another And since Bibulous internals are written entirely in UTF 8 compliant code multilingualism and localization come easily Bibulous is even flexible enough to allow the use of Bibulous A drop in BIBTEX replacement based on style templates 336 TUGboat Volume 34 2013 No 3 TEMPLATES collection lt for_japanese_audience gt lt author_ja gt lt title_ja gt lt volume gt 2 lt publisher_ja gt lt year gt f lt for_english_audience gt lt author_en gt lt title_ja gt lt title_romaji gt makeopenbracket lt title_en gt makeclosebracket vol lt volume gt lt publisher gt lt address gt lt year gt lt for_english_audience gt lt author gt lt title gt vol lt volume gt lt publisher gt lt address gt lt year gt OPTIONS document_language Japanese whether the document is for a Japanese audience VARIABLES for_japanese_audience if options document_language Japanese
7. editor to_namelist gt sortkey lt year gt lt title gt lt editorlist 0 last gt citelabel None OPTIONS bibitemsep Opt Exp1SyntaxOn cs_new_eq NN Repeat prg_replicate nn Exp1Syntax0ff newcommand nstars 1 parbox 3em Repeat 1 star 1 xxxx The Inheritance Per Fly 2003 2 xxx The Celebration Thomas Vinterberg 1998 3 x The Kingdom Lars von Trier 1994 Figure 3 An example illustrating the use of Bibulous style templates for a movie database The citation sorting order is defined to be by year in descending order the minus sign within the variable name inverts the direction of the sort followed by title and then director s last name Note that the editor lt director gt special template is necessary in order to map the director field to the editor field namelist formats with more flexibility than that al lowed by Bibulous standard keyword arguments Thus for most styles these structures are not neces sary and one can use the default namelist format modified through keyword arguments The if_singular arg1 arg2 arg3 opera tor is unique in that it accepts arguments This allows it to insert arg2 if arg1 is singular or arg3 if plural Here the operator is given the argument lt editorlist gt which has one entry if the editor field in the database entry contains only one name In this case it returns the argument edmsg1 defined in the opt
8. see how Bibulous uses a template to generate bb1 file entries we can walk through the definitions given in Fig 1 First from the aux file Bibulous obtains a list of citation keys that map to database entries Using the sortkey template it generates a key for each reference sorts the keys into the desired order and then walks through each corresponding database entry using an appropriate template to for mat each reference in turn In the case of the example shown the sorting key is simply the numbering in which the entry was cited lt citenum gt When Bibu lous locates an entry in the database it reads the entrytype this particular style file assumes that only entrytypes article and book exist in the citation list to locate which template definition to use If TUGboat Volume 34 2013 No 3 TEMPLATES SPECIAL TEMPLATES sortkey lt citenum gt citelabel lt citenum gt short bst article lt au gt enquote lt title gt textit lt journal gt textbf lt volume gt lt startpage gt lt endpage gt lt startpage gt lt eid gt lt year gt lt note gt book lt au gt lt ed gt textit lt title gt lt publisher gt lt year gt pp lt startpage gt lt endpage gt lt note gt 333 Figure 1 A style template file example An ellipsis at the end of a line indicates a line continuation All entries in the Special Templates section of th
9. 332 Bibulous A drop in BIBTEX replacement based on style templates Nathan Hagen Abstract BIBTEX has long been an essential tool for TEX and BTEX users but the long list of re implementation efforts attests to unfulfilled needs The Bibulous project attempts to fulfill many of these needs with a unique approach based on style templates provid ing a flexibility that is unmatched by existing tools We illustrate its capability with examples of cus tom bibliography styles multilingual bibliographies glossaries and more 1 Introduction For beginning TEX BIBTEX users the difficulty of building and customizing bibliography style files can come as a shock BIBTX s style files are written in an old style stack based language that requires sig nificant effort to learn edit and write It is natural however to feel that since bibliographies are highly structured one should be able to specify them simply and not as one commonly finds with BIBTX s bib liography styles in files with over a thousand lines of difficult code The Bibulous project shows that with style templates one can indeed specify complete bibliography styles in a matter of only a few lines of text using a format understandable even for novices Style templates provide a flexibility unmatched by al ternative approaches to creating bibliographies and have important advantages over even the more mod ern approach taken by Biblatex 1 and Biber 2 3
10. And likewise for any other field such as sorttitle or sortyear for modifying citation sorting The final item that Bibulous needs to specify for the reference is its item label the label that goes at the front of the reference and is often the same as the sortkey This label is generated using the citelabel template For scientific journal arti cles the most common choice for this is the citation number e g citelabel lt citenum gt For other areas of study the reference labels may for example take the form of the first author s last name then first name then year as in the following example citelabel textbf lt authorlist 0O last gt lt authorlist 0 first gt lt year gt This can produce a reference list like the following Schmader Toni 2002 Gender identification moderates stereotype threat effects on women s math performance Journal of Experimental Social Psychology 38 194 201 Steele Claude 1997 A threat in the air How stereotypes shape intellectual identity and performance American Psychologist 52 613 629 Bibulous A drop in BIBTEX replacement based on style templates 334 TEMPLATES lt startpage gt lt eid gt lt year gt lt eid gt lt year gt SPECIAL TEMPLATES authorlist lt author to_namelist gt editorlist lt editor to_namelist gt au lt authorname 0 gt ed lt editorname 0 gt OPTIONS etal_message textit et al edms
11. bibliographies and citations Available from CTAN http ctan org pkg biblatex 2 P Kime and F Charette biber A backend bibliography processor for biblatex Available from CTAN http ctan org pkg biber 3 P L Kime Biber the next generation backend processor for BIBATEX TUGboat 33 13 15 2012 4 http tex stackexchange com questions 28010 how to create multilingual english japanese bibliographies with biblatex bib Nathan Hagen Tucson AZ USA nhagen at optics dot arizona dot edu https github com nzhagen bibulous Bibulous A drop in BIBTEX replacement based on style templates
12. curring in the mid dle of a string indicates an implicit loop Thus the definition lt editorname 0 gt and lt editorname 3 gt is equivalent to lt editorname 0 gt when there is only one editor in the database entry or equivalent to lt editorname 0 gt and lt editorname 1 gt when there are only two For three editors the implicit loop expands the template to lt editorname 0 gt lt editorname 1 gt and lt editorname 2 gt and for four lt editorname 0 gt lt editorname i gt lt editorname 2 gt and lt editorname 3 gt Since the template does not specify the format for more than four editor names the code builds an et al construction when there more than the specified number of names so that the result becomes lt editorname 0 gt lt editorname 1 gt lt editorname 2 gt lt editorname 3 gt textit et al where the form of the string et al is specified by an etal_message keyword option The implicit index and implicit loop features are only necessary when one needs to customize the TUGboat Volume 34 2013 No 3 moviedb bib 335 moviedb bst movie key title director year rating moviedb tex In preamble usepackage exp13 TEMPLATES movie nstars lt rating gt color blue lt title gt color black lt director gt year gt SPECIAL TEMPLATES editor lt director gt editorlist lt
13. e file are optional and are used to replace default settings the current database entry is an article entrytype Bibulous will find the list of variables in the article template definition and begin replacing them one by one with their corresponding fields The lt au gt vari able represents a formatted string of author names formatted from the author field according to default options in this case followed by a comma and a space If no author field is found in the bibliography entry then it inserts there to indicate a miss ing required field Next it locates the title field and inserts it with a comma inside enquote format ting instructions Next follows an italicized journal name and a boldface volume number All of these so far are designated as required fields Next if the pages field is found in the entry s database Bibulous will parse the start and end page numbers assum ing that the pages field uses dash delimited page identifiers and insert them here using an en dash separator If the pages field contains only one page then the endpage variable will be undefined and Bibulous will attempt to use the next block which uses only the startpage If the pages field is miss ing entirely from the database entry then Bibulous checks to see if the eid electronic identifier field is defined and if so uses it instead However if the pages and eid fields are both undefined then the code inserts Fi
14. gi ed edmsg2 eds ieee bst article lt au gt enquote href lt url gt lt title gt href lt doi gt lt title gt lt title gt textit lt journal gt lt volume gt lt number gt lt startpage gt lt endpage gt inproceedings lt au gt enquote href lt url gt lt title gt href lt doi gt lt title gt lt title gt in textit lt booktitle gt lt ed if_singular editorlist edmsg1 edmsg2 gt in lt series gt vol lt volume gt pp lt startpage gt lt endpage gt authorname n lt authorlist n first initial gt lt authorlist n middle initial gt lt authorlist n prefix gt lt authorlist n last gt lt authorlist n suffix gt and lt authorname 9 gt editorname n lt editorlist n first initial gt lt editorlist n middle initial gt lt editorlist n prefix gt lt editorlist n last gt lt editorlist n suffix gt and lt editorname 3 gt TUGboat Volume 34 2013 No 3 Figure 2 Two example entrytype templates for an IEEE format bibliography For the hyperlinked title the template allows use of either a url or a doi field in the database entry Figure 2 shows how Bibulous can be used to develop custom bibliography styles using an example that incorporates hyperlinks into the document title of each reference In going from the style used in Fig 1 to the new article style in Fig 2
15. her with corresponding bib and bst files and output bbl file Together these create the formatted glossary etc shown in Fig 6 In the example bib file readers may note the separation of the symbol entrytypes into independent name and description fields instead of the form that the acronym entrytypes use This is necessary to get around the limitation that ATEX cannot use mathematical markup within citation keys TUGboat Volume 34 2013 No 3 gloss tex documentclass article newcommand citename 1 1 protect nocite 1 makeatletter renewcommand biblabel 1 1 renewenvironment thebibliography 1 section refname list setlength labelwidth 1 5cm leftmargin labelwidth advance leftmargin labelsep let makelabel descriptionlabel endlist makeatother renewcommand refname Glossary List of Symbols and Nomenclature begin document While citename Tilt aberration changes only the magnification citename SA induces image blur Wavefront aberration is a function of radial distance cite sym rho and azimuthal angle cite sym phi Of the two aberrations only citename SA has an effect on the citename PSF and citename MTF bibliographystyle gloss bibliography gloss end document gloss bst TEMPLATES symbol lt description gt gloss lt description gt acronym lt description gt SPECIAL TEMPLATES sortkey lt citekey g
16. ions list as ed If more than one editor name is found in the database entry then the operator returns the argument edmsg2 defined in the options list as eds 3 Unorthodox bibliography styles Templates allow easy customization of how BIBTEX format database entries are displayed Fig 3 shows an example bib database structure and a corre sponding template file for the display of a movie database This simple example defines a ATEX com mand nstars for printing N stars as a display of the rating variable shows the use of color com mands and works with new database fields Thus any TEX markup the user wishes to incorporate into a bibliography or into any database formatter can be implemented in Bibulous style templates Another important feature of style templates is that they are language agnostic For example if we replace TEMPLATES article lt au gt enquote book lt au gt lt ed gt from the style template with imc lt au gt enquote AS lt au gt lt ed gt Arim and AX are the Japanese words for journal article and book then we can use the Japanese forms for every entry in the bibliography database so that entries in the bib file would have the form oin C entrykey 7AX entrykey Since this shows only the entry types and not the database fields in a non English language this still shows an English language centric implementation but here is
17. nally the template instructs putting the year inside parentheses and if a note field is defined in the entry then it is added onto the end following the period If note is not defined then Bibulous adds nothing The book template in the example follows a similar procedure but has different required and optional fields The list of names at the beginning of the reference for example can be either a list of authors or a list of editors with preference given to authors if defined in the entry The book template also requires a publisher field to be inserted inside the parentheses with the publication year The sortkey special template allows users flexibility in defining how they want their citations sorted The default is simply to sort by numeri cal order sortkey lt citenum gt but one can also choose to sort by author name then title then year as in sortkey lt authorlist 0 last gt lt authorlist 0 first gt lt title gt lt booktitle gt lt year gt or if a user wants the entry to define a special sort for any given entry then they can use any fields within the entry that they wish For example to have an author sorted under a different name than is used in the reference one can add a sortname key to the database entry and redefine the sortkey template as sortkey lt sortname gt lt authorlist 0 last gt lt authorlist 0 first gt lt title gt lt booktitle gt lt year gt
18. reation of indexes etc require integrating Bibulous with a TEX package front end Bibulous authorextract functionality for example makes it easy to create a publications list such as for a CV but without front end integration it has no means of separating reference entries into independent lists That is one would often like a cvpublications bst style template that will sort references into sections differentiated by entry type e g articles book inproceedings with entries in each section sorted in reverse chronological order 339 Without integration with a front end package Bibu lous can only provide a single list as output for ATEX Similarly advanced citation labelling such as using citation commands like natbib s citep and citet require that additional information be written to the aux file to inform the bibliog raphy processor about the specific requirements of that specific reference s citation label This kind of integration is a goal for version 2 0 of Bibulous Users interested in learning more details about how to use Bibulous can find much more in the user manual available at the project website and in the source code repository The source code for the entire repository the core bibulous py file plus testing software and documentation can be found at https github com nzhagen bibulous References 1 P Lehman A Boruvka P Kime and J Wright The biblatex package Programmable
19. t citelabel lt name gt OPTIONS bibitemsep Opt replace_newlines True case_sensitive_field_names True 337 gloss bib symbol sym phi name phi description Azimuthal angle symbol sym rho name rho description Radial distance from the optical axis gloss SA name Spherical Aberration description The departure from an ideal spherical wavefront that increases quadratically with radial distance gloss Tilt name Tilt aberration description A linear departure from an ideal wavefront equivalent to a magnification error acronym MTIF Modulation Transfer function acronym PSF Point Spread Function gloss bbl begin thebibliography 6 setlength itemsep Opt bibitem MTF MTF Modulation Transfer function bibitem PSF PSF Point Spread Function bibitem Spherical Aberration SA The departure from an ideal spherical wavefront that increases quadratically with radial distance bibitem phi sym phi Azimuthal angle bibitem rho sym rho Radial distance from the optical axis bibitem Tilt aberration Tilt A linear departure from an ideal wavefront equivalent to a magnification error end thebibliography Figure 5 The main tex file style template bst file bibliography database bib file and resulting output bb1 file for the glossary example Note that beca
20. tabases and non English languages international ization localization multilingualism and more In order to specify a bibliography style Biblatex uses a combination of keyword options that are set within the main tex file to specify bibliography formats A weakness of this approach is that a user must know a large set of keywords and how to combine these to generate a custom style Learning how to format references can require reading and understanding a substantial volume of Biblatex s documentation With style templates however even first time users can see how to customize the layout without needing to consult documentation so that entirely new styles can be written up in a matter of minutes Beyond its use of templates Bibulous has other important differences from BIBTEX including 1 Bibulous converts TEX markup accented char acters to Unicode prior to performing sort func tions That is while BIBTEX will sort t ete t e te and t e te all as tete but t te separately as t te Bibulous will sort all of these cases identically as t te In addition Bibulous automatically detects the user s default locale and sorts according to standard string collation algorithms 2 Bibulous adds new options for formatting names inside bib file entries so that individual names are also allowed three or four comma delimiters This gives users more freedom to control name layout 3 Bibulous performs citation extraction by de
21. template is structured into two large op tional blocks and the selection of one or the other is decided by the document_language option variable defined by the user within the file The formatted result will look something like the following for a Japanese audience Nathan Hagen 1 BA KA Sh Em 1906 2 HIE Wih See LOE HCE 1974 1977 3 BH ER COS TE GNT 3 a7 Yay Z 2006 and the following for an English language audience 1 Soseki Natsume Ft Kusamakura Pillow of Grass Shun yod6 Publishing Tokyo 1906 2 Seizan Yanagida mi Rk Zengaku sosho Collected Materials for the Study of Zen vol 10 Chinese Book Publ Co Kyoto 1974 1977 3 Tadao Tsuruta 76 f Hikari no empitsu Pencil of Light vol 7 Shin gijutsu Communi cations Tokyo 2006 Thus the template shown in Fig 4 is not only flexible enough to handle custom database types and heterogeneous fields but also different audience lan guages Note that the example uses fields in English rather than in Japanese e g author_ja rather than 4 A in both the database and the template in order to illustrate the overall structure clearly to readers unfamiliar with Japanese 4 Implementing a glossary The utility of style templates extends beyond bibli ographies Glossaries lists of symbols i e nomen clatures and lists of acronyms are readily generated with Bibulous Figure 5 shows an example tex file toget
22. use it is only a back end en gine Bibulous by itself cannot split the glossary list of acronyms and list of symbols into three sepa rate sections of the document Doing so requires work by IATRX itself and thus requires changes to the front end The example shown here provides only a minimal amount of front end work defining the citename command as well as redefining the biblabel command and the thebibliography en vironment to make the bibliography structure ap pear as a list of definitions Bibulous A drop in BIBTEX replacement based on style templates 338 TUGboat Volume 34 2013 No 3 MTF Modulation Transfer function PSF Point Spread Function quadratically with radial distance ob Azimuthal angle p Radial distance from the optical axis error Glossary List of Symbols and Nomenclature Spherical Aberration The departure from an ideal spherical wavefront that increases Tilt aberration A linear departure from an ideal wavefront equivalent to a magnification Figure 6 The formatted glossary list of symbols and nomenclature list of acronyms for the inputs shown in Fig 5 Note that the symbols and p are sorted by citation key which are sym phi and sym rho for the case shown here Table 1 Timing comparison for BIBTEX Bibulous and Biber showing the amount of time required to generate a bb1 file for every entry in the given database Database size citations
23. y variable that is not wrapped within square brackets is considered a required variable if this field is missing from the bibliography database entry then a warning message is used in its place with the default warning message being simply The bracket notation behaves like an if elseif statement before performing any substitutions of variables into the template the con tents of the first block located inside square brack ets or between the open square bracket and the first vertical bar are checked to see whether all variables within it are defined within the entry If any variables inside the block are undefined missing from the database entry then the second block be tween the vertical bar and the close bracket is evaluated And so on This provides a flexible way of modifying the inputs to the formatted reference depending on which fields exist within a given data base entry Thus while some users may prefer to define a given field as institution and others may prefer organization a structure such as lt institution gt lt organization gt provides a simple means of accommodating both Finally a structure that ends with an empty block rather than means that even though the individual blocks are optional at least one of the blocks is required to be defined within the data base entry Thus for example the required variable lt note gt is equivalent to lt note gt To
Download Pdf Manuals
Related Search