Make xrefs and olinks work, and prevent instances of “ and
” entities in output (closes #741578 and #956072; thanks to
Jens Granseuer and Sam Steingold for reporting the problems)
::Problem:
If you include an xref in a source document, instead of getting
the xref text you would expect in the output, you just get
"[xref to refsect1]", where "refsect" is the name of the target
element for the xref. If you include an olink, it works as
expected -- except that the output text has “ and ”
entities (double "curly" quotation marks).
::Cause:
The manpages/docbook.xsl driver imports the html/docbook.xsl
stylesheet, which in turn imports the html/xref.xsl file.
The manpages/docbook.xsl file then imports the manpages/xref.xsl
file. That file contains a "xref" template that overrides the
the one in html/xref.xsl and that, by design, does nothing
except to generate the "[xref to refsect1]" text instead of the
expected xref output.
On the other hand, the manpages stylesheets don't override the
"olink" template; therefore, the "olink" template from the
html/xref.xsl file is used "as is". And being that it is
intended for HTML output, that template uses the “ and
” to wrap titles in xref output.
::Fix:
The original manpages/xref.xsl file has now been removed. The
build for the manpages distribution now makes that file, using
the textify.xsl stylesheet to automatically generate it from the
html/xref.xsl file. It is built in such a away that it basically
just contains special copies of the "xref" and "olink" templates
that cause “ and ” instances to be transformed into
"\(lq" and "\(rq" (groff "left quote" and "right quote").
It might seem odd that templates from the html/xref.xsl are
used, since those templates a designed to generate hyperlinks of
the form <a href="#foo">the section called "Bar"</a>. But it
works because the manpages stylesheets end up using the text
value of the output of the above. Thus, the <a href="#foo"> and
</a> parts are stripped out, leaving just the text between
('the section called "Bar"').
::Affects
Only affects output of xref and olink elements. The fix may not
be complete and/or may cause other problems. Please test.
In particular, while it may fix the “ and ” problem
that English lang/locales users have run into, it doesn't fix
the corresponding problem for output of xrefs and olinks in many
non-English locales, which use quoting characters other than
“ and ”
To give just one example of many: in Japanese, the quoting
characters are 「 and 」 ("left corner bracket" and
"right corner bracket"). It is possible to "fix" the problem for
all locales; but it is just a question of whether there is
enough of a demand for it that it is worth doing.