[m-dev.] question about how to generate texinfo docs

[Zoltan Somogyi]

I am trying to decide how to generalize the help text in optdb clauses
to allow print_help.m to automatically generate the texinfo version
of the help text, for the invocation chapter of the user's guide.
I can see two ways to do it.

The first way is to keep the help text as a sequence of strings,
but with some strings being interpreted by print_help.m to call for
special treatment of the following string or strings. This has worked
well for plain old "mmc -help", which required a single special string,
"QUOTE", which protected the following string from being broken up
into words. However, for texinfo, we would need at least one special string
that calls for the special treatment of the next THREE strings. This is because
the documentation of some options includes texinfo text of the form
@file{var{modulename}.suffix}, which (a) requires the modulename
and the suffix to be given as separate strings, and if we want to follow
the generate texinfo with punctuation *without* an intervening space,
then we need to special-case the treatment of that punctuation as well.
The optdb help text version of the above example would then be
"QUOTE_FILE_VAR", "modulename", "suffix", ",". The code of print_help.m
would then have to check for "QUOTE_FILE_VAR" always being followed by
at least three strings, but if you forgot to supply the intended-for-punctuation
string, its code would happily take whatever string followed, the result
of which would not be pretty.

A slight variation would be to get "QUOTE_FILE_VAR" and similar quote words
to always take a single argument, which print_help.m would break up
into the required parts by splitting it along a designated special character.
This could allow the above example to be written as "QUOTE_FILE_VAR",
"modulename%suffix%,". Slightly better, but not by much.

The second way would be to change the type of the help text, which now
is a list of strings, to a list of values of a type like this:

:- type help_element
    --->  w(string)  % short for "words"
    ;      quote_file_var(string, string, string)
    ;      ...

This way would make the help text strongly typed (as opposed to stringly
typed for the first way). We would get immediate feedback from mmc
for any mistake, instead of having to wait for the failure of the help_text
test case. The downside is that making the initial switch is a lot of repetitive work.
(That is not a downside for you, since I would be doing that work.)

I nevertheless favor the second way. Does anyone object? If so,
please speak up now, because otherwise, I intend to start implementing
the second way in about 24 hours.

Zoltan.