Commit | Line | Data |
---|---|---|
665a7c3b | 1 | ;;; man.el --- browse UNIX manual pages -*- coding: iso-8859-1 -*- |
55535639 | 2 | |
ab422c4d PE |
3 | ;; Copyright (C) 1993-1994, 1996-1997, 2001-2013 Free Software |
4 | ;; 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 | ||
456e62c2 | 91 | (require 'ansi-color) |
4edd9faf | 92 | (require 'button) |
55535639 | 93 | |
55535639 PJ |
94 | (defgroup man nil |
95 | "Browse UNIX manual pages." | |
96 | :prefix "Man-" | |
ff90f4b0 | 97 | :group 'external |
55535639 PJ |
98 | :group 'help) |
99 | ||
55535639 | 100 | (defvar Man-notify) |
dee4ef93 | 101 | |
55535639 | 102 | (defcustom Man-filter-list nil |
9201cc28 | 103 | "Manpage cleaning filter command phrases. |
55535639 PJ |
104 | This variable contains a list of the following form: |
105 | ||
106 | '((command-string phrase-string*)*) | |
107 | ||
108 | Each phrase-string is concatenated onto the command-string to form a | |
109 | command filter. The (standard) output (and standard error) of the Un*x | |
110 | man command is piped through each command filter in the order the | |
111 | commands appear in the association list. The final output is placed in | |
112 | the manpage buffer." | |
113 | :type '(repeat (list (string :tag "Command String") | |
114 | (repeat :inline t | |
115 | (string :tag "Phrase String")))) | |
116 | :group 'man) | |
117 | ||
55535639 PJ |
118 | (defvar Man-uses-untabify-flag t |
119 | "Non-nil means use `untabify' instead of `Man-untabify-command'.") | |
55535639 PJ |
120 | (defvar Man-sed-script nil |
121 | "Script for sed to nuke backspaces and ANSI codes from manpages.") | |
122 | ||
55535639 | 123 | (defcustom Man-fontify-manpage-flag t |
a88459cd | 124 | "Non-nil means make up the manpage with fonts." |
55535639 PJ |
125 | :type 'boolean |
126 | :group 'man) | |
127 | ||
456e62c2 WJ |
128 | (defface Man-overstrike |
129 | '((t (:inherit bold))) | |
a88459cd | 130 | "Face to use when fontifying overstrike." |
456e62c2 | 131 | :group 'man |
2a1e2476 | 132 | :version "24.3") |
55535639 | 133 | |
456e62c2 WJ |
134 | (defface Man-underline |
135 | '((t (:inherit underline))) | |
a88459cd | 136 | "Face to use when fontifying underlining." |
456e62c2 | 137 | :group 'man |
2a1e2476 | 138 | :version "24.3") |
55535639 | 139 | |
456e62c2 WJ |
140 | (defface Man-reverse |
141 | '((t (:inherit highlight))) | |
a88459cd | 142 | "Face to use when fontifying reverse video." |
456e62c2 | 143 | :group 'man |
2a1e2476 | 144 | :version "24.3") |
456e62c2 WJ |
145 | |
146 | (defvar Man-ansi-color-map (let ((ansi-color-faces-vector | |
147 | [ default Man-overstrike default Man-underline | |
148 | Man-underline default default Man-reverse ])) | |
149 | (ansi-color-make-color-map)) | |
150 | "The value used here for `ansi-color-map'.") | |
079c2d00 | 151 | |
55535639 PJ |
152 | ;; Use the value of the obsolete user option Man-notify, if set. |
153 | (defcustom Man-notify-method (if (boundp 'Man-notify) Man-notify 'friendly) | |
a88459cd | 154 | "Selects the behavior when manpage is ready. |
55535639 PJ |
155 | This variable may have one of the following values, where (sf) means |
156 | that the frames are switched, so the manpage is displayed in the frame | |
157 | where the man command was called from: | |
158 | ||
159 | newframe -- put the manpage in its own frame (see `Man-frame-parameters') | |
160 | pushy -- make the manpage the current buffer in the current window | |
161 | bully -- make the manpage the current buffer and only window (sf) | |
162 | aggressive -- make the manpage the current buffer in the other window (sf) | |
163 | friendly -- display manpage in the other window but don't make current (sf) | |
164 | polite -- don't display manpage, but prints message and beep when ready | |
165 | quiet -- like `polite', but don't beep | |
166 | meek -- make no indication that the manpage is ready | |
167 | ||
168 | Any other value of `Man-notify-method' is equivalent to `meek'." | |
169 | :type '(radio (const newframe) (const pushy) (const bully) | |
170 | (const aggressive) (const friendly) | |
171 | (const polite) (const quiet) (const meek)) | |
172 | :group 'man) | |
173 | ||
aec2bd36 | 174 | (defcustom Man-width nil |
a88459cd | 175 | "Number of columns for which manual pages should be formatted. |
aec2bd36 JL |
176 | If nil, the width of the window selected at the moment of man |
177 | invocation is used. If non-nil, the width of the frame selected | |
178 | at the moment of man invocation is used. The value also can be a | |
179 | positive integer." | |
180 | :type '(choice (const :tag "Window width" nil) | |
181 | (const :tag "Frame width" t) | |
182 | (integer :tag "Specific width" :value 65)) | |
183 | :group 'man) | |
184 | ||
55535639 | 185 | (defcustom Man-frame-parameters nil |
a88459cd | 186 | "Frame parameter list for creating a new frame for a manual page." |
55535639 PJ |
187 | :type 'sexp |
188 | :group 'man) | |
189 | ||
190 | (defcustom Man-downcase-section-letters-flag t | |
a88459cd | 191 | "Non-nil means letters in sections are converted to lower case. |
55535639 PJ |
192 | Some Un*x man commands can't handle uppercase letters in sections, for |
193 | example \"man 2V chmod\", but they are often displayed in the manpage | |
194 | with the upper case letter. When this variable is t, the section | |
195 | letter (e.g., \"2V\") is converted to lowercase (e.g., \"2v\") before | |
196 | being sent to the man background process." | |
197 | :type 'boolean | |
198 | :group 'man) | |
199 | ||
200 | (defcustom Man-circular-pages-flag t | |
a88459cd | 201 | "Non-nil means the manpage list is treated as circular for traversal." |
55535639 PJ |
202 | :type 'boolean |
203 | :group 'man) | |
204 | ||
205 | (defcustom Man-section-translations-alist | |
206 | (list | |
207 | '("3C++" . "3") | |
208 | ;; Some systems have a real 3x man section, so let's comment this. | |
209 | ;; '("3X" . "3") ; Xlib man pages | |
210 | '("3X11" . "3") | |
211 | '("1-UCB" . "")) | |
a88459cd | 212 | "Association list of bogus sections to real section numbers. |
55535639 PJ |
213 | Some manpages (e.g. the Sun C++ 2.1 manpages) have section numbers in |
214 | their references which Un*x `man' does not recognize. This | |
215 | association list is used to translate those sections, when found, to | |
216 | the associated section number." | |
217 | :type '(repeat (cons (string :tag "Bogus Section") | |
218 | (string :tag "Real Section"))) | |
219 | :group 'man) | |
220 | ||
ac2eceee | 221 | ;; FIXME see comments at ffap-c-path. |
4edd9faf | 222 | (defcustom Man-header-file-path |
ac2eceee GM |
223 | (let ((arch (with-temp-buffer |
224 | (when (eq 0 (ignore-errors | |
225 | (call-process "gcc" nil '(t nil) nil | |
226 | "-print-multiarch"))) | |
227 | (goto-char (point-min)) | |
228 | (buffer-substring (point) (line-end-position))))) | |
229 | (base '("/usr/include" "/usr/local/include"))) | |
230 | (if (zerop (length arch)) | |
231 | base | |
232 | (append base (list (expand-file-name arch "/usr/include"))))) | |
4edd9faf | 233 | "C Header file search path used in Man." |
ac2eceee | 234 | :version "24.1" ; add multiarch |
4edd9faf JB |
235 | :type '(repeat string) |
236 | :group 'man) | |
237 | ||
398a825b SM |
238 | (defcustom Man-name-local-regexp (concat "^" (regexp-opt '("NOM" "NAME")) "$") |
239 | "Regexp that matches the text that precedes the command's name. | |
45be326a | 240 | Used in `bookmark-set' to get the default bookmark name." |
2bed3f04 | 241 | :version "24.1" |
45be326a TV |
242 | :type 'string :group 'bookmark) |
243 | ||
dee4ef93 CY |
244 | (defcustom manual-program "man" |
245 | "Program used by `man' to produce man pages." | |
246 | :type 'string | |
247 | :group 'man) | |
55535639 | 248 | |
dee4ef93 CY |
249 | (defcustom Man-untabify-command "pr" |
250 | "Program used by `man' for untabifying." | |
251 | :type 'string | |
252 | :group 'man) | |
55535639 | 253 | |
dee4ef93 CY |
254 | (defcustom Man-untabify-command-args (list "-t" "-e") |
255 | "List of arguments to be passed to `Man-untabify-command' (which see)." | |
256 | :type '(repeat string) | |
257 | :group 'man) | |
55535639 | 258 | |
dee4ef93 CY |
259 | (defcustom Man-sed-command "sed" |
260 | "Program used by `man' to process sed scripts." | |
261 | :type 'string | |
262 | :group 'man) | |
55535639 | 263 | |
dee4ef93 CY |
264 | (defcustom Man-awk-command "awk" |
265 | "Program used by `man' to process awk scripts." | |
266 | :type 'string | |
267 | :group 'man) | |
55535639 | 268 | |
dee4ef93 CY |
269 | (defcustom Man-mode-hook nil |
270 | "Hook run when Man mode is enabled." | |
271 | :type 'hook | |
272 | :group 'man) | |
55535639 | 273 | |
dee4ef93 CY |
274 | (defcustom Man-cooked-hook nil |
275 | "Hook run after removing backspaces but before `Man-mode' processing." | |
276 | :type 'hook | |
277 | :group 'man) | |
55535639 | 278 | |
5f43c63c | 279 |