Re: [docbook-apps] 'endterm' with olinks?

["Bob Stayton" <bobs@sagehill.net>]

Hi,
In the general case, a para is not a suitable target for a cross reference that 
generates text.  It has no title, and it can contain block elements.  Imagine an xref 
in the middle of a para inserting an orderedlist or table as the hot text, and you can 
see what confusion that might create.  So by default, the stylesheet does not take the 
text of the para as the generated text, but instead uses the title of the section 
containing the para.

This feature is handled by a template with mode="xref-to", which is used to generate 
the hot text that is used for both xref and olink.  In fo/xref.xsl, you will find the 
template that handles that feature starts with:

<xsl:template match="para|phrase|simpara|anchor|quote" mode="xref-to">

I would suggest that you add a new template to your customization layer for your case, 
but add a role attribute to the para to specialize it.  Something like this 
(untested):

<xsl:template match="para[@role = 'endterm']" mode="xref-to">
 <xsl:apply-templates/>
</xsl:template>

Then add a role="endterm" to your para and see if that works without the xreflabel.

Bob Stayton
Sagehill Enterprises
bobs@sagehill.net


----- Original Message ----- 
From: "Giuseppe Monticelli" <monty@funambol.com>
To: "Bob Stayton" <bobs@sagehill.net>
Cc: <docbook-apps@lists.oasis-open.org>
Sent: Sunday, February 05, 2012 12:02 PM
Subject: Re: [docbook-apps] 'endterm' with olinks?


Hi Bob, thank you for your answer.

I decided to pay the price of simplicity, and I'm applying your Approach 2.

It works, but the only issue I'm facing (though it can be limited with
a workaround, see below) is that the generated hot text that should
come from the element identified by 'logout' ('otherid' in your
example) is actually the title of the outer 'simplesect' containing
the element:

(REFERENCED document) [1]
...
<sect2 xml:id="sect-logout">
<title>Logout</title>

<para>Log out from the system</para>

<bridgehead>Security realm: public</bridgehead>

<simplesect>
<title>Definition</title>

<para
xml:id="logout">GET /api/login?action=logout</para>
</simplesect>
...

(REFERENCING document) [2]
       ...
<row>
<entry><literal><olink targetdoc="developers-guide"
targetptr="sect-logout">
<olink targetdoc="developers-guide"
targetptr="logout"
role="endterm"/></olink></literal></entry>
...
</row>
       ...

(RESULT) [3]
The generated hot text is then

   'the section called “Definition”'

instead of

   'GET /api/login?action=logout'

The issue can be worked around by adding an 'xreflabel' to [1],
containing the same text as the element 'para' (which is very bad
duplication, indeed):
(WORKAROUND) [4]

    <simplesect>
       <title>Definition</title>

       <para xreflabel="GET /api/login?action=logout"
                  xml:id="logout">GET /api/login?action=logout</para>
     </simplesect>
     ...

Maybe I'm overlooking something trivial.

Thank you,
   Giuseppe

On Thu, Feb 2, 2012 at 7:42 PM, Bob Stayton <bobs@sagehill.net> wrote:
> This is not a feature that is currently supported, so something original is called 
> for here. I can think of two approaches, the former more complex but more complete 
> than the latter.
>
> ...
>
> Approach 2. Create a nested olink with a role attribute, and customize its behavior. 
> When an olink element is processed, if the olink element is not empty, then the 
> stylesheet just does <xsl:apply-templates/> to that content and does not look up the 
> text in the olink database. So you could do this:
>
> <olink targetptr="chapterid"><olink targetptr="otherid" role="endterm"/></olink>
>
> In order to not create a nested link, you would need to add a template like this to 
> your customization:
>
>
> <xsl:template match="olink[@role = 'endterm']">
> <xsl:variable name="content">
> <xsl:apply-imports/>
> </xsl:variable>
> <xsl:value-of select="string($content)"/>
> </xsl:template>
>
> You would also want to set this param so the role attribute is not interpreted as an 
> xrefstyle, which would generate warning messages.
>
> <xsl:param name="use.role.as.xrefstyle" select="0"/>
>
> This template matches the nested olink because of the role value. It then processes 
> that olink with xsl:apply-imports, which would generate a normal active link to the 
> "otherid" element, with text generated from the olink database for "otherid". Then 
> it takes the string value of the result. The outer olink supplies the linking 
> wrapper for that text. With this approach, when you take the string value of the 
> inner olink, you lose any inline formatting, but that's the price of simplicity. 8^)
>
> Bob Stayton
> Sagehill Enterprises
> bobs@sagehill.net
>
>
> ----- Original Message ----- From: Giuseppe Monticelli
> To: docbook-apps@lists.oasis-open.org
> Sent: Wednesday, February 01, 2012 3:06 PM
> Subject: [docbook-apps] 'endterm' with olinks?
>
>
>
> Is there a possibility to emulate with 'olink' the behavior of the attributes 
> 'linkend' and 'endterm' used together in the 'xref' element?
>
> I would like that a couple of my olinks (necessarily used instead of 'xref' in 
> modular documents with XInclude) receive a dedicated cross reference text coming 
> from a particular element, while the cross reference destination should be the 
> beginning of the section in which the element providing the reference text is 
> contained (similarly to Example 15.2 "Xref to a question in qandaentry" at the 
> bottom of http://www.sagehill.net/docbookxsl/CrossRefs.html#OptsGenXref).
>
> Thank you in advance for every hint,
>
> Giuseppe

--
Giuseppe Monticelli :: Funambol, Inc. :: http://docs.funambol.com

MediaHub - Connect Everything Mobile via the Cloud, powered by open source