patchGNU Octave - Patches: patch #9002, generate_html : Adding ...

 
 

patch #9002: generate_html : Adding package_doc_options field to generate texinfo documentation

Submitter:  Fernando Pujaico Rivera <trucomanx>
Submitted:  Fri 13 May 2016 06:39:38 PM UTC
   
 
Category:  None Priority:  5 - Normal
Status:  Done Privacy:  Public
Assigned to:  None Open/Closed:  Closed
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Sun 12 Jun 2016 02:38:24 PM UTC, comment #21: 

Please close this ticket.

Julien Bect <jbect>
Sun 12 Jun 2016 02:37:55 PM UTC, comment #20: 

I believe that the original point of this post has been adressed by the recent release of generate_html 0.1.11.

Concerning the points raised in the most recent comments:

a) The problem of providing an appropriate stylesheet for package documentations should now be discussed in the dedicated bug report: https://savannah.gnu.org/bugs/index.php?48203

b) The new approach suggested by Oliver in comment #14 sounds to me like major rewrite of the generate_html package, corresponding to a 0.2.x or perhaps 1.0.0 release.  Such a change should be addressed in a dedicated ticket on the patch tracker (and perhaps on a separate branch in the hg repo).


Julien Bect <jbect>
Thu 02 Jun 2016 03:42:23 PM UTC, comment #19: 

I think that the name "function reference" is fine (for the moment). Given that the reference manual should be made automatically as in many others libraries (working with Doxigen, Javadoc). And the package_doc variable should be used to a "Tutorial".

Thus, we would have:
Reference manual: (automatically) defining as to use the each one of functions.
Tutorial: (manually) Defining as use the function in a program and in a context, linking and showing a bit of theory.
(optional) examples: (manually) some examples explicated in the manual and others

Maybe, with the time we can work to make something similar to doxygen to Octave.
And that generate_html calls this program, but I think that the current library generate_html, its fine for me.

Also think that the reference manual of the libaries  were made in plain text because the documentation can be implemented with texinfo, or without it to libraries that work also with matlab.

Maybe as future work we need consider enable two types of documentation, }
texinfo source and
matlab compatible source.

options = get_html_options ("octave-forge","texinfo");
options.package_doc="tutorial.texi";
 generate_package_html ("packname_refman", "packname", options);


options = get_html_options ("octave-forge","compatibility");
options.package_doc="tutorial.texi";
generate_package_html ("packname_refman", "packname", options);

Fernando Pujaico Rivera <trucomanx>
Wed 01 Jun 2016 08:25:03 PM UTC, comment #18: 

To comment on some of these issues:

I'm in favour of having a default style sheet for package_doc. I can't say if it should be separate from the octave-forge style sheet or not.

(My personal opinion: The default style sheet should change as little as possible, the current layout without a style sheet seems quite acceptable to me. Readability of text and clear structuring are important. Beautifying, especially of text, can distract from the content.)

If the package maintainer has reasons to use a non-default style sheet -- why not, no objections against an option for this.

I actually didn't link from package_doc to the standard function reference, and I wouldn't like to do it. For package_doc, I extract the function help texts separately and sometimes change them slightly (e.g. by cutting out some marked text) to better fit into the structure of the package_doc. Also, I sometimes embed the function help text into the text of an info page.

(But I'm not happy with the duplication of information by the standard function reference. If a package_doc already contains all function help texts, cooked up to fit into the package_doc, this source of information should probably be preferred over the standard function reference. OTOH the standard function reference could be valuable as a collection of all function help texts. Maybe it should be named this way: 'Collection of function help texts' or so, not 'Function reference', in order to avoid misleading users away from package_doc -- at least in cases where the package_doc includes all function help texts.)

Olaf Till <i7tiol>
Group Member
Wed 01 Jun 2016 06:39:41 PM UTC, comment #17: 

About the comment #14:

> The option has been introduced for the octave-forge defaults, which should be used to create an online OF website (otherwise you would have many more problems like extra OF stuff that you don't want). Also the file name octave-forge.css is very specific.


We could copy the file:
http://www.gnu.org/software/octave/octave.css
and paste it to directory:
http://octave.sourceforge.net/

and to use:
../../octave.css
All the reference manuals of documentation of OF packages are designed to be seen  online. Making a reference link ../../octave.css no will change this fact.
It is no different to the references of files: download.png, fixed.js, manual.png , etc.
And this consideration give us the possibility of to have a off-line version of the same documentation, when copying  the files

download.png 
fixed.js      
manual.png 
""octave.css""
doc.png 
favicon.ico 
javascript.js 
news.png   
oct.png

Fernando Pujaico Rivera <trucomanx>
Wed 01 Jun 2016 06:23:14 AM UTC, comment #16: 

I have added Olaf Till to the discussion, who is the maintainer of the other OF packages with documentation.

The octave-forge.css is hardly compatible with the package_doc in its current form. octave-forge.css is meant for pages which have a (blue) menu bar at the top and the other documentation pages which have a (gray) menu bar at the left. Also these pages have custom HTML structure filled with information by generate_html. It gives the whole site a consistent design.

In contrast, package_doc in its current form is a standalone web page where octave-forge.css doesn't really fit yet.

IMHO, package_doc should get better integration into the OF website. That is, it should ideally use the same CSS file and it should also have the blue menu bar on top and it should probably also get that gray menu bar on the left which is present in the function reference. That is, we should work on getting the navigation bars into the package_doc as well.



Slightly off-topic, but could as well simplify the whole issue:

generate_html currently creates the HTML pages individually by pasting custom HTML snippets (e.g. the blue menu bar) and HTML generated by _makeinfo_ together. This approach is slow (I have to wait 2m33s for the interval package although only half the functions are in the function reference—on a fast machine with SSD) and doesn't work anymore when a whole Texinfo manual shall be converted to HTML: You would have to post-process several HTML files.

Thus, if we want to go in that direction, I'd suggest a (radical?) change to the current way how generate_html works: Currently, it extracts various information (e. g. with get_help_text) and creates individual HTML files. Let us “vectorize” this code. We could collect the information (e. g. Texinfo markup with get_help_text), but collect all these snippets into a Texinfo document, which is then converted into HTML as a whole. We would have to agree on some common structuring (appendix with function reference, NEWS, COPYING) and the current package_doc could optionally be included in that Texinfo document as front matter.

This would integrate function reference and package_doc and would allow for very simple Texinfo cross-references between the two (and also between different packages, see-also links, function index). Olaf is doing this already in the package_doc of his packages. If we polished the style and output of this, the approach could be used for all packages—even those which don't have a package_doc.

Oliver Heimlich <oheim>
Wed 01 Jun 2016 05:16:04 AM UTC, comment #15: 

Ok, so let's keep this ticket open a little longer, to discuss a possibly better choice of default package_doc_options for the OF option style (et the default one, if need be).

> - An offline documentation could still use the absolute URL. This even works in offline documents if there is an Internet connection.


I don't agree with that.  An offline documentation must be browseable offline IMHO, so, without an internet connection.

Even if the "octave forge" option set is meant for the OF website, which is online, one benefit of relative URLs is that the doc remains readable offline is you wget it.


> - The option has been introduced for the octave-forge defaults, which should be used to create an online OF website (otherwise you would have many more problems like extra OF stuff that you don't want). Also the file name octave-forge.css is very specific.


I agree with the first part (see above).

As for the second part, I am not sur what you mean by "very specific".  Is it a bad thing.  Is it not meant to be specific, since ths is the "octave forge" option set?


> - ../../octave-forge.css is not prepared to act as a stylesheet for the package documentation in its current format (which is basically standard texi2any output). A different file like ../../texi.css would have been better.


About this I don't know yet, but this is certainly the most important point in this discussion.

> In the current form I can't make use of the default value for package_doc_options. It would have been better to just omit the --css-ref option if in doubt.


I understand. 

There are currently only a small number of packages with documentation.  So, we should look at the existing packages and perhaps ask other package maintainers before we decide...

Can we (and should we) propose a default style sheet for the package documentation on Octave Forge?  If yes, should it be independent of octave-forge.css, or do we need to modify octave-forge.css?

Perhaps should we provide an additional field in the option structure, to make it easier for each package maintainer to specify a different CSS stylesheet to the package doc?  (I mean, easier than dealing directly with makeinfo options.)

Julien Bect <jbect>
Mon 30 May 2016 11:47:47 PM UTC, comment #14: 

Sorry, I missed the discussion due to vacation.

Regarding comment #2, Fernando's point was that he wanted a relative URL to easily create offline documentation. I don't think that this is a good idea (although it has slipped into to pending release):

- An offline documentation could still use the absolute URL. This even works in offline documents if there is an Internet connection.

- The option has been introduced for the octave-forge defaults, which should be used to create an online OF website (otherwise you would have many more problems like extra OF stuff that you don't want). Also the file name octave-forge.css is very specific.

- ../../octave-forge.css is not prepared to act as a stylesheet for the package documentation in its current format (which is basically standard texi2any output). A different file like ../../texi.css would have been better.

In the current form I can't make use of the default value for package_doc_options. It would have been better to just omit the --css-ref option if in doubt.

Oliver Heimlich <oheim>
Wed 18 May 2016 08:45:54 AM UTC, comment #13: 

This ticket can be closed.

Julien Bect <jbect>
Wed 18 May 2016 08:45:07 AM UTC, comment #12: 

@Fernando: I added a copyright line for you on generate_package_html.m.

I know there are other patches waiting, but they will have to wait a little longe (unless someone else with push access wants to review them). You can always use your own patched version of generate_html in the meantime ;-)

Julien Bect <jbect>
Tue 17 May 2016 11:12:11 PM UTC, comment #11: 

@Julien, please don't forget the patch
https://savannah.gnu.org/patch/?8984

Fernando Pujaico Rivera <trucomanx>
Tue 17 May 2016 10:01:07 PM UTC, comment #10: 

@Julien , For me it would be great to have a citation in the copyright.

Thank you very much for accepting the changes, this made my work more easy.

Fernando Pujaico Rivera <trucomanx>
Tue 17 May 2016 08:37:10 PM UTC, comment #9: 

I have made the changes discussed in comments #2 and #3, and merge the patch branch to default.

This ticket can be closed.

@Fernando: I can add a copyright line for you on generate_package_html.m if you like.

Julien Bect <jbect>
Tue 17 May 2016 04:58:47 PM UTC, comment #8: 

Hi Julien
It's fine for me, to have the package_doc_options field already helps me a lot.

Fernando

Fernando Pujaico Rivera <trucomanx>
Tue 17 May 2016 05:52:53 AM UTC, comment #7: 

Fernando,

I would like to keep things simple here. Doing string concatenation manually is easy, let's leave it at that for the moment.

What you are proposing (comments #4-#6) should be the subject of a separate patch, if you want to discuss it. But I am not sure it is worth the complication, you can always decide to use a separate init file if you like anyway.

Please let us focus in this discussion on the addition of the new package_doc_options field (I think everybody agrees it is useful) and on its value in the "ocave-forge" setting.

@++
Julien

Julien Bect <jbect>
Tue 17 May 2016 02:35:37 AM UTC, comment #6: 

If texinfo init file option is selected, then I think that be good to have the next function (or similar):

create_texinfo_init_file('suggested_texinfo_init_file.init');

Please see attached m-file.

(file #37183)

Fernando Pujaico Rivera <trucomanx>
Tue 17 May 2016 12:30:06 AM UTC, comment #5: 

Although I would not mind not use the initialization file,

and let that the  package_doc_options variable as a variable internal configuration of the make_info program in the get_html_options() function.

because I think this will happen if the variable is very long and difficult to read.
What do you think?

Fernando Pujaico Rivera <trucomanx>
Tue 17 May 2016 12:18:38 AM UTC, comment #4: 

I think that the variable, package_doc_options, could is being overloaded.
Maybe we should to use the variable only for things that can not be initialized by texinfo init file.

So that the variable

-----------------------------------------------------------------------------
options.package_doc_options= ' --css-ref=""../../octave-forge.css"" '
-----------------------------------------------------------------------------

and we recommend to the user to make

-----------------------------------------------------------------------------
options.package_doc_options = [options.package_doc_options, ' --init-file=""overview.init"" '];
-----------------------------------------------------------------------------

with the next texinfo init file

--------------------------------overview.init--------------------------------
use strict;

set_from_init_file('PRE_BODY_CLOSE', "<a class=\"sf-logo\" \
href=\"http://sourceforge.net/\"><img width=\"120\" height=\"30\" \
style=\"border:0\" alt=\"Sourceforge.net Logo\" \
src=\"http://sourceforge.net/sflogo.php?group_id=2888&amp;type=13\" /></a>");

set_from_init_file('TOP_NODE_UP_URL','../index.html');
-----------------------------------------------------------------------------

Thus, be very easy for me, to post my next recommendation (in another patch thread)
to add latex-equation display support.

-------------------------------Others parameters-----------------------------
set_from_init_file('EXTRA_HEAD', "\
  <STYLE> #jsMath_Warning {display: none} </STYLE>\
  <SCRIPT SRC=\"../../jsMath/easy/load.js\"></SCRIPT>");
-----------------------------------------------------------------------------

That's what I believe

Fernando

Fernando Pujaico Rivera <trucomanx>
Mon 16 May 2016 08:23:39 PM UTC, comment #3: 

Oliver proposes to add:

--set-customization-variable 'PRE_BODY_CLOSE <a class="sf-logo"
href="http://sourceforge.net/"><img width="120" height="30"
style="border:0" alt="Sourceforge.net Logo"
src="http://sourceforge.net/sflogo.php?group_id=2888&amp;type=13" /></a>'

http://octave.1599824.n4.nabble.com/generate-html-Adding-new-field-to-option-structure-in-the-generation-of-documentation-from-texinfo-tp4676940p4677004.html

The point is to add the SF logo at the bottom of the page, as is the case on other pages.

I will do that soon, unless someone objects in the meantime.

Julien Bect <jbect>
Mon 16 May 2016 08:14:19 PM UTC, comment #2: 

Fernando proposes to change, in the "octave-forge" settings, from

'--css-ref=""https://www.gnu.org/software/octave/doc/interpreter/octave.css"'

to

'--css-ref=""../../octave-forge.css"'

http://octave.1599824.n4.nabble.com/generate-html-Adding-new-field-to-option-structure-in-the-generation-of-documentation-from-texinfo-tp4676940p4677013.html

This seems a good idea to me.  @Oliver, @Carne: what do you think?

Julien Bect <jbect>
Mon 16 May 2016 08:07:36 PM UTC, comment #1: 

There has been some discussion on this issue on the mailing list:

http://octave.1599824.n4.nabble.com/generate-html-Adding-new-field-to-option-structure-in-the-generation-of-documentation-from-texinfo-tp4676940p4676955.html

A branch named "patch-9002" has been created on the marcurial repo.

Julien Bect <jbect>
Fri 13 May 2016 06:39:38 PM UTC, original submission:  

generate_html : Adding  package_doc_options field to generate texinfo documentation

This proposed patch 'adding_package_doc_options_to_option_structure.diff'
add the 'package_doc_options' field to option structure returned by get_html_options
function. This change is proposed to add more functionalities to texinfo
documentation. By example to use CSS style files or specify additional commands.

The traditional way of generates a tutorial.html with the generate_html package ,
it is using internally the command, 'makeinfo --html -o package_doc tutorial.texi',
executing the next Octave command:

options = get_html_options ("octave-forge");
options.package_doc = 'tutorial.texi';
generate_package_html ("image", "image_html", options);

By other side, I am proposing to use also this structure (if desired):

options = get_html_options ("octave-forge");
options.package_doc = 'tutorial.texi';
options.package_doc_options = '--no-split --css-ref=tutorial.css';
generate_package_html ("image", "image_html", options);

This example code generates a tutorial.html using internally
the command:

makeinfo --html -o package_doc tutorial.texi --no-split --css-ref=tutorial.css

Adding to end of command the string inside of the package_doc_options field.

Additionally, I modify the generate_package_html function to copy any CSS file
called inside the resulting html file. This code is clone of internal function that make
the same work with the images.

PS: Also, I am sending a standalone example documentation package. The code use in the example was
options = get_html_options ("octave-forge");
options.package_doc = 'overview.texi';
options.package_doc_options = '--no-split  --css-ref=manual.css';
generate_package_html ("bsltl", "bsltl_html", options);
With the current source code of bsltl package.

Fernando Pujaico Rivera <trucomanx>

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

Attached Files
file #37183:  create_texinfo_init_file.m added by trucomanx (887B - text/x-objcsrc)
file #37146:  bsltl_html.tar.gz added by trucomanx (64KiB - application/gzip - Adding package_doc_options field )
file #37147:  adding_package_doc_options_to_option_structure.diff added by trucomanx (7KiB - text/x-patch - Adding package_doc_options field )

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by i7tiol (Posted a comment)
  • -email is unavailable- added by oheim (Added database, optim, and parallel package maintainer)
  • -email is unavailable- added by siko1056 (Updated the item)
  • -email is unavailable- added by oheim (Posted a comment)
  • -email is unavailable- added by jbect
  • -email is unavailable- added by jbect (Posted a comment)
  • -email is unavailable- added by trucomanx (Submitted the item)
  • -email is unavailable- added by trucomanx (generate_html: Adding new characteristic.)
  • -email is unavailable- added by trucomanx (generate_html: Adding new characteristic.)
  • -email is unavailable- added by trucomanx (generate_html: Adding new characteristic.)
  • -email is unavailable- added by trucomanx (generate_html: Adding new characteristic.)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 12 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2016-06-17 carandraug StatusNeed Info Done
        Open/ClosedOpen Closed
    2016-06-01 oheim Carbon-Copy- Added -email is unavailable-
    2016-05-31 siko1056 StatusNone Need Info
    2016-05-17 trucomanx Attached File- Added create_texinfo_init_file.m, #37183
    2016-05-16 jbect Carbon-Copy- Added -email is unavailable-
    2016-05-13 trucomanx Attached File- Added bsltl_html.tar.gz, #37146
        Attached File- Added adding_package_doc_options_to_option_structure.diff, #37147
        Carbon-Copy- Added -email is unavailable-
        Carbon-Copy- Added -email is unavailable-
        Carbon-Copy- Added -email is unavailable-
        Carbon-Copy- Added -email is unavailable-

    Back to the top

    Powered by Savane 3.14-f13d.
    Corresponding source code