[Scilab-Dev] Doc: <link> and <xref> considerations. Missing resolved page_id#item_id addresses

[Samuel Gougeon]

Hi Clément,

Le 04/03/2016 12:48, Clément David a écrit :
> Hi Samuel,
>
> Le mardi 23 février 2016 à 21:19 +0100, Samuel Gougeon a écrit :
>>   
>> 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.
> Yep I confirm this behavior and posted [bug #14444]. This feature will alos let us improve
> the current documentation by using this feature on all pages that cross-reference related features
> (eg. almost every page through the "See also" section).
>
> [bug #14444]: http://bugzilla.scilab.org/show_bug.cgi?id=14444

Humm, i am not sure to understand what you mean about the expected 
behavior / purpose of the <xref> tag.

By the way, i am nor sure to clearly understand differences between 
<xref> and <link>, and the initial answer
from Calixte at the beginning of this thread does not clarifies them. 
Even this is not clear in the Docbook user manual.

The <link > tag may as well have an /endterm/ attribute, getting in the 
target the content to be displayed as the link, turning the tag as an 
autoclosed one:
<link linkend="id_of_target" 
endterm="id_of_target_having_the_content_to_be_displayed_in_the_link"/>

So, the only difference that i can see -- according to Docbook -- is 
that <xref> is /always/ an autoclosed tag
that can't be written <xref...>...</xref>. But in Scilab, it is 
implemented exactly as a <link> needing a </link>.

So, *my first question is: Do you intend to make <link> and <xref> 
different? And if yes, in which aspect?*

I was initially looking for a way to target a section of a page, rather 
than the page (its top) itself.
I tried the html syntax with an id in the target and #id in the link, 
but this does not work.
Then i found this <xref> tag, and its non-standard implementation equal 
to the standard <link> one.

Further tests show that, with the current implementation, if in a "See 
also" section or wherever else
one uses <link linkend="the_id">item</link> OR <xref 
linkend="the_id">item</xref> AND

  * a) "the_id" is an xml:id of a page,  OR
  * b) "the_id" is the id of an element of the same page,  OR
  * c) "the_id" is the id of an element of another page,

then the top of the page (a), or the element of the same or other page 
(b) and c))
are already well targeted, in the helpbrowser as well as in HTML files.

Hence, i do not see anything specific to <xref> that should be 
implemented about cross-referencing.

The problems that i see are the following:

  * the xml:id of a page and ids in pages are equally considered. This
    may set some "unresolved"
    conflicts between ids. It would be better to have two distinct
    levels of targeting, as in HTML,
    i.e. to be able to use a 2-level address id_page#id_element for
    linkend/href values.

  * In the "See also" section or in any other part of a page of an
    external module,
    <link> succeeds linking to a Scilab page/in the help browser/, but
    fails to link to the
    online HTML Scilab page in its HTML version. This is already
    reported, and should
    be quite easy to fix, since some Scilab online pages exist and can
    be targeted.

  * In the "See also" section of an external module, <link> pointing to
    Scilab pages are
    not followed by short descriptions of the related pages. This is
    another reported bug.

So, my last questions are :

  * *Do you intend to implement resolved addresses such as page_id#item_id ?

    *
  * *Do you intend to implement the endterm attribute for <link> ?
    *
  * Don't you think that the <xref> tag is useless and should be removed ?

Best regards
Samuel

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