[illumos-Developer] [REVIEW] 243 system manual pages should live with the software

[Richard Lowe]

Hey all,

I'd like code review for:
   243 system manual pages should live with the software
webrev:
   http://richlowe.net/webrevs/il_243

This webrev contains the new Makefiles, and the adjustments made to packaging
metadata.  It does not contain the manual pages (they make the webrev utterly
enormous).

There are source trees available:

  mercurial: http://bitbucket.org/richlowe/illumos-man
  git      : http://github.com/richlowe/illumos-gate (the 'sys-manual' branch)

These are synced every few hours from my workspace.

- Contents

   Manual pages were obtained from the last manual tarball Sun provided[1].  I
   have a branch (currently private) based on pages from the last package Sun
   provided under the terms of the CDDL (the system/manual from build 134),
   but I'm unsure of its propriety.

   I have made changes to the manual pages only to the extent that I removed
   the "Availability" portion of the Attributes table (since it is incorrect,
   and distro-specific), and the table in general if Availability was the only
   entry.  I did this in this wad because it seemed obvious that doing
   _eventually_ was correct, and it was easier to do now.  I can undo this if
   desired.

   There is one manual page, beadm, which is not from the man tarball, but
   derived from the copy that used to be in the slim_install gate.  I have
   translated this to roff.

   The other change I plan to make to manual content is to reformat them to
   fit in 80 columns where possible.  Sun's manual pages are in a separate
   source format and are converted to roff (amongst other) formats.  The
   conversion to roff has each paragraph as one long line, unsuitable for
   editing with traditional text editors.

   I have written a small script, given it a silly name, and made it available
   here: https://gist.github.com/845888

   This is the script I plan to run over the pages as the last thing I do in
   the workspace (to avoid unnecessary pain for me in any future merges,
   backouts, or other changes pre-flight).  The script preserves comments,
   commands, and blank lines verbatim, and preserves certain known "verbatim
   blocks", only textual lines are reflowed.  In my testing (diffs of nroff
   output from before-and-after copies) this works well, as far as I can tell
   only causing differences where line breaks happen to trigger roff's double
   spacing.  If you wish to review "after" copies run the script against the
   manual pages of your choice (it is not general, it is likely only to
   produce sane output when run against pages using the same subset of roff
   and -man as 'pkg:/system/manual'.

- Packaging

   I have packaged the manual pages with the software which they describe,
   under the IPS facet 'doc.man'.  This matches the general IPS-ish approach,
   and is something Albert seemed ok with for OI.

   People not using packaging at all obviously have no need to care about
   packaging at all.

   People using a format other than IPS can easily strip out manual pages by
   looking for 'facet.doc.man=true', and deliver them to a separate package
   (or packages) as they desire.

   grep 'facet.doc.man=true'    packages.i386/SUNWcs.mog > SUNWcs-man.mf
   grep -v 'facet.doc.man=true' packages.i386/SUNWcs.mog > SUNWcs-sparse.mf

   .. then process the manifests as before (I'm presuming that pre-processed
   manifests are used as input, otherwise there'd be no ownership and
   permission information).  I can't think of an easier way to pull them back
   out than having a specific tag that will only be applied to manual pages.

   This gives us, I think, the most flexibility.

   Certain packages (those that have historically been dumping grounds) have
   their manual pages broken out into included files by section, to keep
   things manageable (most notably, system/library).  With luck, the desire in
   various quarters to split, especially, SUNWcs, system/library and
   system/kernel will allow this to be consumed into the newer, more
   reasonable, packages.

- I created a new section

  In doing this, I found that /usr/has/man/man1 shadowing parts of
  /usr/share/man/man1 was particularly annoying.  I broke the /usr/has stuff
  out into a new (1HAS)

- Source location

  I put them in usr/src/man, and then a normal man hierarchy.  It seems a
  natural place, and has the desirable property that 'man -M $SRC/man' is a
  convenient way to preview pages.

  Scattering them throughout the tree is something I considered, but initial
  attempts taking that approach didn't pan out well.

  I have not moved existing manual pages (SUNWonbld, tcpd, pppd) into this
  location, but would be willing to.

- SPARC

  I don't have one, and so can't make sure that anything that involve
  sparc-specifics works.  If someone does, could they please pull from either
  of the workspaces mentioned at the top of this email, try, and let me or
  the list whether it works or not.

- Things I don't care about

   - Updates for changes made in Illumos, or since this content

     These are all separate bugs, It is unreasonable to expect me to update
     all our documentation.

   - "I prefer a different macro set"

     I'm sure we all do, but 4,000 existing manual pages can't be wrong.

   - "I don't like roff and would prefer another source format"

     See above.

-- Rich

[1] http://dlc.sun.com/osol/man/downloads