Improve support for automatic bibliographies, small tweaks to glossary handling

[ndw]

1. I set out to implement support for automatic bibliographies along lines analagous to how automatic bibliographies work, but the analogy isn't very good 😄 . Bibliography entries are identified by ID/IDREF cross references so there's less work to do. I did add documentation about how bibliographies work and I added support for a role="auto" on bibliographies that causes unused entries to be omitted.
2. I reworked the implementation of automatic glossary handling to avoid reordering the entries in the glossary. As implemented, the entries were always in the order of reference. That isn't noticable when the terms are then sorted, but if a user wants to do the sorting manually, enabling the auto feature shouldn't reorder the entries arbitrarily.
3. I fixed a few small markup errors and typos.

[fsteimke]

I believe that the citation element for bibliographies is roughly equivalent to what the glossterm is for glossaries. Therefore it would be nice if there was an improvement in 50-normalize so that citation elements are automatically linked to the biblioentry element whose abbrev element is identical to text-content of citation.

In this case, users would not necessarily have to provide the biblioentry/@xml:id attribute. The only requirement is, that for every citation element there is a matching biblioentry/abbrev Element. The link from citation to biblioentry would be created on the fly in 50-normalize, which means to create both attributes citation/@linkend and biblioentry/@xml:id.

This would also apply for bibliomixed instead of biblioentry.

I would need a new public function f:biblioentries ( element(citation) ) as element()* in standalone-functions.xsl, so that i can write Schematron rules to check the existence of a matching biblioentry or bibliomixed elements in one of the internal or external (shared) bibliographies. And this public functions need helper functions very similar to glossterm / glossentry.

The analogy is not that bad.

[ndw]

Ah. Fair point. Bibliographic markup in DocBook is not as tidy as it could be. I tend to use biblioref but citation is clearly a possibility.

[ndw]

I've added support for automatic bibliographies that are more similar to automatic glossaries when using citation for bibliographic citations. There's a biblioentries function like glossentries that could be used for Schematron (I think).

One consequence of reworking how the bibliographies and glossaries are constructed (to avoid reordering elements) is that those functions aren't actually used by the stylesheets anymore. I don't know if that's a problem or not.

[ndw]

I think the stylesheets are ready to go; what I didn't have time to finish this morning is the documentation.

[fsteimke]

I am also eager to have a new release. Thanks a lot, Norm.

I have started with Schematron for glossaries using SchXslt. The Schema is simple. The challenge is to implement it in a way that can be integrated in the xspec automatic testing. Especially we will have relative URIs to integrate standalone functions in the (compiled) schematron stylesheet. I'm afraid I'll have to bother you for this.

I think we should try to find a solution where Schematron stylesheets and xslTNG transformation stylesheets use the same function to find matching entries for terms. Otherwise there is always a risk that schematron signals "OK" but transformation leads to errors. Maybe i can improve the f:glossentries function, so that it can be used in the transformation stylesheets?

[ndw]

Yes, it makes sense to use the same functions in both places or there's risk of drift. The problem with the f:glossentries function isn't in the implementation, exactly. The problem is that if you start with the terms in the source document, with the references in document order, to find the glossentry elements that should be included, you end up with the list of glossentry elements in that order in the glossary. You don't notice if they're then sorted, of course, but what if they aren't? Changing the order in someone's glossary is unfriendly.

That's even more problematic in the bibliography where sorting is impractical.

I think the solution is probably a pair of simpler functions: given a term or citation, what are it's corresponding referents? And, given a glossentry or bibliography entry, does it have any referrers? I'll take another look this evening after the day job 😄

[fsteimke]

Norm, i have a question about the f:pi#3 function which is now located in standalone-functions.xsl. It contains this line:

<xsl:sequence select="fp:pi-from-list(($context/processing-instruction('db'),
                                             root($context)/processing-instruction('db')),
                                            $property, $default)"/>

Let's say that the $context is an glossterm Element. In this case the line above looks for an PI node at two places:

• child Element of $context, that is glossterm/<?db ... ?> and
• child Element of root(glossterm). The result of a root function call will usually, but not necessarily, be a document node. When i call the f:pi function from schematron, it will be the document node.

In other words, when called from schematron, it will find the dp PI only in this case:

<? db glossary-collection=... ?>
<article>
 ...
</article>

but not when it is a child of the root element

<article>
  <?db glossary-collection=... ?>
  ...
</article>

I am afraid that the f:pi function behaves different when called from schematron (where root() returns a document node) or called from xslTNG Stylesheets (where root() returns an element node).

I have made my first schematron experiments which work very well. But when i test with glossary.007.xml from your pre-release, it can't find the external glossary from schematron. I had to move the processing instruction outside of the article and make it a documents child node. The above seems to explain this issue.

What do you think?

Greetings, Frank

[ndw]

Yeah. I think that's a bug. I'm going to refactor a bunch of things tonight.

[ndw]

I more-or-less completely reworked the way automatic glossaries and bibliographies work. I think the end result is equally useful and suitable for use in Schematron.

1. I reworked the implementation to use xsl:keys
2. I changed the functions so that it's possible to pass the external collections parameters to them (this means you can use $bibliography-collection and $glossary-collection even in the standalone functions. Those parameters will have to be passed to Schematron as well, of course.
3. I hope I haven't broken anything! 😄

[fsteimke]

I have checked with the Schematron schema for Glossary and it looks very good, passing $glossary-collection to Schematron with the processing-instruction.