Re: New Package Documentation

[Kai Torben Ohlhus]

On 10/2/20 3:53 AM, Chuck Cook wrote:
> On Thu, 2020-10-01 at 13:48 +0900, Kai Torben Ohlhus wrote:
>> On 9/30/20 9:20 PM, Chuck Cook wrote:
>>> I picked this link out of one of the other threads.
>>> https://github.com/gnu-octave/pkg-example
>>>
>>>
>>> My question is:
>>> How is new package documentation tied into the regular octave
>>> documentation?  I see packages that obviously have had a lot of work put
>>> into them.  But how to use them is cryptic and superficial.
>>>
>>> Chuck
>>
>>
>> Thank you for your interest.  The "pkg-example" [1] is created according
>> to the only and official Octave package documentation in the manual [2].
>>  Thus using "pkg-example" (also outside GitHub) you do not need to worry
>> to miss something important that Octave's "pkg" cannot install it properly.
>>
>> As an example it serves to demonstrate the bare necessary minimum.  And
>> yes, developing "simple" Octave packages is astonishingly simple 😉
>>
>> Depending on your needs and package purpose, those packages can of
>> course increase (dramatically) in complexity, e.g. "bootstrap",
>> "configure.ac", ...  But all this is not necessary for the start and
>> should best be avoided to reduce the maintenance burden current packages
>> are suffering from.
>>
>>> But how to use them is cryptic and superficial.
>>
>> What do you mean by this?  Do you mean lack of package documentation?
>>
>> HTH,
>> Kai
>>
> I am referring to package documentation.  I want to include brief
> examples, possibly a tiny bit of theory.
>


Sorry, I got your question wrong.  To my knowledge there have been
attempts, but never there was a working and approved "standard" for
package documentation, as the Octave manual shows [2]:

> package/doc
>   An optional directory containing documentation for the package.
>   The files in this directory will be directly installed in a sub-
>   directory of the installed package for future reference.

Every package maintainer does what he thinks is best.  One prominent
example using all potential package documentation approaches (resulting
in unmaintained duplication) is the "interval" package [3]:

  a) Individual function documentation [4,5] generated from the
     m-files help text (Texinfo) and demos ("generate_html"
     package [9])
  b) some user manual with more theory [6] (Texinfo source in the
     package "doc" directory [7], but generated and hosted manually,
     never updated in two years, as the package itself)
  c) Octave wiki [8]

My advise to you is:

(I) write the most documentation for each individual function with some
meaningful complete examples/demos.  When a user has a problem, my
impression is that reading a lengthy manual is the last thing he would
do.  For me unfortunately too, it goes mostly like "PROBLEM -> Try to
hack around -> help func -> Web search -> 10 minutes forums like
StackOverflow -> Search for manual -> Ask in some forum for help".

(II) write the bigger documentation in a format as simple as possible
(e.g. Markdown) which nicely renders math, tables via extensions and
offers via tools like pandoc almost unlimited export possibilities to
other markup languages (Texinfo, LaTeX, ...) and looks good
(automatically rendered) even in the source repository by default.
Texinfo is ugly and weird markup, do not start with it if you don't have
to 🙃

(III) host your bigger documentation at a location you can easily access
and update by yourself and just provide a link to it from all other
locations.  Being dependent on some admin's time and grace to get an
update of your docs is very frustrating for a task no programmer likes
anyways 😇

(II) and (III) in short: use the Octave wiki [8].

Kai


[1] https://github.com/gnu-octave/pkg-example
[2] https://octave.org/doc/v5.2.0/Creating-Packages.html
[3] https://octave.sourceforge.io/interval/
[4] https://octave.sourceforge.io/interval/overview.html
[5] https://octave.sourceforge.io/interval/function/@infsup/plot.html
[6] https://octave.sourceforge.io/interval/package_doc/
[7] https://sourceforge.net/p/octave/interval/ci/default/tree/doc/
[8] https://wiki.octave.org/Interval_package
[9] https://octave.sourceforge.io/generate_html/