|
428
|
1 ;;; help-macro.el --- Makes command line help such as help-for-help
|
|
|
2
|
|
|
3 ;; Copyright (C) 1993, 1994, 1997 Free Software Foundation, Inc.
|
|
|
4
|
|
|
5 ;; Author: Lynn Slater <lrs@indetech.com>
|
|
|
6 ;; Maintainer: FSF
|
|
|
7 ;; Created: : Mon Oct 1 11:42:39 1990
|
|
|
8 ;; Adapted-By: ESR
|
|
|
9
|
|
|
10 ;; This file is part of XEmacs.
|
|
|
11
|
|
|
12 ;; XEmacs 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 ;; XEmacs 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 XEmacs; 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 ;;; Synched up with: FSF 20.2.
|
|
|
30
|
|
|
31 ;; This file supplies the macro make-help-screen which constructs
|
|
|
32 ;; single character dispatching with browsable help such as that provided
|
|
|
33 ;; by help-for-help. This can be used to make many modes easier to use; for
|
|
|
34 ;; example, the Gnu Emacs Empire Tool uses this for every "nested" mode map
|
|
|
35 ;; called from the main mode map.
|
|
|
36
|
|
|
37 ;; The name of this package was changed from help-screen.el to
|
|
|
38 ;; help-macro.el in order to fit in a 14-character limit.
|
|
|
39
|
|
|
40 ;;-> *********************** Example of use *********************************
|
|
|
41
|
|
|
42 ;;->(make-help-screen help-for-empire-redistribute-map
|
|
|
43 ;;-> "c:civ m:mil p:population f:food ?"
|
|
|
44 ;;-> "You have discovered the GEET redistribution commands
|
|
|
45 ;;-> From here, you can use the following options:
|
|
|
46 ;;->
|
|
|
47 ;;->c Redistribute civs from overfull sectors into connected underfull ones
|
|
|
48 ;;-> The functions typically named by empire-ideal-civ-fcn control
|
|
|
49 ;;-> based in part on empire-sector-civ-threshold
|
|
|
50 ;;->m Redistribute military using levels given by empire-ideal-mil-fcn
|
|
|
51 ;;->p Redistribute excess population to highways for max pop growth
|
|
|
52 ;;-> Excess is any sector so full babies will not be born.
|
|
|
53 ;;->f Even out food on highways to highway min and leave levels
|
|
|
54 ;;-> This is good to pump max food to all warehouses/dist pts
|
|
|
55 ;;->
|
|
|
56 ;;->
|
|
|
57 ;;->Use \\[help-for-empire-redistribute-map] for help on redistribution.
|
|
|
58 ;;->Use \\[help-for-empire-extract-map] for help on data extraction.
|
|
|
59 ;;->Please use \\[describe-key] to find out more about any of the other keys."
|
|
|
60 ;;-> empire-shell-redistribute-map)
|
|
|
61
|
|
|
62 ;;-> (define-key c-mp "\C-h" 'help-for-empire-redistribute-map)
|
|
|
63 ;;-> (define-key c-mp help-character 'help-for-empire-redistribute-map)
|
|
|
64
|
|
|
65 ;;; Code:
|
|
|
66
|
|
|
67 (provide 'help-macro)
|
|
|
68
|
|
|
69 ;;;###autoload
|
|
|
70 (defcustom three-step-help t
|
|
|
71 "*Non-nil means give more info about Help command in three steps.
|
|
|
72 The three steps are simple prompt, prompt with all options,
|
|
|
73 and window listing and describing the options.
|
|
|
74 A value of nil means skip the middle step, so that
|
|
|
75 \\[help-command] \\[help-command] gives the window that lists the options."
|
|
|
76 :type 'boolean
|
|
|
77 :group 'help-appearance)
|
|
|
78
|
|
|
79 (defmacro make-help-screen (fname help-line help-text helped-map)
|
|
|
80 "Construct help-menu function name FNAME.
|
|
502
|
81 When invoked, FNAME shows HELP-LINE and reads a command using
|
|
|
82 HELPED-MAP. If the command is the help character, FNAME displays
|
|
|
83 HELP-TEXT and continues trying to read a command using HELPED-MAP.
|
|
|
84 When FNAME finally does get a command, it executes that command and
|
|
|
85 then returns. As of 21.5 (or 21.4?), HELP-LINE and HELP-TEXT are
|
|
|
86 `eval'd, just like for a function call. This allows you to place
|
|
|
87 Lisp expressions in those arguments."
|
|
428
|
88 `(defun ,fname ()
|
|
502
|
89 ,(eval help-text)
|
|
428
|
90 (interactive)
|
|
|
91 (flet ((help-read-key (prompt)
|
|
|
92 ;; This is in `flet' to avoid problems with autoloading.
|
|
|
93 ;; #### The function is ill-conceived -- there should be
|
|
|
94 ;; a way to do it without all the hassle!
|
|
|
95 (let (events)
|
|
|
96 (while (not (key-press-event-p
|
|
|
97 (aref (setq events (read-key-sequence prompt)) 0)))
|
|
|
98 ;; Mouse clicks are not part of the help feature, so
|
|
|
99 ;; reexecute them in the standard environment.
|
|
|
100 (mapc 'dispatch-event events))
|
|
|
101 (let ((key (nconc (event-modifiers (aref events 0))
|
|
|
102 (list (event-key (aref events 0))))))
|
|
|
103 ;; Make the HELP key translate to C-h.
|
|
|
104 (when (lookup-key function-key-map key)
|
|
|
105 (setq key (lookup-key function-key-map key)))
|
|
|
106 (if (eq (length key) 1)
|
|
|
107 (car key)
|
|
|
108 key)))))
|
|
|
109 (let ((line-prompt
|
|
502
|
110 (substitute-command-keys ,(eval help-line))))
|
|
428
|
111 (when three-step-help
|
|
|
112 (message "%s" line-prompt))
|
|
2275
|
113 (let* ((help-screen
|
|
|
114 (condition-case nil
|
|
|
115 (documentation (quote ,fname))
|
|
|
116 (void-function "(alias for undefined function)")
|
|
|
117 (error "(unexpected error from `documention')")))
|
|
428
|
118 ;; We bind overriding-local-map for very small
|
|
|
119 ;; sections, *excluding* where we switch buffers and
|
|
|
120 ;; where we execute the chosen help command.
|
|
|
121 (local-map (make-sparse-keymap))
|
|
|
122 (minor-mode-map-alist nil)
|
|
|
123 (prev-frame (selected-frame))
|
|
|
124 config new-frame key)
|
|
|
125 (unwind-protect
|
|
|
126 (progn
|
|
|
127 (set-keymap-parents local-map (list ,helped-map))
|
|
|
128 (cond (three-step-help
|
|
|
129 (let* ((overriding-local-map local-map))
|
|
|
130 (setq key (help-read-key nil))))
|
|
|
131 (t
|
|
|
132 (setq key ??)))
|
|
|
133 (when (or (equal key ??)
|
|
|
134 (equal key (list help-char)))
|
|
|
135 (setq config (current-window-configuration))
|
|
|
136 (switch-to-buffer-other-window "*Help*")
|
|
|
137 (and (not (eq (window-frame (selected-window))
|
|
|
138 prev-frame))
|
|
|
139 (setq new-frame (window-frame (selected-window))
|
|
|
140 config nil))
|
|
|
141 (setq buffer-read-only nil)
|
|
|
142 (erase-buffer)
|
|
|
143 (insert help-screen)
|
|
|
144 (help-mode)
|
|
|
145 (goto-char (point-min))
|
|
|
146 (while (member key `((,help-char) ?? (control v) space ?\177
|
|
|
147 delete backspace (meta v)))
|
|
|
148 (ignore-errors
|
|
|
149 (cond ((member key '((control v) space))
|
|
|
150 (scroll-up))
|
|
|
151 ((member key '(?\177 delete (meta v) backspace))
|
|
|
152 (scroll-down))))
|
|
|
153 (let ((cursor-in-echo-area t)
|
|
|
154 (overriding-local-map local-map))
|
|
|
155 (setq key (help-read-key
|
|
|
156 (format "Type one of the options listed%s: "
|
|
|
157 (if (pos-visible-in-window-p
|
|
|
158 (point-max))
|
|
|
159 "" " or Space to scroll")))))))
|
|
|
160 ;; We don't need the prompt any more.
|
|
|
161 (message nil)
|
|
|
162 (let ((defn (lookup-key local-map key)))
|
|
|
163 (cond (defn
|
|
|
164 (when config
|
|
|
165 (set-window-configuration config)
|
|
|
166 (setq config nil))
|
|
|
167 (when new-frame
|
|
|
168 (iconify-frame new-frame)
|
|
|
169 (setq new-frame nil))
|
|
|
170 (call-interactively defn))
|
|
|
171 (t
|
|
|
172 (ding)))))
|
|
|
173 (and (get-buffer "*Help*")
|
|
|
174 (bury-buffer "*Help*"))
|
|
|
175 (and new-frame (iconify-frame new-frame))
|
|
|
176 (and config
|
|
|
177 (set-window-configuration config))))))))
|
|
|
178
|
|
|
179 ;;; help-macro.el
|
|
|
180
|
