Good documentations are as important as good lines of code. No one likes to dig up their old code and not understand whatever they wrote years ago. So, writing documentations should be a simple process. And it is!
Linux manpages or manuals are written in something called a troff markdown language. It is not your regular markdown, but uses macros to format text.
In order to preview the manpage file filename, use
man -l filename
The lines in the manpage should start with macros starting with dots. Here are some example macros:
| Command | Description |
|---|---|
| .Dd | date-of-modification |
| .Dt | name-of-the-article 7 (7 for miscellaneous manual. see man man for explanation on the numbering) |
| .Sh | NAME |
| .Nm | name of the article |
| .Nd | description of the article |
.Bd -literal … .Ed block.Em anywhere in your text, it will vanish. Write \&Em
instead.| Macro | Description |
|---|---|
| .Sh | New Section |
| .Ss | New subsection |
| .Bl | begin list. It can take the following parameters: -bullet, -item, -enum, -tag, -hang etc. |
| .It | items inside .Bl and .El |
| .El | end list |
| .Pa | path for a filename |
| .Bd | begin a display block, It takes a few parameters, most importantly -literal which is useful for source codes, spaced and tabbed text. |
| .Dl | literal text of one line |
| .Ed | end display block one line of literal text |
| \fB | begins bold |
| \fI | begins Italian |
| \fR | ends bold and/or Italian |
| .Em | emphasize (a line of bold, similar to \fB ... \fR). If using inside an item of list, use without the dot, e.g. .It Em tagname |
Escape character \e generates a \, \& replaces at the beginning of a sentence, but doesn’t generate a ..
| Type | Output |
|---|---|
| \e | \ |
| \efB | \fB |
| \&. | . |
| \&Em | Em |
See the BSD manpage for mdoc online. (Note: mdoc for Arch is something else)
[link]
There are more things you can do with the manpages, such as adding custom files to a man database.