doc: <xi:include xpointer=".."/> inclusion

classic Classic list List threaded Threaded
2 messages Options
Samuel GOUGEON Samuel GOUGEON
Reply | Threaded
Open this post in threaded view
|

doc: <xi:include xpointer=".."/> inclusion

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.: 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?

Thanks

Samuel


_______________________________________________
dev mailing list
[hidden email]
http://lists.scilab.org/mailman/listinfo/dev
Samuel GOUGEON Samuel GOUGEON
Reply | Threaded
Open this post in threaded view
|

Re: doc: <xi:include xpointer=".."/> inclusion

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 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.: 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
[hidden email]
http://lists.scilab.org/mailman/listinfo/dev

xi_include.zip (25K) Download Attachment