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*
*
_______________________________________________
dev mailing list
dev@lists.scilab.org
http://lists.scilab.org/mailman/listinfo/dev
