[Octave-patch-tracker] [patch #8990] generate_html : Adding field (additional documentation:url) to index.html of ref-man

[Oliver Heimlich]

Follow-up Comment #1, patch #8990 (project octave):

There is going to be a strategic decision regarding this change.

Currently, Octave Forge is used as both, a place to develop packages and a
repository of these packages. The best-practice to add such information is to
put it in a “package documentation” and publish it on Octave Forge.

See the following packages for examples: database, interval, optim, and
parallel. Unfortunately many packages miss such a documentation at the
moment.

To use this feature, you write a manual (in TexInfo format) and distribute it
in your package in a sub folder called “doc” (next to “inst”). The doc
folder is copied over during package installation.

For publication on Octave Forge you can also create the documentation as
follows:

options = get_html_options ('octave-forge');
options.package_doc = 'manual.texi'; # or whatever it is called
generate_package_html ('$(PACKAGE)', '$(HTML_DIR)', options)


This approach also works well with explaining the use of a package (with code
examples), since you may check the correctness of code examples using the
doctest package.

Now, let's go back to your idea of pointing to external documentation. You can
do this very well in a manual (as described above). However, if the primary
source of documentation for a package is hosted elsewhere, i. e. , not at
Octave Forge, this is a step towards making Octave Forge a repository of
externally hosted packages. Something like https://metacpan.org/ as Carnë
pointed out earlier. And, as soon as we start going in that direction, placing
a single link won't help much and will not be enough.

    _______________________________________________________

Reply to this item at:

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

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