Doco fixup 2024-01

[apjanke]

Some problems with the doco. Want fixes soon, for #108 Reconcile with Statistics OF.

TODO

• Get generated doco building again, with contemporary toolchain.
• Fix texi doc: "@ref should not appear on @item line" warnings in make doc #112
• Version-ize the User Guide in docs/ & website - versioned stable releases, make the latest stable the one linked from readme/index on GHP, and a separate "devel"/"head" section for rolling current doco from main branch.
• Publish updated doco to GH Pages.
  • (requires merging to main in current GH Pages setup)
• Add a make clean target for the docs, and preferably file freshness detection that works with git reset --hard and the like.
  • Distinguish the derived doc files from inputs, probably with a separate subdir.
• Get rmmissing and fillmissing "undocumented" items removed from the texinfo function indexes (section 8)
  • (they were in the /INDEX file, not in any of the source code or doc/ stuff themselves)
• Update years in copyright notices.
• Fix bogus bullet lists in doco content, like string
  • (it needed @itemize or @enumerate, not Markdown style lists or fixed-width formatting)
• Consider switching to using the pkg-octave-doc package to generate doco.
• Improve main string class doco #114
• Consider changing {Function} etc to {Tablicious} in @deftypefns like Statistics does.
• New custom domain for Tablicious, for use with GH Pages site?
• Add the table logo to the README and maybe the main gh-pages page.
• Fix Functions in packages (namespaces) not showing up in generated doco? #120 (functions in packages not getting linked right)

Details

Bogus bullet lists in texinfo content

For the bogus bullet lists, e.g. string's class doco has this:

## The string class represents strings, where:
##   - Each element of a string array is a single string
##   - A single string is a 1-dimensional row vector of Unicode characters
##   - Those characters are encoded in UTF-8
##     - This last bit depends on the fact that Octave chars are UTF-8 now
##

But that gets rendered like this (HTML):

(PDF):

(QHelp):

Oops.

References

• Suggestions from pr0m1th3as (Statistics) in other issue comment
• Separate section for Examples in User Manual #51
• Functions in packages (namespaces) not showing up in generated doco? #120

[apjanke]

Moved milestone from 0.4.0 to 0.5.0 because I want to do 0.4.0 soon for Statistics compatibility and some basic fixes, and the relevant items in this ticket for that are fixed now I think. Further items like string doco improvement and switching to a different doc-building tool can wait until the next release.