I have the problem that internal chapter and section links using the docbook <link linkend="sec> element did work in the past but no longer (currently I am using docbook/stylesheets/daps from openSUSE 42.1 Leap (daps-2.1.5)):
If i build with daps2013 stylesheets (with minor unrelated adaptions (mostly colors)) I find my section links rendered in the link color but
a) with empty parenthesis at the end (I'll provide a screenshot) and
b) being defunct (mouse pointer does not change when hovering, no tooltip with page number, click does not follow the link).
For finding the cause I used a minimal example (created with daps-init) and added a few section links.
With that I found to have this problem if I use any other then
We distinguish in our docs between internal and external links strictly. For internal cross references we use always <xref/> and for external (remote) links we use <link/>.
Although DocBook 5 allows the ubiquitous linkend attribute everywhere I wouldn't use it.
With this definition in mind, our stylesheets does much more processing of <xref/> than <link/>. For example, it supports what we call "intra book linking". Here is an example of such a cross reference from the DAPS Quickstart:
For more details, refer to Book “User Guide”, Chapter 9 “Customizing Layout of the Output Formats”.
The text after "refer to" was an <xref/> originally. The stylesheets resolve it to ordinary text. However, this processing isn't done for <link/>.
To make a long story short: The solution would be to make a clearer distinction between internal and external links. Probably something for a styleguide if you want to make it correct.
Does that help?
Tom
Last edit: Thomas Schraitle 2016-06-08
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
We distinguish in our docs between internal and external links strictly.
For internal cross references we use always <xref/> and for external (remote) links we use <link/>.
For our internal docs we distinguish two types of internal links:
1) Using <xref> for verbose links, to be rendered with section (or figure, ...) number and title and
2) Using <link> to be rendered just as 'ordinary' links without any additional link text in order to minimize distraction for the user.
This is intentional.
The text after "refer to" was an <xref/> originally. The stylesheets resolve it to ordinary text.
However, this processing isn't done for <link/>.
On the other hand processing is obviously done for <link>:
- With the suse stylesheet proper PDF links are generated.
- With any other stylesheet the link will be rendered colored with empty parenthesis and a link icon attached (see my screenshot), but it will no longer function as a link.
I'd guess tweaking the stylesheets to fix this (make <link> work) should be easy (as there is a working example given by the suse stylesheets).
And I'd very much prefer to stay with <link> then to replace ~200 occurences with a semantically equivalent <xref linkend=... xrefstyle='whatever'> expression.
Thanks
Stefan
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
For our internal docs we distinguish two types of internal links:
1) Using <xref> for verbose links, to be rendered with section (or figure, ...) number and title and
2) Using <link> to be rendered just as 'ordinary' links without any additional link text in order to minimize distraction for the user.
This is intentional.
Ok, I see.
I'd guess tweaking the stylesheets to fix this (make <link> work) should be easy (as there is a working example given by the suse stylesheets).
You could customize the daps2013 stylesheets. ;-)
And I'd very much prefer to stay with <link> then to replace ~200 occurences with a semantically equivalent <xref linkend="..." xrefstyle="whatever"> expression.
I understand that.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I'd really consider this is a bug in newer stylesheet implementations and it therefore should be fixed there and for everyone.
But its hard for me to identify which XSL does processing of link elements (or inherits it):
The daps stylesheets seem to rely on the suse2013 stylesheets.
The implementation of fo/xref.xsl of the latter differs considerably from the fo/xref.xsl of the older suse stylesheets (which according to the logs were formerly known as 'xslt2005') and which do not show this link generation problem.
For the suse fo stylesheets the only XSL which seems to handle linkend seems to be xref.xsl.
While the suse/fo/xref.xsl has a template explcitly matching link elements this is no longer the case for suse2013/fo/xref.xsl.
Maybe this is the case because some unified handling of all elements having a linkend attribute has been introduced.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I have the problem that internal chapter and section links using the docbook
<link linkend="sec>element did work in the past but no longer (currently I am using docbook/stylesheets/daps from openSUSE 42.1 Leap (daps-2.1.5)):If i build with daps2013 stylesheets (with minor unrelated adaptions (mostly colors)) I find my section links rendered in the link color but
a) with empty parenthesis at the end (I'll provide a screenshot) and
b) being defunct (mouse pointer does not change when hovering, no tooltip with page number, click does not follow the link).
For finding the cause I used a minimal example (created with daps-init) and added a few section links.
With that I found to have this problem if I use any other then
If i build with the latter the links are not colored but do function as links (with tooltip, etc.).
Hi Stefan,
thanks for your report.
We distinguish in our docs between internal and external links strictly. For internal cross references we use always
<xref/>and for external (remote) links we use<link/>.Although DocBook 5 allows the ubiquitous
linkendattribute everywhere I wouldn't use it.With this definition in mind, our stylesheets does much more processing of
<xref/>than<link/>. For example, it supports what we call "intra book linking". Here is an example of such a cross reference from the DAPS Quickstart:The text after "refer to" was an
<xref/>originally. The stylesheets resolve it to ordinary text. However, this processing isn't done for<link/>.To make a long story short: The solution would be to make a clearer distinction between internal and external links. Probably something for a styleguide if you want to make it correct.
Does that help?
Tom
Last edit: Thomas Schraitle 2016-06-08
For our internal docs we distinguish two types of internal links:
1) Using <xref> for verbose links, to be rendered with section (or figure, ...) number and title and
2) Using <link> to be rendered just as 'ordinary' links without any additional link text in order to minimize distraction for the user.
This is intentional.
On the other hand processing is obviously done for <link>:
- With the
susestylesheet proper PDF links are generated.- With any other stylesheet the link will be rendered colored with empty parenthesis and a link icon attached (see my screenshot), but it will no longer function as a link.
I'd guess tweaking the stylesheets to fix this (make <link> work) should be easy (as there is a working example given by the
susestylesheets).And I'd very much prefer to stay with
<link>then to replace ~200 occurences with a semantically equivalent<xref linkend=... xrefstyle='whatever'>expression.Thanks
Stefan
Ok, I see.
You could customize the daps2013 stylesheets. ;-)
I understand that.
Screenshot demonstrating problem with PDF section links.
I'd really consider this is a bug in newer stylesheet implementations and it therefore should be fixed there and for everyone.
But its hard for me to identify which XSL does processing of
linkelements (or inherits it):The daps stylesheets seem to rely on the suse2013 stylesheets.
The implementation of fo/xref.xsl of the latter differs considerably from the fo/xref.xsl of the older suse stylesheets (which according to the logs were formerly known as 'xslt2005') and which do not show this link generation problem.
For the suse fo stylesheets the only XSL which seems to handle
linkendseems to be xref.xsl.While the suse/fo/xref.xsl has a template explcitly matching
linkelements this is no longer the case for suse2013/fo/xref.xsl.Maybe this is the case because some unified handling of all elements having a
linkendattribute has been introduced.Hi Stefan,
yes, I tend to agree that this is a bug in our stylesheets -- can you open an issue on GitHub?
https://github.com/openSUSE/suse-xsl/issues/new
I'll see if we can get this working in the next version of the stylesheets.
Ok,
I opened https://github.com/openSUSE/suse-xsl/issues/238
Thanks
Stefan
Thanks Stefan for the report!