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

[Samuel Gougeon]

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

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
      o --> consolebox on // on Windows
      o 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


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.scilab.org/pipermail/dev/attachments/20180504/0426b65a/attachment.htm>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: xi_include.zip
Type: application/x-zip-compressed
Size: 18750 bytes
Desc: not available
URL: <https://lists.scilab.org/pipermail/dev/attachments/20180504/0426b65a/attachment.bin>