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).

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.)

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.

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.

@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 , 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.

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

Fernando

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)

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

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.