Octave-Forge: How to integrate package documentation?

[Oliver Heimlich]

Hello,

I have observed several fundamental problems with the documentation of
Octave-Forge packages:

 - “See also” links are broken for packages since revision c16947991354
in Octave core back in 2012.  The generated anchor files (XREF….html)
could be used to reference particular functions from external
documentation, which is similar to what Octave does internally for its
documentation:

   [some texi file that gets published at Octave-Forge]
   @ref{XREFdeal,, deal, octave}

   [htmlxref.cnf used during html generation for Octave-Forge]
   octave node https://www.gnu.org/software/octave/doc/interpreter

   This results in the text (octave)deal, which links to
https://www.gnu.org/software/octave/doc/interpreter/XREFdeal.html#XREFdeal

 - References from the package manual to the package function reference
are complicated.  The “node” names for the function reference do not
follow Texinfo standards, so @ref commands do not work. However, there
is a workaround using custom macros:
@uref{../function/\function\.html,\function\} does the trick.

 - References from the package function reference to the package manual
are impossible, unless you hack some urls together.

 - The doc command in Octave core apparently does not support packages.
What would be needed to achieve this?

 - Unlike the function reference, the package documentation does not
integrate into the Octave-Forge design and navigation scheme.

 - Package HTML generation is very slow for packages with many function,
because makeinfo gets called for every function individually.

How about starting a new approach to package documentation? I suggest
that the package documentation should be handled (like Octave core
documentation) in a single Texinfo document during generation, which
would solve above problems in a simple way.

1. The package manual and the package function reference are merged (by
the generage_html package) into a single Texinfo source, which is used
to generate the HTML documentation in a single run of makeinfo.
  a) plaintext documentation strings are automatically converted into
Texinfo
  b) @seealso links are automatically converted into Texinfo
cross-references (either for Octave core, or for the same package, or
for an external Forge package)
  c) The function overview page could be build using an automatically
generated @menu (from the INDEX file).
  d) Arbitrary @ref's between the function reference and the package
manual work out of the box, @ref's towards Octave core will also work.
If required, Octave core could reference packages in a sane way.
  e) If a package manual is present, the function reference could be
included using some @appendix Function Reference / @include
@value{path-to-function-reference}, otherwise generate_package_html
provides a minimal container document.
  f) The Octave-Forge layout can be injected using AFTER_BODY_OPEN,
PRE_BODY_CLOSE, and EXTRA_HEAD customization variables.
  g) Only the index.html, NEWS.html and COPYING.html pages would be
generated as before.

2. The function lists at Octave-Forge could be build around the function
indices, which would be generated by Texinfo as a byproduct.

3. Optional: The unified Texinfo source for the package could be used to
ship an info file as part of the package release, which could be browsed
in Octave's doc browser.


At a first glance this could actually work with no extra costs for Forge
maintainers.  I volunteer for experimenting with this approach unless
you consider it a crazy idea.  What do you think?

Best regards
Oliver

signature.asc
Description: OpenPGP digital signature