Nested lists in man page

manroff

I have a command line parameter that takes a number of flags afterwards, which I would like to have as a list inside the parameter list in the man page.

Currently I am simply making lines of Flag - Description (man page), but this is not ideal for the following reasons:

Doesn't indent wrapped lines. I can manually indent them but then I have to assume a set console width, which I don't want to do
Have to rely on double newlines to go to the next line, I'd rather have something like .TP.

Best Answer

Start the list with .RS, end with .RE.
Start list items with .IP followed by term. Enclose the term in double quotes if contains multiple words.
Put the description text in the next line after the list item start.
Is nestable, so the description may contain further lists.
Use \fB..\fP for bolding the term instead of .B. (Same for underline – use \fI..\fP instead of .I.)

.RS
.IP \fBA\fP
\- Flag 1
.IP \fBB\fP
\- Flag 2
.IP \fBC\fP
\- A slightly longer flag description that could take up more than the width
of the average console. In fact you'd need a very wide console to read all
this.
.RE

To increase your productivity I suggest to write your man pages in a friendlier format then convert them. Some suitable tools are enumerated in Can I create a man page for a script?.

Related Solutions

Man Pages – How to Dump a Man Page

First of all, the man files are usually just gziped text files somewhere in your file system. Since your milage will vary finding them and you probably wanted the processed and formatted version that man gives you instead of the source, you can just dump them with the man tool. By looking at man man, I see that you can change the program used to view man pages with the -P flag like this:

man -P cat command_name

It's also worth nothing that man automatically detects when you pipe it's output instead of viewing it on the screen, so if you are going to process it with something else you can skip straight to that step like so:

man command_name | grep search_string

or to dump TO a file:

man command_name > formatted_man_page.txt

Emacs mode for man pages

How to update the man page in man page mode while editing the roff source:

;;;; MAN / man
(defvar *curr-man* "~/mansv/ls.1")

(defun edman ()
  "edit the current work-in-progress man page"
  (interactive)
  (find-file *curr-man*) )

(defun upman () ; edit: better version of this function below
  "update the current work-in-progress man page"
  (interactive)
  (buffer-menu)
  (revert-buffer)
  (with-temp-buffer
    (progn
      (insert-buffer-substring "*Buffer List*")
      (beginning-of-buffer)
        (let ((man-buffer (format "*Man %s*" *curr-man*)))
          (if (word-search-forward man-buffer (point-max) t) ; t = nil on fail
            (kill-buffer man-buffer) ))
      (man *curr-man*)
      (edman)
      (kill-buffer "*Buffer List*") )))

EDIT

This version of upman is hopefully more stable. Note the introducton of a new global.

(defun upman ()
  "update the current work-in-progress man page"
  (interactive)
  (if (get-buffer *curr-man-file*) (save-buffer))
  (let ((man-buffer (format "*Man %s*" *curr-man*)))
    (if (get-buffer man-buffer) (kill-buffer man-buffer))
    (man *curr-man*)
    (edman) ))

Best Answer

Related Solutions

Man Pages – How to Dump a Man Page

Emacs mode for man pages

Related Question