Trying to update help_from_sci

classic Classic list List threaded Threaded
7 messages Options
Pierre Vuillemin Pierre Vuillemin
Reply | Threaded
Open this post in threaded view
|

Trying to update help_from_sci

Hi all,

I am currently trying to update the routine "help_from_sci" so that it
works both with head comments written with // and with /* ... */.

I was wondering if there was a (quick) way to display the resulting xml
file with the Scilab style to check whether the xml that has been built
is right?

Regards,

Pierre
_______________________________________________
dev mailing list
[hidden email]
http://lists.scilab.org/mailman/listinfo/dev
Clément David-3 Clément David-3
Reply | Threaded
Open this post in threaded view
|

Re: Trying to update help_from_sci

Hello Pierre,

Currently the easiest way is to put the resulting xml file as an exemple of an empty toolbox and
build/load this toolbox to check for the rendering.

HTML files can also be used as an easy content to check using a standard web browser (eg. without
loading the toolbox). See xmltoweb() to generate it.

AFAIK Samuel usually commit updated help files using the pdf format produced by xmltopdf(). As this
PDF backend is not the main one, I tend to prefer the HTML ones but PDF might be a good alternative.

--
Clément

Le vendredi 05 mai 2017 à 15:59 +0200, Pierre Vuillemin a écrit :

> Hi all,
>
> I am currently trying to update the routine "help_from_sci" so that it 
> works both with head comments written with // and with /* ... */.
>
> I was wondering if there was a (quick) way to display the resulting xml 
> file with the Scilab style to check whether the xml that has been built 
> is right?
>
> Regards,
>
> Pierre
> _______________________________________________
> 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: Trying to update help_from_sci

Hello,

>De: "Clément David"
>
>Hello Pierre,
>
>Currently the easiest way is to put the resulting xml file as an exemple of an empty toolbox and
>build/load this toolbox to check for the rendering.
>
>HTML files can also be used as an easy content to check using a standard web browser (eg. without
>loading the toolbox). See xmltoweb() to generate it.
>
>AFAIK Samuel usually commit updated help files using the pdf format produced by xmltopdf(). As this
>PDF backend is not the main one, I tend to prefer the HTML ones but PDF might be a good alternative.

AFAIRemember, xmltopdf() has some issue, so i use now PDF Creator applied the HTML.
To illustrate the whole page setting and rendering, PDF does not need to be zipped,
whereas HTML needs it to include css dependencies etc.

Anyway, the rendering of the HTML (zipped in the .jar) through the Scilab helpbrowser
is limited wrt the true HTML as it appears in web browsers: Many attributes or style
values are well built but are not rendered... But this is another thread.

Regards
Samuel


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

Re: Trying to update help_from_sci

Thanks for the answers and the hints, I have finally managed to do what I wanted using xmltojar and add_help_chapter.

The xml file generated with help_from_sci seems to have some quirk, is there a reference page concerning the xml that should be produced? The main reference I have found is this page but I don't know if it is still up to date.

Besides, I am thinking about extending the features of the routine so that is supports some flavour of markdown (or similar stuff like Matlab's publishing features).
Has there already been some reflection in that direction?
 
Regards,
 
Pierre

Le 10.05.2017 12:33, [hidden email] a écrit :
Hello,

De: "Clément David"

Hello Pierre,

Currently the easiest way is to put the resulting xml file as an exemple of an empty toolbox and
build/load this toolbox to check for the rendering.

HTML files can also be used as an easy content to check using a standard web browser (eg. without
loading the toolbox). See xmltoweb() to generate it.

AFAIK Samuel usually commit updated help files using the pdf format produced by xmltopdf(). As this
PDF backend is not the main one, I tend to prefer the HTML ones but PDF might be a good alternative.

AFAIRemember, xmltopdf() has some issue, so i use now PDF Creator
applied the HTML.
To illustrate the whole page setting and rendering, PDF does not need
to be zipped,
whereas HTML needs it to include css dependencies etc.

Anyway, the rendering of the HTML (zipped in the .jar) through the
Scilab helpbrowser
is limited wrt the true HTML as it appears in web browsers: Many
attributes or style
values are well built but are not rendered... But this is another thread.

Regards
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
Clément David-3 Clément David-3
Reply | Threaded
Open this post in threaded view
|

Re: Trying to update help_from_sci

Hello Pierre,

Great news ! The help_from_sci() feature is currently really useful for new comers and improving it
might be a good idea.

The XML syntax used is a subset of Docbook 5 ; the man help page contains some information but I
usually use the main Docbook documentation.

About Markdown support, it might be a good idea to support it ; currently the syntax is similar but
not standardized.

Thanks,

--
Clément

Le mercredi 10 mai 2017 à 15:01 +0200, Pierre Vuillemin a écrit :

> Thanks for the answers and the hints, I have finally managed to do what I wanted using xmltojar
> and add_help_chapter.
>
> The xml file generated with help_from_sci seems to have some quirk, is there a reference page
> concerning the xml that should be produced? The main reference I have found is this page but I
> don't know if it is still up to date.
>
> Besides, I am thinking about extending the features of the routine so that is supports some
> flavour of markdown (or similar stuff like Matlab's publishing features).
> Has there already been some reflection in that direction?
>  
> Regards,
>  
> Pierre
>
> Le 10.05.2017 12:33, [hidden email] a écrit : 
> > Hello,
> >
> > > De: "Clément David"
> > >
> > > Hello Pierre,
> > >
> > > Currently the easiest way is to put the resulting xml file as an exemple of an empty toolbox
> > > and
> > > build/load this toolbox to check for the rendering.
> > >
> > > HTML files can also be used as an easy content to check using a standard web browser (eg.
> > > without
> > > loading the toolbox). See xmltoweb() to generate it.
> > >
> > > AFAIK Samuel usually commit updated help files using the pdf format produced by xmltopdf(). As
> > > this
> > > PDF backend is not the main one, I tend to prefer the HTML ones but PDF might be a good
> > > alternative.
> >  
> > AFAIRemember, xmltopdf() has some issue, so i use now PDF Creator
> > applied the HTML.
> > To illustrate the whole page setting and rendering, PDF does not need
> > to be zipped,
> > whereas HTML needs it to include css dependencies etc.
> >
> > Anyway, the rendering of the HTML (zipped in the .jar) through the
> > Scilab helpbrowser
> > is limited wrt the true HTML as it appears in web browsers: Many
> > attributes or style
> > values are well built but are not rendered... But this is another thread.
> >
> > Regards
> > 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
_______________________________________________
dev mailing list
[hidden email]
http://lists.scilab.org/mailman/listinfo/dev
Clément David-3 Clément David-3
Reply | Threaded
Open this post in threaded view
|

Re: Trying to update help_from_sci

Hello Pierre,

Thanks for the preview, it sounds really good to me.

> The issue I am facing is that while the .html file obtained after using
> xmltojar is displayed correctly in Firefox, it is not the case in the
> help browser of Scilab where the description section does not appear.
> Do you have some idea about that?

The help browser is using the Java provided HTML4 renderer [1] which may not support some of the
generated attributes (whereas Firefox supports more modern HTML). It is a bit specific as the
Docbook to HTML (for javahelp) will pass through some attributes which might or might not be
rendered.

Do not hesitate to post your buggy files / examples,

[1]: https://docs.oracle.com/javase/8/docs/api/javax/swing/text/html/HTMLDocument.html

Thanks,

--
Clément

Le mercredi 23 août 2017 à 09:54 +0200, Pierre Vuillemin a écrit :

> Hello all,
>
> Some times ago, I started working on an updated (a little bit more
> flexible) version of the routine help_from_sci.
>
> At this point, it can generate .xml file(s) from formatted head comments
> (either line comments or block-comments) and a minimal markdown support
> is working for the section Description (and user-defined section).
> For instance see the files attached that shows the source comments
> (src.png) and the resulting output doc (doc.png) obtained after using
> xmltojar on the file slr_comments_to_xml.xml.
>
> (Note that the sections that are empty in the source file are not
> rendered in the .xml file)
>
> Some things are still not implemented but it should not be that
> difficult: paragraph, parsing of the example section, latex equations.
>
> The issue I am facing is that while the .html file obtained after using
> xmltojar is displayed correctly in Firefox, it is not the case in the
> help browser of Scilab where the description section does not appear.
> Do you have some idea about that?
>
> Best regards,
>
> Pierre
>
>
> Le 11.05.2017 09:22, Clément David a écrit :
> > Hello Pierre,
> >
> > Great news ! The help_from_sci() feature is currently really useful
> > for new comers and improving it
> > might be a good idea.
> >
> > The XML syntax used is a subset of Docbook 5 ; the man help page
> > contains some information but I
> > usually use the main Docbook documentation.
> >
> > About Markdown support, it might be a good idea to support it ;
> > currently the syntax is similar but
> > not standardized.
> >
> > Thanks,
> >
> > --
> > Clément
> >
> > Le mercredi 10 mai 2017 à 15:01 +0200, Pierre Vuillemin a écrit :
> > > Thanks for the answers and the hints, I have finally managed to do
> > > what I wanted using xmltojar
> > > and add_help_chapter.
> > >
> > > The xml file generated with help_from_sci seems to have some quirk, is
> > > there a reference page
> > > concerning the xml that should be produced? The main reference I have
> > > found is this page but I
> > > don't know if it is still up to date.
> > >
> > > Besides, I am thinking about extending the features of the routine so
> > > that is supports some
> > > flavour of markdown (or similar stuff like Matlab's publishing
> > > features).
> > > Has there already been some reflection in that direction?
> > >  
> > > Regards,
> > >  
> > > Pierre
> > >
> > > Le 10.05.2017 12:33, [hidden email] a écrit :
> > > > Hello,
> > > >
> > > > > De: "Clément David"
> > > > >
> > > > > Hello Pierre,
> > > > >
> > > > > Currently the easiest way is to put the resulting xml file as an exemple of an empty
> > > > > toolbox
> > > > > and
> > > > > build/load this toolbox to check for the rendering.
> > > > >
> > > > > HTML files can also be used as an easy content to check using a standard web browser (eg.
> > > > > without
> > > > > loading the toolbox). See xmltoweb() to generate it.
> > > > >
> > > > > AFAIK Samuel usually commit updated help files using the pdf format produced by
> > > > > xmltopdf(). As
> > > > > this
> > > > > PDF backend is not the main one, I tend to prefer the HTML ones but PDF might be a good
> > > > > alternative.
> > > >
> > > >  
> > > > AFAIRemember, xmltopdf() has some issue, so i use now PDF Creator
> > > > applied the HTML.
> > > > To illustrate the whole page setting and rendering, PDF does not need
> > > > to be zipped,
> > > > whereas HTML needs it to include css dependencies etc.
> > > >
> > > > Anyway, the rendering of the HTML (zipped in the .jar) through the
> > > > Scilab helpbrowser
> > > > is limited wrt the true HTML as it appears in web browsers: Many
> > > > attributes or style
> > > > values are well built but are not rendered... But this is another thread.
> > > >
> > > > Regards
> > > > 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
> >
> > _______________________________________________
> > dev mailing list
> > [hidden email]
> > http://lists.scilab.org/mailman/listinfo/dev
_______________________________________________
dev mailing list
[hidden email]
http://lists.scilab.org/mailman/listinfo/dev
Pierre Vuillemin Pierre Vuillemin
Reply | Threaded
Open this post in threaded view
|

Re: Trying to update help_from_sci

It turns out restarting Scilab solved the problem, so it's fine now.
I'll share the routine once the example section is handled.

Thank you for the hints, I'll be careful with the xml tags I use.

Best regards,

Pierre


Le 23.08.2017 14:23, Clément David a écrit :

> Hello Pierre,
>
> Thanks for the preview, it sounds really good to me.
>
>> The issue I am facing is that while the .html file obtained after
>> using
>> xmltojar is displayed correctly in Firefox, it is not the case in the
>> help browser of Scilab where the description section does not appear.
>> Do you have some idea about that?
>
> The help browser is using the Java provided HTML4 renderer [1] which
> may not support some of the
> generated attributes (whereas Firefox supports more modern HTML). It
> is a bit specific as the
> Docbook to HTML (for javahelp) will pass through some attributes which
> might or might not be
> rendered.
>
> Do not hesitate to post your buggy files / examples,
>
> [1]:
> https://docs.oracle.com/javase/8/docs/api/javax/swing/text/html/HTMLDocument.html
>
> Thanks,
>
> --
> Clément
>
> Le mercredi 23 août 2017 à 09:54 +0200, Pierre Vuillemin a écrit :
>> Hello all,
>>
>> Some times ago, I started working on an updated (a little bit more
>> flexible) version of the routine help_from_sci.
>>
>> At this point, it can generate .xml file(s) from formatted head
>> comments
>> (either line comments or block-comments) and a minimal markdown
>> support
>> is working for the section Description (and user-defined section).
>> For instance see the files attached that shows the source comments
>> (src.png) and the resulting output doc (doc.png) obtained after using
>> xmltojar on the file slr_comments_to_xml.xml.
>>
>> (Note that the sections that are empty in the source file are not
>> rendered in the .xml file)
>>
>> Some things are still not implemented but it should not be that
>> difficult: paragraph, parsing of the example section, latex equations.
>>
>> The issue I am facing is that while the .html file obtained after
>> using
>> xmltojar is displayed correctly in Firefox, it is not the case in the
>> help browser of Scilab where the description section does not appear.
>> Do you have some idea about that?
>>
>> Best regards,
>>
>> Pierre
>>
>>
>> Le 11.05.2017 09:22, Clément David a écrit :
>> > Hello Pierre,
>> >
>> > Great news ! The help_from_sci() feature is currently really useful
>> > for new comers and improving it
>> > might be a good idea.
>> >
>> > The XML syntax used is a subset of Docbook 5 ; the man help page
>> > contains some information but I
>> > usually use the main Docbook documentation.
>> >
>> > About Markdown support, it might be a good idea to support it ;
>> > currently the syntax is similar but
>> > not standardized.
>> >
>> > Thanks,
>> >
>> > --
>> > Clément
>> >
>> > Le mercredi 10 mai 2017 à 15:01 +0200, Pierre Vuillemin a écrit :
>> > > Thanks for the answers and the hints, I have finally managed to do
>> > > what I wanted using xmltojar
>> > > and add_help_chapter.
>> > >
>> > > The xml file generated with help_from_sci seems to have some quirk, is
>> > > there a reference page
>> > > concerning the xml that should be produced? The main reference I have
>> > > found is this page but I
>> > > don't know if it is still up to date.
>> > >
>> > > Besides, I am thinking about extending the features of the routine so
>> > > that is supports some
>> > > flavour of markdown (or similar stuff like Matlab's publishing
>> > > features).
>> > > Has there already been some reflection in that direction?
>> > >
>> > > Regards,
>> > >
>> > > Pierre
>> > >
>> > > Le 10.05.2017 12:33, [hidden email] a écrit :
>> > > > Hello,
>> > > >
>> > > > > De: "Clément David"
>> > > > >
>> > > > > Hello Pierre,
>> > > > >
>> > > > > Currently the easiest way is to put the resulting xml file as an exemple of an empty
>> > > > > toolbox
>> > > > > and
>> > > > > build/load this toolbox to check for the rendering.
>> > > > >
>> > > > > HTML files can also be used as an easy content to check using a standard web browser (eg.
>> > > > > without
>> > > > > loading the toolbox). See xmltoweb() to generate it.
>> > > > >
>> > > > > AFAIK Samuel usually commit updated help files using the pdf format produced by
>> > > > > xmltopdf(). As
>> > > > > this
>> > > > > PDF backend is not the main one, I tend to prefer the HTML ones but PDF might be a good
>> > > > > alternative.
>> > > >
>> > > >
>> > > > AFAIRemember, xmltopdf() has some issue, so i use now PDF Creator
>> > > > applied the HTML.
>> > > > To illustrate the whole page setting and rendering, PDF does not need
>> > > > to be zipped,
>> > > > whereas HTML needs it to include css dependencies etc.
>> > > >
>> > > > Anyway, the rendering of the HTML (zipped in the .jar) through the
>> > > > Scilab helpbrowser
>> > > > is limited wrt the true HTML as it appears in web browsers: Many
>> > > > attributes or style
>> > > > values are well built but are not rendered... But this is another thread.
>> > > >
>> > > > Regards
>> > > > 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
>> >
>> > _______________________________________________
>> > dev mailing list
>> > [hidden email]
>> > http://lists.scilab.org/mailman/listinfo/dev
_______________________________________________
dev mailing list
[hidden email]
http://lists.scilab.org/mailman/listinfo/dev