SNAFU in System V Release 2 manuals

[wayne at ORVILLE-EC.ARPA]

From:  Wayne Hathaway <wayne at ORVILLE-EC.ARPA>

We just discovered an interesting "feature" -- no, it's not
documented, so it must still be a bug -- in the System V
Release 2 manuals.

It seems that for manual pages with more than one "NAME"
(such as "brk(2)"), the Release 2 permuted index includes
only the FIRST name, neatly removing all others.  Note that
this means the other names are never permuted into the key
position, so THEY NEVER SHOW UP!  (Emphasis added, after a
co-worker spent a not insignificant amount of time trying to
find "tzset"!)  And this is strictly a Release 2 phenomenon;
the System V Release 1 manuals are fine.

My guess at the origin of this anomaly is that somebody
decided that having all names in every index entry was bad;
it clutters the index and it shortens the amount of descrip-
tion which will fit.  Given this, an obvious approach is to
concatenate the first name with the description (the text
following the hyphen) and process it, then concatenate the
second name with the description and process it, and so
forth for all names.  A (possibly) good idea, but the imple-
mentation of it seems to have forgotten all about steps 2
through n ...  (In fact, this would NOT seem very good,
since it would include every word in every description once
for every name, definitely more cluttery than before.)

Anyway, to put it nicely, this substantially decreases the
utility of the manual (except possibly for REAL wizards, who
already have the manual "organization" memorized).  It would
now seem that AT&T owes everybody one (or more) of the fol-
lowing:

  1) Replacement permuted indexes for all manuals.

  2) Fixed source to the index generator program.

  3) Apologies.


Wayne Hathaway  (wayne at AMELIA.ARPA)



      ****************************************************
      ****                                            ****
      ****           UNIX System V Release 2          ****
      ****                                            ****
      ****     From now on, consider it stranded!     ****
      ****                                            ****
      ****************************************************


-- UNIX is a trade secret of AT&T