code.delx.au - gnu-emacs/blob - lisp/man.el

   1 ;;; man.el --- browse UNIX manual pages
   2
   3 ;; Copyright (C) 1993, 1994, 1996, 1997 Free Software Foundation, Inc.
   4
   5 ;; Author:              Barry A. Warsaw <bwarsaw@cen.com>
   6 ;; Keywords:            help
   7 ;; Adapted-By:          ESR, pot
   8
   9 ;; This file is part of GNU Emacs.
  10
  11 ;; GNU Emacs is free software; you can redistribute it and/or modify
  12 ;; it under the terms of the GNU General Public License as published by
  13 ;; the Free Software Foundation; either version 2, or (at your option)
  14 ;; any later version.
  15
  16 ;; GNU Emacs is distributed in the hope that it will be useful,
  17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19 ;; GNU General Public License for more details.
  20
  21 ;; You should have received a copy of the GNU General Public License
  22 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
  23 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  24 ;; Boston, MA 02111-1307, USA.
  25
  26 ;;; Commentary:
  27
  28 ;; This code provides a function, `man', with which you can browse
  29 ;; UNIX manual pages.  Formatting is done in background so that you
  30 ;; can continue to use your Emacs while processing is going on.
  31 ;;
  32 ;; The mode also supports hypertext-like following of manual page SEE
  33 ;; ALSO references, and other features.  See below or do `?' in a
  34 ;; manual page buffer for details.
  35
  36 ;; ========== Credits and History ==========
  37 ;; In mid 1991, several people posted some interesting improvements to
  38 ;; man.el from the standard emacs 18.57 distribution.  I liked many of
  39 ;; these, but wanted everything in one single package, so I decided
  40 ;; to incorporate them into a single manual browsing mode.  While
  41 ;; much of the code here has been rewritten, and some features added,
  42 ;; these folks deserve lots of credit for providing the initial
  43 ;; excellent packages on which this one is based.
  44
  45 ;; Nick Duffek <duffek@chaos.cs.brandeis.edu>, posted a very nice
  46 ;; improvement which retrieved and cleaned the manpages in a
  47 ;; background process, and which correctly deciphered such options as
  48 ;; man -k.
  49
  50 ;; Eric Rose <erose@jessica.stanford.edu>, submitted manual.el which
  51 ;; provided a very nice manual browsing mode.
  52
  53 ;; This package was available as `superman.el' from the LCD package
  54 ;; for some time before it was accepted into Emacs 19.  The entry
  55 ;; point and some other names have been changed to make it a drop-in
  56 ;; replacement for the old man.el package.
  57
  58 ;; Francesco Potorti` <pot@cnuce.cnr.it> cleaned it up thoroughly,
  59 ;; making it faster, more robust and more tolerant of different
  60 ;; systems' man idiosyncrasies.
  61
  62 ;; ========== Features ==========
  63 ;; + Runs "man" in the background and pipes the results through a
  64 ;;   series of sed and awk scripts so that all retrieving and cleaning
  65 ;;   is done in the background. The cleaning commands are configurable.
  66 ;; + Syntax is the same as Un*x man
  67 ;; + Functionality is the same as Un*x man, including "man -k" and
  68 ;;   "man <section>", etc.
  69 ;; + Provides a manual browsing mode with keybindings for traversing
  70 ;;   the sections of a manpage, following references in the SEE ALSO
  71 ;;   section, and more.
  72 ;; + Multiple manpages created with the same man command are put into
  73 ;;   a narrowed buffer circular list.
  74
  75 ;; ============= TODO ===========
  76 ;; - Add a command for printing.
  77 ;; - The awk script deletes multiple blank lines.  This behaviour does
  78 ;;   not allow to understand if there was indeed a blank line at the
  79 ;;   end or beginning of a page (after the header, or before the
  80 ;;   footer).  A different algorithm should be used.  It is easy to
  81 ;;   compute how many blank lines there are before and after the page
  82 ;;   headers, and after the page footer.  But it is possible to compute
  83 ;;   the number of blank lines before the page footer by euristhics
  84 ;;   only.  Is it worth doing?
  85 ;; - Allow a user option to mean that all the manpages should go in
  86 ;;   the same buffer, where they can be browsed with M-n and M-p.
  87 ;; - Allow completion on the manpage name when calling man.  This
  88 ;;   requires a reliable list of places where manpages can be found.  The
  89 ;;   drawback would be that if the list is not complete, the user might
  90 ;;   be led to believe that the manpages in the missing directories do
  91 ;;   not exist.
  92
  93 \f
  94 ;;; Code:
  95
  96 (require 'assoc)
  97
  98 ;; vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
  99 ;; empty defvars (keep the compiler quiet)
 100
 101 (defgroup man nil
 102   "Browse UNIX manual pages."
 103   :prefix "Man-"
 104   :group 'help)
 105
 106
 107 (defvar Man-notify)
 108 (defvar Man-current-page)
 109 (defvar Man-page-list)
 110 (defcustom Man-filter-list nil
 111   "*Manpage cleaning filter command phrases.
 112 This variable contains a list of the following form:
 113
 114 '((command-string phrase-string*)*)
 115
 116 Each phrase-string is concatenated onto the command-string to form a
 117 command filter.  The (standard) output (and standard error) of the Un*x
 118 man command is piped through each command filter in the order the
 119 commands appear in the association list.  The final output is placed in
 120 the manpage buffer."
 121   :type '(repeat (list (string :tag "Command String")
 122                        (repeat :inline t
 123                                (string :tag "Phrase String"))))
 124   :group 'man)
 125
 126 (defvar Man-original-frame)
 127 (defvar Man-arguments)
 128 (defvar Man-sections-alist)
 129 (defvar Man-refpages-alist)
 130 (defvar Man-uses-untabify-flag t
 131   "When non-nil use `untabify' instead of Man-untabify-command.")
 132 (defvar Man-page-mode-string)
 133 (defvar Man-sed-script nil
 134   "Script for sed to nuke backspaces and ANSI codes from manpages.")
 135
 136 ;; vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
 137 ;; user variables
 138
 139 (defcustom Man-fontify-manpage-flag t
 140   "*Make up the manpage with fonts."
 141   :type 'boolean
 142   :group 'man)
 143
 144 (defcustom Man-overstrike-face 'bold
 145   "*Face to use when fontifying overstrike."
 146   :type 'face
 147   :group 'man)
 148
 149 (defcustom Man-underline-face 'underline
 150   "*Face to use when fontifying underlining."
 151   :type 'face
 152   :group 'man)
 153
 154 ;; Use the value of the obsolete user option Man-notify, if set.
 155 (defcustom Man-notify-method (if (boundp 'Man-notify) Man-notify 'friendly)
 156   "*Selects the behavior when manpage is ready.
 157 This variable may have one of the following values, where (sf) means
 158 that the frames are switched, so the manpage is displayed in the frame
 159 where the man command was called from:
 160
 161 newframe   -- put the manpage in its own frame (see `Man-frame-parameters')
 162 pushy      -- make the manpage the current buffer in the current window
 163 bully      -- make the manpage the current buffer and only window (sf)
 164 aggressive -- make the manpage the current buffer in the other window (sf)
 165 friendly   -- display manpage in the other window but don't make current (sf)
 166 polite     -- don't display manpage, but prints message and beep when ready
 167 quiet      -- like `polite', but don't beep
 168 meek       -- make no indication that the manpage is ready
 169
 170 Any other value of `Man-notify-method' is equivalent to `meek'."
 171   :type '(radio (const newframe) (const pushy) (const bully)
 172                 (const aggressive) (const friendly)
 173                 (const polite) (const quiet) (const meek))
 174   :group 'man)
 175
 176 (defcustom Man-frame-parameters nil
 177   "*Frame parameter list for creating a new frame for a manual page."
 178   :type 'sexp
 179   :group 'man)
 180
 181 (defcustom Man-downcase-section-letters-flag t
 182   "*Letters in sections are converted to lower case.
 183 Some Un*x man commands can't handle uppercase letters in sections, for
 184 example \"man 2V chmod\", but they are often displayed in the manpage
 185 with the upper case letter.  When this variable is t, the section
 186 letter (e.g., \"2V\") is converted to lowercase (e.g., \"2v\") before
 187 being sent to the man background process."
 188   :type 'boolean
 189   :group 'man)
 190
 191 (defcustom Man-circular-pages-flag t
 192   "*If t, the manpage list is treated as circular for traversal."
 193   :type 'boolean
 194   :group 'man)
 195
 196 (defcustom Man-section-translations-alist
 197   (list
 198    '("3C++" . "3")
 199    ;; Some systems have a real 3x man section, so let's comment this.
 200    ;; '("3X" . "3")                        ; Xlib man pages
 201    '("3X11" . "3")
 202    '("1-UCB" . ""))
 203   "*Association list of bogus sections to real section numbers.
 204 Some manpages (e.g. the Sun C++ 2.1 manpages) have section numbers in
 205 their references which Un*x `man' does not recognize.  This
 206 association list is used to translate those sections, when found, to
 207 the associated section number."
 208   :type '(repeat (cons (string :tag "Bogus Section")
 209                        (string :tag "Real Section")))
 210   :group 'man)
 211
 212 (defvar manual-program "man"
 213   "The name of the program that produces man pages.")
 214
 215 (defvar Man-untabify-command "pr"
 216   "Command used for untabifying.")
 217
 218 (defvar Man-untabify-command-args (list "-t" "-e")
 219   "List of arguments to be passed to Man-untabify-command (which see).")
 220
 221 (defvar Man-sed-command "sed"
 222   "Command used for processing sed scripts.")
 223
 224 (defvar Man-awk-command "awk"
 225   "Command used for processing awk scripts.")
 226
 227 (defvar Man-mode-line-format
 228   '("-"
 229     mode-line-mule-info
 230     mode-line-modified
 231     mode-line-frame-identification
 232     mode-line-buffer-identification "  "
 233     global-mode-string
 234     " " Man-page-mode-string
 235     "  %[(" mode-name mode-line-process minor-mode-alist "%n)%]--"
 236     (line-number-mode "L%l--")
 237     (column-number-mode "C%c--")
 238     (-3 . "%p") "-%-")
 239   "Mode line format for manual mode buffer.")
 240
 241 (defvar Man-mode-map nil
 242   "Keymap for Man mode.")
 243
 244 (defvar Man-mode-hook nil
 245   "Hook run when Man mode is enabled.")
 246
 247 (defvar Man-cooked-hook nil
 248   "Hook run after removing backspaces but before Man-mode processing.")
 249
 250 (defvar Man-name-regexp "[-a-zA-Z0-9_][-a-zA-Z0-9_.]*"
 251   "Regular expression describing the name of a manpage (without section).")
 252
 253 (defvar Man-section-regexp "[0-9][a-zA-Z+]*\\|[LNln]"
 254   "Regular expression describing a manpage section within parentheses.")
 255
 256 (defvar Man-page-header-regexp
 257   (if (and (string-match "-solaris2\\." system-configuration)
 258            (not (string-match "-solaris2\\.[123435]$" system-configuration)))
 259       (concat "^[-A-Za-z0-9_].*[ \t]\\(" Man-name-regexp
 260               "(\\(" Man-section-regexp "\\))\\)$")
 261     (concat "^[ \t]*\\(" Man-name-regexp
 262             "(\\(" Man-section-regexp "\\))\\).*\\1"))
 263   "Regular expression describing the heading of a page.")
 264
 265 (defvar Man-heading-regexp "^\\([A-Z][A-Z ]+\\)$"
 266   "Regular expression describing a manpage heading entry.")
 267
 268 (defvar Man-see-also-regexp "SEE ALSO"
 269   "Regular expression for SEE ALSO heading (or your equivalent).
 270 This regexp should not start with a `^' character.")
 271
 272 (defvar Man-first-heading-regexp "^[ \t]*NAME$\\|^[ \t]*No manual entry fo.*$"
 273   "Regular expression describing first heading on a manpage.
 274 This regular expression should start with a `^' character.")
 275
 276 (defvar Man-reference-regexp
 277   (concat "\\(" Man-name-regexp "\\)(\\(" Man-section-regexp "\\))")
 278   "Regular expression describing a reference in the SEE ALSO section.")
 279
 280 (defvar Man-switches ""
 281   "Switches passed to the man command, as a single string.")
 282
 283 (defvar Man-specified-section-option
 284   (if (string-match "-solaris[0-9.]*$" system-configuration)
 285       "-s"
 286     "")
 287   "Option that indicates a specified a manual section name.")
 288
 289 ;; ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 290 ;; end user variables
 291 \f
 292 ;; other variables and keymap initializations
 293 (make-variable-buffer-local 'Man-sections-alist)
 294 (make-variable-buffer-local 'Man-refpages-alist)
 295 (make-variable-buffer-local 'Man-page-list)
 296 (make-variable-buffer-local 'Man-current-page)
 297 (make-variable-buffer-local 'Man-page-mode-string)
 298 (make-variable-buffer-local 'Man-original-frame)
 299 (make-variable-buffer-local 'Man-arguments)
 300
 301 (setq-default Man-sections-alist nil)
 302 (setq-default Man-refpages-alist nil)
 303 (setq-default Man-page-list nil)
 304 (setq-default Man-current-page 0)
 305 (setq-default Man-page-mode-string "1 of 1")
 306
 307 (defconst Man-sysv-sed-script "\
 308 /\b/ {  s/_\b//g
 309         s/\b_//g
 310         s/o\b+/o/g
 311         s/+\bo/o/g
 312         :ovstrk
 313         s/\\(.\\)\b\\1/\\1/g
 314         t ovstrk
 315         }
 316 /\e\\[[0-9][0-9]*m/ s///g"
 317   "Script for sysV-like sed to nuke backspaces and ANSI codes from manpages.")
 318
 319 (defconst Man-berkeley-sed-script "\
 320 /\b/ {  s/_\b//g\\
 321         s/\b_//g\\
 322         s/o\b+/o/g\\
 323         s/+\bo/o/g\\
 324         :ovstrk\\
 325         s/\\(.\\)\b\\1/\\1/g\\
 326         t ovstrk\\
 327         }\\
 328 /\e\\[[0-9][0-9]*m/ s///g"
 329   "Script for berkeley-like sed to nuke backspaces and ANSI codes from manpages.")
 330
 331 (defvar man-mode-syntax-table
 332   (let ((table (copy-syntax-table (standard-syntax-table))))
 333     (modify-syntax-entry ?. "w" table)
 334     (modify-syntax-entry ?_ "w" table)
 335     table)
 336   "Syntax table used in Man mode buffers.")
 337
 338 (if Man-mode-map
 339     nil
 340   (setq Man-mode-map (make-keymap))
 341   (suppress-keymap Man-mode-map)
 342   (define-key Man-mode-map " "    'scroll-up)
 343   (define-key Man-mode-map "\177" 'scroll-down)
 344   (define-key Man-mode-map "n"    'Man-next-section)
 345   (define-key Man-mode-map "p"    'Man-previous-section)
 346   (define-key Man-mode-map "\en"  'Man-next-manpage)
 347   (define-key Man-mode-map "\ep"  'Man-previous-manpage)
 348   (define-key Man-mode-map ">"    'end-of-buffer)
 349   (define-key Man-mode-map "<"    'beginning-of-buffer)
 350   (define-key Man-mode-map "."    'beginning-of-buffer)
 351   (define-key Man-mode-map "r"    'Man-follow-manual-reference)
 352   (define-key Man-mode-map "g"    'Man-goto-section)
 353   (define-key Man-mode-map "s"    'Man-goto-see-also-section)
 354   (define-key Man-mode-map "k"    'Man-kill)
 355   (define-key Man-mode-map "q"    'Man-quit)
 356   (define-key Man-mode-map "m"    'man)
 357   (define-key Man-mode-map "\r"   'man-follow)
 358   (define-key Man-mode-map "?"    'describe-mode)
 359   )
 360
 361 \f
 362 ;; ======================================================================
 363 ;; utilities
 364
 365 (defun Man-init-defvars ()
 366   "Used for initialising variables based on the value of window-system.
 367 This is necessary if one wants to dump man.el with emacs."
 368
 369   ;; The following is necessary until fonts are implemented on
 370   ;; terminals.
 371   (setq Man-fontify-manpage-flag (and Man-fontify-manpage-flag
 372                                       window-system))
 373
 374   ;; Avoid possible error in call-process by using a directory that must exist.
 375   (let ((default-directory "/"))
 376     (setq Man-sed-script
 377           (cond
 378            (Man-fontify-manpage-flag
 379             nil)
 380            ((= 0 (call-process Man-sed-command nil nil nil Man-sysv-sed-script))
 381             Man-sysv-sed-script)
 382            ((= 0 (call-process Man-sed-command nil nil nil Man-berkeley-sed-script))
 383             Man-berkeley-sed-script)
 384            (t
 385             nil))))
 386
 387   (setq Man-filter-list
 388         ;; Avoid trailing nil which confuses customize.
 389         (apply 'list
 390          (cons
 391           Man-sed-command
 392           (list
 393            (if Man-sed-script
 394                (concat "-e '" Man-sed-script "'")
 395              "")
 396            "-e '/^[\001-\032][\001-\032]*$/d'"
 397            "-e '/\e[789]/s///g'"
 398            "-e '/Reformatting page.  Wait/d'"
 399            "-e '/Reformatting entry.  Wait/d'"
 400            "-e '/^[ \t]*Hewlett-Packard[ \t]Company[ \t]*-[ \t][0-9]*[ \t]-/d'"
 401            "-e '/^[ \t]*Hewlett-Packard[ \t]*-[ \t][0-9]*[ \t]-.*$/d'"
 402            "-e '/^[ \t][ \t]*-[ \t][0-9]*[ \t]-[ \t]*Formatted:.*[0-9]$/d'"
 403            "-e '/^[ \t]*Page[ \t][0-9]*.*(printed[ \t][0-9\\/]*)$/d'"
 404            "-e '/^Printed[ \t][0-9].*[0-9]$/d'"
 405            "-e '/^[ \t]*X[ \t]Version[ \t]1[01].*Release[ \t][0-9]/d'"
 406            "-e '/^[A-Za-z].*Last[ \t]change:/d'"
 407            "-e '/^Sun[ \t]Release[ \t][0-9].*[0-9]$/d'"
 408            "-e '/[ \t]*Copyright [0-9]* UNIX System Laboratories, Inc.$/d'"
 409            "-e '/^[ \t]*Rev\\..*Page [0-9][0-9]*$/d'"
 410            ))
 411          (cons
 412           Man-awk-command
 413           (list
 414            "'\n"
 415            "BEGIN { blankline=0; anonblank=0; }\n"
 416            "/^$/ { if (anonblank==0) next; }\n"
 417            "{ anonblank=1; }\n"
 418            "/^$/ { blankline++; next; }\n"
 419            "{ if (blankline>0) { print \"\"; blankline=0; } print $0; }\n"
 420            "'"
 421            ))
 422          (if (not Man-uses-untabify-flag)
 423              ;; The outer list will be stripped off by apply.
 424              (list (cons
 425                     Man-untabify-command
 426                     Man-untabify-command-args))
 427            )))
 428 )
 429
 430 (defsubst Man-match-substring (&optional n string)
 431   "Return the substring matched by the last search.
 432 Optional arg N means return the substring matched by the Nth paren
 433 grouping.  Optional second arg STRING means return a substring from
 434 that string instead of from the current buffer."
 435   (if (null n) (setq n 0))
 436   (if string
 437       (substring string (match-beginning n) (match-end n))
 438     (buffer-substring (match-beginning n) (match-end n))))
 439
 440 (defsubst Man-make-page-mode-string ()
 441   "Formats part of the mode line for Man mode."
 442   (format "%s page %d of %d"
 443           (or (nth 2 (nth (1- Man-current-page) Man-page-list))
 444               "")
 445           Man-current-page
 446           (length Man-page-list)))
 447
 448 (defsubst Man-build-man-command ()
 449   "Builds the entire background manpage and cleaning command."
 450   (let ((command (concat manual-program " " Man-switches
 451                          ; Stock MS-DOS shells cannot redirect stderr;
 452                          ; `call-process' below sends it to /dev/null,
 453                          ; so we don't need `2>' even with DOS shells
 454                          ; which do support stderr redirection.
 455                          (if (not (fboundp 'start-process))
 456                              " %s"
 457                            " %s 2>/dev/null")))
 458         (flist Man-filter-list))
 459     (while (and flist (car flist))
 460       (let ((pcom (car (car flist)))
 461             (pargs (cdr (car flist))))
 462         (setq command
 463               (concat command " | " pcom " "
 464                       (mapconcat '(lambda (phrase)
 465                                     (if (not (stringp phrase))
 466                                         (error "Malformed Man-filter-list"))
 467                                     phrase)
 468                                  pargs " ")))
 469         (setq flist (cdr flist))))
 470     command))
 471
 472 (defun Man-translate-references (ref)
 473   "Translates REF from \"chmod(2V)\" to \"2v chmod\" style.
 474 Leave it as is if already in that style.  Possibly downcase and
 475 translate the section (see the Man-downcase-section-letters-flag
 476 and the Man-section-translations-alist variables)."
 477   (let ((name "")
 478         (section "")
 479         (slist Man-section-translations-alist))
 480     (cond
 481      ;; "chmod(2V)" case ?
 482      ((string-match (concat "^" Man-reference-regexp "$") ref)
 483       (setq name (Man-match-substring 1 ref)
 484             section (Man-match-substring 2 ref)))
 485      ;; "2v chmod" case ?
 486      ((string-match (concat "^\\(" Man-section-regexp
 487                             "\\) +\\(" Man-name-regexp "\\)$") ref)
 488       (setq name (Man-match-substring 2 ref)
 489             section (Man-match-substring 1 ref))))
 490     (if (string= name "")
 491         ref                             ; Return the reference as is
 492       (if Man-downcase-section-letters-flag
 493           (setq section (downcase section)))
 494       (while slist
 495         (let ((s1 (car (car slist)))
 496               (s2 (cdr (car slist))))
 497           (setq slist (cdr slist))
 498           (if Man-downcase-section-letters-flag
 499               (setq s1 (downcase s1)))
 500           (if (not (string= s1 section)) nil
 501             (setq section (if Man-downcase-section-letters-flag
 502                               (downcase s2)
 503                             s2)
 504                   slist nil))))
 505       (concat Man-specified-section-option section " " name))))
 506
 507 \f
 508 ;; ======================================================================
 509 ;; default man entry: get word under point
 510
 511 (defsubst Man-default-man-entry ()
 512   "Make a guess at a default manual entry.
 513 This guess is based on the text surrounding the cursor, and the
 514 default section number is selected from `Man-auto-section-alist'."
 515   (let (word)
 516     (save-excursion
 517       ;; Default man entry title is any word the cursor is on, or if
 518       ;; cursor not on a word, then nearest preceding word.
 519       (setq word (current-word))
 520       (if (string-match "[._]+$" word)
 521           (setq word (substring word 0 (match-beginning 0))))
 522       ;; If looking at something like ioctl(2) or brc(1M), include the
 523       ;; section number in the returned value.  Remove text properties.
 524       (forward-word 1)
 525       ;; Use `format' here to clear any text props from `word'.
 526       (format "%s%s"
 527               word
 528               (if (looking-at
 529                    (concat "[ \t]*([ \t]*\\(" Man-section-regexp "\\)[ \t]*)"))
 530                   (format "(%s)" (Man-match-substring 1))
 531                 "")))))
 532
 533 \f
 534 ;; ======================================================================
 535 ;; Top level command and background process sentinel
 536
 537 ;; For compatibility with older versions.
 538 ;;;###autoload
 539 (defalias 'manual-entry 'man)
 540
 541 ;;;###autoload
 542 (defun man (man-args)
 543   "Get a Un*x manual page and put it in a buffer.
 544 This command is the top-level command in the man package.  It runs a Un*x
 545 command to retrieve and clean a manpage in the background and places the
 546 results in a Man mode (manpage browsing) buffer.  See variable
 547 `Man-notify-method' for what happens when the buffer is ready.
 548 If a buffer already exists for this man page, it will display immediately."
 549   (interactive
 550    (list (let* ((default-entry (Man-default-man-entry))
 551                 (input (read-string
 552                         (format "Manual entry%s: "
 553                                 (if (string= default-entry "")
 554                                     ""
 555                                   (format " (default %s)" default-entry))))))
 556            (if (string= input "")
 557                (if (string= default-entry "")
 558                    (error "No man args given")
 559                  default-entry)
 560              input))))
 561
 562   ;; Possibly translate the "subject(section)" syntax into the
 563   ;; "section subject" syntax and possibly downcase the section.
 564   (setq man-args (Man-translate-references man-args))
 565
 566   (Man-getpage-in-background man-args))
 567
 568 ;;;###autoload
 569 (defun man-follow (man-args)
 570   "Get a Un*x manual page of the item under point and put it in a buffer."
 571   (interactive (list (Man-default-man-entry)))
 572   (if (or (not man-args)
 573           (string= man-args ""))
 574       (error "No item under point")
 575     (man man-args)))
 576
 577 (defun Man-getpage-in-background (topic)
 578   "Uses TOPIC to build and fire off the manpage and cleaning command."
 579   (let* ((man-args topic)
 580          (bufname (concat "*Man " man-args "*"))
 581          (buffer  (get-buffer bufname)))
 582     (if buffer
 583         (Man-notify-when-ready buffer)
 584       (require 'env)
 585       (message "Invoking %s %s in the background" manual-program man-args)
 586       (setq buffer (generate-new-buffer bufname))
 587       (save-excursion
 588         (set-buffer buffer)
 589         (setq Man-original-frame (selected-frame))
 590         (setq Man-arguments man-args))
 591       (let ((process-environment (copy-sequence process-environment))
 592             ;; The following is so Awk script gets \n intact
 593             ;; But don't prevent decoding of the outside.
 594             (coding-system-for-write 'raw-text-unix)
 595             ;; Avoid possible error by using a directory that always exists.
 596             (default-directory "/"))
 597         ;; Prevent any attempt to use display terminal fanciness.
 598         (setenv "TERM" "dumb")
 599         (if (fboundp 'start-process)
 600             (set-process-sentinel
 601              (start-process manual-program buffer "sh" "-c"
 602                             (format (Man-build-man-command) man-args))
 603              'Man-bgproc-sentinel)
 604           (progn
 605             (let ((exit-status
 606                    (call-process shell-file-name nil (list buffer nil) nil "-c"
 607                                  (format (Man-build-man-command) man-args)))
 608                   (msg ""))
 609               (or (and (numberp exit-status)
 610                        (= exit-status 0))
 611                   (and (numberp exit-status)
 612                        (setq msg
 613                              (format "exited abnormally with code %d"
 614                                      exit-status)))
 615                   (setq msg exit-status))
 616               (Man-bgproc-sentinel bufname msg))))))))
 617
 618 (defun Man-notify-when-ready (man-buffer)
 619   "Notify the user when MAN-BUFFER is ready.
 620 See the variable `Man-notify-method' for the different notification behaviors."
 621   (let ((saved-frame (save-excursion
 622                        (set-buffer man-buffer)
 623                        Man-original-frame)))
 624     (cond
 625      ((eq Man-notify-method 'newframe)
 626       ;; Since we run asynchronously, perhaps while Emacs is waiting
 627       ;; for input, we must not leave a different buffer current.  We
 628       ;; can't rely on the editor command loop to reselect the
 629       ;; selected window's buffer.
 630       (save-excursion
 631         (let ((frame (make-frame Man-frame-parameters)))
 632           (set-window-buffer (frame-selected-window frame) man-buffer)
 633           (set-window-dedicated-p (frame-selected-window frame) t))))
 634      ((eq Man-notify-method 'pushy)
 635       (switch-to-buffer man-buffer))
 636      ((eq Man-notify-method 'bully)
 637       (and window-system
 638            (frame-live-p saved-frame)
 639            (select-frame saved-frame))
 640       (pop-to-buffer man-buffer)
 641       (delete-other-windows))
 642      ((eq Man-notify-method 'aggressive)
 643       (and window-system
 644            (frame-live-p saved-frame)
 645            (select-frame saved-frame))
 646       (pop-to-buffer man-buffer))
 647      ((eq Man-notify-method 'friendly)
 648       (and window-system
 649            (frame-live-p saved-frame)
 650            (select-frame saved-frame))
 651       (display-buffer man-buffer 'not-this-window))
 652      ((eq Man-notify-method 'polite)
 653       (beep)
 654       (message "Manual buffer %s is ready" (buffer-name man-buffer)))
 655      ((eq Man-notify-method 'quiet)
 656       (message "Manual buffer %s is ready" (buffer-name man-buffer)))
 657      ((or (eq Man-notify-method 'meek)
 658           t)
 659       (message ""))
 660      )))
 661
 662 (defun Man-softhyphen-to-minus ()
 663   ;; \255 is some kind of dash in Latin-1.
 664   (goto-char (point-min))
 665   (if enable-multibyte-characters
 666       (while (search-forward "\255" nil t)
 667         (if (= (preceding-char) ?\255)
 668             (replace-match "-")))
 669     (while (search-forward "\255" nil t) (replace-match "-"))))
 670
 671 (defun Man-fontify-manpage ()
 672   "Convert overstriking and underlining to the correct fonts.
 673 Same for the ANSI bold and normal escape sequences."
 674   (interactive)
 675   (message "Please wait: making up the %s man page..." Man-arguments)
 676   (goto-char (point-min))
 677   (while (search-forward "\e[1m" nil t)
 678     (delete-backward-char 4)
 679     (put-text-property (point)
 680                        (progn (if (search-forward "\e[0m" nil 'move)
 681                                   (delete-backward-char 4))
 682                               (point))
 683                        'face Man-overstrike-face))
 684   (goto-char (point-min))
 685   (while (search-forward "_\b" nil t)
 686     (backward-delete-char 2)
 687     (put-text-property (point) (1+ (point)) 'face Man-underline-face))
 688   (goto-char (point-min))
 689   (while (search-forward "\b_" nil t)
 690     (backward-delete-char 2)
 691     (put-text-property (1- (point)) (point) 'face Man-underline-face))
 692   (goto-char (point-min))
 693   (while (re-search-forward "\\(.\\)\\(\b\\1\\)+" nil t)
 694     (replace-match "\\1")
 695     (put-text-property (1- (point)) (point) 'face Man-overstrike-face))
 696   (goto-char (point-min))
 697   (while (re-search-forward "o\b\\+\\|\\+\bo" nil t)
 698     (replace-match "o")
 699     (put-text-property (1- (point)) (point) 'face 'bold))
 700   (goto-char (point-min))
 701   (while (re-search-forward "[-|]\\(\b[-|]\\)+" nil t)
 702     (replace-match "+")
 703     (put-text-property (1- (point)) (point) 'face 'bold))
 704   (Man-softhyphen-to-minus)
 705   (message "%s man page made up" Man-arguments))
 706
 707 (defun Man-cleanup-manpage ()
 708   "Remove overstriking and underlining from the current buffer."
 709   (interactive)
 710   (message "Please wait: cleaning up the %s man page..."
 711            Man-arguments)
 712   (if (or (interactive-p) (not Man-sed-script))
 713       (progn
 714         (goto-char (point-min))
 715         (while (search-forward "_\b" nil t) (backward-delete-char 2))
 716         (goto-char (point-min))
 717         (while (search-forward "\b_" nil t) (backward-delete-char 2))
 718         (goto-char (point-min))
 719         (while (re-search-forward "\\(.\\)\\(\b\\1\\)+" nil t)
 720           (replace-match "\\1"))
 721         (goto-char (point-min))
 722         (while (re-search-forward "\e\\[[0-9]+m" nil t) (replace-match ""))
 723         (goto-char (point-min))
 724         (while (re-search-forward "o\b\\+\\|\\+\bo" nil t) (replace-match "o"))
 725         ))
 726   (goto-char (point-min))
 727   (while (re-search-forward "[-|]\\(\b[-|]\\)+" nil t) (replace-match "+"))
 728   (Man-softhyphen-to-minus)
 729   (message "%s man page cleaned up" Man-arguments))
 730
 731 (defun Man-bgproc-sentinel (process msg)
 732   "Manpage background process sentinel.
 733 When manpage command is run asynchronously, PROCESS is the process
 734 object for the manpage command; when manpage command is run
 735 synchronously, PROCESS is the name of the buffer where the manpage
 736 command is run.  Second argument MSG is the exit message of the
 737 manpage command."
 738   (let ((Man-buffer (if (stringp process) (get-buffer process)
 739                       (process-buffer process)))
 740         (delete-buff nil)
 741         (err-mess nil))
 742
 743     (if (null (buffer-name Man-buffer)) ;; deleted buffer
 744         (or (stringp process)
 745             (set-process-buffer process nil))
 746
 747       (save-excursion
 748         (set-buffer Man-buffer)
 749         (let ((case-fold-search nil))
 750           (goto-char (point-min))
 751           (cond ((or (looking-at "No \\(manual \\)*entry for")
 752                      (looking-at "[^\n]*: nothing appropriate$"))
 753                  (setq err-mess (buffer-substring (point)
 754                                                   (progn
 755                                                     (end-of-line) (point)))
 756                        delete-buff t))
 757                 ((or (stringp process)
 758                      (not (and (eq (process-status process) 'exit)
 759                                (= (process-exit-status process) 0))))
 760                  (or (zerop (length msg))
 761                      (progn
 762                        (setq err-mess
 763                              (concat (buffer-name Man-buffer)
 764                                      ": process "
 765                                      (let ((eos (1- (length msg))))
 766                                        (if (= (aref msg eos) ?\n)
 767                                            (substring msg 0 eos) msg))))
 768                        (goto-char (point-max))
 769                        (insert (format "\nprocess %s" msg))))
 770                  ))
 771         (if delete-buff
 772             (kill-buffer Man-buffer)
 773           (if Man-fontify-manpage-flag
 774               (Man-fontify-manpage)
 775             (Man-cleanup-manpage))
 776           (run-hooks 'Man-cooked-hook)
 777           (Man-mode)
 778           (set-buffer-modified-p nil)
 779           ))
 780         ;; Restore case-fold-search before calling
 781         ;; Man-notify-when-ready because it may switch buffers.
 782
 783         (if (not delete-buff)
 784             (Man-notify-when-ready Man-buffer))
 785
 786         (if err-mess
 787             (error err-mess))
 788         ))))
 789
 790 \f
 791 ;; ======================================================================
 792 ;; set up manual mode in buffer and build alists
 793
 794 (defun Man-mode ()
 795   "A mode for browsing Un*x manual pages.
 796
 797 The following man commands are available in the buffer. Try
 798 \"\\[describe-key] <key> RET\" for more information:
 799
 800 \\[man]       Prompt to retrieve a new manpage.
 801 \\[Man-follow-manual-reference]       Retrieve reference in SEE ALSO section.
 802 \\[Man-next-manpage]   Jump to next manpage in circular list.
 803 \\[Man-previous-manpage]   Jump to previous manpage in circular list.
 804 \\[Man-next-section]       Jump to next manpage section.
 805 \\[Man-previous-section]       Jump to previous manpage section.
 806 \\[Man-goto-section]       Go to a manpage section.
 807 \\[Man-goto-see-also-section]       Jumps to the SEE ALSO manpage section.
 808 \\[Man-quit]       Deletes the manpage window, bury its buffer.
 809 \\[Man-kill]       Deletes the manpage window, kill its buffer.
 810 \\[describe-mode]       Prints this help text.
 811
 812 The following variables may be of some use. Try
 813 \"\\[describe-variable] <variable-name> RET\" for more information:
 814
 815 Man-notify-method               What happens when manpage formatting is done.
 816 Man-downcase-section-letters-flag  Force section letters to lower case.
 817 Man-circular-pages-flag         Treat multiple manpage list as circular.
 818 Man-auto-section-alist          List of major modes and their section numbers.
 819 Man-section-translations-alist  List of section numbers and their Un*x equiv.
 820 Man-filter-list                 Background manpage filter command.
 821 Man-mode-line-format            Mode line format for Man mode buffers.
 822 Man-mode-map                    Keymap bindings for Man mode buffers.
 823 Man-mode-hook                   Normal hook run on entry to Man mode.
 824 Man-section-regexp              Regexp describing manpage section letters.
 825 Man-heading-regexp              Regexp describing section headers.
 826 Man-see-also-regexp             Regexp for SEE ALSO section (or your equiv).
 827 Man-first-heading-regexp        Regexp for first heading on a manpage.
 828 Man-reference-regexp            Regexp matching a references in SEE ALSO.
 829 Man-switches                    Background `man' command switches.
 830
 831 The following key bindings are currently in effect in the buffer:
 832 \\{Man-mode-map}"
 833   (interactive)
 834   (setq major-mode 'Man-mode
 835         mode-name "Man"
 836         buffer-auto-save-file-name nil
 837         mode-line-format Man-mode-line-format
 838         truncate-lines t
 839         buffer-read-only t)
 840   (buffer-disable-undo (current-buffer))
 841   (auto-fill-mode -1)
 842   (use-local-map Man-mode-map)
 843   (set-syntax-table man-mode-syntax-table)
 844   (Man-build-page-list)
 845   (Man-strip-page-headers)
 846   (Man-unindent)
 847   (Man-goto-page 1)
 848   (run-hooks 'Man-mode-hook))
 849
 850 (defsubst Man-build-section-alist ()
 851   "Build the association list of manpage sections."
 852   (setq Man-sections-alist nil)
 853   (goto-char (point-min))
 854   (let ((case-fold-search nil))
 855     (while (re-search-forward Man-heading-regexp (point-max) t)
 856       (aput 'Man-sections-alist (Man-match-substring 1))
 857       (forward-line 1))))
 858
 859 (defsubst Man-build-references-alist ()
 860   "Build the association list of references (in the SEE ALSO section)."
 861   (setq Man-refpages-alist nil)
 862   (save-excursion
 863     (if (Man-find-section Man-see-also-regexp)
 864         (let ((start (progn (forward-line 1) (point)))
 865               (end (progn
 866                      (Man-next-section 1)
 867                      (point)))
 868               hyphenated
 869               (runningpoint -1))
 870           (save-restriction
 871             (narrow-to-region start end)
 872             (goto-char (point-min))
 873             (back-to-indentation)
 874             (while (and (not (eobp)) (/= (point) runningpoint))
 875               (setq runningpoint (point))
 876               (if (re-search-forward Man-reference-regexp end t)
 877                   (let* ((word (Man-match-substring 0))
 878                          (len (1- (length word))))
 879                     (if hyphenated
 880                         (setq word (concat hyphenated word)
 881                               hyphenated nil))
 882                     (if (= (aref word len) ?-)
 883                         (setq hyphenated (substring word 0 len))
 884                       (aput 'Man-refpages-alist word))))
 885               (skip-chars-forward " \t\n,")))))))
 886
 887 (defun Man-build-page-list ()
 888   "Build the list of separate manpages in the buffer."
 889   (setq Man-page-list nil)
 890   (let ((page-start (point-min))
 891         (page-end (point-max))
 892         (header ""))
 893     (goto-char page-start)
 894     ;; (switch-to-buffer (current-buffer))(debug)
 895     (while (not (eobp))
 896       (setq header
 897             (if (looking-at Man-page-header-regexp)
 898                 (Man-match-substring 1)
 899               nil))
 900       ;; Go past both the current and the next Man-first-heading-regexp
 901       (if (re-search-forward Man-first-heading-regexp nil 'move 2)
 902           (let ((p (progn (beginning-of-line) (point))))
 903             ;; We assume that the page header is delimited by blank
 904             ;; lines and that it contains at most one blank line.  So
 905             ;; if we back by three blank lines we will be sure to be
 906             ;; before the page header but not before the possible
 907             ;; previous page header.
 908             (search-backward "\n\n" nil t 3)
 909             (if (re-search-forward Man-page-header-regexp p 'move)
 910                 (beginning-of-line))))
 911       (setq page-end (point))
 912       (setq Man-page-list (append Man-page-list
 913                                   (list (list (copy-marker page-start)
 914                                               (copy-marker page-end)
 915                                               header))))
 916       (setq page-start page-end)
 917       )))
 918
 919 (defun Man-strip-page-headers ()
 920   "Strip all the page headers but the first from the manpage."
 921   (let ((buffer-read-only nil)
 922         (case-fold-search nil)
 923         (page-list Man-page-list)
 924         (page ())
 925         (header ""))
 926     (while page-list
 927       (setq page (car page-list))
 928       (and (nth 2 page)
 929            (goto-char (car page))
 930            (re-search-forward Man-first-heading-regexp nil t)
 931            (setq header (buffer-substring (car page) (match-beginning 0)))
 932            ;; Since the awk script collapses all successive blank
 933            ;; lines into one, and since we don't want to get rid of
 934            ;; the fast awk script, one must choose between adding
 935            ;; spare blank lines between pages when there were none and
 936            ;; deleting blank lines at page boundaries when there were
 937            ;; some.  We choose the first, so we comment the following
 938            ;; line.
 939            ;; (setq header (concat "\n" header)))
 940            (while (search-forward header (nth 1 page) t)
 941              (replace-match "")))
 942       (setq page-list (cdr page-list)))))
 943
 944 (defun Man-unindent ()
 945   "Delete the leading spaces that indent the manpage."
 946   (let ((buffer-read-only nil)
 947         (case-fold-search nil)
 948         (page-list Man-page-list))
 949     (while page-list
 950       (let ((page (car page-list))
 951             (indent "")
 952             (nindent 0))
 953         (narrow-to-region (car page) (car (cdr page)))
 954         (if Man-uses-untabify-flag
 955             (untabify (point-min) (point-max)))
 956         (if (catch 'unindent
 957               (goto-char (point-min))
 958               (if (not (re-search-forward Man-first-heading-regexp nil t))
 959                   (throw 'unindent nil))
 960               (beginning-of-line)
 961               (setq indent (buffer-substring (point)
 962                                              (progn
 963                                                (skip-chars-forward " ")
 964                                                (point))))
 965               (setq nindent (length indent))
 966               (if (zerop nindent)
 967                   (throw 'unindent nil))
 968               (setq indent (concat indent "\\|$"))
 969               (goto-char (point-min))
 970               (while (not (eobp))
 971                 (if (looking-at indent)
 972                     (forward-line 1)
 973                   (throw 'unindent nil)))
 974               (goto-char (point-min)))
 975             (while (not (eobp))
 976               (or (eolp)
 977                   (delete-char nindent))
 978               (forward-line 1)))
 979         (setq page-list (cdr page-list))
 980         ))))
 981
 982 \f
 983 ;; ======================================================================
 984 ;; Man mode commands
 985
 986 (defun Man-next-section (n)
 987   "Move point to Nth next section (default 1)."
 988   (interactive "p")
 989   (let ((case-fold-search nil))
 990     (if (looking-at Man-heading-regexp)
 991         (forward-line 1))
 992     (if (re-search-forward Man-heading-regexp (point-max) t n)
 993         (beginning-of-line)
 994       (goto-char (point-max)))))
 995
 996 (defun Man-previous-section (n)
 997   "Move point to Nth previous section (default 1)."
 998   (interactive "p")
 999   (let ((case-fold-search nil))
1000     (if (looking-at Man-heading-regexp)
1001         (forward-line -1))
1002     (if (re-search-backward Man-heading-regexp (point-min) t n)
1003         (beginning-of-line)
1004       (goto-char (point-min)))))
1005
1006 (defun Man-find-section (section)
1007   "Move point to SECTION if it exists, otherwise don't move point.
1008 Returns t if section is found, nil otherwise."
1009   (let ((curpos (point))
1010         (case-fold-search nil))
1011     (goto-char (point-min))
1012     (if (re-search-forward (concat "^" section) (point-max) t)
1013         (progn (beginning-of-line) t)
1014       (goto-char curpos)
1015       nil)
1016     ))
1017
1018 (defun Man-goto-section ()
1019   "Query for section to move point to."
1020   (interactive)
1021   (aput 'Man-sections-alist
1022         (let* ((default (aheadsym Man-sections-alist))
1023                (completion-ignore-case t)
1024                chosen
1025                (prompt (concat "Go to section: (default " default ") ")))
1026           (setq chosen (completing-read prompt Man-sections-alist))
1027           (if (or (not chosen)
1028                   (string= chosen ""))
1029               default
1030             chosen)))
1031   (Man-find-section (aheadsym Man-sections-alist)))
1032
1033 (defun Man-goto-see-also-section ()
1034   "Move point the the \"SEE ALSO\" section.
1035 Actually the section moved to is described by `Man-see-also-regexp'."
1036   (interactive)
1037   (if (not (Man-find-section Man-see-also-regexp))
1038       (error (concat "No " Man-see-also-regexp
1039                      " section found in the current manpage"))))
1040
1041 (defun Man-follow-manual-reference (reference)
1042   "Get one of the manpages referred to in the \"SEE ALSO\" section.
1043 Specify which reference to use; default is based on word at point."
1044   (interactive
1045    (if (not Man-refpages-alist)
1046        (error "There are no references in the current man page")
1047      (list (let* ((default (or
1048                              (car (all-completions
1049                                    (save-excursion
1050                                      (skip-syntax-backward "w()")
1051                                      (skip-chars-forward " \t")
1052                                      (let ((word (current-word)))
1053                                        ;; strip a trailing '-':
1054                                        (if (string-match "-$" word)
1055                                            (substring word 0
1056                                                       (match-beginning 0))
1057                                          word)))
1058                                    Man-refpages-alist))
1059                              (aheadsym Man-refpages-alist)))
1060                    chosen
1061                    (prompt (concat "Refer to: (default " default ") ")))
1062               (setq chosen (completing-read prompt Man-refpages-alist nil t))
1063               (if (or (not chosen)
1064                       (string= chosen ""))
1065                   default
1066                 chosen)))))
1067   (if (not Man-refpages-alist)
1068       (error "Can't find any references in the current manpage")
1069     (aput 'Man-refpages-alist reference)
1070     (Man-getpage-in-background
1071      (Man-translate-references (aheadsym Man-refpages-alist)))))
1072
1073 (defun Man-kill ()
1074   "Kill the buffer containing the manpage."
1075   (interactive)
1076   (quit-window t))
1077
1078 (defun Man-quit ()
1079   "Bury the buffer containing the manpage."
1080   (interactive)
1081   (quit-window))
1082
1083 (defun Man-goto-page (page)
1084   "Go to the manual page on page PAGE."
1085   (interactive
1086    (if (not Man-page-list)
1087        (let ((args Man-arguments))
1088          (kill-buffer (current-buffer))
1089          (error "Can't find the %s manpage" args))
1090      (if (= (length Man-page-list) 1)
1091          (error "You're looking at the only manpage in the buffer")
1092        (list (read-minibuffer (format "Go to manpage [1-%d]: "
1093                                       (length Man-page-list)))))))
1094   (if (not Man-page-list)
1095       (let ((args Man-arguments))
1096         (kill-buffer (current-buffer))
1097         (error "Can't find the %s manpage" args)))
1098   (if (or (< page 1)
1099           (> page (length Man-page-list)))
1100       (error "No manpage %d found" page))
1101   (let* ((page-range (nth (1- page) Man-page-list))
1102          (page-start (car page-range))
1103          (page-end (car (cdr page-range))))
1104     (setq Man-current-page page
1105           Man-page-mode-string (Man-make-page-mode-string))
1106     (widen)
1107     (goto-char page-start)
1108     (narrow-to-region page-start page-end)
1109     (Man-build-section-alist)
1110     (Man-build-references-alist)
1111     (goto-char (point-min))))
1112
1113
1114 (defun Man-next-manpage ()
1115   "Find the next manpage entry in the buffer."
1116   (interactive)
1117   (if (= (length Man-page-list) 1)
1118       (error "This is the only manpage in the buffer"))
1119   (if (< Man-current-page (length Man-page-list))
1120       (Man-goto-page (1+ Man-current-page))
1121     (if Man-circular-pages-flag
1122         (Man-goto-page 1)
1123       (error "You're looking at the last manpage in the buffer"))))
1124
1125 (defun Man-previous-manpage ()
1126   "Find the previous manpage entry in the buffer."
1127   (interactive)
1128   (if (= (length Man-page-list) 1)
1129       (error "This is the only manpage in the buffer"))
1130   (if (> Man-current-page 1)
1131       (Man-goto-page (1- Man-current-page))
1132     (if Man-circular-pages-flag
1133         (Man-goto-page (length Man-page-list))
1134       (error "You're looking at the first manpage in the buffer"))))
1135 \f
1136 ;; Init the man package variables, if not already done.
1137 (Man-init-defvars)
1138
1139 (provide 'man)
1140
1141 ;;; man.el ends here