[m-rev.] for post-commit review: implement --help-texinfo

[Julien Fischer]

On Fri, 4 Jul 2025 at 03:13, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:
>
> This diff gets us close to the point where we can generate
> the contents of the Invocation chapter of the User's Guide
> automatically, but we are not there yet. There are five references
> to the Invocation chapter in the rest of the user guide that become
> dangling links when the output of mmc --help-texinfo replaces
> the invocation chapter, and until those are fixed, I cannot show
> you what the updated user guide would look like.
>
> Before I can get there, I need to make some decisions that
> I would like your feedback on.
>
> First, at the moment, the user guide's documentation of the
> --grade option is *much* more extensive than the corresponding help text in mmc --help. Where should this be put? The obvious answer is a new chapter in the user's guide, but where should
> that chapter be?
>
> The two possible answers I see are (a) just before the current invocation
> chapter, and (b) somewhere around the current sections 3 and 4 (Using mmc
> and running programs respectively). I would be fine with either, but would
> prefer the latter, because both sections 3 and 4 already talk about
> grade-specific stuff, but do not explicitly call this out.

I don't have a strong preference either way.

> Second, some of the dangling links are in descriptions of smart recompilation.
> As far as I know, that functionality was never finished, and is not ready
> for prime time. As such, I think the right fix is to comment out all the text
> that talks about smart recompilation, and make the related options private.

I have no objections to that.  IIRC, the major limitations with smart
recompilation
are that it does not work with --intermodule-optimization or with --make.


> Implement (mostly) mmc --help-texinfo.
>
> compiler/print_help.m:
>     Implement mmc --help-texinfo for real by generating near-final texinfo
>     output when asked to.
>
>     Move some utility operations to the end of the file.
>
> doc/update_opts:
>     A script to replace the bulk of the invocation chapter of the
>     User's Guide with the output of mmc --help-texinfo.
>
> doc/Mmakefile:
>     Add a new target, intended to be invoked manually, to both
>     invoke update_opts, and to show the user its effect.
>
> compiler/options.m:
>     Fix a link and some texinfo format bugs.
>
> tests/warnings/help_text.err_exp:
>     Expect the fixed link.
...
> diff --git a/compiler/print_help.m b/compiler/print_help.m
> index 31f2acf8b..303eeaafd 100644
> --- a/compiler/print_help.m
> +++ b/compiler/print_help.m
...
> @@ -428,7 +516,8 @@ document_requested_options(Format, What, OptionsLines) :-
>          ),
>      solutions_set(CategoryPred, AllCategoriesSet),
>      acc_help_sections(Format, What, all_chapters,
> -        AllCategoriesSet, UndoneCategoriesSet, cord.init, OptionsLineCord),
> +        AllCategoriesSet, UndoneCategoriesSet,
> +        cord.init, SectionNameCord, cord.init, OptionsLineCord),
>      set.to_sorted_list(UndoneCategoriesSet, UndoneCategories),
>      (
>          UndoneCategories = []
> @@ -436,125 +525,224 @@ document_requested_options(Format, What, OptionsLines) :-
>          UndoneCategories = [_ | _],
>          unexpected($pred, "undone: " ++ string(UndoneCategories))
>      ),
> +    SectionNames = cord.list(SectionNameCord),
>      OptionsLines = cord.list(OptionsLineCord).
>
>  %---------------------------------------------------------------------------%
>
> -:- pred acc_help_sections(help_format, print_what_help, list(help_section),
> -    set(option_category), set(option_category), cord(string), cord(string)).
> -:- mode acc_help_sections(in(help_plain_text), in, in,
> -    in, out, in, out) is det.
> -:- mode acc_help_sections(in(help_texinfo), in, in,
> -    in, out, in, out) is det.
> +:- type menu_item
> +    --->    menu_item(string, string).
> +            % The name of the menu item, and its short description, if any.
> +            % (Nonexistent descriptions are represented by an empy string.)

s/empy/empty/

The rest looks fine.

Julien.