What's a good way to embed C code into a man page?

duncan21 · 04-21-2007, 01:39 AM

For example, I'm looking to make a man page for the solution to an exercise from K&R about stripping comments from a C source file, and I would like to add a code example and have it show up as bold and offset. Using the .nf macro to insert the code as preformatted text seems pretty inelegant. The code sample I want to embed is in the EXAMPLES section of the man page.

Here's what the man page looks like, and following it is the source file (cstrip.1)

man cstrip

Code:

cstrip(1)                  K&R Programs                 cstrip(1)

NAME
       cstrip - a C-comment stripper

SYNOPSIS
       cstrip [-ahutV] [infile [outfile]]

DESCRIPTION
       cstrip  removes  comments  from  a C or a C++ source file.
       Note that C99 line comments (i.e., comments starting  with
       //)  are  stripped  by default. C89 processing can be done
       using the --ansi flag. Also, note that trigraph processing
       is  not supported by cstrip, and any source file that uses
       the trigraph ??/ will not be processed correctly.

       If infile is not specified, the C file is  read  from  the
       standard  input. If outfile is not specified, the stripped
       C file is written to the standard output.

COPYRIGHT
       cstrip is Copyright (C) 2007 by XXX

OPTIONS
       -a, --ansi
              Parse infile as ANSI C89, instead of the default of
              ISO C99/C++.

       -h, --help
              Print  a help message that briefly describes how to
              use the program.

       -t, --trigraphs
              Enable trigraph processing, which  is  disabled  by
              default.

       -u, --usage
              Prints  a  brief  usage  message and exits success-
              fully.

       -V, --version
              Prints information about the version  of  the  pro-
              gram, as well as license info.

EXAMPLES
       Note  that  using  ANSI C89 vs ISO C99 processing can very
       rarely affect the meaning of the code it is stripping com-
       ments  from. Thus, C89 stripping should never be used on a
       source file intended to  be  compiled  as  C99,  and  vice
       versa.  Consider the following (contrived) example:

            int  x = 8 //* pretty unlikely*/ 2
                   ;

       which, under C89 processing is translated to:

cstrip-1.1                April 19, 2007                        1

cstrip(1)                  K&R Programs                 cstrip(1)

            int  x = 8 /  2
                   ;

       under C99 processing, this example translates to:
            int  x = 8
                   ;

AUTHOR
       XXX <xxx@yyy.com>

SEE ALSO
       cpp(1)

BUGS
        trigraph ??/
              cstrip  will  not correctly strip comments from any
              file that contains the trigraph ??/ in normal  pro-
              gram code (i.e., outside of comments or string lit-
              erals). cpp should instead be used in this case.

cstrip-1.1                April 19, 2007                        2

cstrip.1

Code:

.TH "cstrip" 1 "April 19, 2007" "cstrip-1.1" "K&R Programs"
.SH NAME
cstrip \- a C-comment stripper
.SH SYNOPSIS
.B cstrip [-ahutV] [infile [outfile]]
.SH DESCRIPTION
cstrip removes comments from a C or a C++ source file. Note that C99 line
comments (i.e., comments starting with //) are stripped by default. C89
processing can be done using the --ansi flag. Also, note that trigraph
processing is not supported by cstrip, and any source file that uses the
trigraph ??/ will not be processed correctly.

If infile is not specified, the C file is read from the standard input. If
outfile is not specified, the stripped C file is written to the standard
output.
.SH COPYRIGHT
cstrip is Copyright (C) 2007 by XXX.
.SH OPTIONS
.TP
.B \-a, --ansi
Parse infile as ANSI C89, instead of the default of ISO C99/C++.
.TP
.B \-h, --help
Print a help message that briefly describes how to use the program.
.TP
.B \-t, --trigraphs
Enable trigraph processing, which is disabled by default.
.TP
.B \-u, --usage
Prints a brief usage message and exits successfully.
.TP
.B \-V, --version
Prints information about the version of the program, as well as license info.
.SH EXAMPLES
.PP
Note that using ANSI C89 vs ISO C99 processing can very rarely affect the
meaning of the code it is stripping comments from. Thus, C89 stripping should
never be used on a source file intended to be compiled as C99, and vice versa.
Consider the following (contrived) example:
.nf

     int  x = 8 //* pretty unlikely*/ 2
            ;

.fi
.PP
which, under C89 processing is translated to:
.nf
     int  x = 8 /  2
            ;

.fi
.PP
under C99 processing, this example translates to:
.nf
     int  x = 8
            ;

.fi
.SH AUTHOR
.B XXX    <xxx@yyy.com>
.SH "SEE ALSO"
.BR cpp(1)
.SH BUGS
.TP
.B \ trigraph ??/
cstrip will not correctly strip comments from any file that contains the
trigraph ??/ in normal program code (i.e., outside of comments or string
literals). cpp should instead be used in this case.

I know one part of my man page says I support trigraphs, and another doesn't.

:
I'm working on that.

tronayne · 04-21-2007, 06:38 AM

The way I've always done it is to use left-justified code (at the margin) with tabs for the indents. Here's an example from a man page:

Code:

.IP
.ft CB
.nf
#!/bin/ksh
for file in *.unl
do
        #       get the name without the extension
        name=${file%%.unl}
        #       display what we're doing
        print "Working on ${name}..."
        #       execute dbload with appropriate arguments
        dbload -d bchahold -c ${name}.cmd -l ${name}.err -n 1000
done
.fi
.ft P

Just remember that the text is at the left margin with tabs used only for indenting the code example inside the .nf - .fi pair.