<html>
<head>
<meta content="text/html; charset=windows-1252"
http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<div class="moz-cite-prefix">Le 04/05/2018 à 16:12, Samuel Gougeon a
écrit :<br>
</div>
<blockquote cite="mid:1371a0d7-6809-b06a-fe97-e27930b3fabe@free.fr"
type="cite">
<meta http-equiv="content-type" content="text/html;
charset=windows-1252">
<p>Dear devs and authors,</p>
<p>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..<br>
This is a common and important concern, a very time-consuming
one.<br>
<br>
The <xi:include ../> tag already allows to do it for
Scilab pages. The Scilab documentation builder already supports
it.<br>
This tag is being documented for Scilab. It is already used in
only one page (other thousands..), to build the JKFLIPFLOP.xml
one.<br>
This tag is not properly a docbook one. Its usage is well
documented, for instance here:<br>
<a moz-do-not-send="true" class="moz-txt-link-freetext"
href="https://msdn.microsoft.com/en-us/library/aa302291.aspx#xinc_topic4">https://msdn.microsoft.com/en-us/library/aa302291.aspx#xinc_topic4</a></p>
<p>But the Scilab support of <xi:include ../> has a major
issue: the <b>xpointer=".."</b> attribute that specifies the
targeted tag in the source file, to be included in the
destination file, looks to support only the <a
moz-do-not-send="true"
href="https://msdn.microsoft.com/en-us/library/aa302291.aspx#xinc_topic6">"<b>element(/i/j/k..)</b>"
syntax</a>.: 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.</p>
<p>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 <b>xpointer="the_id_of_tag_to_be_imported"</b>.
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. <br>
This present limitation could be the reason why
<xi:include..> was not more used up to now.<br>
It is rather frustrating. <br>
In Scilab, the required <b>xmlns:xi=<a moz-do-not-send="true"
class="moz-txt-link-rfc2396E"
href="http://www.w3.org/2001/XInclude">"http://www.w3.org/2001/XInclude"</a></b>
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.</p>
<p>To conclude : <font color="#009900">Would it be possible to
make the Scilab documentation builder compliant with the <i>xmlns:xi="<a
moz-do-not-send="true" class="moz-txt-link-freetext"
href="http://www.w3.org/">http://www.w3.org/</a></i><i><b>200</b></i><i><b>3</b></i><i>/XInclude"</i>
release?</font><br>
</p>
</blockquote>
<br>
For information and tests, the template that i use for my own tests
is attached:<br>
<ul>
<li>unzip it</li>
<li>edit ~/help/en_US/get.xml and ~/help/en_US/get.xml with an
external editor (Notepad++ is excellent for xml :)</li>
<li>In Scilab, run <br>
</li>
<ul>
<li><tt>--> consolebox on</tt> // on Windows</li>
<li>load and exec ~/builder.sce</li>
</ul>
<li>See the error messages from the doc builder in the consolebox</li>
<li><tt>--> host cls</tt> // to clear the consolebox</li>
<li>change the xpointer value in get.xml and/or the id of the
examples <refsection > in get_source.dbk, and rerun
builder.sce etc<br>
</li>
</ul>
<p>Samuel</p>
<p><br>
</p>
</body>
</html>