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

[Clément David]

Hello Samuel,

After some trial and error as well as debug session to track the issue, it seems that the underlying
xpointer implementation (Xerces from JRE) does not support the id syntax. To clarify none of the
following works (from http://www.sagehill.net/docbookxsl/ModularDoc.html):

 <xinclude href="..." xpointer="id_of_the_element"/>
 <xinclude href="..." xpointer="element(id('id_of_the_element')"/> <!-- id is not supported -->
 <xinclude href="..." xpointer="xpointer(/id_of_the_element)"/> <!-- xpointer is not supported -->
 
Only the fragile (I fully agree with you):

 <xinclude href="..." xpointer="element(/1/2/3)"/> <!-- path to the element -->

Initially I tried to push this usage to restructure the Xcos help pages while preserving the content
and setup the JKFLIPFLOP.xml and associated JKFLIPFLOP_content.dbk with this idea. The path approach
is acceptable in my case as the content will always be structured.

If you wish to share content, another option is to import the whole dbk document using xinclude or
to fallback to the ENTITY DTD declaration as in the master xml file.

Thanks,

--
Clément

Le vendredi 04 mai 2018 à 17:30 +0200, Samuel Gougeon a écrit :
> Le 04/05/2018 à 16:12, Samuel Gougeon a écrit :
> > 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 	 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.: 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/2003/XInclude" release?
>  
> For information and tests, the template that i use for my own tests is attached:
> unzip it
> edit ~/help/en_US/get.xml  and  ~/help/en_US/get.xml with an external editor (Notepad++ is
> excellent for xml :)
> In Scilab, run 
> --> consolebox on // on Windows
> load and exec ~/builder.sce
> See the error messages from the doc builder in the consolebox
> --> host cls  // to clear the consolebox
> change the xpointer value in get.xml and/or the id of the examples <refsection > in
> get_source.dbk, and rerun builder.sce  etc
> Samuel
> 
> _______________________________________________
> dev mailing list
> dev at lists.scilab.org
> http://lists.scilab.org/mailman/listinfo/dev