[Octave-patch-tracker] [patch #9002] generate_html : Adding package_doc_options field to generate texinfo documentation

[Oliver Heimlich]

Follow-up Comment #16, patch #9002 (project octave):

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.


    _______________________________________________________

Reply to this item at:

  <http://savannah.gnu.org/patch/?9002>

_______________________________________________
  Nachricht gesendet von/durch Savannah
  http://savannah.gnu.org/