[Groff] new man-page groff-filenames.7 (filename extensions for roff files)

[Bernd Warken]

Hallo groff group,

the filename extensions for files using the roff language are not
documented.  As there are many of these, a kind of standard should be
implemented.  I propose the following description as a man-page
"groff-filenames.7".  The file should go to the source position
"groff/man/groff-filenames.man".

Please tell me if I missed something.

Bernd Warken



########################################################################
groff-filenames.7
########################################################################

Since the evolution of roff in the 1970s, a whole bunch of file name
extensions for roff files were used.  They refer to the roff
preprocessors or macro packages.  These extensions are fixed in all
Unix-like operating systems.

Later on groff added some more extensions.  We will now write a
man-page about these filename extensions.  It should become some type
of standard that can be included in the Emacs nroff-mode or in
programs like "file".


########################################################################
Compression
########################################################################

Each roff file can be optionally compressed.  That means that the
total filename ends with a compressor name.  So the whole filename has
the structure "<name>.<extension>[.<compression>]".

Mostly known are the compressor extensions ".Z", ".gz", and ".bzip2".
Relatively new is ".xz".

>From now on, we will ignore the compressions and only comment the
structure "<name>.<extension>".


########################################################################
Man-pages
########################################################################

The "<extension>" for man-pages has the structure
".<section>[<group>]".

##### sections

The traditional "<section>" is a digit from 1 to 8.

<name>.1
<name>.2
<name>.3
<name>.4
<name>.5
<name>.6
<name>.7
<name>.8
        Classic man-page sections.


Linux added the section number 9 for kernel man-pages.

<name>.9
        Linux kernel man-pages


In older commercial Unix systems, the 3 characters n, o, or l were
also used as section names.  This is today deprecated, but there are
still documents in this format.

<name>.n
<name>.o
<name>.l
        Deprecated old sections.


###### group extensions

The "<group>" extension in ".<section>[<group>]" is optional, but it
can be any string of word characters.  Usually programmers use a group
name that is already used, e.g. "x" for X-window documents or "tk" to
refer to the tk programming language.

Examples:

groff.1           is the man-page for "groff" in section "1" without
                  a group
xargs.1posix.gz   is the man-page for "xargs" in section "1" and group
                  "posix"; moreover it is compressed with "gz".
config.5ssl       OpenSSL CONF library configuration files from
                  section "5" with group "ssl".
dpkg-reconfigure.8cdebconf
                  man-page for "dpkg-reconfigure" in section 8 and
                  group "cdebconf".


##### source of man pages

There are 2 styles for writing man pages: "man" and "mdoc".  These 2
extensions are used in the source code package of groff.

<name>.man     traditional man-page format
<name>.mdoc    additional man-page format
<name>.mandoc  recognizing both man-page formats


########################################################################
Traditional troff extensions
########################################################################


##### macro packages

Traditional troff used the following extensions for the macro package
used in the file:

<name>.me   roff file using the "me" macro package
<name>.mm   roff file using the "mm" macro package
<name>.ms   roff file using the "ms" macro package


##### preprocessors

Moreover the following preprocessors were used as filename extrension:

<name>.chem     for the integration of chemical formulas
<name>.eqn      for the mathematical use of equations
<name>.pic      graphical tool
<name>.tbl      for tables with tbl
<name>.ref      for files using the prefer preprocesor


##### classical roff files

<name>.t
<name>.tr
                for files using the roff language of any kind



########################################################################
New groff extensions
########################################################################

GNU roff groff is the actual roff standard.  So we should add necessary
extensions.  I propose the following instead of ".t" or ".tr":

<name>.groff
<name>.roff
                general ending for files using the "groff" language

<name>.mmse     file with swedish "mm" makros for groff
<name>.mom      files written in the groff macro package "mom"
<name>.www      files written in HTML-like groff macros

<name>.grap     files written for the graphical "grap" processor.
<name>.grn      for including gremlin(1) pictures,


<name>.RUNOFF   for files in the historical "RUNOFF" format of the 1960s