Manpages Tips

This page is not talking about "basic" editing, if you want this i advise you to open with an editor the file /usr/share/doc/man-db/examples/manpage.example where you will get almost all you need for editing/creating a manual page. In fact, this page has been created to try to complete it, and like it, to be short.

See also the page SandroTosi/ManPages for more information about tools used to create or edit manpages.

More formatting

If you want a complete list of groff formatting commands, i advise you to read groff(7) manpage. You need to install the groff package to have all the doc about groff in your system.

Writing fixed text

It's very useful for section 2 and 3, in order to write structures or codes. You need to use .nf and .fi the same way you use <pre></pre> in HTML.

.nf
/* The structure with the cookie function pointers.  */
typedef struct
{
  cookie_read_function_t  *read;       /* Read cookie  */
  cookie_write_function_t *write;      /* Write cookie */
  cookie_seek_function_t  *seek;       /* Seek/tell file position */
  cookie_close_function_t *close;      /* Close file */
} cookie_io_functions_t ;
.fi

Override the SS newline protection

By default you can't insert a blank line just after a .SS title. You need to clearly define a new line, even a paragraph won't work. Just use \x'-1' at the begining of the line just after the .SS

.SH "OVERRIDE IT"
.SS "Override a blanks line"
here it fails. I saw sometimes tricky things like :
.SS "Dirty way"
\<space>
like this ? It's dirty, avoid it please
.SS "This how to do it"
\x'-1'It's
.B the correct and recommended way :)

Centered text

Just use .ce <number of lines> to start and .ce 0 so stop it. .ce without parameters centers only the following line.

.ce 100
Centered text, can center up to 100 lines !
.br
Centered text
.br
It will contiinue to be centered until you specify :
.ce 0
No more centered text !!!

Creating tables

Tables are not common in manpages, but can be useful sometimes. It's not really some groff syntax here, it's tbl(1) that manages it. I strongly advise you to read the manpage, it's complete (excepted examples).

Just always remember that cells must be separated with the <tab> character !

Simple table

c c. means that the first row contains 2 columns of centered, and all the lines that follows it have the same format. You can use l and r to justify respectively at left and right. I will always use c here to make things clear.

.TS
allbox;
c c.
Manpage Package
xchat.1 xchat
midid.1 dosemu
.TE

Result :

       +--------+---------+
       |Manpage | Package |
       +--------+---------+
       |xchat.1 |  xchat  |
       +--------+---------+
       |midid.1 | dosemu  |
       +--------+---------+

Simple columns spanning

Let's introduce the s cell formatting. s remember means "span the previous cell into this cell".

.TS
allbox;
c s
c c.
Capital
France  Paris
Italy   Rome
.TE

Result :

       +---------------+
       |   Capital     |
       +-------+-------+
       |France | Paris |
       +-------+-------+
       |Italy  | Rome  |
       +-------+-------+

More complex columns spanning

.TS
allbox;
c s s s s s
c c c c c c
c c c s c c
c c c c c s
c c c c c c.
Spanning (colspan)
One     Two     Three   Four    Five    Six
One     Two     ThreeFour       Five    Six
One     Two     Three   Four    FiveSix
One     Two     Three   Four    Five    Six
.TE

Result :

       +--------------------------------------+
       |         Spanning (colspan)           |
       +----+-----+-------+------+------+-----+
       |One | Two | Three | Four | Five | Six |
       +----+-----+-------+------+------+-----+
       |One | Two |  ThreeFour   | Five | Six |
       +----+-----+-------+------+------+-----+
       |One | Two | Three | Four |  FiveSix   |
       +----+-----+-------+------+------+-----+
       |One | Two | Three | Four | Five | Six |
       +----+-----+-------+------+------+-----+

Row and colums spanning, all together !

• The characters \^ mean that the cell above spans downward.

.TS
allbox;
c s s s s s
c c c c c c
c c c s c c
c s s s s s
c c c c s c
c c c c c c
c c c c c c.
Colspan
One     Two     Three   Four    Five    Six
One     Two     ThreeFour       Five    Six
Rowspan + Colspan
One     Two     Three   FourFive        Six
\^      Two     Three   Four    Five    Six
One     Two     Three   Four    Five    \^      
.TE

Result :

       +--------------------------------------+
       |               Colspan                |
       +----+-----+-------+------+------+-----+
       |One | Two | Three | Four | Five | Six |
       +----+-----+-------+------+------+-----+
       |One | Two |  ThreeFour   | Five | Six |
       +----+-----+--------------+------+-----+
       |          Rowspan + Colspan           |
       +----+-----+-------+-------------+-----+
       |    | Two | Three |  FourFive   | Six |
       |One +-----+-------+------+------+-----+
       |    | Two | Three | Four | Five |     |
       +----+-----+-------+------+------+ Six |
       |One | Two | Three | Four | Five |     |
       +----+-----+-------+------+------+-----+