Linux – Do I need to write man pages for C library

freebsdlinuxman

I wrote a small C library for Linux and FreeBSD, and I'm going to write the documentation for it. I tried to learn more about creating man pages and not found the instructions or descriptions of best practices making man pages for libraries. In particular I'm interested in what section to put man pages of the functions? 3? Maybe there good examples or manuals? Create man pages for each function from the library a bad idea?

Best Answer

Manual pages for a library would go in section 3.

For good examples of manual pages, bear in mind that some are written using specific details of groff and/or use specific macros which are not really portable.

There are always some pitfalls in portability of man-pages, since some systems may (or may not) use special features. For instance, in documenting dialog, I have had to keep in mind (and work around) differences in various systems for displaying examples (which are not justified).

Start by reading the relevant sections of man man where it mentions the standard macros, and compare those descriptions for FreeBSD and Linux.

Whether you choose to write one manual page for the library, or separate manual pages for the functions (or groups of functions) depends on how complicated the descriptions of the functions would be:

ncurses has a few hundred functions across several dozen manual pages.
dialog has several dozen functions in one manual page. Others will be sure to show many more examples.

Related Solutions

Man Pages – Full Text Search Guide

By using the command man man we can see that we have two options.

   -k     Equivalent to apropos.

   -K     Search  for  the  specified  string in *all* man pages. Warning:
          this is probably very slow!  It  helps  to  specify  a  section.
          (Just  to  give  a  rough idea, on my machine this takes about a
          minute per 500 man pages.)

This is on a RHEL 5 system

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 – Full Text Search Guide

Emacs mode for man pages

Related Question