[m-rev.] for post-commit review: rewrite opmode options' help texts

[Julien Fischer]

On Mon, 30 Jun 2025 at 02:00, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:

> Convert the opmode options to use semantic help_pieces.
>
> compiler/options.m:
>     As above. In the process, rewrite many options' help texts
>
>     - to make them more informative,
>     - to use more standard phraseology, and
>     - to delete unnecessary restrictions.
>
>    (Some of the rewritten text came from doc/user_guide.texi.)
>
> compiler/optdb_help.m:
> compiler/print_help.m:
>     Define and implement some new semantic categories,
>     to help with the change to options.m.
>
> tests/warnings/help_text.err_exp:
>     Expect the updated help texts.
>
> diff --git a/compiler/optdb_help.m b/compiler/optdb_help.m
> index 0568ea0cb..5ba29f9cc 100644
> --- a/compiler/optdb_help.m
> +++ b/compiler/optdb_help.m
> @@ -204,6 +204,10 @@
>      --->    w(string)                           % words
>      ;       opt(string)                         %
>      ;       opt(string, string)                 %
> +    ;       arg(string)                         % ?
> +    ;       arg(string, string)                 % ?
> +    ;       quote(string)                       % ``str1''
> +    ;       quote(string, string)               % ``str1''str2
>      ;       samp(string)                        % @samp{str1}
>      ;       samp(string, string)                % @samp{str1}str2
>      ;       emph(string)                        % @emph{str1}
> diff --git a/compiler/options.m b/compiler/options.m
> index b1c031e38..b090c6019 100644
> --- a/compiler/options.m
> +++ b/compiler/options.m
> @@ -1267,116 +1267,172 @@ optdb(oc_cmdline,   filenames_from_stdin,              bool(no),
>
>  optdb(oc_opmode,    only_opmode_generate_source_file_mapping, bool(no),
>      short_help('f', "generate-source-file-mapping", [], [
> -        w("Output the module-name-to-file-name mapping for the list"),
> -        w("of source files given as non-option arguments to mmc"),
> -        w("to `Mercury.modules'. This must be done before"),
> -        w("`mmc --generate-dependencies' if there are any modules"),
> -        w("for which the file name does not match the module name."),
> -        w("If there are no such modules the mapping need not be"),
> -        w("generated.")])).
> +        w("Output to"), file("Mercury.modules"),
> +        w("the module-name-to-file-name mapping for the"),
> +        w("list of source files given as non-option arguments to mmc."),
> +        w("This must be done before invoking"),
> +        code("mmc --generate-dependencies"),

I know this is what the existing text said, but who are we expecting to invoke
mmc --generate-dependencies directly? It might be better to say before invoking
mmc --make or mmake depend, since this is what most users are actually
going to do.

> +        w("if there are any modules for which"),
> +        w("the file name does not match the module name."),

That's not the only reason for using a source file mapping. They
are quite commonly used to direct the compiler to source files that
reside in another directory.

...

>  optdb(oc_opmode,    only_opmode_make_interface,        bool(no),
>      short_help('i', "make-interface", ["make-int"], [
> -        w("Write the module interface to `<module>.int',"),
> -        w("and write the short interface to `<module>.int2'"),
> -        w("This option should only be used by mmake.")])).
> +        w("Write to"), file_var("module", "int"),
> +        w("and to"), file_var("module", "int2"),
> +        w("a list of entities"),
> +        w("(including types, insts, modes, predicates and functions)"),
> +        w("that the given module exports for use by other modules."),
> +        w("When generaring code, the compiler reads the"),

s/generaring/generating/

> +        file(".int"), w("file of every directly imported module,"),
> +        w("and the"), file(".int2"), w("file"),
> +        w("of every indirectly imported module."),
> +        w("(Each"), file(".int2"), w("file"),
> +        w("is a slightly shorter version"),
> +        w("of the corresponding"), file(".int"), w("file,"),
> +        w("because it is specialized for its intended use.)")])).

...

>  optdb(oc_opmode,    only_opmode_output_library_link_flags, bool(no),
>      help("output-library-link-flags", [
> -        w("Print to standard output the flags that are passed to linker"),
> -        w("in order to link against the current set of libraries."),
> -        w("This includes the standard library, as well as any other"),
> -        w("libraries specified via the --ml option.")])).
> +        w("Print to standard output the flags"),
> +        w("that must be passed to the linker in order to"),
> +        w("link against the current set of libraries."),
> +        w("This includes the Mercury standard library, as well as any other"),
> +        w("libraries specified via the"), opt("--ml"), w("option.")])).

or with the `-l' option (i.e. for non-Mercury libraries).

That looks fine otherwise.

Julien.