How to make "man" pages

[Giorgos Keramidas]

On Mon, 12 Apr 2010 16:49:04 +0800, Fbsd1 <fbsd1 at a1poweruser.com> wrote:
> For the questions list archives:
> I wrote an How To  Creating a manpage from scratch.
>
> You can read it here.
>
> http://www.daemonforums.org/showthread.php?t=4602
>
> Thanks to all the people who replied to my post.

Nice post.  This is exactly the sort of post that raises the signal to
noise ratio in web-based forums.  Good job writing it :-)

You should probably try to grok some of the semantic markup requests
like .Op too though.  For example this part:

: SYNOPSIS
:      jail [-dhi] [-J jid_file] [-l -u username | -U username] [-c | -m]
:      jail [-hi] [-n jailname] [-J jid_file] [-s securelevel]
:           [-l -u username | -U username] [path hostname [ip[,..]]

Is commonly written in several lines.  If you try to read each line
separately they do make sense, e.g.:

    .Nm
    .Op Fl dhi

Will render as:

    jail [-dhl]

with the flag letters displayed in bold text.

The .Op macro wraps everything in [...] brackets.

The .Fl macro marks up 'command flags'.

It takes a bit of practice to write manpages using this sort of markup,
but the displayed output looks great in ascii, PostScript or HTML output
modes.  So it's worth trying to learn more about it.