diff options
author | Shaun McCance <shaunm@gnome.org> | 2012-01-18 09:39:39 -0500 |
---|---|---|
committer | Shaun McCance <shaunm@gnome.org> | 2012-01-18 09:39:39 -0500 |
commit | 46ca871c89231a46ce46bff457737d8ca0de51f5 (patch) | |
tree | 13b6ccc52fedf65b7189f396a16b9fcf95a39825 /xslt | |
parent | f9927fa95c106ea70c093a0270b81beca34c18d1 (diff) | |
download | yelp-xsl-46ca871c89231a46ce46bff457737d8ca0de51f5.tar.gz |
mal-link: Making linking behavior more customizable
Diffstat (limited to 'xslt')
-rw-r--r-- | xslt/mallard/common/mal-link.xsl | 292 |
1 files changed, 218 insertions, 74 deletions
diff --git a/xslt/mallard/common/mal-link.xsl b/xslt/mallard/common/mal-link.xsl index cf28a7b2..0355fac8 100644 --- a/xslt/mallard/common/mal-link.xsl +++ b/xslt/mallard/common/mal-link.xsl @@ -28,7 +28,7 @@ Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA <!--!!========================================================================== Mallard Links Common linking utilities for Mallard documents. -:Revision:version="1.0" date="2010-01-02" status="final" +:Revision:version="3.4" date="2012-01-17" status="final" This stylesheet contains various utilities for handling links in Mallard documents. The templates in this stylesheet make it easier to handle the @@ -40,7 +40,7 @@ linking systems. <!--@@========================================================================== mal.cache.file The location of the cache file. -:Revision:version="1.0" date="2010-01-02" status="final" +:Revision:version="3.0" date="2010-01-02" status="final" In order to locate and process links between pages, this stylesheet requires a Mallard cache file. Use this parameter to pass the path to a valid cache @@ -52,7 +52,7 @@ file. <!--@@========================================================================== mal.cache The cache document as a node set. -:Revision:version="1.0" date="2010-01-02" status="final" +:Revision:version="3.0" date="2010-01-02" status="final" This parameter points to the root #{cache:cache} element of a Mallard cache document. By default, it selects the root element from the file provided in @@ -109,10 +109,25 @@ mal.link.seealso.key <!--@@========================================================================== +mal.link.prefix +A prefix for link targets. +:Revision:version="3.4" date="2012-01-17" status="final" + +When link targets are constructed by *{mal.link.target} from #{xref} attributes, +this string is prepended. This can be used, for example, to specify absolute +directories or URLs. +--> +<xsl:param name="mal.link.prefix"/> + + +<!--@@========================================================================== mal.link.extension The filename extension for output files. +:Revision:version="3.4" date="2012-01-17" status="final" -FIXME +When link targets are constructed by *{mal.link.target} from #{xref} attributes, +this string is appended. This is used to specify the file extension when creating +output files from Mallard pages. --> <xsl:param name="mal.link.extension"/> @@ -120,6 +135,7 @@ FIXME <!--@@========================================================================== mal.link.default_root The default root ID. +:Revision:version="3.4" date="2012-01-17" status="final" This parameter provides the default ID for the page that is taken to be the root of the document. By default, #{'index'} is used. This should not be @@ -132,7 +148,7 @@ some Mallard extension formats. <!--**========================================================================== mal.link.linkid Output the fully qualified link ID for a page or section. -:Revision:version="1.0" date="2010-01-02" status="final" +:Revision:version="3.0" date="2010-01-02" status="final" $node: The #{page} or #{section} element to generate a link ID for. This template outputs the fully qualified link ID for a page or section. For @@ -163,7 +179,7 @@ template or *{mal.link.xref.linkid}. <!--**========================================================================== mal.link.xref.linkid Output the fully qualified link ID for an #{xref} attribute. -:Revision:version="1.0" date="2010-01-02" status="final" +:Revision:version="3.0" date="2010-01-02" status="final" $node: The element containing an #{xref} attribute. $xref: The #{xref} value to generate a link ID from. @@ -186,8 +202,9 @@ See *{mal.link.linkid} for more on link IDs. <!--**========================================================================== mal.link.content Output the content for a #{link} element. -:Revision:version="1.0" date="2010-01-02" status="final" +:Revision:version="3.4" date="2012-01-17" status="final" $node: The #{link} or other element creating the link. +$action: The #{action} attribute of ${node}. $xref: The #{xref} attribute of ${node}. $href: The #{href} attribute of ${node}. $role: A link role, used to select the appropriate title. @@ -199,59 +216,104 @@ will be selected, based on ${role}. The %{mal.link.content.mode} mode will be applied to the contents of that title. Stylesheets using this template should map that mode to inline processing. +This template first calls *{mal.link.content.custom} with the same arguments. +If that templates returns a non-empty result, it is used as the return value, +overriding any other behavior of this template. + If only ${href} is provided, that URL is used as the text content. If a target page or section cannot be found, ${xref} is used as the text content. --> <xsl:template name="mal.link.content"> <xsl:param name="node" select="."/> + <xsl:param name="action" select="$node/@action"/> <xsl:param name="xref" select="$node/@xref"/> <xsl:param name="href" select="$node/@href"/> <xsl:param name="role" select="''"/> - <xsl:variable name="linkid"> - <xsl:call-template name="mal.link.xref.linkid"> + <xsl:variable name="custom"> + <xsl:call-template name="mal.link.content.custom"> <xsl:with-param name="node" select="$node"/> + <xsl:with-param name="action" select="$action"/> <xsl:with-param name="xref" select="$xref"/> + <xsl:with-param name="href" select="$href"/> + <xsl:with-param name="role" select="$role"/> </xsl:call-template> </xsl:variable> - <xsl:for-each select="$mal.cache"> - <xsl:variable name="target" select="key('mal.cache.key', $linkid)"/> - <xsl:choose> - <xsl:when test="$target"> - <xsl:variable name="titles" select="$target/mal:info/mal:title[@type = 'link']"/> - <xsl:choose> - <xsl:when test="$role != '' and $titles[@role = $role]"> - <xsl:apply-templates mode="mal.link.content.mode" - select="$titles[@role = $role][1]/node()"/> - </xsl:when> - <xsl:when test="$titles[not(@role)]"> - <xsl:apply-templates mode="mal.link.content.mode" - select="$titles[not(@role)][1]/node()"/> - </xsl:when> - <xsl:otherwise> - <xsl:apply-templates mode="mal.link.content.mode" - select="$target/mal:title[1]/node()"/> - </xsl:otherwise> - </xsl:choose> - </xsl:when> - <xsl:otherwise> + <xsl:choose> + <xsl:when test="exsl:node-set($custom)/node()"> + <xsl:copy-of select="$custom"/> + </xsl:when> + <xsl:otherwise> + <xsl:variable name="linkid"> + <xsl:call-template name="mal.link.xref.linkid"> + <xsl:with-param name="node" select="$node"/> + <xsl:with-param name="xref" select="$xref"/> + </xsl:call-template> + </xsl:variable> + <xsl:for-each select="$mal.cache"> + <xsl:variable name="target" select="key('mal.cache.key', $linkid)"/> <xsl:choose> - <xsl:when test="$href"> - <xsl:value-of select="$href"/> + <xsl:when test="$target"> + <xsl:variable name="titles" select="$target/mal:info/mal:title[@type = 'link']"/> + <xsl:choose> + <xsl:when test="$role != '' and $titles[@role = $role]"> + <xsl:apply-templates mode="mal.link.content.mode" + select="$titles[@role = $role][1]/node()"/> + </xsl:when> + <xsl:when test="$titles[not(@role)]"> + <xsl:apply-templates mode="mal.link.content.mode" + select="$titles[not(@role)][1]/node()"/> + </xsl:when> + <xsl:otherwise> + <xsl:apply-templates mode="mal.link.content.mode" + select="$target/mal:title[1]/node()"/> + </xsl:otherwise> + </xsl:choose> </xsl:when> <xsl:otherwise> - <xsl:value-of select="$xref"/> + <xsl:choose> + <xsl:when test="$href"> + <xsl:value-of select="$href"/> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="$xref"/> + </xsl:otherwise> + </xsl:choose> </xsl:otherwise> </xsl:choose> - </xsl:otherwise> - </xsl:choose> - </xsl:for-each> + </xsl:for-each> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + + +<!--**========================================================================== +mal.link.content.custom +Output the content for a custom #{link} element. +:Stub: true +:Revision:version="3.4" date="2012-01-17" status="final" +$node: The #{link} or other element creating the link. +$action: The #{action} attribute of ${node}. +$xref: The #{xref} attribute of ${node}. +$href: The #{href} attribute of ${node}. +$role: A link role, used to select the appropriate title. + +This template is called by *{mal.link.content} to create content for custom +links. Use this template to support the #{action} attribute or extended #{xref} +attributes containing slash or colon characters. +--> +<xsl:template name="mal.link.content.custom"> + <xsl:param name="node" select="."/> + <xsl:param name="action" select="$node/@action"/> + <xsl:param name="xref" select="$node/@xref"/> + <xsl:param name="href" select="$node/@href"/> + <xsl:param name="role" select="''"/> </xsl:template> <!--%%========================================================================== mal.link.content.mode Output the content for a link from the contents of a #{title} element. -:Revision:version="1.0" date="2010-01-02" status="final" +:Revision:version="3.0" date="2010-01-02" status="final" This mode is applied to the contents of a #{title} element by *{mal.link.content}. By default, it returns the string value of its input. Stylesheets that use @@ -265,63 +327,111 @@ By default, it returns the string value of its input. Stylesheets that use <!--**========================================================================== mal.link.tooltip Output a tooltip for a #{link} element. -:Revision:version="1.0" date="2011-05-14" status="final" +:Revision:version="3.4" date="2012-01-18" status="final" $node: The #{link} or other element creating the link. +$action: The #{action} attribute of ${node}. $xref: The #{xref} attribute of ${node}. $href: The #{href} attribute of ${node}. +$role: A link role, used to select the appropriate title. This template outputs a text-only tooltip for a link. If ${xref} points to a valid page or section, the text title from that page or section will be used. If the target does not specify a text title, the primary title is ued. +This template first calls *{mal.link.tooltip.custom} with the same arguments. +If that templates returns a non-empty string, it is used as the return value, +overriding any other behavior of this template. + If only ${href} is provided, that URL is used as the tooltip. If a target page or section cannot be found, ${xref} is used as the text content. Special tooltips may be provided for certain URI schemes. --> <xsl:template name="mal.link.tooltip"> <xsl:param name="node" select="."/> + <xsl:param name="action" select="$node/@action"/> <xsl:param name="xref" select="$node/@xref"/> <xsl:param name="href" select="$node/@href"/> <xsl:param name="role" select="''"/> - <xsl:variable name="linkid"> - <xsl:call-template name="mal.link.xref.linkid"> + <xsl:variable name="custom"> + <xsl:call-template name="mal.link.tooltip.custom"> <xsl:with-param name="node" select="$node"/> + <xsl:with-param name="action" select="$action"/> <xsl:with-param name="xref" select="$xref"/> + <xsl:with-param name="href" select="$href"/> + <xsl:with-param name="role" select="$role"/> </xsl:call-template> </xsl:variable> - <xsl:for-each select="$mal.cache"> - <xsl:variable name="target" select="key('mal.cache.key', $linkid)"/> - <xsl:choose> - <xsl:when test="$target/mal:info/mal:title[@type = 'text']"> - <xsl:value-of select="normalize-space($target/mal:info/mal:title[@type = 'text'][1])"/> - </xsl:when> - <xsl:when test="$target/mal:title"> - <xsl:value-of select="normalize-space($target/mal:title[1])"/> - </xsl:when> - <xsl:when test="starts-with($href, 'mailto:')"> - <xsl:variable name="address" select="substring-after($href, 'mailto:')"/> - <xsl:call-template name="l10n.gettext"> - <xsl:with-param name="msgid" select="'email.tooltip'"/> - <xsl:with-param name="string" select="$address"/> - <xsl:with-param name="format" select="true()"/> + <xsl:choose> + <xsl:when test="$custom != ''"> + <xsl:value-of select="$custom"/> + </xsl:when> + <xsl:otherwise> + <xsl:variable name="linkid"> + <xsl:call-template name="mal.link.xref.linkid"> + <xsl:with-param name="node" select="$node"/> + <xsl:with-param name="xref" select="$xref"/> </xsl:call-template> - </xsl:when> - <xsl:when test="$href"> - <xsl:value-of select="$href"/> - </xsl:when> - <xsl:otherwise> - <xsl:value-of select="$xref"/> - </xsl:otherwise> - </xsl:choose> - </xsl:for-each> + </xsl:variable> + <xsl:for-each select="$mal.cache"> + <xsl:variable name="target" select="key('mal.cache.key', $linkid)"/> + <xsl:choose> + <xsl:when test="$target/mal:info/mal:title[@type = 'text']"> + <xsl:value-of select="normalize-space($target/mal:info/mal:title[@type = 'text'][1])"/> + </xsl:when> + <xsl:when test="$target/mal:title"> + <xsl:value-of select="normalize-space($target/mal:title[1])"/> + </xsl:when> + <xsl:when test="starts-with($href, 'mailto:')"> + <xsl:variable name="address" select="substring-after($href, 'mailto:')"/> + <xsl:call-template name="l10n.gettext"> + <xsl:with-param name="msgid" select="'email.tooltip'"/> + <xsl:with-param name="string" select="$address"/> + <xsl:with-param name="format" select="true()"/> + </xsl:call-template> + </xsl:when> + <xsl:when test="$href"> + <xsl:value-of select="$href"/> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="$xref"/> + </xsl:otherwise> + </xsl:choose> + </xsl:for-each> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + + +<!--**========================================================================== +mal.link.tooltip.custom +Output a tooltip for a custom #{link} element. +:Stub: true +:Revision:version="3.4" date="2012-01-17" status="final" +$node: The #{link} or other element creating the link. +$action: The #{action} attribute of ${node}. +$xref: The #{xref} attribute of ${node}. +$href: The #{href} attribute of ${node}. +$role: A link role, used to select the appropriate title. + +This template is called by *{mal.link.tooltip} to create tooltips for custom +links. Use this template to support the #{action} attribute or extended #{xref} +attributes containing slash or colon characters. +--> +<xsl:template name="mal.link.tooltip.custom"> + <xsl:param name="node" select="."/> + <xsl:param name="action" select="$node/@action"/> + <xsl:param name="xref" select="$node/@xref"/> + <xsl:param name="href" select="$node/@href"/> + <xsl:param name="role" select="''"/> </xsl:template> <!--**========================================================================== mal.link.target Output the target URL for a #{link} or other linking element. -:Revision:version="1.0" date="2010-01-02" status="final" +:Revision:version="3.4" date="2012-01-17" status="final" $node: The #{link} or other element creating the link. +$action: The #{action} attribute of ${node}. $xref: The #{xref} attribute of ${node}. $href: The #{href} attribute of ${node}. @@ -329,39 +439,72 @@ This template outputs a URL for a #{link} element or another element using linking attributes. If ${xref} points to a valid page or section, it uses a file name based on the ID of the target page plus @{mal.link.extension}. Otherwise, the link will point to ${href}. + +This template first calls *{mal.link.target.custom} with the same arguments. +If that templates returns a non-empty string, it is used as the return value, +overriding any other behavior of this template. --> <xsl:template name="mal.link.target"> <xsl:param name="node" select="."/> + <xsl:param name="action" select="$node/@action"/> <xsl:param name="xref" select="$node/@xref"/> <xsl:param name="href" select="$node/@href"/> + <xsl:variable name="custom"> + <xsl:call-template name="mal.link.target.custom"> + <xsl:with-param name="node" select="$node"/> + <xsl:with-param name="action" select="$action"/> + <xsl:with-param name="xref" select="$xref"/> + <xsl:with-param name="href" select="$href"/> + </xsl:call-template> + </xsl:variable> <xsl:choose> + <xsl:when test="$custom != ''"> + <xsl:value-of select="$custom"/> + </xsl:when> <xsl:when test="string($xref) = ''"> <xsl:value-of select="$href"/> </xsl:when> <xsl:when test="contains($xref, '/') or contains($xref, ':')"> - <!-- - This is a link to another document, which we don't handle in these - stylesheets. Extensions such as library or yelp should override - this template to provide this functionality. - --> <xsl:value-of select="$href"/> </xsl:when> <xsl:when test="contains($xref, '#')"> <xsl:variable name="pageid" select="substring-before($xref, '#')"/> <xsl:variable name="sectionid" select="substring-after($xref, '#')"/> <xsl:if test="$pageid != ''"> - <xsl:value-of select="concat($pageid, $mal.link.extension)"/> + <xsl:value-of select="concat($mal.link.prefix, $pageid, $mal.link.extension)"/> </xsl:if> <xsl:value-of select="concat('#', $sectionid)"/> </xsl:when> <xsl:otherwise> - <xsl:value-of select="concat($xref, $mal.link.extension)"/> + <xsl:value-of select="concat($mal.link.prefix, $xref, $mal.link.extension)"/> </xsl:otherwise> </xsl:choose> </xsl:template> <!--**========================================================================== +mal.link.target.custom +Output the target URL for an element with #{action} or extended #{xref} attributes. +:Stub: true +:Revision:version="3.4" date="2012-01-17" status="final" +$node: The #{link} or other element creating the link. +$action: The #{action} attribute of ${node}. +$xref: The #{xref} attribute of ${node}. +$href: The #{href} attribute of ${node}. + +This template is called by *{mal.link.target} to create URLs for custom links. +Use this template to support the #{action} attribute or extended #{xref} +attributes containing slash or colon characters. +--> +<xsl:template name="mal.link.target.custom"> + <xsl:param name="node" select="."/> + <xsl:param name="action" select="$node/@action"/> + <xsl:param name="xref" select="$node/@xref"/> + <xsl:param name="href" select="$node/@href"/> +</xsl:template> + + +<!--**========================================================================== mal.link.guidelinks Output the guide links for a page or section. :Revision:version="3.4" date="2011-11-01" status="final" @@ -677,6 +820,7 @@ The output is a result tree fragment. To use these results, call <!--**========================================================================== mal.link.linktrails Output link trails for a page or section. +:Revision:version="3.4" date="2012-01-18" status="final" $node: The #{page} or #{section} element to generate links for. $trail: The link trail leading to ${node}. $root: The ID of the root page. @@ -705,7 +849,7 @@ link to that page. This #{link} element has the attribute #{child="section"} to indicate the link from it to its child is not a topic link. Recursion stops when the ID of ${node} is ${root}. Link trails are only -output if they reach ${root}. +output if they reach ${root}, which is @{mal.link.default_root} by default. --> <!-- FIXME: @@ -785,7 +929,7 @@ FIXME: <!--**========================================================================== mal.link.facetlinks Output the facet links for a facets page or section. -:Revision:version="1.0" date="2010-12-16" status="final" +:Revision:version="3.0" date="2010-12-16" status="final" $node: The #{page} or #{section} element to generate links for. This template outputs all the facet links for facets page or section. Links are |