(In reply to comment #0)
> [forwarded from http://bugs.debian.org/501560]
> 
> "gfortran documentation lacks any kind of info about how to create a module
> .mod file. It should be quite easy to indicate that the standard gcc option -c
> when applied to the to-be-compiled file creates the .mod file along with the .o
> file."
> 
> should -c explain how a .mod file is created?

IMHO, the answer is a resounding 'no.'  Adding such information
would simply add unneeded clutter to the manual, and should be
an insult to anyone that uses Fortran.

Also, the Fortran standard does not require that a .mod be created,
and with -fwhole-file it is entirely possible that gfortran 
can keep the module information in memory while compiling a
program and never emit anything.  In fact, the intrinsic
modules specified in the standard (that gfortran has implemented)
do not exist as files.  These are built on the fly.

Should we also explain to the user that 'fire is hot and water
at room temperature is wet.'?

I think a description does not belong into "man gfortran" (invoke.texi), but maybe into the general text of gfortran.texi.

I think .mod files are not obvious; the standard does not say anything about them, though (almost?) all compilers use them. On the other hand, few people seem to have problems with .mod files.

Intel has for instance the following in their manual:
http://software.intel.com/sites/products/documentation/hpc/compilerpro/en-us/fortran/lin/compiler_f/index.htm
 - and mentions it short as output files:
http://software.intel.com/sites/products/documentation/hpc/compilerpro/en-us/fortran/lin/compiler_f/bldaps_for/common/bldaps_produce_outfiles.htm

IBM mentions them shortly at
http://publib.boulder.ibm.com/infocenter/lnxpcomp/v8v101/index.jsp?topic=/com.ibm.xlf101l.doc/xlfcr/compilgpgms.htm

IMHO there is no need to add this to the -c section of the man page, but I think it should be added as a section in the gfortran info maual, named "Module Files". There it can be stated how -J and related flags work, and how module files are created.

(In reply to comment #2)
> I think .mod files are not obvious; the standard does not say anything about
> them, though (almost?) all compilers use them. On the other hand, few people
> seem to have problems with .mod files.

the current Cray compiler (from cce) does not have modules, the mod info ends up in the .o files.

one thing that could be documented about the gfortran mod files is that they are left untouched if possible. We use that in our makefile to avoid recompilation cascades. This is actually an important feature for developers, since it makes gfortran much faster for development than many of the other compilers.

Furthermore, the fact that left-over mod files from older/newer gfortran compilers leads to user-visible error messages could also be worth documenting (At least state that even though .o, .a and .so files might be 'ABI-compatible' over several versions of the compiler, .mod files a specific to even a minor version of the compiler). 

(In reply to comment #1)
> > should -c explain how a .mod file is created?
> 
> IMHO, the answer is a resounding 'no.'  Adding such information
> would simply add unneeded clutter to the manual, and should be
> an insult to anyone that uses Fortran.

Not documenting the semantics of module files anywhere is a sure way for build tools like Automake to never get decent support for building Fortran.  As it is now, the user needs to fake dependencies manually to make up for this missing information.  (Where to put the information is another question altogether.)

> Also, the Fortran standard does not require that a .mod be created,

The Fortran standard is irrelevant for this question.  Users want 'make clean' to remove cruft that 'make' created, and you don't provide a 'gfortran --clean' to keep information about .mod files under the hood either.

That idea of a --clean is interesting.  I can see where it would be useful to force a recompile of module files.  I am not sure what the actual flag should be. Of course one could use make to do all of this.

(In reply to comment #5)
> (In reply to comment #1)
> > > should -c explain how a .mod file is created?
> > 
> > IMHO, the answer is a resounding 'no.'  Adding such information
> > would simply add unneeded clutter to the manual, and should be
> > an insult to anyone that uses Fortran.
> 
> Not documenting the semantics of module files anywhere is a sure way for build
> tools like Automake to never get decent support for building Fortran.  As it is
> now, the user needs to fake dependencies manually to make up for this missing
> information.  (Where to put the information is another question altogether.)

I don't use automake, so I really don't care what it does or does
not do.

> > Also, the Fortran standard does not require that a .mod be created,
> 
> The Fortran standard is irrelevant for this question.  Users want 'make clean'
> to remove cruft that 'make' created, and you don't provide a 'gfortran --clean'
> to keep information about .mod files under the hood either.
> 

The Fortran standard is the only thing that matters.

'make clean' does the right thing for me.  Of course,
I know how to write a Makefile without depending on
the whim (yes, I wrote whim) of the automake developers.

I do not care particularly about automake and such, but precisely because the Fortran standard does not say a word about module files the user expects to get info about them _for his compiler_ in _his compiler documentation_.

That's why I think we must (yes, I included myself, because I've spent so much time trying to figure out how gfortran module files work) create a documentation section for them. User has the right to know what module files are (not necessarily the internals), when they're created, where they're stored and searched for, and whether they're changed if source code change does not change the module interface.

Any chance of this happening?

(In reply to comment #9)
> Any chance of this happening?

No one who seemed to care about the issue has
stepped up with a patch.  One may then draw
the conclusion of 'no'.

What should we do with this PR?

(In reply to Dominique d'Humieres from comment #11)
> What should we do with this PR?

See my comment #1 and #10.  I think that the PR
should be closed with WONTFIX (because gcc does not
have INDIFFERENCE).

Contributing documentation for gfortran is the
easiest way to get involved with its development.
Yet, none of the individuals, who seem to think
that .mod file creation needs to be document,
have step forward to write the doc.

Since Cray was mentioned, the Cray online documentation says:

[...]
The following files are produced by or accepted by the Cray Fortran compiler:
[...]

modulename.mod
            If the -em option is specified, the compiler writes a
            modulename.mod file for each module; modulename is created by
            taking the name of the module and, if necessary, converting it to
            uppercase. This file contains module information, including any
            contained module procedures.


I consider that an example of a reasonable documentation.

Gfortran generated module files (modulename.mod) are always lower case.
Gfortran creates a .mod file not only for -c, but also for -fsyntax-only,
and apparently always when it is presented a source file which contains
a module statement.  It should not be that difficult to put that into the
documentation.

A downside to having no documentation for .mod files .. 

cmake suppresses the output from make (get % completed) 

gfortran acts on 
.f90 files to produce .o files .. and when needed also the .mod file
but one .o file fails to produce a .mod file  

and cmake then fails because it can't find the .mod file

suspect this is not a problem with gfortran (likely the preprocessor
failed) but IMHO words in the documentation about when gfortran produces
a .mod file would help in debugging. 

Regards, 
Gary Howell

Related to pr82215. Submodules should probably also documented.

Closing from lack of interest from anyone that seemed to care.