Re: Octave-Forge: How to integrate package documentation?

[Juan Pablo Carbajal]

On Tue, Dec 22, 2015 at 11:50 PM, Oliver Heimlich <address@hidden> wrote:
> 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
>
Sounds like some work, but if you are willing to do it, you have my blessing. :D