[Scilab-Dev] Trying to update help_from_sci

[Clément David]

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, sgougeon at free.fr 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
> > > > dev at lists.scilab.org
> > > > http://lists.scilab.org/mailman/listinfo/dev
> > > 
> > > _______________________________________________
> > > dev mailing list
> > > dev at lists.scilab.org
> > > http://lists.scilab.org/mailman/listinfo/dev
> > 
> > _______________________________________________
> > dev mailing list
> > dev at lists.scilab.org
> > http://lists.scilab.org/mailman/listinfo/dev