* Makefile.in (ALL_CFLAGS, LINK_CFLAGS, CPP_CFLAGS): Move to the
[bpt/emacs.git] / lisp / man.el
CommitLineData
665a7c3b 1;;; man.el --- browse UNIX manual pages -*- coding: iso-8859-1 -*-
55535639 2
597e2240 3;; Copyright (C) 1993, 1994, 1996, 1997, 2001, 2002, 2003, 2004, 2005,
114f9c96 4;; 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
55535639
PJ
5
6;; Author: Barry A. Warsaw <bwarsaw@cen.com>
7;; Maintainer: FSF
8;; Keywords: help
9;; Adapted-By: ESR, pot
10
11;; This file is part of GNU Emacs.
12
eb3fa2cf 13;; GNU Emacs is free software: you can redistribute it and/or modify
55535639 14;; it under the terms of the GNU General Public License as published by
eb3fa2cf
GM
15;; the Free Software Foundation, either version 3 of the License, or
16;; (at your option) any later version.
55535639
PJ
17
18;; GNU Emacs is distributed in the hope that it will be useful,
19;; but WITHOUT ANY WARRANTY; without even the implied warranty of
20;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21;; GNU General Public License for more details.
22
23;; You should have received a copy of the GNU General Public License
eb3fa2cf 24;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
55535639
PJ
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
a88459cd 38;; man.el from the standard Emacs 18.57 distribution. I liked many of
55535639
PJ
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
4cb071a4 65;; is done in the background. The cleaning commands are configurable.
55535639
PJ
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.
fffa137c 77;; - The awk script deletes multiple blank lines. This behavior does
55535639
PJ
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
72397ff1 83;; the number of blank lines before the page footer by heuristics
55535639
PJ
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.
55535639
PJ
87
88\f
89;;; Code:
90
079c2d00 91(eval-when-compile (require 'cl))
55535639 92(require 'assoc)
4edd9faf 93(require 'button)
55535639
PJ
94
95;; vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
96;; empty defvars (keep the compiler quiet)
97
98(defgroup man nil
99 "Browse UNIX manual pages."
100 :prefix "Man-"
ff90f4b0 101 :group 'external
55535639
PJ
102 :group 'help)
103
55535639 104(defvar Man-notify)
55535639 105(defcustom Man-filter-list nil
9201cc28 106 "Manpage cleaning filter command phrases.
55535639
PJ
107This variable contains a list of the following form:
108
109'((command-string phrase-string*)*)
110
111Each phrase-string is concatenated onto the command-string to form a
112command filter. The (standard) output (and standard error) of the Un*x
113man command is piped through each command filter in the order the
114commands appear in the association list. The final output is placed in
115the manpage buffer."
116 :type '(repeat (list (string :tag "Command String")
117 (repeat :inline t
118 (string :tag "Phrase String"))))
119 :group 'man)
120
55535639
PJ
121(defvar Man-uses-untabify-flag t
122 "Non-nil means use `untabify' instead of `Man-untabify-command'.")
55535639
PJ
123(defvar Man-sed-script nil
124 "Script for sed to nuke backspaces and ANSI codes from manpages.")
125
126;; vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
127;; user variables
128
129(defcustom Man-fontify-manpage-flag t
a88459cd 130 "Non-nil means make up the manpage with fonts."
55535639
PJ
131 :type 'boolean
132 :group 'man)
133
134(defcustom Man-overstrike-face 'bold
a88459cd 135 "Face to use when fontifying overstrike."
55535639
PJ
136 :type 'face
137 :group 'man)
138
139(defcustom Man-underline-face 'underline
a88459cd 140 "Face to use when fontifying underlining."
55535639
PJ
141 :type 'face
142 :group 'man)
143
8d2a4f61 144(defcustom Man-reverse-face 'highlight
a88459cd 145 "Face to use when fontifying reverse video."
079c2d00
SM
146 :type 'face
147 :group 'man)
148
55535639
PJ
149;; Use the value of the obsolete user option Man-notify, if set.
150(defcustom Man-notify-method (if (boundp 'Man-notify) Man-notify 'friendly)
a88459cd 151 "Selects the behavior when manpage is ready.
55535639
PJ
152This variable may have one of the following values, where (sf) means
153that the frames are switched, so the manpage is displayed in the frame
154where the man command was called from:
155
156newframe -- put the manpage in its own frame (see `Man-frame-parameters')
157pushy -- make the manpage the current buffer in the current window
158bully -- make the manpage the current buffer and only window (sf)
159aggressive -- make the manpage the current buffer in the other window (sf)
160friendly -- display manpage in the other window but don't make current (sf)
161polite -- don't display manpage, but prints message and beep when ready
162quiet -- like `polite', but don't beep
163meek -- make no indication that the manpage is ready
164
165Any other value of `Man-notify-method' is equivalent to `meek'."
166 :type '(radio (const newframe) (const pushy) (const bully)
167 (const aggressive) (const friendly)
168 (const polite) (const quiet) (const meek))
169 :group 'man)
170
aec2bd36 171(defcustom Man-width nil
a88459cd 172 "Number of columns for which manual pages should be formatted.
aec2bd36
JL
173If nil, the width of the window selected at the moment of man
174invocation is used. If non-nil, the width of the frame selected
175at the moment of man invocation is used. The value also can be a
176positive integer."
177 :type '(choice (const :tag "Window width" nil)
178 (const :tag "Frame width" t)
179 (integer :tag "Specific width" :value 65))
180 :group 'man)
181
55535639 182(defcustom Man-frame-parameters nil
a88459cd 183 "Frame parameter list for creating a new frame for a manual page."
55535639
PJ
184 :type 'sexp
185 :group 'man)
186
187(defcustom Man-downcase-section-letters-flag t
a88459cd 188 "Non-nil means letters in sections are converted to lower case.
55535639
PJ
189Some Un*x man commands can't handle uppercase letters in sections, for
190example \"man 2V chmod\", but they are often displayed in the manpage
191with the upper case letter. When this variable is t, the section
192letter (e.g., \"2V\") is converted to lowercase (e.g., \"2v\") before
193being sent to the man background process."
194 :type 'boolean
195 :group 'man)
196
197(defcustom Man-circular-pages-flag t
a88459cd 198 "Non-nil means the manpage list is treated as circular for traversal."
55535639
PJ
199 :type 'boolean
200 :group 'man)
201
202(defcustom Man-section-translations-alist
203 (list
204 '("3C++" . "3")
205 ;; Some systems have a real 3x man section, so let's comment this.
206 ;; '("3X" . "3") ; Xlib man pages
207 '("3X11" . "3")
208 '("1-UCB" . ""))
a88459cd 209 "Association list of bogus sections to real section numbers.
55535639
PJ
210Some manpages (e.g. the Sun C++ 2.1 manpages) have section numbers in
211their references which Un*x `man' does not recognize. This
212association list is used to translate those sections, when found, to
213the associated section number."
214 :type '(repeat (cons (string :tag "Bogus Section")
215 (string :tag "Real Section")))
216 :group 'man)
217
4edd9faf
JB
218(defcustom Man-header-file-path
219 '("/usr/include" "/usr/local/include")
220 "C Header file search path used in Man."
221 :type '(repeat string)
222 :group 'man)
223
55535639
PJ
224(defvar manual-program "man"
225 "The name of the program that produces man pages.")
226
227(defvar Man-untabify-command "pr"
228 "Command used for untabifying.")
229
230(defvar Man-untabify-command-args (list "-t" "-e")
231 "List of arguments to be passed to `Man-untabify-command' (which see).")
232
233(defvar Man-sed-command "sed"
234 "Command used for processing sed scripts.")
235
236(defvar Man-awk-command "awk"
237 "Command used for processing awk scripts.")
238
55535639
PJ
239(defvar Man-mode-hook nil
240 "Hook run when Man mode is enabled.")
241
242(defvar Man-cooked-hook nil
243 "Hook run after removing backspaces but before `Man-mode' processing.")
244
5f43c63c 245