Skip to content

Commit

Permalink
Merge pull request #466 from ndw/improve-bib
Browse files Browse the repository at this point in the history 
Improve support for automatic bibliographies, small tweaks to glossary handling
  • Loading branch information
@ndw
ndw authored Feb 2, 2024
2 parents ca65487 + bcc217a commit 6276ffe
Show file tree
Hide file tree
Showing 28 changed files with 1,265 additions and 142 deletions.
11 changes: 11 additions & 0 deletions build.gradle
View file
Original file line number Diff line number Diff line change
Expand Up @@ -541,10 +541,21 @@ task copyXslt(dependsOn: ['copyResources', 'makeVersion',
}
}

task testStandalone(type: SaxonXsltTask) {
// The output of this test doesn't matter; it simply assures that
// the standalone-functions.xsl file hasn't accidentally become
// dependent on other stylesheets so it isn't properly standalone
inputs.dir "${buildDir}/xslt"
input "${projectDir}/src/test/resources/xml/article.001.xml"
stylesheet "${projectDir}/tools/standalone.xsl"
output "${buildDir}/tmp/standalone.xml"
}

task makeXslt(type: SaxonXsltTask, dependsOn: ["copyXslt"]) {
input "${projectDir}/src/guide/xml/ref-params.xml"
stylesheet "${projectDir}/tools/generate-parameters.xsl"
output "${buildDir}/xslt/param.xsl"
finalizedBy = [ 'testStandalone' ]
}

task makeUriList(
Expand Down
4 changes: 2 additions & 2 deletions properties.gradle
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@
ext {
xslTNGtitle = 'DocBook xslTNG'
xslTNGbaseName = 'docbook-xslTNG'
xslTNGversion = '2.1.9'
guideVersion = '2.1.9'
xslTNGversion = '2.2.0'
guideVersion = '2.2.0'
guidePrerelease = false

docbookVersion = '5.2CR5'
Expand Down
113 changes: 112 additions & 1 deletion src/guide/xml/ch03.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -675,7 +675,7 @@ This most closely reproduces the numbering from the 1.x stylesheets.</para>

</section>

<section>
<section xml:id="using-glossaries">
<title>Using glossaries</title>

<para>There are essentially two ways to manage glossaries: you can
Expand Down Expand Up @@ -743,6 +743,117 @@ xslTNG framework.</para>
<parameter>glossary-automatic-divisions</parameter> parameter.</para>
</section>

<section xml:id="using-bibliographies">
<title>Using bibliographies</title>

<para>Bibliographies are more complicated than glossaries.
Bibliography entries can be “cooked” (<tag>bibliomixed</tag>) or “raw”
(<tag>biblioentry</tag>) and there’s no obvious way to sort
bibliography entries in the general case.</para>

<para>There are also two different cross-referencing mechanisms for
bibliographic entries: by ID, using <tag>biblioref</tag> or <tag>xref</tag>,
or with <tag>citation</tag> that matches on <tag>abbrev</tag> elements
in the bibliography entry.</para>

<para>Consider this example bibliography:</para>

<programlisting language="xml"><![CDATA[<bibliography>
<bibliomixed xml:id="bib.xml"><abbrev>XML</abbrev>Tim Bray,
Jean Paoli, …</bibliomixed>
<biblioentry><abbrev>MalerElAndaloussi96</abbrev>
<title>Developing SGML DTDs</title> …</biblioentry>
</bibliography>]]></programlisting>

<para>The first entry can be cited in two ways: <code>&lt;biblioref linkend="bib.xml"/&gt;</code>
or <code>&lt;citation&gt;XML&lt;/citation&gt;</code>. The second can only be cited with
a <code>&lt;citation&gt;MalerElAndaloussi96&lt;/citation&gt;</code>
(it has no <att>xml:id</att> to link to).</para>

<para>Taking all of these variations into account, there are three
ways to construct bibliographies:</para>

<orderedlist>
<listitem><para><link linkend="bib.byhand">Entirely by hand</link>.</para>
</listitem>
<listitem><para><link linkend="bib.managed.by.hand">Managed by hand</link>,
with empty elements as placeholders.</para>
</listitem>
<listitem><para><link linkend="bib.automatic">Managed automatically</link>.</para>
</listitem>
</orderedlist>

<para>There are tradeoffs to each approach.</para>

<para>When external bibliographies are used, they can be identified either with the
<parameter>bibliography-collection</parameter> parameter or with
<tag class="pi">db</tag><indexterm><primary>db processing instruction</primary>
</indexterm> processing instructions with a
<literal>bibliography-collection</literal><indexterm>
<primary>db processing instruction</primary>
<secondary>bibliography-collection pseudo-attribute</secondary>
</indexterm> pseudo-attribute in the root element.</para>

<section xml:id="bib.byhand">
<title>Entirely by hand</title>
<para>In a bibliography constructed entirely by hand, no special processing
takes place. The entries appear as they are listed and every entry appears
whether it is cited or not. The author is free to use <tag>bibliodiv</tag> elements
to divide the bibliography into sections and the document may have multiple
<tag>bibliography</tag> elements.</para>
</section>

<section xml:id="bib.managed.by.hand">
<title>Managed by hand</title>
<para>Bibliographic entries can be complex and may be shared across multiple
documents. One approach to managing this complexity is to store the full entries in
an external bibliography and use only placeholders in your actual document.</para>
<para>A placeholder is an empty entry with an <att>xml:id</att>, or an entry that contains only an
<tag>abbrev</tag> (if it has both an <att>xml:id</att> and contains only an <tag>abbrev</tag>, the
ID will be used to search for a matching entry in the external bibliography).
It will be replaced by the full entry from the external bibliography
when the document is formatted.</para>
<para>For example, if the full entries are available externally, the preceding
bibliography example could be shortened to:</para>

<programlisting language="xml"><![CDATA[<bibliography>
<bibliomixed xml:id="bib.xml"/>
<biblioentry><abbrev>MalerElAndaloussi96</abbrev>
</biblioentry>
</bibliography>]]></programlisting>

<para>The entries appear in the order listed and every entry appears
whether it is cited or not. The author is free to use <tag>bibliodiv</tag> elements
to divide the bibliography into sections and the document may have multiple
<tag>bibliography</tag> elements.</para>
</section>

<section xml:id="bib.automatic">
<title>Automatic</title>

<para>An automatic bibliography is selected by using the token
<code>auto</code> in the <att>role</att> attribute on a bibliography.
Placeholders can still be used, but they are unnecessary when using
<tag>citation</tag> for citations.</para>

<para>Any citation that appear in the text will be matched to entries
in the external bibliographies. Those entries will be included
automatically. Automatically added entries appear at the end of the
bibliography (after any internal ones, if the internal bibliography
has entries), in the order that they appear in the external
bibliographies.
If multiple external entries match, only the first is added.</para>

<para>Any bibliography entries in the internal bibliography that
<emphasis>aren’t</emphasis> cited will be removed.</para>

<para>When using the automatic style, there should be only one
<tag>bibliography</tag> in the document and it cannot contain
divisions.</para>
</section>
</section>

<section xml:id="different">
<title>Creating something completely different</title>

Expand Down
97 changes: 97 additions & 0 deletions src/guide/xml/changelog.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,103 @@ be of interest to users of the stylesheets. See the commits and pull requests on
<link xlink:href="https://github.com/docbook/xslTNG/">the repository</link> for
finer detail.</para>

<section xml:id="r220">
<info>
<title>Changes in version 2.2.0</title>
<productnumber>2.2.0</productnumber>
<date>2024-02-02</date>
</info>
<itemizedlist>
<listitem>
<para>Ensure that subtitle appears on a book titlepage, fixed
<link xlink:href="https://github.com/docbook/xslTNG/issues/415">#415</link>.
</para>
</listitem>

<listitem>
<para>Make sure <varname>v:debug</varname> is declared in <filename>print.xsl</filename>, fixed
<link xlink:href="https://github.com/docbook/xslTNG/issues/420">#420</link>.
</para>
</listitem>

<listitem>
<para>Corrected the image intrinsic functions so that non-integer dimensions are supported in SVG;
added support for dimensions with units, fixed
<link xlink:href="https://github.com/docbook/xslTNG/issues/413">#413</link>,
<link xlink:href="https://github.com/docbook/xslTNG/issues/432">#432</link>, and
<link xlink:href="https://github.com/docbook/xslTNG/issues/443">#443</link>.
</para>
</listitem>

<listitem>
<para>Column widths computed from CALS tables did not correctly specify units, fixed
<link xlink:href="https://github.com/docbook/xslTNG/issues/410">#410</link>.
</para>
</listitem>

<listitem>
<para>Integrated improved support for improved
<link linkend="customize-individual-cross-references">cross reference styles</link>
contributed by Frank Steimke, fixed
<link xlink:href="https://github.com/docbook/xslTNG/issues/414">#414</link>.
</para>
</listitem>

<listitem>
<para>Merged a fix to the German localization contributed by Tom Schraitle, fixed
<link xlink:href="https://github.com/docbook/xslTNG/issues/428">#428</link>.
</para>
</listitem>

<listitem>
<para>Attempted to work around a scrolling issue in the persistent ToC, fixed
<link xlink:href="https://github.com/docbook/xslTNG/issues/451">#451</link>.
</para>
</listitem>

<listitem>
<para>Merged a patch, contributed by Frank Steimke, to avoid a
warning when a table width is exactly the same as the nominal page
width, fixed
<link xlink:href="https://github.com/docbook/xslTNG/issues/411">#411</link>.
</para>
</listitem>

<listitem>
<para>Allow pre- and post-processing transforms to be specified as command line parameters, fixed
<link xlink:href="https://github.com/docbook/xslTNG/issues/440">#440</link>
and
<link xlink:href="https://github.com/docbook/xslTNG/issues/441">#441</link>
</para>
</listitem>

<listitem>
<para>Integrated support for
<link linkend="using-glossaries">automatic glossaries</link>
contributed by Frank Steimke. Fixed
<link xlink:href="https://github.com/docbook/xslTNG/issues/453">#453</link>,
and
<link xlink:href="https://github.com/docbook/xslTNG/issues/445">#445</link>.
Extended to support automatic glossary divisions, fixed
<link xlink:href="https://github.com/docbook/xslTNG/issues/453">#460</link>.
</para>
</listitem>

<listitem>
<para>Added support for
<link linkend="using-bibliographies">automatic bibliographies</link>
somewhat analagous to automatic glossaries.
</para>
</listitem>

<listitem>
<para>Integrated documentation improvements contributed by Frank Steimke, fixed
<link xlink:href="https://github.com/docbook/xslTNG/issues/452">#452</link>.
</para>
</listitem>
</itemizedlist>
</section>

<section xml:id="r219">
<info>
<title>Changes in version 2.1.9</title>
Expand Down
1 change: 1 addition & 0 deletions src/guide/xml/guide.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ contained herein.</para>
<year>2021</year>
<year>2022</year>
<year>2023</year>
<year>2024</year>
<holder>Norman Walsh</holder>
</copyright>
</info>
Expand Down
Loading

0 comments on commit 6276ffe

Please sign in to comment.