[illumos-Developer] [REVIEW] 243 system manual pages should live with the software
Richard Lowe
richlowe at richlowe.net
Wed Mar 2 20:15:18 PST 2011
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
More information about the Developer
mailing list