[m-rev.] Fwd: Re: for post-commit review: fill in most of the grade modifiers section

[Zoltan Somogyi]

It seems that I accidentally sent this to just Julien,
and not the list.

In the absence of an objection by then, in about 24 hours
I intend to proceed with the rename using the long names below.

Zoltan.

----- Start Forwarded Message -----
Sent: Sat, 09 Aug 2025 09:51:15 +0200 (CEST)
From: "Zoltan Somogyi" <zoltan.somogyi at runbox.com>
To: "Julien Fischer" <juliensf at gmail.com>
Subject: Re: [m-rev.] for post-commit review: fill in most of the grade
 modifiers section



On Sat, 9 Aug 2025 16:25:31 +1000, Julien Fischer <juliensf at gmail.com> wrote:
> On Fri, 8 Aug 2025 at 18:47, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:
> > I followed all your suggestions, though without an install, I cannot
> > easily check that the xrefs to the reference manual work as intended,
> > and I don't think installing the user guide on mercurylang.org just now
> > would be wise :-(
> 
> Someone should have explained that to the ROTD builds ;-)

Sorry, I thought you installed the manuals manually :-(

> The cross document xrefs look fine in the HTML version of the docs that
> were installed last night. The PDF versions are broken.
> 
> The PDF version of the user's guide has the following link to the
> reference manual
> 
>     https://mercurylang.org/information/doc-latest/mercury_ref.pdf
> 
> whereas the actual link should be:
> 
>     https://mercurylang.org/information/doc-latest/reference_manual.pdf

Based on what I see at

https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Four-and-Five-Arguments.html

I don't think this *can* be fixed with our current setup.

The fourth argument of @pxref is, according to that page,
the "manual-name". With classical elegance, it fails to even hint
at the answer to the obvious question, the name of *which version*
of the manual?

Our problem is, we do not have anything that could be called
THE manual name, because we have TWO such names:

- mercury_ref, for .html and .info files, and
- reference_manual, for .dvi and .pdf files.

The fourth argument cannot be both at the same time,
and there is no version of @pxref that has more slots
to allow the different versions' names to be specified separately.

This unnecessary difference has always been inelegant, but I believe
it was initially driven by a desire to keep the name short in the .info version.
(The very first commit that added the first draft of the reference manual
by Fergus in 1995 had the file name reference_manual.texi, but had
mercury_ref as its name for the info program.)

The obvious cure is to use the same name for all versions of each manual.
It is also obvious that the names of these manuals should follow the same pattern.
The question is: what should that pattern be:

One name set could be

- mercury_reference_manual
- mercury_user_guide
- mercury_library_manual
- mercury_transition_guide
- mercury_faq

Another could be

- mercury_ref or mercury_refman
- mercury_ug
- mercury_lm, mercury_lib or mercury_library
- mercury_tg
- mercury_faq

I don't like the too-short names that don't give a clue as to what they are short for.
I could go for medium-length names (after the mercury_ prefix, that is),
but I prefer the long, fully-spelled-out names, even if goes against the usual style
of .info files.

Opinions?

> Also, the title pages of the PDF versions seem to have acquired a vim modeline
> comment, which is not ideal.

I just pushed a simple fix for that.

Zoltan.





----- End Forwarded Message -----