[m-rev.] for post-commit review: fix doc in term_io.m

[Julien Fischer]

Hi Zoltan,

On Fri, 7 Apr 2023, Zoltan Somogyi wrote:

> The code of term_io.m was written before we had stream.string_writer,
> so for some operations, it implements them twice (one version doing I/O,
> one constructing a string), while for others, the string version is missing.
> Would anyone object if I rewrote its guts using stream ops, the same way
> that parse_tree_out_*.m now has write_X, X_to_string, and format_X
> for various X? It would be slower than the current code at lower-than-default
> optimization levels, but two typespec pragmas for all affected predicates,
> enabled in Mercury.options, should cure this.

No objections from me.

> I also think we need a better naming scheme that allows people
> to look at a pred or func name and know whether that op (a) quotes
> the entity in question AND whether it (b) puts quotes around it or not.
> At the moment, most names answer just one of those questions,
> not both. But that is for a different diff.

> Fix user-visible documentation in term_io.m.
> 
> library/term_io.m:
>     Four predicates that wrote to the current output stream were documented
>     as writing to stdout, which may, or *may not*, be stdout. Fix this.
>
>     Make the code of escaped_string more readable.
>
>     Delete unneeded explicit module qualifications.
> 
> NEWS.md:
>     Announce the fix.

I will merge this change on to the 22.01 branch since the documentation
fixes should go into the 22.01.6 release.

>  * This new module contains predicates that perform substitutions
> diff --git a/library/term_io.m b/library/term_io.m
> index f011fe309..c3fc859c1 100644
> --- a/library/term_io.m
> +++ b/library/term_io.m

...

> @@ -103,8 +103,9 @@
>      %
>  :- func quoted_char(char) = string.
> 
> -    % Given a character C, write C, escaped if necessary, to stdout.
> -    % The character is not enclosed in quotes.
> +    % Given a character C, write C, escaped if necessary,
> +    % to the current output stream, or to the specified output stream.
> +    % Don't enclose the character in quotes.

s/Don't/Do not/

>      %
>  :- pred write_escaped_char(char::in, io::di, io::uo) is det.
>  :- pred write_escaped_char(Stream::in, char::in, State::di, State::uo) is det
> @@ -136,13 +137,13 @@
>      %
>  :- func quoted_string(string) = string.
> 
> -    % Given a string S, write S, with characters escaped if necessary,
> -    % to stdout. The string is not enclosed in quotes.
> +    % Given a string S, write S, with characters escaped if necessary.
> +    % Don't enclose the string in quotes. Write to the current output stream,
> +    % or to the specified output stream.

Ditto.

That's fine otherwise.

Julien.