[Scilab-Dev] doc: <xi:include xpointer=".."/> inclusion

[Samuel Gougeon]

Dear devs and authors,

When writting or improving some documentation pages, in many occasions 
it would be great to share some XML parts between several XML files. 
This would avoid very heavy synchronization issues: when a part is 
changed in a file, it must be changed in the same way in N other files..
This is a common and important concern, a very time-consuming one.

The <xi:include ../> tag already allows to do it for Scilab pages. The 
Scilab documentation builder already supports it.
This tag is being documented for Scilab. It is already used in only one 
page (other thousands..), to build the JKFLIPFLOP.xml one.
This tag is not properly a docbook one. Its usage is well documented, 
for instance here:
https://msdn.microsoft.com/en-us/library/aa302291.aspx#xinc_topic4

But the Scilab support of <xi:include ../> has a major issue: the 
*xpointer=".."* attribute that specifies the targeted tag in the source 
file, to be included in the destination file, looks to support only the 
"*element(/i/j/k..)*" syntax 
<https://msdn.microsoft.com/en-us/library/aa302291.aspx#xinc_topic6>.: 
this means that the tag to be copied is the kth child of the jth child 
of the ith main tag in the source file.

After many trials, i did not find any way how to actually use other much 
more handy, robust and reliable xpointer syntaxes using tags ids, like 
simply *xpointer="the_id_of_tag_to_be_imported"*. The /i/j/k  addressing 
is very fragile: As soon as the architecture of the source file is 
changed -- for instance we insert a section, subsection, paragraph 
somewhere, and this shifts all indices of following children, and 
demands to update all /i/j/k references.
This present limitation could be the reason why <xi:include..> was not 
more used up to now.
It is rather frustrating.
In Scilab, the required *xmlns:xi="http://www.w3.org/2001/XInclude"* is 
dated of 2001. Scilab does not accept the later 2003 release as used in 
the aa302291.asp documentation page. In 2003, XInclude was still in 
development. So we may easily think that 2 years earlier in 2001,  some 
xpointer features described in 2003 did not yet exist.

To conclude : Would it be possible to make the Scilab documentation 
builder compliant with the 
/xmlns:xi="http://www.w3.org///*200*//*3*///XInclude"/ release?

Thanks

Samuel*
*

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