Drop groff_filenames(5) document.

It says nothing accurate that is not covered elsewhere.

* contrib/groff_filenames: Delete.
* doc/doc.am (GROFF_MAN_PAGES): Drop.
* src/roff/groff/groff.1.man: Drop cross reference to it.
* NEWS: Add item.

Fixes <https://savannah.gnu.org/bugs/index.php?61818>.
This commit is contained in:
G. Branden Robinson 2022-09-02 18:19:40 -05:00
parent c4dd2772f3
commit ff2e281ed4
8 changed files with 17 additions and 772 deletions

View File

@ -1,3 +1,15 @@
2022-09-02 G. Branden Robinson <g.branden.robinson@gmail.com>
Drop groff_filenames(5) document. It says nothing accurate that
is not covered elsewhere.
* contrib/groff_filenames: Delete.
* doc/doc.am (GROFF_MAN_PAGES): Drop.
* src/roff/groff/groff.1.man: Drop cross reference to it.
* NEWS: Add item.
Fixes <https://savannah.gnu.org/bugs/index.php?61818>.
2022-09-01 G. Branden Robinson <g.branden.robinson@gmail.com>
* src/preproc/tbl/tbl.1.man (Table data): Generalize discussion

View File

@ -619,7 +619,6 @@ include $(top_srcdir)/contrib/glilypond/glilypond.am
include $(top_srcdir)/contrib/gperl/gperl.am
include $(top_srcdir)/contrib/gpinyin/gpinyin.am
include $(top_srcdir)/contrib/grap2graph/grap2graph.am
include $(top_srcdir)/contrib/groff_filenames/groff_filenames.am
include $(top_srcdir)/contrib/hdtbl/hdtbl.am
include $(top_srcdir)/contrib/mm/mm.am
include $(top_srcdir)/contrib/mom/mom.am

4
NEWS
View File

@ -576,6 +576,10 @@ o grog no longer supports the "--warnings" option; the one diagnostic
o The ditroff(7) man page has been deleted. The "History" section of
roff(7) covers the same subject in greater depth.
o The groff_filenames(5) man page has been deleted. It had inaccuracies
and spurious content. The "File name conventions" section of roff(7)
covers the same subject.
VERSION 1.22.4
==============

View File

@ -1,114 +0,0 @@
2020-04-22 G. Branden Robinson <g.branden.robinson@gmail.com>
* groff_filenames.5.man: Delete references to groffer.
2015-08-22 Bernd Warken <groff-bernd.warken-72@web.de>
* groff_filenames.5.man: Use section 5 within this man-page.
2015-08-22 Bernd Warken <groff-bernd.warken-72@web.de>
* groff_filenames.5.man: Rename `groff_filenames.1.man'.
* groff_filenames.am: Include section changing.
2015-08-22 Bernd Warken <groff-bernd.warken-72@web.de>
* groff_filenames.1.man: Rename `groff_filenames.man'.
* groff_filenames.am: Include renaming.
2015-08-05 Bernd Warken <groff-bernd.warken-72@web.de>
* groff_filenames.am: Add `Last update'. Setup Emacs mode.
2015-04-03 Werner LEMBERG <wl@gnu.org>
* groff_filenames.man: Make it work in compatibility mode.
2014-09-03 Bernd Warken <groff-bernd.warken-72@web.de>
* groff_filenames.man, Makefile.sub: Repair copying and Emacs
setup.
2014-08-31 Bernd Warken <groff-bernd.warken-72@web.de>
* groff_filenames.man: Replace Heirloom links to more actual
places. Create macro definitions for authors and copying.
2014-08-30 Bernd Warken <groff-bernd.warken-72@web.de>
* groff_filenames.man: Add extension `.1b' for `heirloom'
man-pages.
2014-07-06 Bernd Warken <groff-bernd.warken-72@web.de>
* groff_filenames.man: Make it compatible to doclifter.
2014-07-04 Bernd Warken <groff-bernd.warken-72@web.de>
* groff_filenames.man: Transform to classical man-page style.
2014-01-06 Bernd Warken <groff-bernd.warken-72@web.de>
* Makefile.sub: fix this file
2014-01-05 Bernd Warken <groff-bernd.warken-72@web.de>
* runoff.man: remove this file
* groff/contrib/RUNOFF: rename this directory to
`groff/contrib/groff_filenames'
* Makefile.sub: change this file correspondingly
2013-07-31 Bernd Warken <groff-bernd.warken-72@web.de>
Fix RUNOFF
2013-06-17 Bernd Warken <groff-bernd.warken-72@web.de>
Remove files *~
2013-06-17 Bernd Warken <groff-bernd.warken-72@web.de>
* groff_filenames.man: Corrections.
2013-06-17 Bernd Warken <groff-bernd.warken-72@web.de>
* groff_filenames.man: Extension.
2013-05-14 Bernd Warken <groff-bernd.warken-72@web.de>
* runoff.man: Major rewrite, due to good documentation of 1974,
especially for text lines.
2013-05-05 Bernd Warken <groff-bernd.warken-72@web.de>
New `groff' project: `RUNOFF', which is the predecessor of `roff'.
* ChangeLog: New file for the `contrib' source.
* Makefile.sub: New `make' file, so far only for 2 man-files.
* runoff.man: New file which documents the `RUNOFF' language from
the 1960s up to the 1980s.
* groff_filenames.man: New file about the file name extensions
since `RUNOFF'.
########################################################################
Copyright 2013-2020 Free Software Foundation, Inc.
Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved.
Local Variables:
coding: utf-8
fill-column: 72
mode: change-log
version-control: never
End:
vim:set autoindent textwidth=72:

View File

@ -1,619 +0,0 @@
.TH groff_filenames @MAN5EXT@ "@MDATE@" "groff @VERSION@"
.SH Name
groff_filenames \- filename conventions used in roff systems
.
.
.\" ====================================================================
.\" Legal Terms
.\" ====================================================================
.\"
.\" Copyright (C) 2013-2020 Free Software Foundation, Inc.
.\"
.\" This file is part of groff, a free software project. You can
.\" redistribute it and/or modify it under the terms of the GNU General
.\" Public License version 2 (GPL2) as published by the Free Software
.\" Foundation (FSF).
.\"
.\" The license text can be found in the internet at
.\" <http://www.gnu.org/licenses>.
.
.
.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
.do nr *groff_groff_filenames_5_man_C \n[.cp]
.cp 0
.
.
.\" ====================================================================
.SH Description
.\" ====================================================================
.
Since the evolution of
.I roff
in the 1970s, a whole bunch of filename extensions for
.I roff
files were used.
.
.
.P
The
.I roff
extensions refer to preprocessors or macro packages.
.
These extensions are fixed in all
.IR Unix \-like
operating systems.
.
.
.P
Later on,
.B groff
added some more extensions.
.
This
.I man page
is about these filename extensions.
.
.
.\" ====================================================================
.SH "Compression of \f[I]roff\f[] files"
.\" ====================================================================
.
Each
.I roff
file can be optionally
.IR compressed .
.
That means that the
.I total filename
ends with a
.IR "compressor name" .
.
So the whole filename has the structure
.IR <name> . <extension>[ . <compression>] .
.
.
.P
Best-known are the
.I compressor extensions
.BR .Z ,
.BR .gz ,
and
.BR .bzip2 .
.
Relatively new is
.BR .xz .
.
.
.P
From now on, we will ignore the
.I compressions
and only comment the structure
.IB <name> . <extension>\fR.\fP
.
.
.\" ====================================================================
.SH "Man pages"
.\" ====================================================================
.
The
.I Unix manual pages
are widely called
.IR "man pages" .
.
The
.I man page
style is the best-known part of the
.I roff
language.
.
.
.P
The extensions for
.I man
should be better documented.
.
So this is documented here.
.
.
.P
Files written in the
.I man
language use the following extension:
.BI *. <section>[<group>] \fR.\fP
.
.
.\" ====================================================================
.SS "Man page sections"
.\" ====================================================================
.
The traditional
.I man page <section>
is a digit from
.B 1
to
.BR 8 .
.
.
.TP
.IB <name> .1
.TQ
.IB <name> .2
.TQ
.IB <name> .3
.TQ
.IB <name> .4
.TQ
.IB <name> .5
.TQ
.IB <name> .6
.TQ
.IB <name> .7
.TQ
.IB <name> .8
Classic man page
.IR sections .
.
.
.\" NOTE: There was once a feeble attempt in this direction, but it
.\" hasn't been true in any sense for a long time.
.\"Linux added the section number
.\".B 9
.\"for kernel man pages.
.\".
.\".
.\".TP
.\".IB <name> .9
.\".I Linux
.\"kernel man pages
.\".
.\".
.P
In older commercial
.I Unix
systems, the 3 characters
.BR l ,
.BR n ,
and
.B o
were also used as
.I section
names.
.
This is today
.IR deprecated ,
but there are still documents in this format.
.
.
.TP
.IB <name> .l
.TQ
.IB <name> .n
.TQ
.IB <name> .o
.I Deprecated
man page sections, which stood for \[lq]local\[rq], \[lq]new\[rq], and
\[lq]old\[rq], respectively.
.
.
.\" ====================================================================
.SS "Man page group extensions"
.\" ====================================================================
.
The
.I <group>
extension in
.BI . <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.,
.B x
for
X Window System
documents or
.B tcl
to refer to the
.I Tcl
programming language.
.
.
.P
Examples:
.
.
.TP
.B groff.1
is the man page for
.B groff
in
.I section
.B 1
without a
.I group
.
.
.TP
.B xargs.1posix.gz
is the man page for the program
.B xargs
in
.I section
.B 1
and
.I group
.BR posix ;
moreover it is
.I compressed
with
.B gz
.RB ( gzip ).
.
.
.TP
.B config.5ssl
.I "OpenSSL CONF"
library configuration files from
.I section
.B 5
with
.I group
.BR ssl .
.
.
.TP
.B dpkg\-reconfigure.8cdebconf
man page for the program
.B dpkg\-reconfigure
in
.I section
.B 8
and
.I group
.BR cdebconf .
.
.
.\" ====================================================================
.SS "Source of man pages"
.\" ====================================================================
.
There are 2
.I roff
languages for writing man pages:
.B man
and
.BR mdoc .
.
.
.P
The names of these 2 styles are taken as
.I extensions
for the source code files of man pages in the
.I groff
package.
.
.
.TP
.IB <name> .man
.I traditional
Unix-like man page format within groff source files.
.
.
.TP
.IB <name> . n
A temporary man page file produced from a
.IB name .man
man page by a run of
.B make
within the
.B groff
source package.
.
.
.TP
.IB <name> .mdoc
Man page format in BSD.
.
.
.\" ====================================================================
.SH "Traditional \f[I]troff\f[] extensions"
.\" ====================================================================
.
.\" ====================================================================
.SS "Files using macro packages"
.\" ====================================================================
.
The
.I "classical roff"
languages were interpreted by the traditional
.B "troff"
and
.B "nroff"
programs.
.
.
.P
The
.I roff
language has been extended by a variety of macro packages,
each producing a sort of dialect of the common language.
.
Documents written using such packages tend to bear a characteristic
file name extension.
.
.
.TP
.IB <name> .me
.I roff
file using the
.B me
.IR "macro package" .
.
.
.TP
.IB <name> .mm
.I roff
file using the
.B mm
.I macro package
.
.
.TP
.IB <name> .ms
.I roff
file using the
.B ms
.I macro package
.
.
.P
All of these classical
.I roff
languages and their extensions are still very active in
.BR groff .
.
.
.\" ====================================================================
.SS "Source code for macro packages (\f[I]tmac\f[] files)"
.\" ====================================================================
.
In traditional
.I roff
the source code for the macro packages was stored in
.I TMAC
files.
.
Their file names have the form:
.
.
.TP
.BI tmac. <package> \fR,\fP
.I <package>
is the name of the macro package without the leading
.B m
character, which is reintegrated by the option
.BR \-m .
.
.
.P
For example,
.B tmac.an
is the source for the
.B man
macro package.
.
.
.P
In the
.B groff
source, more suitable file names were integrated; see later on.
.
.
.\" ====================================================================
.SS Preprocessors
.\" ====================================================================
.
Moreover, the following
.I preprocessors
were used as filename extension:
.
.
.TP
.IB <name> .chem
for the integration of chemical formulas
.
.
.TP
.IB <name> .eqn
for the mathematical use of equations
.
.
.TP
.IB <name> .pic
graphical tool
.
.
.TP
.IB <name> .tbl
for tables with
.I tbl
.
.
.TP
.IB <name> .ref
for files using the
.B prefer
.I preprocessor
.
.
.\" ====================================================================
.SS "\f[I]roff\f[] files"
.\" ====================================================================
.
.TP
.IB <name> .t
.TQ
.IB <name> .tr
for files using the
.I roff
language of any kind
.
.
.\" ====================================================================
.SH "New \f[I]groff\f[] extensions"
.\" ====================================================================
.
.I "GNU roff"
.B groff
is the actual
.I roff
standard, both for classical
.I roff
and new extensions.
.
So even the used new extensions in the source code should be regarded
as actual standard.
.
The following extensions are used instead of classical
.B .t
or
.BR .tr :
.
.
.TP
.IB <name> .groff
.TQ
.IB <name> .roff
general ending for files using the
.I groff language
.
.
.\" ====================================================================
.SS "Source code for macro packages (\f[I]tmac\f[] files)"
.\" ====================================================================
.
As the classical form
.BI tmac. <package_without_m> \fR,\fP
of the
.I TMAC
file names is quite strange,
.
.I groff
added the following structures:
.
.
.TP
.IB <package_without_m> .tmac
.TQ
.BI m <package> .tmac
.TQ
.BI groff_m <package> .tmac
.
.
.\" ====================================================================
.SS "Files using new macro packages"
.\" ====================================================================
.
.I Groff
uses the following new macro packages:
.
.
.TP
.IB <name> .mmse
file with swedish
.B mm
.I macros
for
.B groff
.
.
.TP
.IB <name> .mom
files written in the
.I "groff macro package"
.B mom
.
.
.TP
.IB <name> .www
files written in HTML-like
.I groff
.IR macros .
.
.
.\" ====================================================================
.SS "Preprocessors and postprocessors"
.\" ====================================================================
.
.TP
.IB <name> .hdtbl
Heidelberger tables, an alternative to the preprocessor
.IR tbl .
.
See
.MR groff_hdtbl @MAN7EXT@ .
.
.
.TP
.IB <name> .grap
files written for the graphical
.B grap
processor.
.
.
.TP
.IB <name> .grn
for including
.MR gremlin @MAN1EXT@ ,
pictures, see
.MR grn @MAN1EXT@ .
.
.
.TP
.IB <name> .pdfroff
transform this file with
.B pdfroff
of the
.I groff
system
.
.
.\" ====================================================================
.SH Authors
.\" ====================================================================
.
This document was written by
.MT groff\-bernd\:.warken\-72@\:web\:.de
Bernd Warken
.ME .
.
.
.\" ====================================================================
.SH "See also"
.\" ====================================================================
.
.
.TP
History and future
.MR roff @MAN7EXT@ ,
.MR man\-pages 7 ,
.MR groff_diff @MAN7EXT@ ,
.MR groff @MAN7EXT@
.
.
.TP
.I Compression
.MR uncompress 1posix ,
.MR gzip2 1 ,
.MR bzip2 1 ,
.MR xz 1
.
.
.\" Restore compatibility mode (for, e.g., Solaris 10/11).
.cp \n[*groff_groff_filenames_5_man_C]
.do rr *groff_groff_filenames_5_man_C
.
.
.\" Local Variables:
.\" fill-column: 72
.\" mode: nroff
.\" End:
.\" vim: set filetype=groff textwidth=72:

View File

@ -1,35 +0,0 @@
# Automake rules for 'groff_filenames'
# Copyright (C) 2013-2020 Free Software Foundation, Inc.
# Written by Bernd Warken <groff-bernd.warken-72@web.de>.
# Automake migration by Bertrand Garrigues
# This file is part of 'groff'.
# 'groff' is free software; you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 2 of the License, or
# (at your option) any later version.
# 'groff' is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# General Public License for more details.
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
########################################################################
man5_MANS += contrib/groff_filenames/groff_filenames.5
EXTRA_DIST += \
contrib/groff_filenames/ChangeLog \
contrib/groff_filenames/groff_filenames.5.man
# Local Variables:
# mode: makefile-automake
# fill-column: 72
# End:
# vim: set autoindent filetype=automake textwidth=72:

View File

@ -214,7 +214,6 @@ GROFF_MAN_PAGES1 = \
src/utils/tfmtodit/tfmtodit.1 \
src/roff/troff/troff.1 \
$(XTOTROFF_MAN1) \
contrib/groff_filenames/groff_filenames.5 \
man/groff_font.5 \
man/groff_out.5 \
man/groff_tmac.5 \

View File

@ -2166,7 +2166,7 @@ manual.
You can browse it interactively with \[lq]info groff\[rq].
.
.
.\" groff ships 61 man pages generated from 60 source files. The
.\" groff ships 60 man pages generated from 59 source files. The
.\" numbered comments refer to their sorting order in the source tree,
.\" so that it is easier to tell that we've enumerated all of them.
.TP
@ -2230,7 +2230,6 @@ and GNU extensions:
.MR groff @MAN7EXT@ , \" #17
.MR groff_char @MAN7EXT@ , \" #18
.MR groff_diff @MAN7EXT@ , \" #19
.MR groff_filenames @MAN5EXT@ , \" #8
.MR groff_font @MAN5EXT@ , \" #20
.MR groff_tmac @MAN5EXT@ \" #22
.