How to make "man" pages

[Giorgos Keramidas]

On Wed, 31 Mar 2010 15:54:25 +0800, Fbsd1 <fbsd1 at a1poweruser.com> wrote:
> OK i want to write a man page from scratch. So lets say i want to use
> /usr/share/man/man2/jail.2.gz as my starting sample. How do I convert
> this .gz file to a plain text file so I can edit it with ee? And how do
> I turn the edited text file back in to a man page .gz file?

The manpage sources are plain text files with text that uses formatting
macros from the groff_mdoc(7) macro collection.  You can find sample
files for the style commonly used by the FreeBSD manpages in your
'/usr/share/examples/mdoc' directory.

    keramida at kobe:/usr/share/examples/mdoc$ ls -ld *[0-9]
    -r--r--r--  1 root  wheel  - 3550 18 Μαρ 01:55 example.1
    -r--r--r--  1 root  wheel  - 7582 18 Μαρ 01:55 example.3
    -r--r--r--  1 root  wheel  - 3302 18 Μαρ 01:55 example.4
    -r--r--r--  1 root  wheel  - 7700 18 Μαρ 01:55 example.9
    keramida at kobe:/usr/share/examples/mdoc$

Installed manpages can be found under '/usr/share/man/man?'.  They are
usually compressed with gzip(1) to save some space, but you can extract
any manpage to a plain text file with gzip or zcat:

    zcat /usr/share/man2/jail.2.gz | more

The source of a manpage commonly uses _many_ formatting macros from the
groff_mdoc(7) collection.  You should probably print a copy of the
'groff_mdoc' manpage and keep it around for reference.  Reading through
this printed copy of the manpage at least once will be useful too, as it
will help you understand how macro options work and you will have a good
idea of what features are available.  Then you will be able to quickly
look in the printed reference copy for the features you need, because
you will know "they are there".