Commit | Line | Data |
---|---|---|
665a7c3b | 1 | ;;; man.el --- browse UNIX manual pages -*- coding: iso-8859-1 -*- |
55535639 | 2 | |
665a7c3b | 3 | ;; Copyright (C) 1993, 1994, 1996, 1997, 2001, 2003 Free Software Foundation, Inc. |
55535639 PJ |
4 | |
5 | ;; Author: Barry A. Warsaw <bwarsaw@cen.com> | |
6 | ;; Maintainer: FSF | |
7 | ;; Keywords: help | |
8 | ;; Adapted-By: ESR, pot | |
9 | ||
10 | ;; This file is part of GNU Emacs. | |
11 | ||
12 | ;; GNU Emacs is free software; you can redistribute it and/or modify | |
13 | ;; it under the terms of the GNU General Public License as published by | |
14 | ;; the Free Software Foundation; either version 2, or (at your option) | |
15 | ;; any later version. | |
16 | ||
17 | ;; GNU Emacs is distributed in the hope that it will be useful, | |
18 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of | |
19 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
20 | ;; GNU General Public License for more details. | |
21 | ||
22 | ;; You should have received a copy of the GNU General Public License | |
23 | ;; along with GNU Emacs; see the file COPYING. If not, write to the | |
24 | ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330, | |
25 | ;; Boston, MA 02111-1307, USA. | |
26 | ||
27 | ;;; Commentary: | |
28 | ||
29 | ;; This code provides a function, `man', with which you can browse | |
30 | ;; UNIX manual pages. Formatting is done in background so that you | |
31 | ;; can continue to use your Emacs while processing is going on. | |
32 | ;; | |
33 | ;; The mode also supports hypertext-like following of manual page SEE | |
34 | ;; ALSO references, and other features. See below or do `?' in a | |
35 | ;; manual page buffer for details. | |
36 | ||
37 | ;; ========== Credits and History ========== | |
38 | ;; In mid 1991, several people posted some interesting improvements to | |
39 | ;; man.el from the standard emacs 18.57 distribution. I liked many of | |
40 | ;; these, but wanted everything in one single package, so I decided | |
41 | ;; to incorporate them into a single manual browsing mode. While | |
42 | ;; much of the code here has been rewritten, and some features added, | |
43 | ;; these folks deserve lots of credit for providing the initial | |
44 | ;; excellent packages on which this one is based. | |
45 | ||
46 | ;; Nick Duffek <duffek@chaos.cs.brandeis.edu>, posted a very nice | |
47 | ;; improvement which retrieved and cleaned the manpages in a | |
48 | ;; background process, and which correctly deciphered such options as | |
49 | ;; man -k. | |
50 | ||
51 | ;; Eric Rose <erose@jessica.stanford.edu>, submitted manual.el which | |
52 | ;; provided a very nice manual browsing mode. | |
53 | ||
54 | ;; This package was available as `superman.el' from the LCD package | |
55 | ;; for some time before it was accepted into Emacs 19. The entry | |
56 | ;; point and some other names have been changed to make it a drop-in | |
57 | ;; replacement for the old man.el package. | |
58 | ||
59 | ;; Francesco Potorti` <pot@cnuce.cnr.it> cleaned it up thoroughly, | |
60 | ;; making it faster, more robust and more tolerant of different | |
61 | ;; systems' man idiosyncrasies. | |
62 | ||
63 | ;; ========== Features ========== | |
64 | ;; + Runs "man" in the background and pipes the results through a | |
65 | ;; series of sed and awk scripts so that all retrieving and cleaning | |
66 | ;; is done in the background. The cleaning commands are configurable. | |
67 | ;; + Syntax is the same as Un*x man | |
68 | ;; + Functionality is the same as Un*x man, including "man -k" and | |
69 | ;; "man <section>", etc. | |
70 | ;; + Provides a manual browsing mode with keybindings for traversing | |
71 | ;; the sections of a manpage, following references in the SEE ALSO | |
72 | ;; section, and more. | |
73 | ;; + Multiple manpages created with the same man command are put into | |
74 | ;; a narrowed buffer circular list. | |
75 | ||
76 | ;; ============= TODO =========== | |
77 | ;; - Add a command for printing. | |
78 | ;; - The awk script deletes multiple blank lines. This behaviour does | |
79 | ;; not allow to understand if there was indeed a blank line at the | |
80 | ;; end or beginning of a page (after the header, or before the | |
81 | ;; footer). A different algorithm should be used. It is easy to | |
82 | ;; compute how many blank lines there are before and after the page | |
83 | ;; headers, and after the page footer. But it is possible to compute | |
72397ff1 | 84 | ;; the number of blank lines before the page footer by heuristics |
55535639 PJ |
85 | ;; only. Is it worth doing? |
86 | ;; - Allow a user option to mean that all the manpages should go in | |
87 | ;; the same buffer, where they can be browsed with M-n and M-p. | |
88 | ;; - Allow completion on the manpage name when calling man. This | |
89 | ;; requires a reliable list of places where manpages can be found. The | |
90 | ;; drawback would be that if the list is not complete, the user might | |
91 | ;; be led to believe that the manpages in the missing directories do | |
92 | ;; not exist. | |
93 | ||
94 | \f | |
95 | ;;; Code: | |
96 | ||
97 | (require 'assoc) | |
4edd9faf | 98 | (require 'button) |
55535639 PJ |
99 | |
100 | ;; vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv | |
101 | ;; empty defvars (keep the compiler quiet) | |
102 | ||
103 | (defgroup man nil | |
104 | "Browse UNIX manual pages." | |
105 | :prefix "Man-" | |
106 | :group 'help) | |
107 | ||
108 | ||
109 | (defvar Man-notify) | |
110 | (defvar Man-current-page) | |
111 | (defvar Man-page-list) | |
112 | (defcustom Man-filter-list nil | |
113 | "*Manpage cleaning filter command phrases. | |
114 | This variable contains a list of the following form: | |
115 | ||
116 | '((command-string phrase-string*)*) | |
117 | ||
118 | Each phrase-string is concatenated onto the command-string to form a | |
119 | command filter. The (standard) output (and standard error) of the Un*x | |
120 | man command is piped through each command filter in the order the | |
121 | commands appear in the association list. The final output is placed in | |
122 | the manpage buffer." | |
123 | :type '(repeat (list (string :tag "Command String") | |
124 | (repeat :inline t | |
125 | (string :tag "Phrase String")))) | |
126 | :group 'man) | |
127 | ||
128 | (defvar Man-original-frame) | |
129 | (defvar Man-arguments) | |
130 | (defvar Man-sections-alist) | |
131 | (defvar Man-refpages-alist) | |
132 | (defvar Man-uses-untabify-flag t | |
133 | "Non-nil means use `untabify' instead of `Man-untabify-command'.") | |
134 | (defvar Man-page-mode-string) | |
135 | (defvar Man-sed-script nil | |
136 | "Script for sed to nuke backspaces and ANSI codes from manpages.") | |
137 | ||
138 | ;; vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv | |
139 | ;; user variables | |
140 | ||
141 | (defcustom Man-fontify-manpage-flag t | |
142 | "*Non-nil means make up the manpage with fonts." | |
143 | :type 'boolean | |
144 | :group 'man) | |
145 | ||
146 | (defcustom Man-overstrike-face 'bold | |
147 | "*Face to use when fontifying overstrike." | |
148 | :type 'face | |
149 | :group 'man) | |
150 | ||
151 | (defcustom Man-underline-face 'underline | |
152 | "*Face to use when fontifying underlining." | |
153 | :type 'face | |
154 | :group 'man) | |
155 | ||
156 | ;; Use the value of the obsolete user option Man-notify, if set. | |
157 | (defcustom Man-notify-method (if (boundp 'Man-notify) Man-notify 'friendly) | |
158 | "*Selects the behavior when manpage is ready. | |
159 | This variable may have one of the following values, where (sf) means | |
160 | that the frames are switched, so the manpage is displayed in the frame | |
161 | where the man command was called from: | |
162 | ||
163 | newframe -- put the manpage in its own frame (see `Man-frame-parameters') | |
164 | pushy -- make the manpage the current buffer in the current window | |
165 | bully -- make the manpage the current buffer and only window (sf) | |
166 | aggressive -- make the manpage the current buffer in the other window (sf) | |
167 | friendly -- display manpage in the other window but don't make current (sf) | |
168 | polite -- don't display manpage, but prints message and beep when ready | |
169 | quiet -- like `polite', but don't beep | |
170 | meek -- make no indication that the manpage is ready | |
171 | ||
172 | Any other value of `Man-notify-method' is equivalent to `meek'." | |
173 | :type '(radio (const newframe) (const pushy) (const bully) | |
174 | (const aggressive) (const friendly) | |
175 | (const polite) (const quiet) (const meek)) | |
176 | :group 'man) | |
177 | ||
178 | (defcustom Man-frame-parameters nil | |
179 | "*Frame parameter list for creating a new frame for a manual page." | |
180 | :type 'sexp | |
181 | :group 'man) | |
182 | ||
183 | (defcustom Man-downcase-section-letters-flag t | |
184 | "*Non-nil means letters in sections are converted to lower case. | |
185 | Some Un*x man commands can't handle uppercase letters in sections, for | |
186 | example \"man 2V chmod\", but they are often displayed in the manpage | |
187 | with the upper case letter. When this variable is t, the section | |
188 | letter (e.g., \"2V\") is converted to lowercase (e.g., \"2v\") before | |
189 | being sent to the man background process." | |
190 | :type 'boolean | |
191 | :group 'man) | |
192 | ||
193 | (defcustom Man-circular-pages-flag t | |
194 | "*Non-nil means the manpage list is treated as circular for traversal." | |
195 | :type 'boolean | |
196 | :group 'man) | |
197 | ||
198 | (defcustom Man-section-translations-alist | |
199 | (list | |
200 | '("3C++" . "3") | |
201 | ;; Some systems have a real 3x man section, so let's comment this. | |
202 | ;; '("3X" . "3") ; Xlib man pages | |
203 | '("3X11" . "3") | |
204 | '("1-UCB" . "")) | |
205 | "*Association list of bogus sections to real section numbers. | |
206 | Some manpages (e.g. the Sun C++ 2.1 manpages) have section numbers in | |
207 | their references which Un*x `man' does not recognize. This | |
208 | association list is used to translate those sections, when found, to | |
209 | the associated section number." | |
210 | :type '(repeat (cons (string :tag "Bogus Section") | |
211 | (string :tag "Real Section"))) | |
212 | :group 'man) | |
213 | ||
4edd9faf JB |
214 | (defcustom Man-header-file-path |
215 | '("/usr/include" "/usr/local/include") | |
216 | "C Header file search path used in Man." | |
217 | :type '(repeat string) | |
218 | :group 'man) | |
219 | ||
55535639 PJ |
220 | (defvar manual-program "man" |
221 | "The name of the program that produces man pages.") | |
222 | ||
223 | (defvar Man-untabify-command "pr" | |
224 | "Command used for untabifying.") | |
225 | ||
226 | (defvar Man-untabify-command-args (list "-t" "-e") | |
227 | "List of arguments to be passed to `Man-untabify-command' (which see).") | |
228 | ||
229 | (defvar Man-sed-command "sed" | |
230 | "Command used for processing sed scripts.") | |
231 | ||
232 | (defvar Man-awk-command "awk" | |
233 | "Command used for processing awk scripts.") | |
234 | ||
55535639 PJ |
235 | (defvar Man-mode-map nil |
236 | "Keymap for Man mode.") | |
237 | ||
238 | (defvar Man-mode-hook nil | |
239 | "Hook run when Man mode is enabled.") | |
240 | ||
241 | (defvar Man-cooked-hook nil | |
242 | "Hook run after removing backspaces but before `Man-mode' processing.") | |
243 | ||
50099a09 | 244 |