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

[Garrett D'Amore]

Casually screening, it looks reasonable, but I would like others to pay
special attention to the "facets".  Also I see that /usr/share/man has a
facet, and /usr/share/man/man2 has a different facet.  How does this
work?  Does the second facet override the first?

Also, how well exercised is the whole facets thing in IPS?  Admittedly,
I've been burned by IPS so many times that I approach the whole thing
with a high degree of skepticism.

	- Garrett

On Wed, 2011-03-02 at 23:15 -0500, Richard Lowe wrote:
> 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
> 
> _______________________________________________
> Developer mailing list
> Developer at lists.illumos.org
> http://lists.illumos.org/m/listinfo/developer