6 <tmdoc-title|Writing <TeXmacs> bibliography styles>
10 <TeXmacs> admits support both for <BibTeX> and a native tool for managing
11 bibliographies. <BibTeX> styles are denoted by their usual names. <TeXmacs>
12 styles are prefixed by <verbatim|tm->. For example, the <TeXmacs>
13 <verbatim|<group|tm-plain>> style is the replacement for the <BibTeX>
14 <verbatim|plain> style. Equivalents for the following <BibTeX> styles have
15 been implemented: <verbatim|abbrv>, <verbatim|alpha>, <verbatim|ieeetr>,
16 <verbatim|plain> et <verbatim|siam>. These styles can therefore be used
17 without installation of <BibTeX>.
19 New bibliography styles can be defined by the user. Each style is
20 associated to a<nbsp>unique <scheme> file, which should be added to the
21 directory <verbatim|$TEXMACS_PATH/prog/bibtex>. Style files are treated as
22 regular Scheme programs. Since the creation of a style file from scratch is
23 a complex task, we recommend you customize existing style files or modules.
24 In the next sections, we will describe the creation of a new style on a
25 simple example and give a detailed lists of available <scheme> functions
26 which facilitate the creation of new styles.
28 <section|Example of a simple blibliography style>
30 Bibliographic style files are stored in directory
31 <verbatim|$TEXMACS_PATH/progs/bibtex>. They have the name of the style
32 followed with extension <verbatim|.scm>. For example,
33 <verbatim|example.scm> is the file name associated to the style
34 <verbatim|example>, which is denoted by <verbatim|tm-example> when it is
35 used in a <TeXmacs> document.
37 All style files must be declared as a module as follows:
40 (texmacs-module (bibtex example)
42 \ \ (:use (bibtex bib-utils)))
45 The module <verbatim|bib-utils> contains all usefull fonctions needed to
46 write bibliographic styles.
48 All style files must me declared as a bibliographic style as follows:
50 <scm-fragment|(bib-define-style "example" "plain")>
52 The first argument to <scm|bib-define-style> is the name of the current
53 style. The second argument is the name of a fall-back style,
54 <verbatim|plain> in our case. If a function is not defined in current
55 style, the function from the fall-back style is used instead. Hence, the
56 following minimalistic style file behaves in an identical way as the
57 <verbatim|plain> style:
60 (texmacs-module (bibtex example)
62 \ \ (:use (bibtex bib-utils)))
66 (bib-define-style "example" "plain")
69 Each formatting function defined in the default style can be overloaded in
70 the current style. For example, the function <scm|bib-format-date> is used
71 to format the date in the <verbatim|plain> style. It is redefinable in our
72 example style as follows:
75 (tm-define (bib-format-date e)
77 \ \ (:mode bib-example?)
79 \ \ (bib-format-field e "year"))
82 All exported functions must be prefixed with <verbatim|bib->. Overloaded
83 functions must be followed with directive <scm|(:mode bib-example?)>, in
84 which <verbatim|example> is the name of the current style.
86 Our complete example file <verbatim|example.scm> is as follows:
89 (texmacs-module (bibtex example)
91 \ \ (:use (bibtex bib-utils)))
95 (bib-define-style "example" "plain")
99 (tm-define (bib-format-date e)
101 \ \ (:mode bib-example?)
103 \ \ (bib-format-field e "year"))
106 It behaves in a similar way as the <verbatim|plain> style, except that all
107 dates are formatted according to our custom routine.
109 <section|<scheme> functions for writing bibliography styles>
111 <subsection|Style management>
114 <scm|(bib-define-style name default)><explain-synopsis|style declaration>
116 This function declares a style called <scm|name> (string) with fall-back
117 style <scm|default> (string). The style is selected by choosing
118 <verbatim|tm-><scm|name> when adding a bibliography to a document.
119 Whenever a<nbsp>formatting function is not defined in the current style,
120 its definition in the fall-back style is used as replacement.
124 <scm|(bib-with-style style expr)><explain-synopsis|local style>
126 This function evaluates expression <scm|expr> as if the current style
127 were <scm|style> (string).
130 <subsection|Field related routines>
133 <scm|(bib-field entry field)><explain-synopsis|field data>
135 This function creates a <TeXmacs> tree corresponding to the field
136 <scm|field> (string) of entry <scm|entry> without format. In some cases,
137 the output is special:
140 <item>If <scm|field> is <scm|"author"> or <scm|"editor">, we return a
141 tree with label <verbatim|bib-names> followed by a list of author
142 names; each author name is a tree with label <verbatim|bib-name>
143 containing four elements: first name, particule (von), last name and
146 <item>If <scm|field> is <scm|"page">, then we return a list of
147 integers: the empty list, or a singleton with a page number, or a pair
148 corresponding to a pages interval.
153 <scm|(bib-format-field entry field)><explain-synopsis|basic format>
155 This function creates a <TeXmacs> tree corresponding to the field
156 <scm|field> (string) of entry <scm|entry>, with basic format.
160 <scm|(bib-format-field-Locase entry field)><explain-synopsis|special
163 This function is similar to <scm|bib-format-field> ; but field are
164 formatted in lower case with an upper case letter at the beginning.
168 <scm|(bib-empty? entry field)><explain-synopsis|null-test of a field>
170 This function returns boolean <scm|#t> if the field <scm|field> (string)
171 of entry <scm|entry> is empty or absent; it returns <scm|#f> in the other
175 <subsection|Routines for structuring the output>
178 <scm|(bib-new-block tm)><explain-synopsis|new block>
180 This function creates a<TeXmacs> tree consisting of a block containing
181 <TeXmacs> tree <scm|tm>.
185 <scm|(bib-new-list sep ltm)><explain-synopsis|separated list>
187 This function creates a <TeXmacs> tree which is the concatenation of all
188 the elements of list <scm|ltm> separated with <TeXmacs> tree <scm|sep>.
192 <scm|(bib-new-list-spc ltm)><explain-synopsis|blank separated list>
194 This function is equivalent to the evaluaton of <scm|(bib-new-list " "
199 <scm|(bib-new-sentence ltm)><explain-synopsis|new sentence>
201 This function creates a <TeXmacs> tree corresponding to a sentence
202 containing all the elements of list <scm|ltm> separated by commas.
205 <subsection|Routines for textual manipulations>
208 <scm|(bib-abbreviate name dot spc)><explain-synopsis|name abbreviation>
210 This function creates a <TeXmacs> tree corresponding to the abbreviation
211 of the name contained in <scm|name> <TeXmacs> tree: it retrieves the list
212 of first letters of each word, followed by <scm|dot> (<TeXmacs> tree) and
213 separated by <scm|spc> (<TeXmacs> tree).
217 <scm|(bib-add-period tm)><explain-synopsis|dot>
219 This function creates a <TeXmacs> tree with a dot at the end of <scm|tm>.
223 <scm|(bib-default tm)><explain-synopsis|default <TeXmacs> tree>
225 This function creates a <TeXmacs> tree without label
226 <verbatim|keep-case>.
230 <scm|(bib-emphasize tm)><explain-synopsis|italic>
232 This function creates a <TeXmacs> tree corresponding to the italic
237 <scm|(bib-locase tm)><explain-synopsis|lower case>
239 This function creates a <TeXmacs> tree, which is equal to <scm|tm> with
240 all letters in lower case, except for those within <verbatim|keep-case>
245 <scm|(bib-prefix tm nbcar)><explain-synopsis|beginning of a <TeXmacs>
248 This function returns a string containing the first <scm|nbcar>
249 characters of <scm|tm>.
253 <scm|(bib-upcase tm)><explain-synopsis|upper case>
255 This function creates a <TeXmacs> tree, which is equal to <scm|tm> with
256 all letters in upper case, except for those within <verbatim|keep-case>
261 <scm|(bib-upcase-first tm)><explain-synopsis|upper case first letter>
263 This function creates a <TeXmacs> tree, which is equal to <scm|tm> with
264 its first letter in upper case, except inside <verbatim|keep-case>
268 <subsection|Miscellaneous routines>
271 <scm|(bib-null? v)><explain-synopsis|null-test>
273 This function returns boolean <scm|#t> if value <scm|v> is empty; it
274 returns <scm|#f> in the other cases.
278 <scm|(bib-purify tm)><explain-synopsis|flattening of a <TeXmacs> tree>
280 This function returns a string made of all letters of the <TeXmacs> tree
285 <scm|(bib-simplify tm)><explain-synopsis|simplification of a <TeXmacs>
288 This function returns a <TeXmacs> tree corresponding to the
289 simplification of <TeXmacs> tree <scm|tm>.
293 <scm|(bib-text-length tm)><explain-synopsis|length of a <TeXmacs> tree>
295 This function returns the length of <TeXmacs> tree <scm|tm>.
299 <scm|(bib-translate msg)><explain-synopsis|translation>
301 This function translates the string message <scm|msg> from english into
302 the current language.
308 <associate|language|english>
309 <associate|preamble|false>