Improve online help with manpages

Final Release Note

Description

Use Sphinx (YDBDoc) to create manpages and Info pages instead of .hlp files for MUPIP, GDE, LKE, and DSE. This will let us remove the .hlp files so that there is only one source of documentation to maintain. It involves:

  • Change the interactive HELP command to run man <command> instead.
  • YDBDoc can already create Info pages from AdminOpsGuide, so use sed to split out the relevant chapters for MUPIP, GDE, LKE, DSE.
  • YDBDoc can already create manpages from AdminOpsGuide, so use sed to extract the command summaries. Consider adding a column to the summary table that contains a short (e.g. 6-word) description of what the command does.
  • ydbinstall should be changed so that it installs these pages (with a switch to disable their installation). It should fetch these info/manpages from the YDBDoc releases tag for the YottaDB version being installed and highlight any discrepancy. The release procedure will obviously need to change so that it creates these pages.
  • Prefix a command synopsis to both manpages and Info pages.
  • Make --help and -h simply print a synopsis and reference the manpage, Info page, and online help, cf. #1102 (closed)

The effort for this MR will be relatively small (2-3 days), compared to writing or maintaining two sets of docs. Plus, it will provide highly desirable man pages.

Note: the main differences between the online MUPIP HELP (mupip.hlp) and the AdminOps manpage material are, in the case of MUPIP for example:

  • mupip.hlp has its commands categorised under sections (GDM, Journaling, Replication). This could easily be provided in a brief ToC / list at the start of the AdminOps/manpage material. Since manpages are searchable, the relevant command heading will easily be found.
  • The mupip.hlp command summary has an additional column stating the GTM version number where each MUPIP command and qualifier was introduced. (This has not yet been updated to include YottaDB version numbers, cf. #701).

Draft Release Note

  • To do: describe new and previous behaviour
Edited by Berwyn Hoyt