[m-rev.] for review: disable_warning [unknown_format_calls]

[Julien Fischer]

Hi Zoltan,

On Mon, 12 Sep 2022, Zoltan Somogyi wrote:

> 2022-09-07 20:05 GMT+10:00 "Zoltan Somogyi" <zoltan.somogyi at runbox.com>:
>> Ah. In that case, I propose that after the identification of the pred/func,
>> the second argument should either have the format "format_string_poly_types(N, M)",
>> where N & M are the argument numbers of the format string and the poly types
>> respectively (for the usual use case), or a list of such terms (for the use case
>> you just brought up). Having the format string and the poly types specified
>> separately would work, or at least wouldn't work well, in the latter use case.
>
> Attached is the proposed diff to the reference manual. For review by anyone.
>
> You will notice that I changed both the name of the pragma, and the function symbol
> above, slightly.

I don't have any objections to the new names.

> With the description of what checks the pragma calls for, the added text
> takes up three and a half pages in the PDF version of the manual.

It does have theeffect of the documentation of the pragma being more
extensive than that of string.format in the library reference.

> I am not entirely happy with the way the indentation comes out around
> some of the examples and around the table, but I don't know what would be better.
>
> There are two intentional omissions in this diff.
>
> - I do not say that the new pragma cannot apply to a typeclass method.
>  The reason for the omission is that this is much more a property
>  of typeclass definitions than of this pragma (other kinds of decl_pragmas
>  cannot appear in typeclass definitions either).
>
> - I do not mention that the new pragma suppresses unknown format warnings
>  for format calls that use the specified arguments for the format string and
>  the values list. The reason for this omission is that this pragma effectively
>  transfers the responsibility to get the format string/values list correspondence right
>  from the pragma that the pragma names to its callers, and that therefore
>  any such warnings would be generated at those call sites instead.
>  Therefore the absence of such warnings inside this predicate should not
>  be surprising; in fact, it is their *presence* that would be surprising.

...

> diff --git a/doc/reference_manual.texi b/doc/reference_manual.texi
> index fb2b23eac..df0c3d957 100644
> --- a/doc/reference_manual.texi
> +++ b/doc/reference_manual.texi
> @@ -11535,6 +11535,8 @@ with implementation-dependent semantics
> @@ -11772,6 +11774,258 @@ either directly or indirectly.

...

> +For the full set of the rules, please see the documentation
> +of @code{string.format} in the Mercury Library Reference Manual;
> +the same rules apply to @code{io.format}
> +and @code{stream.string_writer.format)} as well.
> +
> +For several years now, the Mercury compiler has checked calls
> +to the formatting predicates and function in the Mercury standard library,
> +specifically

Omit "For several years now" and just say:

     The Mercury compiler checks calls to the formatting ...

> + at table @asis
> + at item predicate @code{io.format/4}
> + at item predicate @code{io.format/5}
> + at item predicate @code{stream.string_writer.format/5}
> + at item function @code{string.format/2}
> + at item predicate @code{string.format/3}
> + at end table
> +
> +for inconsistencies between the format string and the value list,
> +generating a report for each such inconsistency.
> +This improves both program reliability
> +(because programmers get the problem brough to their attention

s/brough/brought/

That looks fine otherwise.

Julien.