]> granicus.if.org Git - docbook-dsssl/commit
Make xrefs and olinks work, and prevent instances of “ and
authorMichael Smith <xmldoc@users.sourceforge.net>
Tue, 24 May 2005 22:40:41 +0000 (22:40 +0000)
committerMichael Smith <xmldoc@users.sourceforge.net>
Tue, 24 May 2005 22:40:41 +0000 (22:40 +0000)
commit6122c8882861de52db2a2c5557787d35b6f97a91
tree600cee6d2e7f088894ae633cd5c36ecbd7afe39d
parent084797e7bcb12ec6a5809993d123e2b545edcb8c
Make xrefs and olinks work, and prevent instances of &#8220; and
&#8221; 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 &#8220; and &#8221;
  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 &#8220; and
  &#8221; 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 &#8220; and &#8221; 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 &#8220; and &#8221; 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
  &#8220; and &#8221;

  To give just one example of many: in Japanese, the quoting
  characters are &#12300; and &#12301; ("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.
xsl/manpages/.cvsignore
xsl/manpages/Makefile
xsl/manpages/textify.xsl [new file with mode: 0644]
xsl/manpages/xref.xsl [deleted file]