[m-rev.] for post-commit review: update the file name conventions chapter in the user guide

[Julien Fischer]

On Tue, 15 Jul 2025 at 06:53, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:

> Update the user guide's "file naming conventions" chapter.
>
> Comment out the documentation of .lpic_o files, since we have
> not supported them since 2016.
>
> Document .int* files a bit better.
>
> Document the role of .mh and .mih files.
>
> Use both headings and itemize scopes to make it easier to see
> where each file extension is documented.
>
> Move index entries to just before the text they apply to.
>
> diff --git a/doc/user_guide.texi b/doc/user_guide.texi
> index 83d42d178..18725825d 100644
> --- a/doc/user_guide.texi
> +++ b/doc/user_guide.texi
> @@ -171,84 +171,195 @@ Each Mercury source file should contain a single Mercury module
>  whose module name should be (although it does not have to be)
>  the same as the filename without the @samp{.m} extension.
>
> + at findex --use-subdirs
>  The Mercury implementation uses a variety of intermediate files,
>  which are described below.
>  But all you really need to know is how to name source files.
>  For historical reasons, the default behaviour
>  is for intermediate files to be created in the current directory,
>  but if you use the @samp{--use-subdirs} option to @samp{mmc} or @samp{mmake},
> - at findex --use-subdirs
>  all these intermediate files will be created in a @file{Mercury} subdirectory,
>  where you can happily ignore them.

It may be worth pointing out that --use-subdirs is enable by default
if you are using --make.

...

 + at itemize
> +
> + at item
>  @findex --make-short-interface
> - at findex --make-priv-interface
> + at findex --make-short-int
> + at file{.int3} files are created by invoking @samp{mmc} with the
> + at samp{--make-short-interface} (or @samp{--make-short-int}) option.
> +Roughly, tThey contain basic information about the entities

s/tThey/they/

> +defined in the interface section of the module,
> +and exported from the module to all other modules importing this one.
> +Their purpose is to provide the information needed
> +for the generation of the other kinds of interface files below.
> +
> + at item

...

 + at itemize
> + at item
>  Files ending in @file{.dep} are automatically generated Makefile fragments
>  which contain the rules for an entire program.
> + at item
>  Files ending in @file{.dv} are automatically generated Makefile fragments
>  which contain variable definitions for an entire program.
> + at item
> +Files ending in @file{.d} are automatically generated Makefile fragments
> +which contain the dependencies for a module.
> + at end itemize
> +
> + at file{.dep} and @file{.dv} files are built
> +as part of the initial setup of the program,
> +when @samp{mmc} is invoked with @samp{--generate-dependencies}
> +(or some related options).
> + at file{.d} files contain information about a single module,
> +and they are updated (if needed) by every recompilation of that module.
> +
> + at heading Files generated when targeting C
> +
> + at itemize
> +
> + at item
> + at file{.c} files are C source code.
> +
> + at item
> + at file{.o} files are object code.

or .obj files if you are using MSVC.

The rest looks fine.

Julien.