Re: [docbook-apps] Entities references vs. XRef as a way to manage changing glossary

[Bob Stayton <bobs at sco dot com>]

On Mon, Aug 04, 2003 at 03:50:25PM -0400, Taro Ikai wrote:
> > >   xsltproc --stringparam collect.xref.targets "only" docbook.xsl 
> test.xml 
> > > 
> > > is like this:
> > > 
> > >   <div element="chapter" href="" number="1" targetptr="dessert">
> > >     <ttl>Dessert</ttl>
> > >     <xreftext>Chapter??1, <i>Tiramisu</i></xreftext>
> > >   </div>
> > 
> > I don't understand why the href attribute is blank.
> > It should be "#id", where id is either the element's
> > id value or a generated id.  That was why I thought
> > it would be necessary to delete those attribute values
> > that are generated.
> 
> Sorry, Bob. I had copied the block above after I emptied the value of 
> @href 
> attribute according to your suggestion. What
> 
>    xsltproc --stringparam collect.xref.targets "only" docbook.xsl test.xml
> 
> really produces is the following:
> 
>    <div element="chapter" href="#dessert" number="1" targetptr="dessert">
>      <ttl>Dessert</ttl>
>      <xreftext>Chapter??1, <i>Tiramisu</i></xreftext>
>    </div>
> 
> Like you said, it seems necessary to empty the @href attribute value to 
> turn off production of hotlinks.
> 
> > One other option might be XInclude.  It will survive
> > XSL identity transformations if you don't turn on
> > xinclude processing (omit the --xinclude option to
> > xsltproc).  If you need to import the parameterization
> > to FrameMaker, then you could convert the XIncludes
> > to entities just before import, and then FrameMaker
> > will handle them.
> > 
> 
> XInclude is another technique we can use for parameterizing text I 
> was not aware of. With XInclude, given glossary.xml:
> 
> <glossary>
>   <varname id="main_course">fish</varname>
>   <varname id="dessert">apple pie</varname>
> </glossary>
> 
> I can make a reference to a glossary entry as follows:
> 
>   <xi:include 
> href="glossary.xml#xpointer(range-inside(//*[@id='dessert']))" 
> parse="xml"/>
> 
> Compared to the olink technique, where the glossary looks like:
> 
>   <div targetptr="main_course"><xreftext>beef</xreftext></div>
>   <div targetptr="dessert"><xreftext>tiramisu</xreftext></div>
> 
> and the reference looks like:
> 
>   <olink targetdoc="glossary" targetptr="dessert"/>
> 
> My observations/questions are: 
> 
> 1) XInclude requires each glossary entry to be wrapped in an
> element. Here, I've used <varname>, but what if I don't want
> any wrapping element? Is there any way to return only the character
> data inside? 

Yes, add "/text()" to the end of our xpointer syntax to
select just the text elements inside the selected element.
This works with xsltproc, anyway.

> 
> 2) The XInclude technique's referencing element is textually more
> verbose, and so visually more intrusive. Is there any way to 
> make the reference more terse?

I was able to use this:

<xi:include href="glossary.xml#xpointer(//*[@id='dessert'])/text())"/>

The 'parse' attribute's default value is xml, so you don't
need that attribute. I don't think you need the range-inside either.
This is not much shorter, though.

When you say it is visually intrusive, I presume you mean
at the editing level, right?  You could convert each include
into an entity that resolves to an <xi:include>.  The
entity would be resolved at the first stage, and the
xinclude element would survive further transformations
at don't process xincludes.  But this seems to be even
more complicated.
 
> 3) With XInclude, I don't need a special XSLT stylesheet to 
> resolve the references. XSLT processor does this for us.
> 
> 4) With XInclude, I don't need to build the target database 
> as required with olink.

Another approach is to let a customized stylesheet resolve
the references.  For example, you could enter a nice clean:

<glossterm role="lookup">dessert</glossterm>

and the custom stylesheet file would handle the insertion of
the text.  You would pass the pathname of the glossary.xml
file to the XSLT processor as a stylesheet parameter,
the stylesheet would use document() to load its content into
a variable. Then the template that matches on
match="glossterm[@role = 'lookup']" would look up the
text value in the variable with something like:

<xsl:variable name="key" select="text()"/>
<xsl:variable name="glossary" select="document($glossdoc, /)"/>
<xsl:value-of select="$glossary//varname[@id=$key]/*"/>

It's even easier if the glossary is included in the document.
Then you don't need to open the separate glossary file.
You could do the lookup from a path inside the document.
You could even use id and idref (linkend for glossterm)
to make sure your references were valid.

-- 

Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
The SCO Group                               fax:   (831) 429-1887
                                            email: bobs@sco.com

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org