Skip to content

Commit

Permalink
Merge pull request #446 from ndw/fsteimke-414-xrefstyle-support
Browse files Browse the repository at this point in the history 
Small tweaks to fsteimke's PR to support xrefstyle
  • Loading branch information
@ndw
ndw authored Jan 15, 2024
2 parents e9280d5 + 93d9885 commit 49d8030
Show file tree
Hide file tree
Showing 8 changed files with 535 additions and 17 deletions.
164 changes: 163 additions & 1 deletion src/guide/xml/ch02.xml
100644 → 100755
View file
Original file line number Diff line number Diff line change
Expand Up @@ -815,7 +815,7 @@ targeted to the audience specified.</para>
<para>DocBook supports a wide variety of common attributes for this
purpose:</para>

<table>
<table xml:id="table.effectivity-attributes">
<title>Common DocBook effectivity attributes</title>
<tgroup cols="2">
<thead>
Expand Down Expand Up @@ -988,6 +988,168 @@ any of it’s values match.</para>
</section>
</section>

<section xml:id="customize-individual-cross-references">
<title>Customize individual cross references</title>

<para>Most kinds of generated text apply across an entire document: do you want chapters
to be numbered? Should generated text be in English or French? What form should numbered
and unnumbered sections have? The mechanisms for changing this generated text are
described in <xref linkend="gentext"/>. These mechanisms control the formatting
of cross references.</para>

<para>But it’s sometimes desirable to be able to change the format of a
cross reference on an individual basis (that is, on the basis of the
context in which the <emphasis>reference</emphasis> occurs, not the
nature of what is <emphasis>referenced</emphasis>). You might, for
example, want to shorten a cross reference to just a label if it’s
already been referenced several times.</para>

<para>Consider a cross reference to a section:
<code><![CDATA[see <xref linkend="syntax-highlighting"/>]]></code>.
In the localization style of this guide, that is rendered like this:
see <xref linkend="syntax-highlighting"/>.</para>

<para>The text that is generated by a cross reference can be customized
for individual references with the <code>xrefstyle</code> attribute.
For example,
<code><![CDATA[see <xref linkend="syntax-highlighting" xrefstyle="%l"/>]]></code>,
will produce a result like this:
see <xref linkend="syntax-highlighting" xrefstyle="%l"/>.</para>

<para>You can use the <code>%c</code>, <code>%l</code> and
<code>%p</code> values from <xref
linkend="table.template-letter-substitutions"/> in
<code>xrefstyle</code>. There is also an additional
<code>%label</code> for <emphasis>the full Label</emphasis>, which is
the component`s name and number. The use of these percent-values is
explained in the following table, where all cross references target
the next section called <xref linkend="syntax-highlighting"
xrefstyle="%c"/>.</para>

<informaltable frame="all">
<tgroup cols="3" rowsep="1" colsep="1">
<colspec colname="c1" colwidth="2*" rowsep="1"/>
<colspec colname="c2" colwidth="1*" rowsep="1"/>
<colspec colname="c3" colwidth="2*" rowsep="1"/>

<thead valign="top">
<row>
<entry>Value of <code>xref/@xrefstyle</code></entry>
<entry>Result</entry>
<entry>Remark</entry>
</row>
</thead>

<tbody valign="top">
<row>
<entry>(<code>@xrefstyle</code> is absent)</entry>
<entry><xref linkend="syntax-highlighting"/></entry>
<entry>Default</entry>
</row>
<row>
<entry><code>%c</code></entry>
<entry><xref linkend="syntax-highlighting" xrefstyle="%c"/></entry>
<entry>Content, e. g. title of target</entry>
</row>
<row>
<entry><code>%l</code></entry>
<entry><xref linkend="syntax-highlighting" xrefstyle="%l"/></entry>
<entry>Label, ususally the targets number.</entry>
</row>
<row>
<entry><code>%label</code></entry>
<entry><xref linkend="syntax-highlighting" xrefstyle="%label"/></entry>
<entry>The full Label, ususally the targets number and name.</entry>
</row>
<row>
<entry><code>%p</code></entry>
<entry><phrase outputformat="print"><xref linkend="syntax-highlighting" xrefstyle="%p"/></phrase></entry>
<entry>Page number. Intended for print output (PDF). Displayed as <emphasis>"#"</emphasis> in HTML,
unless you differentiate between the output formats for print and online. See <xref
linkend="using-pagenumber-in-crossreferences" xrefstyle="%label"/> for a possible
solution.</entry>
</row>
<row>
<entry><code>%label (%c)</code></entry>
<entry><xref linkend="syntax-highlighting" xrefstyle="%label (%c)"/></entry>
<entry>You can use different %-letters and combine with text</entry>
</row>
</tbody>
</tgroup>
</informaltable>

<bridgehead>Legacy values for xrefstyle</bridgehead>

<para>In order to support migration from XSLT 1.0 Stylesheets, xslTNG supports the
<code>template:</code> Syntax which is explained in
“<link xmlns:xlink="http://www.w3.org/1999/xlink"
xlink:href="http://www.sagehill.net/docbookxsl/CustomXrefs.html#usingtemplate">Customizing
with an xrefstyle attribute / Using template:</link>” in
the book “<citetitle>DocBook XSL: The Complete
Guide</citetitle>”. This is summarized in the following
table.</para>

<informaltable frame="all">
<tgroup cols="3" colsep="1" rowsep="1">
<colspec colname="c1" colwidth="2*" rowsep="1"/>
<colspec colname="c2" colwidth="1*" rowsep="1"/>
<colspec colname="c3" colwidth="2*" rowsep="1"/>

<thead valign="top">
<row>
<entry>Value of <code>xref/@xrefstyle</code></entry>
<entry>Result</entry>
<entry>Remark</entry>
</row>
</thead>

<tbody valign="top">
<row>
<entry><code>template:the chapter numbered %n</code></entry>
<entry><xref linkend="syntax-highlighting"
xrefstyle="template:the chapter numbered %n"/></entry>
<entry>XSLT 1.0 Legacy Syntax</entry>
</row>
<row>
<entry><code>template:the chapter called %t</code></entry>
<entry><xref linkend="syntax-highlighting"
xrefstyle="template:the chapter called %t"/></entry>
<entry>XSLT 1.0 Legacy Syntax</entry>
</row>
</tbody>
</tgroup>
</informaltable>

<section xml:id="using-pagenumber-in-crossreferences">
<title>Using pagenumber in cross-references</title>
<para>The <code>%p</code> makes little sense in HTML output, since there are no page numbers.
If you use it anyway, it will be displayed as <emphasis>"#"</emphasis>, which can be
confusing for readers. A possible solution for this problem is the use of the
<code>outputformat</code> attribute, that was intoduced in <xref linkend="profiling"/> and
<xref linkend="table.effectivity-attributes" xrefstyle="%label"/><phrase
outputformat="print"> on page <xref linkend="table.effectivity-attributes" xrefstyle="%p"
/></phrase>.</para>

<para><emphasis>This</emphasis> cross reference to <xref linkend="syntax-highlighting"
xrefstyle="%label"/>
<phrase outputformat="print"> on <xref linkend="syntax-highlighting" xrefstyle="page %p"
/></phrase> will include the target`s page number only when the
<code>@profile.outputformat</code> parameter is <emphasis>"print"</emphasis>, but without
the annoying <emphasis>#</emphasis> in HTML.</para>

<example>
<title>Use outputformat to deal with page numbers in cross references</title>
<programlisting>This cross reference to
&lt;xref linkend=&quot;syntax-highlighting&quot; xrefstyle="%label/&gt;
&lt;phrase outputformat=&quot;print&quot;&gt;
on &lt;xref linkend=&quot;syntax-highlighting&quot; xrefstyle=&quot;page %p&quot;/&gt;
&lt;/phrase&gt;
will reference the page number only when the @profile.outputformat parameter is print,
but without the annoying # in HTML.</programlisting>
</example>
</section>
</section>

<section xml:id="syntax-highlighting">
<title>Syntax highlighting</title>

Expand Down
8 changes: 5 additions & 3 deletions src/guide/xml/ch03b.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -266,7 +266,7 @@ this is just the group that’s used if they could be. See
curly braces are replaced by the corresponding mapping and %-letter values
are substituted as follows:</para>

<table>
<table xml:id="table.template-letter-substitutions">
<title>Template %-letter substitutions</title>
<tgroup cols="2">
<thead>
Expand Down Expand Up @@ -545,12 +545,14 @@ necessary to include the predicate that limits this title to sections
in a preface (although it wouldn’t change the result if you did).</para>
</section>

<section>
<section xml:id="changing-the-cross-reference-group">
<title>Changing the cross reference group</title>

<para>Cross references are processed just like titles, except that the
<varname>v:user-xref-groups</varname> element consists of a
list of <code>crossref</code> elements.</para>
list of <code>crossref</code> elements. (See also
<xref linkend="customize-individual-cross-references"/>, for a discussion
of how individual cross references can be customized.)</para>

<para>The default for cross references to chapters and appendixes is
“<code>xref-number-and-title</code>”, so you get things like “Chapter
Expand Down
5 changes: 5 additions & 0 deletions src/main/scss/media-all.scss
View file
Original file line number Diff line number Diff line change
Expand Up @@ -358,6 +358,11 @@ a.pmuj {
font-style: italic;
}

.xref-pagenum {
content: target-counter(attr(href), page);
font-style:normal;
}

.xref-area,
.xref-areaset,
.xref-co,
Expand Down
5 changes: 5 additions & 0 deletions src/main/xslt/modules/l10n.xsl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,11 @@
<xsl:apply-templates mode="mp:localization"/>
</xsl:element>
</xsl:template>

<!-- page number is not content of html:a, but needs its own html:a element -->
<xsl:template match="lt:pagenum" mode="mp:localization">
<xsl:sequence select="."/>
</xsl:template>

<xsl:template match="lt:*" mode="mp:localization">
<xsl:message terminate="yes"
Expand Down
89 changes: 82 additions & 7 deletions src/main/xslt/modules/links.xsl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,18 @@
xmlns:f="http://docbook.org/ns/docbook/functions"
xmlns:fp="http://docbook.org/ns/docbook/functions/private"
xmlns:h="http://www.w3.org/1999/xhtml"
xmlns:l="http://docbook.org/ns/docbook/l10n"
xmlns:lt="http://docbook.org/ns/docbook/l10n/templates"
xmlns:m="http://docbook.org/ns/docbook/modes"
xmlns:t="http://docbook.org/ns/docbook/templates"
xmlns:tp="http://docbook.org/ns/docbook/templates/private"
xmlns:v="http://docbook.org/ns/docbook/variables"
xmlns:vp="http://docbook.org/ns/docbook/variables/private"
xmlns:xlink='http://www.w3.org/1999/xlink'
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns="http://www.w3.org/1999/xhtml"
default-mode="m:docbook"
exclude-result-prefixes="db f fp h m t tp v xlink xs"
exclude-result-prefixes="db f fp h l lt m t tp v vp xlink xs"
version="3.0">

<xsl:template match="db:anchor">
Expand Down Expand Up @@ -202,6 +205,7 @@
<xsl:choose>
<xsl:when test="empty($target)">
<xsl:message select="'Link to non-existent ID: ' || $linkend"/>
<span class='error'>???</span>
</xsl:when>
<xsl:otherwise>
<xsl:variable name="content" as="item()*">
Expand All @@ -222,21 +226,92 @@
<xsl:when test="$target/@xreflabel">
<xsl:sequence select="$target/@xreflabel/string()"/>
</xsl:when>
<xsl:when test="@xrefstyle">
<xsl:call-template name="tp:apply-localization-template">
<xsl:with-param name="target" select="$target"/>
<xsl:with-param name="localization-template"
select="fp:localization-template-from-xrefstyle(., $target)"/>
</xsl:call-template>
</xsl:when>
<xsl:otherwise>
<xsl:apply-templates select="$target" mode="m:crossref"/>
</xsl:otherwise>
</xsl:choose>
</xsl:variable>

<a href="#{f:id($target)}" class="xref xref-{local-name($target)}">
<xsl:if test="fp:pmuj-enabled(/)">
<xsl:attribute name="id" select="f:generate-id(.)"/>
</xsl:if>
<xsl:sequence select="$content"/>
</a>
<xsl:variable name="vp:pmuj" as="xs:boolean" select="fp:pmuj-enabled(/)"/>

<!-- page number needs its own html:a element -->
<xsl:for-each-group select="$content"
group-adjacent=". instance of node() and local-name() = ('pagenum')">
<xsl:choose>
<xsl:when test="boolean(current-grouping-key())">
<a href="#{f:id($target)}" class="xref xref-{local-name($target)} xref-{local-name(.)}">#</a>
</xsl:when>
<xsl:otherwise>
<a href="#{f:id($target)}" class="xref xref-{local-name($target)}">
<xsl:if test="$vp:pmuj">
<xsl:attribute name="id" select="f:generate-id(.)"/>
</xsl:if>
<xsl:sequence select="current-group()"/>
</a>
</xsl:otherwise>
</xsl:choose>
</xsl:for-each-group>
</xsl:otherwise>
</xsl:choose>
</xsl:template>

<xsl:function name="fp:localization-template-from-xrefstyle" as="element(l:template)">
<xsl:param name="xref" as="element(db:xref)"/>
<xsl:param name="target" as="element()"/>

<xsl:variable name="content" as="item()*">
<xsl:choose>
<xsl:when test="starts-with($xref/@xrefstyle, 'template:')">
<!-- Legacy XSLT 1.0 Stylesheets,
see http://www.sagehill.net/docbookxsl/CustomXrefs.html#UsingTemplate -->
<xsl:analyze-string select="substring-after($xref/@xrefstyle, 'template:')" regex="%n|%t">
<xsl:matching-substring>
<xsl:choose>
<xsl:when test=". eq '%n'"><lt:label/></xsl:when>
<xsl:when test=". eq '%t'"><lt:content/></xsl:when>
</xsl:choose>
</xsl:matching-substring>
<xsl:non-matching-substring>
<lt:text><xsl:sequence select="."/></lt:text>
</xsl:non-matching-substring>
</xsl:analyze-string>
</xsl:when>
<xsl:when test="starts-with($xref/@xrefstyle, 'select:')">
<!-- Legacy XSLT 1.0 Stylesheets,
see http://www.sagehill.net/docbookxsl/CustomXrefs.html#UsingSelect -->
<xsl:message select="'Warning: xref/@xrefstyle with select: Syntax is not supported'"/>
</xsl:when>
<xsl:otherwise>
<!-- See xslTNG Reference Table 4.1. Template %-letter substitutions -->
<xsl:analyze-string select="$xref/@xrefstyle" regex="%label|%l|%c|%p">
<xsl:matching-substring>
<xsl:choose>
<xsl:when test=". eq '%label'">
<xsl:sequence select="fp:localization-template($target,'xref-number')/*"/>
</xsl:when>
<xsl:when test=". eq '%l'"><lt:label/></xsl:when>
<xsl:when test=". eq '%c'"><lt:content/></xsl:when>
<xsl:when test=". eq '%p'"><lt:pagenum/></xsl:when>
</xsl:choose>
</xsl:matching-substring>
<xsl:non-matching-substring>
<lt:text><xsl:sequence select="."></xsl:sequence></lt:text>
</xsl:non-matching-substring>
</xsl:analyze-string>
</xsl:otherwise>
</xsl:choose>
</xsl:variable>
<l:template>
<xsl:sequence select="$content"/>
</l:template>
</xsl:function>

<xsl:template match="db:olink">
<xsl:variable name="targetdoc" select="@targetdoc/string()"/>
Expand Down
Loading

0 comments on commit 49d8030

Please sign in to comment.