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

classic Classic list List threaded Threaded
4 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
Clément David-3 Clément David-3
Reply | Threaded
Open this post in threaded view
|

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

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

Hello Clément,

Le 29/05/2018 à 21:40, Clément David a écrit :

> 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 for your input.
If i well understand your answer, upgrading the Scilab support of
<xinclude> to a 2003 release
is either not relevant, or not applicable, or would not extend xpointer
usages.
It is rather disappointing, but ok, i am taking note of it.

The workarounds that you indicate at the end are not clear to be. I must
spend additional
time to see what's possible, test things, and if it's actually
worthwhile to go this way versus
time to maintain/update such a documentation structure.

Regards
Samuel

_______________________________________________
dev mailing list
[hidden email]
http://lists.scilab.org/mailman/listinfo/dev