[Scilab-Dev] <xref>: non-standard scilab implementation for the documentation <= Re: Update of the online documentation

[Samuel Gougeon]

Hello,

Le 20/10/2010 10:52, Calixte Denizet a écrit :
> .../..
>
> I fixed the bug on the forge:
> http://forge.scilab.org/index.php/p/scidoc/source/commit/cb432547a66e60f1fd96561ac121e5e957e85c81/
>
> And I fixed a bug in MATEIG.xml (link instead of xref) :
> http://codereview.scilab.org/#change,2319

I fought more than 1 hour, trying to use the <xref> docbook tag to build 
a /Table of Contents/ with local cross-references (in a long page), and 
i failed.
I have finally found this message, and going to the codereview, i 
discovered that *the Scilab implementation of the <xref> docbook tag is 
not standard*. This is why i lost my time.

Indeed, according to the http://docbook.org/tdg/en/html/xref.html 
reference technical page, <xref> is normally an empty tag: the visible 
clickable text is normally grabbed from the target, not provided by 
<xref> itself. Normally, <xref ...>The text to click</xref> is not meant 
to work, like <link..>...</link> does.
But Scilab's <xref> works like a <link></link>, and does not work 
according to the docbook specification: Tried:
<xref linkend="targetted_id">
...
<term id="targetted_id" xreflabel="The option wb">Option wb</term>

should build and display a link <a href="page_id.html#targetted_id">The 
option wb</a>  where <xref> is located, where the xreflabel attribute 
provides the visible text to be clicked. But <xref>  does not do that.
Another standard way to use <xref> would be:
<xref linkend="targetted_id" endterm="targetted_id">
...
<term id="targetted_id">Option wb</term>

building <a href="page_id.html#targetted_id">Option wb</a>  still where 
<xref> is located, the text to click being equal to the text embraced by 
the targeted tag (here <term...>_____</term>)
But the Scilab doc compiler does nor do that.

So, just to remember: just use <xref> like the <link> tag, with 
providing a reference that is internal to the page, instead of the 
reference to an external page :
<xref linkend="blabla">Option wb</xref>
...
<term id="blabla">"wb"</term>

will show a link /Option wb/ that when ones click on it will go to the 
section of the page where the term <term id="blabla">"wb"</term> appears.
That's all.

HTH
Samuel Gougeon



-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.scilab.org/pipermail/dev/attachments/20160223/c0cf1138/attachment.htm>