CKMAN(8)                                                              CKMAN(8)



NAME
       ckman - check manual pages for required local site policy

SYNOPSIS
       ckman [xapply-options] pages
       ckman -- -V
       ckman -- -h


DESCRIPTION
       Local  manual  pages have required markup and format rules, which allow
       automation to format, install, and deinstall them.  They also have spe-
       cific groff(1) macros and formatting restrictions. Ckman checks most of
       these rules for the listed pages.

RULES
       Each page must be a plain file.
              That seems clear enough.

       The mk(1l) processor must find the marker Install
              The resulting command should copy the source file to the correct
              location  in  the  man(1) structure.  Ckman only checks that the
              tail of the command matches /[.][1-9][a-zA-Z]*$/.  The  matching
              digit is taken as the current section for the manual page.

       The mk processor must find the marker Deinstall
              The  resulting  command  should  remove the source and cat files
              from the Install location in the  man  structure.  The  expected
              glob pattern matches "/man/[cm]a[tn]section/page.section[a-z]*",
              where section is the single digit section number.  All the  sec-
              tion  numbers  in  both  mk  commands  should  match,  but  some
              allowance is made for the migration of pages between sections by
              matching  a  character  class  like  "[18]" for the Deinstall of
              pages that were previously under the wrong section.

       Option formatting.
              Any dash linked to a bold option letter  must  itself  be  bold.
              Spaces  between  options  and  there  specification must be non-
              breaking.  i.e. a backslashed tilde (\~).  We also look for pos-
              sibly  broken  font markup (matching /\f[^PBRIU(1-9]/).  Leading
              dashes should be long (as \-).

       We must find a .TH header.
              That header must include the name  of  the  page  (matching  the
              basename  of  the page), a section number (matching the one pro-
              vided by mk).  It may have additional parameters.  For example:
                   .TH NAME 8 LOCAL

       The next line must be a .SH header for NAME
              This provide the whatis(1) entry for the page.

       The next line is the whatis line.
              The name of the program followed by a single unquoted  dash  (-)
              followed by a short description.  For example:
                   mk - detect and execute shell commands in files
              No  backslash  markup  is allowed, as whatis will not remove it.
              Note that makewhatis inserts any section specification, based on
              the section under which it found the page.

       The next line is a .SH for either SYNOPSIS or DESCRIPTION
              A synopsis for shell commands that shows the command-line usage,
              or a description for informational pages.

       The next line must be a macro definition of PN, a default program name.
              The macro PN should be defined as:
                   .ds PN "basename
              Where basename is the common name for the  program.   References
              to  the  canonical  name  of  the  program  should  be  given as
              \fI\*(PN\fP (the upper-case version may be  spelled  literally).
              This  is  italic  because  the  name  of a program is actually a
              parameter, which does not have to match the name in the filesys-
              tem.

       Internal references to other manual pages are in bold font.
              Any reference to another manual page should be rendered by page-
              name (page) and section (section)  as  below.   It  is  best  to
              assure that the first reference notes the section.
                   \fBpage\fP(section)
              Later  references  may elide the parenthesized section.  To pre-
              vent ckman from mistaking a bold word for a manual  page  refer-
              ence  add a zero-length character after the font change to bold,
              as:
                   Remember to \fB\&never\fP run this program as the superuser!

       Empty sections are flagged as errors.
              These usually indicate that a template manual page was not  com-
              pletely finished.

       The SEE ALSO section name must be in double quotes.
              Some macro package versions for groff's man macros require this.

       Each entry in the SEE ALSO section may be separated with  commas.   The
       bare  words  "and" and "or" are removed from the list, to allow entries
       like "tar(1) or cpio(1)".  Each remaining entry is compared against the
       present  whatis  database.   Entries  presently missing from whatis are
       reported.


OPTIONS
       To force an option to ckman itself one must prefix the options  with  a
       double-dash (--), as in the usage above.

       -h
              Output only a brief help message.

       -V
              Output only the version information for ckman itself.

       [-Pjobs] [-dfmnxz] [-N else]
              These are all xapply(1l) options that might be useful to pass on
              to ckman.

EXAMPLES
       ckman *.man
              Check all the manual page source files in the current directory.

       find . -name man -print |ckman -mP6 -f - |${PAGER:-less}
              Check all the manual pages below the current working directory 6
              at a time, send the report to my pager.

       ckman -- -V
              Output only the version of ckman.

       ckman -n ckman.man | ${PAGER:-less}
              Output the shell code to check the manual page for this program.
              This  depend  on  the  xapply  to output the script after it has
              expanded the percent markup.

BUGS
       Doesn't check everything it could: for example I think the command-line
       options should always be listed in alphabetical order, but I didn't add
       ckman check that, yet.

       Finds a non-bug in this manual page, because there in an explicit regu-
       lar expression that looks like font markup.


AUTHOR
       KS Braunsdorf
       NonPlayer Character Guild
       mkcat at ksb dot npcGuild.org

SEE ALSO
       sh(1), mk(1l), manstyle(1l), makewhatis(1), groff(1) or nroff(1)



                                     LOCAL                            CKMAN(8)

NAME | SYNOPSIS | DESCRIPTION | RULES | OPTIONS | EXAMPLES | BUGS | AUTHOR | SEE ALSO