1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
<section>
<title>Writing a Bibliography</title>
<para>
A bibliography (<sgmltag>bibliography</sgmltag>) can be written and put anywhere in the document. It appears as a chapter or a section and is composed by several divisions (<sgmltag>bibliodiv</sgmltag>) displayed as sections or subsections.
</para>
<section><title>Using Bibliography Entries</title>
<para>
The writer selects information that describes each bibliography entry (<sgmltag>biblioentry</sgmltag>), and chooses the presentation order. The titles and authors are displayed first.
</para>
<example><title>A Bibliography</title>
<programlisting>
<![CDATA[<bibliography><title>Bibliography Example</title>
<bibliodiv><title>References</title>
<biblioentry>
<title>Document title</title>
<author><firstname>J.</firstname><surname>Doe</surname></author>
<pubsnumber>DEX000567325</pubsnumber>
</biblioentry>
</bibliodiv>
<bibliodiv><title>White papers</title>
<biblioentry>
<title>Technical notes</title>
<authorgroup>
<author><firstname>J.</firstname><surname>Doe</surname></author>
<author><firstname>R.</firstname><surname>Marion</surname></author>
</authorgroup>
<pubsnumber>DEX000704520</pubsnumber>
</biblioentry>
</bibliodiv>
</bibliography>
]]> </programlisting>
</example>
</section>
<section id="sec-bibtex"><title>Using BibTeX Databases</title>
<para>Instead of writing the bibliographic materials in DocBook you can reuse
some already available BibTeX databases. Of course, this feature is specific to
<command>dblatex</command>, that will automatically call <command>bibtex</command>
if some bibtex databases are used.</para>
<para>To do so, write a <sgmltag>bibliodiv</sgmltag> containing an empty
<sgmltag>bibliomixed</sgmltag> element having a
<literal>bibtex</literal> processing instruction specifying the databases to use
and the style to apply.</para>
<para>More precisely here are the attributes supported by the
<literal>bibtex</literal> PI:
<variablelist>
<varlistentry><term>bibfiles</term>
<listitem><para>This attribute is mandatory and specifies the databases to use.
The databases are separated by
commas, and must not contain the file suffix (<literal>.bib</literal>). The bibfiles
paths must be absolute or relative to the base directory of the document. You
can also add some bibfile paths by using the <option>-L</option> option.</para>
</listitem>
</varlistentry>
<varlistentry><term>bibstyle</term>
<listitem>
<para>Optional attribute specifying the bibliographic style to apply for rendering
the databases. You can also change globally the style to apply with the
<parameter>latex.biblio.style</parameter>.</para>
<para>The actual style file used by
<command>bibtex</command> is searched in the default paths, but some extra paths
can be added by using the <option>-l</option> option.</para>
</listitem>
</varlistentry>
<varlistentry><term>mode</term>
<listitem>
<para>Optional print mode. The available values are:
<variablelist>
<varlistentry><term>all</term>
<listitem><para>Print all the entries contained in the databases.</para></listitem>
</varlistentry>
<varlistentry><term>cited</term>
<listitem><para>Print only the entries cited in the document.</para></listitem>
</varlistentry>
<varlistentry><term>notcited</term>
<listitem><para>Print only the entries <emphasis>not</emphasis> cited in the
document.</para></listitem>
</varlistentry>
</variablelist>
</para>
<para>When the attribute is not used, the
<parameter>latex.biblio.output</parameter> parameter is used as print mode. By
default the print mode is set to 'all'.</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>Some <sgmltag>bibliodiv</sgmltag>s embedding bibliographic entries can be mixed with some <sgmltag>bibliodiv</sgmltag>s using BibTeX databases, as shown by <xref
linkend="eg-bibmixed"/>.</para>
<example id="eg-bibmixed"><title>Bibliography using BibTeX databases</title>
<programlisting>
<![CDATA[<bibliography><title>Bibliography Example</title>
<bibliodiv><title>References</title>
<biblioentry>
<title>Document Title</title>
<author><firstname>J.</firstname><surname>Doe</surname></author>
<pubsnumber>DEX000567325</pubsnumber>
</biblioentry>
</bibliodiv>
<bibliodiv><title>Bibtex References</title>
<bibliomixed><?bibtex bibfiles="bib/latex-bib" bibstyle="alpha"?></bibliomixed>
</bibliodiv>
<bibliodiv><title>Cited Bibtex References</title>
<bibliomixed><?bibtex bibfiles="bib/database1,bib/database2"
bibstyle="plain"
mode="cited"?></bibliomixed>
</bibliodiv>
</bibliography>
]]> </programlisting>
</example>
</section>
<section id="sec-natbib"><title>Natbib Citations</title>
<para>You can apply natbib citation styles by playing with the citation role
attribute, or with a <literal>dblatex</literal> processing instruction. The
natbib use is enabled only when the <parameter>citation.natbib.use</parameter>
paramater is set to 1; if not (default) the role attribute or PI are not taken
into account even if present. The natbib package can be loaded with user specific
options by setting the <parameter>citation.natbib.options</parameter>
parameter.</para>
<para>When using the role attribute, simply type the natbib citation command to
apply. When using the <literal>dblatex</literal> PI, put the natbib command in
the <sgmltag>citestyle</sgmltag> attribute.</para>
<para>If you need to put some square brackets "[ ]" in the citation texts, enclose
the whole text with "{ }" to protect them (as you would do in latex).</para>
<para>Here are some examples:</para>
<programlisting><![CDATA[<para>
<citation role="\citep[see][chap. #2]">texbook</citation>
<citation role="\citep[see][{[chap. #2]}]">texbook</citation>
<citation><?dblatex citestyle="\citep[see][chap. #2]"?>texbook</citation>
<citation>texbook</citation>
</para>]]></programlisting>
<para>You can use a global natib citation style with the
<parameter>citation.default.style</parameter> parameter. By default the
parameter is empty, and therefor is not used.</para>
</section>
</section>
|
