GNU rm's man page doesn't name chattr as a "See Also" program

[Craig Carey]

A defect in the 'man' reference manual document of the 'rm' program,
is that it does not name the 'chattr' program.

'rm' won't delete files that have some randomized attributes (i.e
the immutable attribute).

Each GNU manual document fails to name other GNU reference documents.

However they seem to reliably centre around the idea of saying that
the 'man pages' are out of date and on checking, there are no
more references in the 'info' documents.

I have never assisted the GNU project with their documentation.

When the Ext3 filesystem software is corrupting the filesystem or
erasing it, then files with random attributes appear.

One file got corrupted in my (data-unsafe) Debian Linux OS.
'rm' would not delete the file and said something like
'operation not permitted'.

GNU/Linux (v2.4.20) guesses at the location of the kernel if it is
stored on an Ext3 filesystem, and a lot of data loss can result. I
can't think of any other OS that guesses and gets it wrong, on where
the OS software is. The time that could be spent learning Linux is
instead spent on getting the filesystem back into shape. It could be
quicker if the 'rm' document said how to delete protected immutable
files that are larger than the filesystem but good enough for the GNU
fsck program. The 'rm' documentation is not good enough at describing
how to delete Debian Linux files.

---

The GNU groff manual is outstanding (a tall poppy) in how it names
so very many other reference manuals.

----------

Here is a copy of a Cygwin version of the GNU 'groff' man page.
Note that large number of references to other man documents.

MANWIDTH=69
--------------------------------------------------------------------------------
| GROFF(1)                                                              GROFF(1)
|
|
|
| NAME
|        groff - front-end for the groff document formatting system
|
| SYNOPSIS
|        groff [-abcegilpstzCEGNRSUVXZ] [-d cs] [-f fam] [-F dir] [-I dir]
|              [-L arg] [-m name] [-M dir] [-n num] [-o list] [-P arg] [-r cn]
|              [-T dev] [-w name] [-W name] [file ...]
|        groff -h | --help
|        groff -v | --version [option ...]
|
|        The  command line is parsed according to the usual GNU convention.  The
|        whitespace between a command line option and its argument is  optional.
|        Options can be grouped behind a single - (minus character).  A filename
|        of - (minus character) denotes the standard input.
|
| DESCRIPTION
|        This document describes the groff program, the main front-end  for  the
|        groff document formatting system.  The groff program and macro suite is
|        the implementation of a roff(7) system within the free software collec-
|        tion  GNU  <http://www.gnu.org>.   The groff system has all features of
|        the classical roff, but adds many extensions.
 ...
|
|
| AUTHORS
|        Copyright (C) 1989, 2002 Free Software Foundation, Inc.
|
|        This document is distributed under the terms of the FDL (GNU Free Docu-
|        mentation License) version 1.1 or later.  You should  have  received  a
|        copy of the FDL on your system, it is also available on-line at the GNU
|        copyleft site <http://www.gnu.org/copyleft/fdl.html>.
|
|        This document is based on the original groff man page written by  James
|        Clark  <address@hidden>.  It was rewritten, enhanced, and put under the
|        FDL license by Bernd Warken <address@hidden>.   It  is  maintained  by
|        Werner Lemberg <address@hidden>.
 ...
|
| SEE ALSO
|        The groff info file contains all information on the groff system within
|        a single document.  Beneath the detailed documentation of all  aspects,
|        it provides examples and background information.  See info(1) on how to
|        read it.
|
|        Due to its complex structure, the groff  system  has  many  man  pages.
|        They can be read with man(1) or groffer(1).
|
|        Introduction, history and further readings:
|               roff(7).
|
|        Viewer for groff files:
|               groffer(1), gxditview(1), xditview(1x).
|
|        Wrapper programs for formatters:
|               groff(1), grog(1).
|
|        Roff preprocessors:
|               eqn(1), grn(1), pic(1), refer(1), soelim(1), tbl(1), grap(1).
|
|        Roff language with the groff extensions:
|               groff(7), groff_char(7), groff_diff(7), groff_font(5).
|
|        Roff formatter programs:
|               nroff(1), troff(1), ditroff(7).
|
|        The intermediate output language:
|               groff_out(7).
|
|        Postprocessors for the output devices:
|               grodvi(1),    grohtml(1),    grolbp(1),   grolj4(1),   grops(1),
|               grotty(1).
|
|        Groff macro packages and macro-specific utilities:
|               groff_tmac(5),   groff_man(7),    groff_mdoc(7),    groff_me(7),
|               groff_mm(7),     groff_mmse(7),    groff_mom(7),    groff_ms(7),
|               groff_www(7), mmroff(7).
|
|        The following utilities are available:
|               addftinfo(1),     afmtodit(1),     eqn2graph(1),     groffer(1),
|               gxditview(1),  hpftodit(1),  indxbib(1), lookbib(1), pfbtops(1),
|               pic2graph(1), tfmtodit(1).
|
|
|
|
| Groff Version 1.18.1             13 July 2002                         GROFF(1)
| (END)
|
--------------------------------------------------------------------------------

The groff reference manual refers to about 48 other reference manuals.

In constrast the 'rm' document refers to 0 other programs, and thus it
does not provide helpful links permitting the name 'chattr' to be
found.

Groff's man page names these (so many!):

  01  addftinfo(1)
  02  afmtodit(1)
  03  ditroff(7)
  04  eqn(1)
  05  eqn2graph(1)
  06  grap(1)
  07  grn(1)
  08  grodvi(1)
  09  groff(1)
  10  groff(7)
  11  groff_char(7)
  12  groff_diff(7)
  13  groff_font(5)
  14  groff_man(7)
  15  groff_mdoc(7)
  16  groff_me(7)
  17  groff_mm(7)
  18  groff_mmse(7)
  19  groff_mom(7)
  20  groff_ms(7)
  21  groff_out(7)
  22  groff_tmac(5)
  23  groff_www(7)
  24  groffer(1)
  25  groffer(1)
  26  groffer(1)
  27  grog(1)
  28  grohtml(1)
  29  grolbp(1)
  30  grolj4(1)
  31  grops(1)
  32  grotty(1).
  33  gxditview(1)
  34  gxditview(1)
  35  hpftodit(1)
  36  indxbib(1)
  37  lookbib(1)
  38  man(1)
  39  mmroff(7)
  40  nroff(1)
  41  pfbtops(1)
  42  pic(1)
  43  pic2graph(1)
  44  refer(1)
  45  roff(7)
  46  soelim(1)
  47  tbl(1)
  48  tfmtodit(1)
  49  troff(1)
  50  xditview(1x)

-------------

FreeBSD 4,7 also has a 'rm' man page that does not name its chflags.
That is not optimal, but in FreeBSD, there are not frequent mishaps
where the software alone randomly resets flags in files, names,
attributes, data and sizes. In FreeBSD, the immutable attribute
basically is only set on, with the very same program that turns it
off.

The fact that 'groff' refers to 'refer', but 'refer' does not refer to
'groff' in the "See Also' section, suggests that the GNU project is
not checking that a reference from A to B, is creating a case for
having document B refer to document A.






G. A. Craig Carey