(gc_sweep): Add comment.
[emacs.git] / lisp / woman.el
blobe98ab8255aaae10de14f600f0e9603583a16b1f8
1 ;;; woman.el --- browse UN*X manual pages `wo (without) man'
3 ;; Copyright (C) 2000 Free Software Foundation, Inc.
5 ;; Author: Francis J. Wright <F.J.Wright@Maths.QMW.ac.uk>
6 ;; Maintainer: Francis J. Wright <F.J.Wright@Maths.QMW.ac.uk>
7 ;; Keywords: help, man, UN*X, manual
8 ;; Adapted-By: Eli Zaretskii <eliz@is.elta.co.il>
9 ;; Version: see `woman-version'
10 ;; URL: http://centaur.maths.qmw.ac.uk/Emacs/WoMan/
12 ;; This file is part of GNU Emacs.
14 ;; GNU Emacs is free software; you can redistribute it and/or modify
15 ;; it under the terms of the GNU General Public License as published by
16 ;; the Free Software Foundation; either version 2, or (at your option)
17 ;; any later version.
19 ;; GNU Emacs is distributed in the hope that it will be useful,
20 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
21 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22 ;; GNU General Public License for more details.
24 ;; You should have received a copy of the GNU General Public License
25 ;; along with GNU Emacs; see the file COPYING. If not, write to the
26 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
27 ;; Boston, MA 02111-1307, USA.
29 ;;; Commentary:
31 ;; WoMan implements a subset of the formatting performed by the Emacs
32 ;; `man' (or `manual-entry') command to format a UN*X manual `page'
33 ;; for display, but without calling any external programs. It is
34 ;; intended to emulate the whole of the -man macro package, plus those
35 ;; ?roff requests that are most commonly used in man pages. However,
36 ;; the emulation is modified to include the reformatting done by the
37 ;; Emacs `man' command. No hyphenation is performed.
39 ;; Advantages
41 ;; Much more direct, does not require any external programs.
42 ;; Supports completion on man page names.
44 ;; Disadvantages
46 ;; Not a complete emulation. Currently no support for eqn or tbl.
47 ;; Slightly slower for large man pages (but usually faster for
48 ;; small- and medium-size pages).
50 ;; This browser works quite well on simple well-written man files. It
51 ;; works less well on idiosyncratic files that `break the rules' or
52 ;; use the more obscure ?roff requests directly. Current test results
53 ;; are available in the file woman.status.
55 ;; WoMan supports the use of compressed man files via
56 ;; `auto-compression-mode' by turning it on if necessary. But you may
57 ;; need to adjust the user option `woman-file-compression-regexp'.
59 ;; Read on for (currently) the only documentation for WoMan!
61 ;; See also the documentation for the WoMan interactive commands and
62 ;; user option variables, all of which begin with the prefix `woman-'.
63 ;; This can be done most easily by loading WoMan and then running the
64 ;; command `woman-mini-help', or selecting the WoMan menu option `Mini
65 ;; Help' when WoMan is running.
67 ;; WoMan is still under development! Please let me know what doesn't
68 ;; work -- I am adding and improving functionality as testing shows
69 ;; that it is necessary. See below for guidance on reporting bugs.
71 ;; Recommended use
72 ;; ===============
74 ;; Put this in your .emacs:
75 ;; (autoload 'woman "woman"
76 ;; "Decode and browse a UN*X man page." t)
77 ;; (autoload 'woman-find-file "woman"
78 ;; "Find, decode and browse a specific UN*X man-page file." t)
80 ;; Then either (1 -- *RECOMMENDED*): If the `MANPATH' environment
81 ;; variable is set then WoMan will use it; otherwise you may need to
82 ;; reset the Lisp variable `woman-manpath', and you may also want to
83 ;; set the Lisp variable `woman-path'. Please see the online
84 ;; documentation for these variables. Now you can execute the
85 ;; extended command `woman', enter or select a manual entry topic,
86 ;; using completion, and if necessary select a filename, using
87 ;; completion. By default, WoMan suggests the word nearest to the
88 ;; cursor in the current buffer as the topic.
90 ;; Or (2): Execute the extended command `woman-find-file' and enter a
91 ;; filename, using completion. This mode of execution may be useful
92 ;; for temporary files outside the standard UN*X manual directory
93 ;; structure.
95 ;; Or (3): Put the next two sexpr's in your .emacs:
96 ;; (autoload 'woman-dired-find-file "woman"
97 ;; "In dired, run the WoMan man-page browser on this file." t)
98 ;; (add-hook 'dired-mode-hook
99 ;; (lambda ()
100 ;; (define-key dired-mode-map "W" 'woman-dired-find-file)))
101 ;; and open the directory containing the man page file using dired,
102 ;; put the cursor on the file, and press `W'.
104 ;; In each case, the result should (!) be a buffer in Man mode showing
105 ;; a formatted manual entry. When called from WoMan, Man mode should
106 ;; work as advertised, but modified where necessary in the context of
107 ;; WoMan. (However, `Man' will still invoke the standard Emacs
108 ;; manual-browsing facility rather than `WoMan' -- this is
109 ;; intentional!)
111 ;; (By default, WoMan will automatically define the dired keys "W" and
112 ;; "w" when it loads, but only if they are not already defined. This
113 ;; behaviour is controlled by the user option `woman-dired-keys'.
114 ;; Note that the `dired-x' (dired extra) package binds
115 ;; `dired-copy-filename-as-kill' to the key "w" (as pointed out by Jim
116 ;; Davidson), although "W" appears to be really unused. The `dired-x'
117 ;; package will over-write the WoMan binding to "w", whereas (by
118 ;; default) WoMan will not overwrite the `dired-x' binding.)
120 ;; The following is based on suggestions by Guy Gascoigne-Piggford and
121 ;; Juanma Barranquero. If you really want to square the man-woman
122 ;; circle then you might care to define the following bash function in
123 ;; .bashrc:
125 ;; man() { gnudoit -q '(raise-frame (selected-frame)) (woman' \"$1\" ')' ; }
127 ;; If you use Microsoft COMMAND.COM then you can create a file called
128 ;; man.bat somewhere in your path containing the two lines:
130 ;; @echo off
131 ;; gnudoit -q (raise-frame (selected-frame)) (woman \"%1\")
133 ;; and then (e.g. from a command prompt or the Run... option in the
134 ;; Start menu) just execute
136 ;; man man_page_name
139 ;; Using the `word at point' as a topic suggestion
140 ;; ===============================================
142 ;; By default, the `woman' command uses the word nearest to point in
143 ;; the current buffer as a suggestion for the topic to look up. The
144 ;; topic must be confirmed or edited in the minibuffer. This
145 ;; suggestion can be turned off, or `woman' can use the suggested
146 ;; topic without confirmation* if possible, by setting the user-option
147 ;; `woman-topic-at-point' to nil or t respectively. (Its default
148 ;; value is neither nil nor t, meaning ask for confirmation.)
150 ;; [* Thanks to Benjamin Riefenstahl for suggesting this
151 ;; functionality.]
153 ;; The variable `woman-topic-at-point' can be rebound locally, which
154 ;; may be useful to provide special private key bindings, e.g.
156 ;; (global-set-key "\C-cw"
157 ;; (lambda ()
158 ;; (interactive)
159 ;; (let ((woman-topic-at-point t))
160 ;; (woman)))))
163 ;; Customization, Hooks and Imenu
164 ;; ==============================
166 ;; WoMan supports the GNU Emacs 20+ customization facility, and puts
167 ;; a customization group called `WoMan' in the `Help' group under the
168 ;; top-level `Emacs' group. In order to be able to customize WoMan
169 ;; without first loading it, add the following sexp to your .emacs:
171 ;; (defgroup woman nil
172 ;; "Browse UNIX manual pages `wo (without) man'."
173 ;; :tag "WoMan" :group 'help :load "woman")
176 ;; WoMan currently runs two hooks: `woman-pre-format-hook' immediately
177 ;; before formatting a buffer and `woman-post-format-hook' immediately
178 ;; after formatting a buffer. These hooks can be used for special
179 ;; customizations that require code to be executed, etc., although
180 ;; most customization should be possible by setting WoMan user option
181 ;; variables, e.g. in `.emacs' and should NOT require the use of the
182 ;; hooks. `woman-pre-format-hook' might be appropriate for face
183 ;; customization, whereas `woman-post-format-hook' might be
184 ;; appropriate for installing a dynamic menu using `imenu' (although
185 ;; it is better to use the built-in WoMan imenu support).
187 ;; The WoMan menu provides an option to make a contents menu for the
188 ;; current man page (using imenu). Alternatively, if you set the
189 ;; variable `woman-imenu' to `t' then WoMan will do it automatically
190 ;; for every man page. The menu title is the value of the variable
191 ;; `woman-imenu-title', which is "CONTENTS" by default. By default,
192 ;; the menu shows manual sections and subsections, but you can change
193 ;; this by changing the value of `woman-imenu-generic-expression'.
194 ;; This facility is not yet widely tested and may be fooled by obscure
195 ;; man pages that `break the rules'.
197 ;; WoMan is configured not to replace spaces in an imenu *Completion*
198 ;; buffer. For further documentation of the use of imenu, such as
199 ;; menu sorting, see the source file imenu.el, which is distributed
200 ;; with GNU Emacs.
202 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
204 ;; Howard Melman made (essentially) the following suggestions, which
205 ;; are slightly different from the expression that I currently use.
206 ;; You may prefer one of Howard's suggestions, which I think assume
207 ;; that `case-fold-search' is `t' (which it is by default):
209 ;; (setq woman-imenu-generic-expression
210 ;; '((nil "^\\( \\)?\\([A-Z][A-Z ]+[A-Z]\\)[ \t]*$" 2)))
212 ;; will give support for .SH and .SS, though it won't show the heading
213 ;; name hierarchy. If you just want .SH in the imenu then use:
215 ;; (setq woman-imenu-generic-expression
216 ;; '((nil "^\\([A-Z][A-Z ]+[A-Z]\\)[ \t]*$" 1)))
218 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
221 ;; Vertical spacing and blank lines
222 ;; ================================
224 ;; The number of consecutive blank lines in the formatted buffer
225 ;; should be either 0 or 1. A blank line should leave a space like
226 ;; .sp 1 (p. 14). Current policy is to output vertical space only
227 ;; immediately before text is output.
230 ;; Horizontal and vertical spacing and resolution
231 ;; ==============================================
233 ;; WoMan currently assumes 10 characters per inch horizontally, hence
234 ;; a horizontal resolution of 24 basic units, and 5 lines per inch
235 ;; vertically, hence a vertical resolution of 48 basic units. (nroff
236 ;; uses 240 per inch).
239 ;; The *WoMan-Log* buffer
240 ;; ======================
242 ;; This is modelled on the byte-compiler. It logs all files formatted
243 ;; by WoMan, and if WoMan finds anything that it cannot handle then it
244 ;; writes a warning to this buffer. If the variable `woman-show-log'
245 ;; is non-nil (by default it is `nil') then WoMan automatically
246 ;; displays this buffer. Many WoMan warnings can be completely
247 ;; ignored, because they are reporting the fact that WoMan has ignored
248 ;; requests that it is correct to ignore. In some future version this
249 ;; level of paranoia will be reduced, but not until WoMan is more
250 ;; reliable. At present, all warnings should be treated with some
251 ;; suspicion. Uninterpreted escape sequences are also logged (in some
252 ;; cases).
254 ;; Uninterpreted ?roff requests can optionally be left in the
255 ;; formatted buffer to indicate precisely where they occur by
256 ;; resetting the variable `woman-ignore' to `nil' (by default it is
257 ;; `t').
259 ;; Automatic initiation of woman decoding
261 ;; (Probably not a good idea. If you use it, be careful!)
263 ;; Put something like this in your .emacs. The call to
264 ;; set-visited-file-name is to avoid font-locking triggered by
265 ;; automatic major mode selection.
267 ;; (autoload 'woman-decode-region "woman")
269 ;; (setq format-alist
270 ;; (cons
271 ;; '(man "UN*X man-page source format" "\\.\\(TH\\|ig\\) "
272 ;; woman-decode-region nil nil
273 ;; (lambda (arg)
274 ;; set-visited-file-name
275 ;; (file-name-sans-extension buffer-file-name)))))
276 ;; format-alist))
279 ;; Reporting Bugs
280 ;; ==============
282 ;; If WoMan fails completely, or formats a file incorrectly
283 ;; (i.e. obviously wrongly or significantly differently from man) or
284 ;; inelegantly, then please
286 ;; (a) check that you are running the latest version of woman.el
287 ;; available from my web site (see above),
289 ;; (b) check that the problem is not already described in the file
290 ;; woman.status, also available from my web site.
292 ;; If both of the above are true then please email me the entry from
293 ;; the *WoMan-Log* buffer relating to the problem file, together with
294 ;; a brief description of the problem. Please indicate where you got
295 ;; the source file from, but do not send it to me unless I ask you to!
296 ;; Thanks. (There is at present no automated bug-reporting facility
297 ;; for WoMan.)
299 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
301 ;; NOTE:
303 ;; CASE-DEPENDENCE OF FILENAMES. By default, WoMan ignores case in
304 ;; file pathnames only when it seems appropriate. MS-Windows users
305 ;; who want complete case independence should set the NTEmacs variable
306 ;; `w32-downcase-file-names' to `t' and use all lower case when
307 ;; setting WoMan file paths.
309 ;; (1) INCOMPATIBLE CHANGE! WoMan no longer uses a persistent topic
310 ;; cache by default. (It caused too much confusion!) Explicitly set
311 ;; the variable `woman-cache-filename' to save the cache between Emacs
312 ;; sessions. This is recommended only if the command `woman' is too
313 ;; slow the first time that it is run in an Emacs session, while it
314 ;; builds its cache in main memory, which MAY be VERY slow.
316 ;; (2) The user option `woman-cache-level' controls the amount of
317 ;; information cached (in main memory and, optionally, saved to disc).
319 ;; (3) UPDATING THE CACHE. A prefix argument always causes the
320 ;; `woman' command (only) to rebuild its topic cache, and to re-save
321 ;; it to `woman-cache-filename' if this variable has a non-nil value.
322 ;; This is necessary if the NAMES (not contents) of any of the
323 ;; directories or files in the paths specified by `woman-manpath' or
324 ;; `woman-path' change. If WoMan user options that affect the cache
325 ;; are changed then WoMan will automatically update its cache file on
326 ;; disc (if one is in use) the next time it is run in a new Emacs
327 ;; session.
329 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
332 ;; TO DO
333 ;; =====
335 ;; Reconsider case sensitivity of file names.
336 ;; MUST PROCESS .if, .nr IN ORDER ENCOUNTERED IN FILE! (rcsfile, mf).
337 ;; Allow general delimiter in `\v', cf. `\h'.
338 ;; Improve major-mode documentation.
339 ;; Pre-process conditionals in macro bodies if possible for speed?
340 ;; Emulate some preprocessor support for tbl (.TS/.TE) and eqn (.EQ/.EN)
341 ;; Re-write filling and adjusting code!
342 ;; Allow word wrap at comma (for long option lists)?
343 ;; Buffer list handling not quite right.
344 ;; Make 10 or 12 pitch (cpi) optional -- 12 => ll = 78
345 ;; Use unpaddable space for tabbing?
346 ;; Tidy up handling of fonts when filling and adjusting
347 ;; -- see text/text properties?
348 ;; Improve speed
349 ;; Add font-lock support (for quoted strings, etc.)?
350 ;; Optionally save large files in enriched format?
351 ;; Add apropos facility by searching NAME (?) entry in man files?
352 ;; Documentation -- optional auto-display of formatted WoMan man page?
353 ;; Implement a bug reporter?
354 ;; Support diversion and traps (to some extent) - for Tcl/tk pages?
355 ;; Add a menu of WoMan buffers?
356 ;; Fix .fc properly?
359 ;; Implementation strategy [this description is now well out of date!]
360 ;; -- three main passes, each to process respectively:
362 ;; 1) non-breaking `.' requests including font macros
363 ;; 2) \ escape sequences, mainly special characters and font changes
364 ;; 3) breaking `.' requests, mainly filling and justification
366 ;; For each pass, a control function finds and pre-processes the
367 ;; escape or request and then calls the appropriate function to
368 ;; perform the required formatting. Based originally on enriched.el
369 ;; and format.el.
371 ;; The background information that made this project possible is
372 ;; freely available courtesy of Bell Labs from
373 ;; http://cm.bell-labs.com/7thEdMan/
376 ;; Acknowledgements
377 ;; ================
379 ;; For Heather, Kathryn and Madelyn, the women in my life
380 ;; (although they will probably never use it)!
382 ;; I also thank the following for helpful suggestions, bug reports,
383 ;; code fragments, general interest, etc.:
384 ;; Jari Aalto <jari.aalto@cs.tpu.fi>
385 ;; Dean Andrews <dean@dra.com>
386 ;; Juanma Barranquero <barranquero@laley-actualidad.es>
387 ;; Karl Berry <kb@cs.umb.edu>
388 ;; Jim Chapman <jchapman@netcomuk.co.uk>
389 ;; Frederic Corne <frederic.corne@erli.fr>
390 ;; Peter Craft <craft@alacritech.com>
391 ;; Charles Curley <ccurley@trib.com>
392 ;; Jim Davidson <jdavidso@teknowledge.com>
393 ;; Kevin D'Elia <Kevin.DElia@mci.com>
394 ;; John Fitch <jpff@maths.bath.ac.uk>
395 ;; Hans Frosch <jwfrosch@rish.b17c.ingr.com>
396 ;; Guy Gascoigne-Piggford <ggp@informix.com>
397 ;; Brian Gorka <gorkab@sanchez.com>
398 ;; Nicolai Henriksen <nhe@lyngso-industri.dk>
399 ;; Thomas Herchenroeder <the@software-ag.de>
400 ;; Alexander Hinds <ahinds@thegrid.net>
401 ;; Stefan Hornburg <sth@hacon.de>
402 ;; Theodore Jump <tjump@cais.com>
403 ;; Paul Kinnucan <paulk@mathworks.com>
404 ;; Jonas Linde <jonas@init.se>
405 ;; Andrew McRae <andrewm@optimation.co.nz>
406 ;; Howard Melman <howard@silverstream.com>
407 ;; Dennis Pixton <dennis@math.binghamton.edu>
408 ;; T. V. Raman <raman@Adobe.COM>
409 ;; Bruce Ravel <bruce.ravel@nist.gov>
410 ;; Benjamin Riefenstahl <benny@crocodial.de>
411 ;; Kevin Ruland <kruland@seistl.com>
412 ;; Tom Schutter <tom@platte.com>
413 ;; Wei-Xue Shi <wxshi@ma.neweb.ne.jp>
414 ;; Fabio Somenzi <fabio@joplin.colorado.edu>
415 ;; Karel Sprenger <ks@ic.uva.nl>
416 ;; Chris Szurgot <szurgot@itribe.net>
417 ;; Paul A. Thompson <pat@po.cwru.edu>
418 ;; Arrigo Triulzi <arrigo@maths.qmw.ac.uk>
419 ;; Geoff Voelker <voelker@cs.washington.edu>
420 ;; Eli Zaretskii <eliz@is.elta.co.il>
422 (defvar woman-version "0.54 (beta)" "WoMan version information.")
424 ;;; History:
425 ;; For recent change log see end of file.
428 ;;; Code:
430 (require 'man)
431 (eval-when-compile ; to avoid compiler warnings
432 (require 'dired)
433 (require 'apropos))
435 (defun woman-mapcan (fn x)
436 "Return concatenated list of FN applied to successive `car' elements of X.
437 FN must return a list, cons or nil. Useful for splicing into a list."
438 ;; Based on the Standard Lisp function MAPCAN but with args swapped!
439 (and x (nconc (funcall fn (car x)) (woman-mapcan fn (cdr x)))))
441 (defun woman-parse-colon-path (cd-path)
442 "Explode a search path CD-PATH into a list of directory names.
443 Replace null components by calling `woman-parse-man.conf'.
444 Allow UN*X-style search paths on Microsoft platforms, i.e. allow path
445 elements to be separated by colons and convert Cygwin-style drive
446 specifiers `//x/' to `x:'."
447 ;; Based on suggestions by Jari Aalto and Eli Zaretskii.
448 (mapcar
449 (lambda (path) ; //a/b -> a:/b
450 (when (and path (string-match "\\`//./" path))
451 (setq path (substring path 1)) ; //a/b -> /a/b
452 (aset path 0 (aref path 1)) ; /a/b -> aa/b
453 (aset path 1 ?:)) ; aa/b -> a:/b
454 path)
455 (woman-mapcan ; splice into list...
456 (lambda (path)
457 ;; parse-colon-path returns nil for a null path component and
458 ;; an empty substring of MANPATH denotes the default list...
459 (if path (list path) (woman-parse-man.conf)))
460 (if (and (memq system-type '(windows-nt ms-dos))
461 (not (string-match ";" cd-path)))
462 (let ((path-separator ":"))
463 (parse-colon-path cd-path))
464 (parse-colon-path cd-path)))))
467 ;;; User options:
469 ;; NB: Group identifiers must be lowercase!
471 (defgroup woman nil
472 "Browse UNIX manual pages `wo (without) man'."
473 :tag "WoMan"
474 :group 'help)
476 (defcustom woman-show-log nil
477 "*If non-nil then show the *WoMan-Log* buffer if appropriate.
478 I.e. if any warning messages are written to it. Default is nil."
479 :type 'boolean
480 :group 'woman)
482 (defcustom woman-pre-format-hook nil
483 "*Hook run by WoMan immediately before formatting a buffer.
484 Change only via `Customization' or the function `add-hook'."
485 :type 'hook
486 :group 'woman)
488 (defcustom woman-post-format-hook nil
489 "*Hook run by WoMan immediately after formatting a buffer.
490 Change only via `Customization' or the function `add-hook'."
491 :type 'hook
492 :group 'woman)
495 ;; Interface options
497 (defgroup woman-interface nil
498 "Interface options for browsing UNIX manual pages `wo (without) man'."
499 :tag "WoMan Interface"
500 :group 'woman)
502 (defcustom woman-man.conf-path
503 '("/etc" "/etc/manpath.config" "/usr/local/lib")
504 "*List of dirs to search and/or files to try for man config file.
505 Default is '(\"/etc\" \"/usr/local/lib\") [for GNU/Linux, Cygwin resp.]
506 A trailing separator (`/' for UNIX etc.) on directories is optional
507 and the filename matched if a directory is specified is the first to
508 contain the string \"man.conf\".
509 If MANPATH is not set but a config file is found then it is parsed
510 instead to provide a default value for `woman-manpath'."
511 :type '(repeat string)
512 :group 'woman-interface)
514 (defun woman-parse-man.conf ()
515 "Parse if possible Linux-style configuration file for man command.
516 Used only if MANPATH is not set or contains null components.
517 Look in `woman-man.conf-path' and return a value for `woman-manpath'.
518 Concatenate data from all lines in the config file of the form
520 MANPATH /usr/man
524 MANDATORY_MANPATH /usr/man"
525 ;; Functionality suggested by Charles Curley.
526 (let ((path woman-man.conf-path)
527 file manpath)
528 (while (and
529 path
530 (not (and
531 (file-readable-p (setq file (car path)))
532 ;; If not a file then find the file:
533 (or (not (file-directory-p file))
534 (and
535 (setq file
536 (directory-files file t "man\\.conf" t))
537 (file-readable-p (setq file (car file)))))
538 ;; Parse the file -- if no MANPATH data ignore it:
539 (with-temp-buffer
540 (insert-file-contents file)
541 (while (re-search-forward
542 "^[ \t]*\\(MANDATORY_\\)?MANPATH[ \t]+\\(\\S-+\\)" nil t)
543 (setq manpath (cons (match-string 2) manpath)))
544 manpath))
546 (setq path (cdr path)))
547 (nreverse manpath)))
549 (defcustom woman-manpath
550 (let ((manpath (getenv "MANPATH")))
552 (and manpath (woman-parse-colon-path manpath))
553 (woman-parse-man.conf)
554 '("/usr/man" "/usr/share/man" "/usr/local/man")
556 "*List of DIRECTORY TREES to search for UN*X manual files.
557 Each element should be the name of a directory that contains
558 subdirectories of the form `man?', or more precisely subdirectories
559 selected by the value of `woman-manpath-man-regexp'. Non-directory
560 and unreadable files are ignored.
562 If not set then the environment variable MANPATH is used. If no such
563 environment variable is found, the default list is determined by
564 consulting the man configuration file if found. By default this is
565 either `/etc/man.config' or `/usr/local/lib/man.conf', which is
566 determined by the user option `woman-man.conf-path'. An empty
567 substring of MANPATH denotes the default list. Otherwise, the default
568 value of this variable is
570 (\"/usr/man\" \"/usr/local/man\").
572 Any environment variables (names must have the UN*X-style form $NAME,
573 e.g. $HOME, $EMACSDATA, $EMACS_DIR) are evaluated first but each
574 element must evaluate to a SINGLE directory name. Trailing `/'s are
575 ignored. (Specific directories in `woman-path' are also searched.)
577 Microsoft platforms:
578 I recommend including drive letters explicitly, e.g.
580 (\"C:/Cygnus/cygwin-b20/man\" \"C:/usr/man\" \"C:/usr/local/man\").
582 The MANPATH environment variable may be set using DOS semi-colon-
583 separated or UN*X / Cygwin colon-separated syntax (but not mixed)."
584 :type '(repeat string)
585 :group 'woman-interface)
587 (defcustom woman-manpath-man-regexp "[Mm][Aa][Nn]"
588 "Regexp to match man directories UNDER `woman-manpath' directories.
589 These normally have names of the form `man?'. Its default value is
590 \"[Mm][Aa][Nn]\", which is case-insensitive mainly for the benefit of
591 Microsoft platforms. Its purpose is to avoid `cat?', `.', `..', etc."
592 ;; Based on a suggestion by Wei-Xue Shi.
593 :type 'string
594 :group 'woman-interface)
596 (defcustom woman-path
597 (if (eq system-type 'ms-dos) '("$DJDIR/info" "$DJDIR/man/cat[1-9onlp]"))
598 "*List of SPECIFIC DIRECTORIES to search for UN*X manual files.
599 For example
601 (\"/emacs/etc\").
603 These directories are searched in addition to the directory trees
604 specified in `woman-manpath'. Each element should be a directory
605 string or nil, which represents the current directory when the path is
606 expanded and cached. However, the last component (only) of each
607 directory string is treated as a regexp \(Emacs, not shell) and the
608 string is expanded into a list of matching directories. Non-directory
609 and unreadable files are ignored. The default value is nil.
611 Any environment variables (which must have the UN*X-style form $NAME,
612 e.g. $HOME, $EMACSDATA, $EMACS_DIR) are evaluated first but each
613 element must evaluate to a SINGLE directory name (regexp, see above).
614 For example
616 (\"$EMACSDATA\") [or equivalently (\"$EMACS_DIR/etc\")].
618 Trailing `/'s are discarded. (The directory trees in `woman-manpath'
619 are also searched.) On Microsoft platforms I recommend including
620 drive letters explicitly."
621 :type '(repeat (choice string (const nil)))
622 :group 'woman-interface)
624 (defcustom woman-cache-level 2
625 "*The level of topic caching.
626 1 - cache only the topic and directory lists
627 (the only level before version 0.34 - only for compatibility);
628 2 - cache also the directories for each topic
629 (faster, without using much more memory);
630 3 - cache also the actual filenames for each topic
631 (fastest, but uses twice as much memory).
632 The default value is currently 2, a good general compromise.
633 If the `woman' command is slow to find files then try 3, which may be
634 particularly beneficial with large remote-mounted man directories.
635 Run the `woman' command with a prefix argument or delete the cache
636 file `woman-cache-filename' for a change to take effect.
637 \(Values < 1 behave like 1; values > 3 behave like 3.)"
638 :type '(choice (const :tag "Minimal" 1)
639 (const :tag "Default" 2)
640 (const :tag "Maximal" 3))
641 :group 'woman-interface)
643 (defcustom woman-cache-filename nil
644 "*The full pathname of the WoMan directory and topic cache file.
645 It is used to save and restore the cache between sessions. This is
646 especially useful with remote-mounted man page files! The default
647 value of nil suppresses this action. The `standard' non-nil
648 filename is \"~/.wmncach.el\". Remember that a prefix argument forces
649 the `woman' command to update and re-write the cache."
650 :type '(choice (const :tag "None" nil)
651 (const :tag "~/.wmncach.el" "~/.wmncach.el")
652 file)
653 :group 'woman-interface)
655 (defcustom woman-dired-keys t
656 "*List of `dired' mode keys to define to run WoMan on current file.
657 E.g. '(\"w\" \"W\"), or any non-null atom to automatically define
658 \"w\" and \"W\" if they are unbound, or nil to do nothing.
659 Default is t."
660 :type '(choice (const :tag "None" nil)
661 (repeat string)
662 (other :tag "Auto" t))
663 :group 'woman-interface)
665 (defcustom woman-imenu-generic-expression
666 '((nil "\n\\([A-Z].*\\)" 1) ; SECTION, but not TITLE
667 ("*Subsections*" "^ \\([A-Z].*\\)" 1))
668 "*Imenu support for Sections and Subsections.
669 An alist with elements of the form (MENU-TITLE REGEXP INDEX) --
670 see the documentation for `imenu-generic-expression'."
671 :type 'sexp
672 :group 'woman-interface)
674 (defcustom woman-imenu nil
675 "*If non-nil then WoMan adds a Contents menu to the menubar.
676 It does this by calling `imenu-add-to-menubar'. Default is nil."
677 :type 'boolean
678 :group 'woman-interface)
680 (defcustom woman-imenu-title "CONTENTS"
681 "*The title to use if WoMan adds a Contents menu to the menubar.
682 Default is \"CONTENTS\"."
683 :type 'string
684 :group 'woman-interface)
686 (defcustom woman-topic-at-point-default 'confirm
687 ;; `woman-topic-at-point' may be let-bound when woman is loaded, in
688 ;; which case its global value does not get defined.
689 ;; `woman-file-name' sets it to this value if it is unbound.
690 "*Default value for `woman-topic-at-point'."
691 :type '(choice (const :tag "Yes" t)
692 (const :tag "No" nil)
693 (other :tag "Confirm" confirm))
694 :group 'woman-interface)
696 (defcustom woman-topic-at-point woman-topic-at-point-default
697 "*Controls use by `woman' of `word at point' as a topic suggestion.
698 If non-nil then the `woman' command uses the word at point as an
699 initial topic suggestion when it reads a topic from the minibuffer; if
700 t then the `woman' command uses the word at point WITHOUT
701 INTERACTIVE CONFIRMATION if it exists as a topic. The default value
702 is `confirm', meaning suggest a topic and ask for confirmation."
703 :type '(choice (const :tag "Yes" t)
704 (const :tag "No" nil)
705 (other :tag "Confirm" confirm))
706 :group 'woman-interface)
708 (defvar woman-file-regexp nil
709 "Regexp used to select (possibly compressed) man source files, e.g.
710 \"\\.\\([0-9lmnt]\\w*\\)\\(\\.\\(g?z\\|bz2\\)\\)?\\'\".
711 Built automatically from the customizable user options
712 `woman-uncompressed-file-regexp' and `woman-file-compression-regexp'.")
714 (defvar woman-uncompressed-file-regexp) ; for the compiler
715 (defvar woman-file-compression-regexp) ; for the compiler
717 (defun set-woman-file-regexp (symbol value)
718 "Bind SYMBOL to VALUE and set `woman-file-regexp' as per user customizations.
719 Used as :set cookie by Customize when customizing the user options
720 `woman-uncompressed-file-regexp' and `woman-file-compression-regexp'."
721 (set-default symbol value)
722 (and (boundp 'woman-uncompressed-file-regexp)
723 (boundp 'woman-file-compression-regexp)
724 (setq woman-file-regexp
725 (concat woman-uncompressed-file-regexp
726 "\\("
727 (substring woman-file-compression-regexp 0 -2)
728 "\\)?\\'"))))
730 (defcustom woman-uncompressed-file-regexp
731 "\\.\\([0-9lmnt]\\w*\\)" ; disallow no extension
732 "*Do not change this unless you are sure you know what you are doing!
733 Regexp used to select man source files (ignoring any compression extension).
735 The SysV standard man pages use two character suffixes, and this is
736 becoming more common in the GNU world. For example, the man pages
737 in the ncurses package include `toe.1m', `form.3x', etc.
739 Note: an optional compression regexp will be appended, so this regexp
740 MUST NOT end with any kind of string terminator such as $ or \\'."
741 :type 'regexp
742 :set 'set-woman-file-regexp
743 :group 'woman-interface)
745 (defcustom woman-file-compression-regexp
746 "\\.\\(g?z\\|bz2\\)\\'"
747 "*Do not change this unless you are sure you know what you are doing!
748 Regexp used to match compressed man file extensions for which
749 decompressors are available and handled by auto-compression mode,
750 e.g. \"\\\\.\\\\(g?z\\\\|bz2\\\\)\\\\'\" for `gzip' or `bzip2'.
751 Should begin with \\. and end with \\' and MUST NOT be optional."
752 ;; Should be compatible with car of
753 ;; `jka-compr-file-name-handler-entry', but that is unduly
754 ;; complicated, includes an inappropriate extension (.tgz) and is
755 ;; not loaded by default!
756 :type 'regexp
757 :set 'set-woman-file-regexp
758 :group 'woman-interface)
760 (defcustom woman-use-own-frame ; window-system
761 (or (and (fboundp 'display-graphic-p) (display-graphic-p)) ; Emacs 21
762 (memq window-system '(x w32))) ; Emacs 20
763 "*If non-nil then use a dedicated frame for displaying WoMan windows.
764 Only useful when run on a graphic display such as X or MS-Windows."
765 :type 'boolean
766 :group 'woman-interface)
769 ;; Formatting options
771 (defgroup woman-formatting nil
772 "Formatting options for browsing UNIX manual pages `wo (without) man'."
773 :tag "WoMan Formatting"
774 :group 'woman)
776 (defcustom woman-fill-column 65
777 "*Right margin for formatted text -- default is 65."
778 :type 'integer
779 :group 'woman-formatting)
781 (defcustom woman-fill-frame nil
782 ;; Based loosely on a suggestion by Theodore Jump:
783 "*If non-nil then most of the frame width is used."
784 :type 'boolean
785 :group 'woman-formatting)
787 (defcustom woman-default-indent 5
788 "*Default prevailing indent set by -man macros -- default is 5.
789 Set this variable to 7 to emulate Linux man formatting."
790 :type 'integer
791 :group 'woman-formatting)
793 (defcustom woman-bold-headings t
794 "*If non-nil then embolden section and subsection headings. Default is t.
795 Heading emboldening is NOT standard `man' behaviour."
796 :type 'boolean
797 :group 'woman-formatting)
799 (defcustom woman-ignore t
800 "*If non-nil then unrecognised requests etc. are ignored. Default is t.
801 This gives the standard ?roff behaviour. If nil then they are left in
802 the buffer, which may aid debugging."
803 :type 'boolean
804 :group 'woman-formatting)
806 (defcustom woman-preserve-ascii nil
807 "*If non-nil then preserve ASCII characters in the WoMan buffer.
808 Otherwise, non-ASCII characters (that display as ASCII) may remain.
809 This is irrelevant unless the buffer is to be saved to a file."
810 :type 'boolean
811 :group 'woman-formatting)
813 (defcustom woman-emulation 'nroff
814 "*WoMan emulation, currently either nroff or troff. Default is nroff.
815 Troff emulation is experimental and largely untested.
816 \(Add groff later?)"
817 :type '(choice (const nroff) (const troff))
818 :group 'woman-formatting)
821 ;; Faces:
823 (defgroup woman-faces nil
824 "Face options for browsing UNIX manual pages `wo (without) man'."
825 :tag "WoMan Faces"
826 :group 'woman
827 :group 'faces)
829 (defcustom woman-fontify
830 (or (and (fboundp 'display-color-p) (display-color-p))
831 (and (fboundp 'display-graphic-p) (display-graphic-p))
832 (x-display-color-p))
833 "*If non-nil then WoMan assumes that face support is available.
834 It defaults to a non-nil value if the display supports either colors
835 or different fonts."
836 :type 'boolean
837 :group 'woman-faces)
839 ;; This is overkill! Troff uses just italic; Nroff uses just underline.
840 ;; You should probably select either italic or underline as you prefer, but
841 ;; not both, although italic and underline work together perfectly well!
842 (defface woman-italic-face
843 `((((background light)) (:italic t :underline t :foreground "red"))
844 (((background dark)) (:italic t :underline t)))
845 "Face for italic font in man pages."
846 :group 'woman-faces)
848 (defface woman-bold-face
849 '((((background light)) (:bold t :foreground "blue"))
850 (((background dark)) (:bold t :foreground "green2")))
851 "Face for bold font in man pages."
852 :group 'woman-faces)
854 ;; Brown is a good compromise: it is distinguishable from the default
855 ;; but not enough so to make font errors look terrible. (Files that use
856 ;; non-standard fonts seem to do so badly or in idiosyncratic ways!)
857 (defface woman-unknown-face
858 '((((background light)) (:foreground "brown"))
859 (((background dark)) (:foreground "cyan")))
860 "Face for all unknown fonts in man pages."
861 :group 'woman-faces)
863 (defface woman-addition-face
864 '((t (:foreground "orange")))
865 "Face for all additions made by WoMan to man pages.
866 Default: foreground orange."
867 :group 'woman-faces)
869 (defun woman-default-faces ()
870 "Set foreground colours of italic and bold faces to their default values."
871 (interactive)
872 (face-spec-set 'woman-italic-face
873 (face-user-default-spec 'woman-italic-face))
874 (face-spec-set 'woman-bold-face (face-user-default-spec 'woman-bold-face)))
876 (defun woman-monochrome-faces ()
877 "Set foreground colours of italic and bold faces to that of the default face.
878 This is usually either black or white."
879 (interactive)
880 (set-face-foreground 'woman-italic-face 'unspecified)
881 (set-face-foreground 'woman-bold-face 'unspecified))
883 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
884 ;; Experimental font support, initially only for MS-Windows.
885 (defconst woman-font-support
886 (eq window-system 'w32) ; Support X later!
887 "If non-nil then non-ASCII characters and symbol font supported.")
889 (defun woman-select-symbol-fonts (fonts)
890 "Select symbol fonts from a list FONTS of font name strings."
891 (let (symbol-fonts)
892 ;; With NTEmacs 20.5, the PATTERN option to `x-list-fonts' does
893 ;; not seem to work and fonts may be repeated, so ...
894 (while fonts
895 (and (string-match "-Symbol-" (car fonts))
896 (not (member (car fonts) symbol-fonts))
897 (setq symbol-fonts (cons (car fonts) symbol-fonts)))
898 (setq fonts (cdr fonts)))
899 symbol-fonts))
901 (when woman-font-support
902 (make-face 'woman-symbol-face)
904 ;; Set the symbol font only if `woman-use-symbol-font' is true, to
905 ;; avoid unnecessarily upsetting the line spacing in NTEmacs 20.5!
907 (defcustom woman-use-extended-font t
908 "*If non-nil then may use non-ASCII characters from the default font."
909 :type 'boolean
910 :group 'woman-faces)
912 (defcustom woman-use-symbol-font nil
913 "*If non-nil then may use the symbol font. It is off by default,
914 mainly because it may change the line spacing (in NTEmacs 20.5)."
915 :type 'boolean
916 :group 'woman-faces)
918 (defconst woman-symbol-font-list
919 (or (woman-select-symbol-fonts (x-list-fonts "*" 'default))
920 (woman-select-symbol-fonts (x-list-fonts "*")))
921 "Symbol font(s), preferably same size as default when WoMan was loaded.")
923 (defcustom woman-symbol-font (car woman-symbol-font-list)
924 "*A string describing the symbol font to use for special characters.
925 It should be compatible with, and the same size as, the default text font.
926 Under MS-Windows, the default is
927 \"-*-Symbol-normal-r-*-*-*-*-96-96-p-*-ms-symbol\"."
928 :type `(choice
929 ,@(mapcar (lambda (x) (list 'const x))
930 woman-symbol-font-list)
931 string)
932 :group 'woman-faces)
936 ;; For non windows-nt ...
937 (defvar woman-use-extended-font nil)
938 (defvar woman-use-symbol-font nil)
939 (defvar woman-symbol-font nil)
940 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
943 ;;; Internal variables:
945 (defconst woman-justify-list
946 '(left right center full)
947 "Justify styles for `fill-region-as-paragraph'.")
948 (defconst woman-adjust-left 0 ; == adjust off, noadjust
949 "Adjustment indicator `l' -- adjust left margin only.")
950 (defconst woman-adjust-right 1
951 "Adjustment indicator `r' -- adjust right margin only.")
952 (defconst woman-adjust-center 2
953 "Adjustment indicator `c' -- center.")
954 (defconst woman-adjust-both 3 ; default -- adj,both
955 "Adjustment indicator `b' or `n' -- adjust both margins.")
957 (defvar woman-adjust woman-adjust-both
958 "Current adjustment number-register value.")
959 (defvar woman-adjust-previous woman-adjust
960 "Previous adjustment number-register value.")
961 (defvar woman-justify
962 (nth woman-adjust woman-justify-list) ; use vector?
963 "Current justification style for `fill-region-as-paragraph'.")
964 (defvar woman-justify-previous woman-justify
965 "Previous justification style for `fill-region-as-paragraph'.")
967 (defvar woman-left-margin woman-default-indent
968 "Current left margin.")
969 (defvar woman-prevailing-indent woman-default-indent
970 "Current prevailing indent.")
971 (defvar woman-interparagraph-distance 1
972 "Interparagraph distance in lines.
973 Set by .PD; used by .SH, .SS, .TP, .LP, .PP, .P, .IP, .HP.")
974 (defvar woman-leave-blank-lines nil
975 "Blank lines to leave as vertical space.")
976 (defconst woman-tab-width 5
977 "Default tab width set by -man macros.")
978 (defvar woman-nofill nil
979 "Current fill mode: nil for filling.")
980 (defvar woman-RS-left-margin nil
981 "Left margin stack for nested use of `.RS/.RE'.")
982 (defvar woman-RS-prevailing-indent nil
983 "Prevailing indent stack for nested use of `.RS/.RE'.")
984 (defvar woman-nospace nil
985 "Current no-space mode: nil for normal spacing.
986 Set by `.ns' request; reset by any output or `.rs' request")
988 (defsubst woman-reset-nospace ()
989 "Set `woman-nospace' to nil."
990 (setq woman-nospace nil))
992 (defconst woman-mode-line-format
993 ;; This is essentially the Man-mode format with page numbers removed
994 ;; and line numbers added. (Online documents do not have pages, but
995 ;; they do have lines!)
996 '("-" mode-line-mule-info mode-line-modified
997 mode-line-frame-identification mode-line-buffer-identification
998 " " global-mode-string
999 " %[(WoMan" mode-line-process minor-mode-alist ")%]--"
1000 (line-number-mode "L%l--")
1001 (-3 . "%p") "-%-")
1002 "Mode line format for WoMan buffer.")
1004 (defconst woman-request-regexp "^[.'][ \t]*\\(\\S +\\) *"
1005 ;; Was "^\\.[ \t]*\\([a-z0-9]+\\) *" but cvs.1 uses a macro named
1006 ;; "`" and CGI.man uses a macro named "''"!
1007 ;; CGI.man uses ' as control character in places -- it *should*
1008 ;; suppress breaks!
1009 ;; Could end with "\\( +\\|$\\)" instead of " *"
1010 "Regexp to match a ?roff request plus trailing white space.")
1012 (defvar woman-imenu-done nil
1013 "Buffer-local: set to true if function `woman-imenu' has been called.")
1014 (make-variable-buffer-local 'woman-imenu-done)
1016 ;; From imenu.el -- needed when reformatting a file in its old buffer.
1017 ;; The latest buffer index used to update the menu bar menu.
1018 (eval-when-compile
1019 (require 'imenu))
1020 (make-variable-buffer-local 'imenu--last-menubar-index-alist)
1022 (defvar woman-buffer-alist nil
1023 "An alist representing WoMan buffers that are already decoded.
1024 Each element is of the form (FILE-NAME . BUFFER-NAME).")
1026 (defvar woman-buffer-number 0
1027 "Ordinal number of current buffer entry in `woman-buffer-alist'.
1028 The ordinal numbers start from 0.")
1030 (defvar woman-if-conditions-true '(?n ?e ?o)
1031 "List of one-character built-in condition names that are true.
1032 Should include ?e, ?o (page even/odd) and either ?n (nroff) or ?t (troff).
1033 Default is '(?n ?e ?o). Set via `woman-emulation'.")
1036 ;;; Specialized utility functions:
1038 ;;; Fast deletion without saving on the kill ring (cf. simple.el):
1040 (defun woman-delete-line (&optional arg)
1041 "Delete rest of current line; if all blank then delete thru newline.
1042 With a numeric argument ARG, delete that many lines from point.
1043 Negative arguments delete lines backward."
1044 ;; This is a non-interactive version of kill-line in simple.el that
1045 ;; deletes instead of killing and assumes kill-whole-line is nil,
1046 ;; which is essential!
1047 (delete-region (point)
1048 (progn
1049 (if arg
1050 (forward-line arg)
1051 (if (eobp)
1052 (signal 'end-of-buffer nil))
1053 (if (looking-at "[ \t]*$")
1054 (forward-line 1)
1055 (end-of-line)))
1056 (point))))
1058 (defsubst woman-delete-whole-line ()
1059 "Delete current line from beginning including eol."
1060 (beginning-of-line)
1061 (woman-delete-line 1))
1063 (defsubst woman-delete-following-space ()
1064 "Delete all spaces and tabs FOLLOWING point (cf. `delete-horizontal-space')."
1065 ;; cf. delete-horizontal-space in simple.el:
1066 (delete-region (point) (progn (skip-chars-forward " \t") (point))))
1068 (defsubst woman-delete-match (subexp)
1069 "Delete subexpression SUBEXP of buffer text matched by last search."
1070 (delete-region (match-beginning subexp) (match-end subexp)))
1072 ;; delete-char does not kill by default
1073 ;; delete-backward-char does not kill by default
1074 ;; delete-horizontal-space does not kill
1075 ;; delete-blank-lines does not kill
1078 ;;; File handling:
1080 (defvar woman-expanded-directory-path nil
1081 "Expanded directory list cache. Resetting to nil forces update.")
1083 (defvar woman-topic-all-completions nil
1084 "Expanded topic alist cache. Resetting to nil forces update.")
1086 ;;;###autoload
1087 (defun woman (&optional topic re-cache)
1088 "Browse UN*X man page for TOPIC (Without using external Man program).
1089 The major browsing mode used is essentially the standard Man mode.
1090 Choose the filename for the man page using completion, based on the
1091 topic selected from the directories specified in `woman-manpath' and
1092 `woman-path'. The directory expansions and topics are cached for
1093 speed, but a non-nil interactive argument forces the caches to be
1094 updated (e.g. to re-interpret the current directory).
1096 Used non-interactively, arguments are optional: if given then TOPIC
1097 should be a topic string and non-nil RE-CACHE forces re-caching."
1098 (interactive (list nil current-prefix-arg))
1099 ;; The following test is for non-interactive calls via gnudoit etc.
1100 (if (or (interactive-p) (not (stringp topic)) (string-match "\\S " topic))
1101 (let ((file-name (woman-file-name topic re-cache)))
1102 (if file-name
1103 (woman-find-file file-name)
1104 (message
1105 "WoMan Error: No matching manual files found in search path")
1106 (ding))
1108 (message "WoMan Error: No topic specified in non-interactive call")
1109 (ding))
1112 ;; Allow WoMan to be called via the standard Help menu:
1113 (define-key-after menu-bar-manuals-menu [woman]
1114 '(menu-item "Read Man Page (WoMan)..." woman
1115 :help "Man-page documentation Without Man") t)
1117 (defvar woman-cached-data nil
1118 "A list of cached data used to determine cache validity.
1119 Set from the cache by `woman-read-directory-cache'.")
1121 (defun woman-cached-data ()
1122 "Generate a list of data used to determine cache validity.
1123 Called both to generate and to check the cache!"
1124 ;; Must use substituted paths because values of env vars may change!
1125 (list woman-cache-level
1126 (mapcar 'substitute-in-file-name woman-manpath)
1127 (mapcar 'substitute-in-file-name woman-path)))
1129 (defun woman-read-directory-cache ()
1130 "Load the directory and topic cache.
1131 It is loaded from the file named by the variable `woman-cache-filename'.
1132 Return t if the file exists, nil otherwise."
1133 (and
1134 woman-cache-filename
1135 (load woman-cache-filename t nil t) ; file exists
1136 (equal woman-cached-data (woman-cached-data)))) ; cache valid
1138 (defun woman-write-directory-cache ()
1139 "Save the directory and topic cache.
1140 It is saved to the file named by the variable `woman-cache-filename'."
1141 (if woman-cache-filename
1142 (save-excursion ; to restore current buffer
1143 ;; Make a temporary buffer; name starting with space "hides" it.
1144 (let ((standard-output
1145 (set-buffer (generate-new-buffer "WoMan tmp buffer")))
1146 (backup-inhibited t))
1147 ;; (switch-to-buffer standard-output t) ; only for debugging
1148 (buffer-disable-undo standard-output)
1149 (princ
1150 ";;; WoMan directory and topic cache -- generated automatically\n")
1151 (print
1152 ;; For data validity check:
1153 `(setq woman-cached-data ',(woman-cached-data)))
1154 (print
1155 `(setq woman-expanded-directory-path
1156 ',woman-expanded-directory-path))
1157 (print
1158 `(setq woman-topic-all-completions
1159 ',woman-topic-all-completions))
1160 (write-file woman-cache-filename) ; write CURRENT buffer
1161 (kill-buffer standard-output)
1162 ))))
1164 (defvar woman-topic-history nil "Topic read history.")
1165 (defvar woman-file-history nil "File-name read history.")
1167 (defun woman-file-name (topic &optional re-cache)
1168 "Get the name of the UN*X man-page file describing a chosen TOPIC.
1169 When `woman' is called interactively, the word at point may be used as
1170 the topic or initial topic suggestion, subject to the value of the
1171 user option `woman-topic-at-point'. Return nil if no file can be found.
1172 Optional argument RE-CACHE, if non-nil, forces the cache to be re-read."
1173 ;; Handle the caching of the directory and topic lists:
1174 (if (and (not re-cache)
1176 (and woman-expanded-directory-path woman-topic-all-completions)
1177 (woman-read-directory-cache)))
1179 (message "Building list of manual directory expansions...")
1180 (setq woman-expanded-directory-path
1181 (woman-expand-directory-path woman-manpath woman-path))
1182 (message "Building completion list of all manual topics...")
1183 (setq woman-topic-all-completions
1184 (woman-topic-all-completions woman-expanded-directory-path))
1185 (woman-write-directory-cache))
1186 ;; There is a problem in that I want to offer case-insensitive
1187 ;; completions, but to return only a case-sensitive match. This
1188 ;; does not seem to work properly by default, so I re-do the
1189 ;; completion if necessary.
1190 (let (files)
1191 (or (stringp topic)
1192 (and (eq t
1193 (if (boundp 'woman-topic-at-point)
1194 woman-topic-at-point
1195 ;; Was let-bound when file loaded, so ...
1196 (setq woman-topic-at-point woman-topic-at-point-default)))
1197 (setq topic
1198 (current-word t)) ; only within or adjacent to word
1199 (assoc topic woman-topic-all-completions))
1200 (setq topic
1201 (completing-read
1202 "Manual entry: "
1203 woman-topic-all-completions nil 1
1204 ;; Initial input suggestion (was nil), with
1205 ;; cursor at left ready to kill suggestion!:
1206 (and woman-topic-at-point
1207 (cons (current-word) 0)) ; nearest word
1208 'woman-topic-history)))
1209 ;; Note that completing-read always returns a string.
1210 (if (= (length topic) 0)
1211 nil ; no topic, so no file!
1212 (cond
1213 ((setq files (woman-file-name-all-completions topic)))
1214 ;; Complete topic more carefully, i.e. use the completion
1215 ;; rather than the string entered by the user:
1216 ((setq files (all-completions topic woman-topic-all-completions))
1217 (while (/= (length topic) (length (car files)))
1218 (setq files (cdr files)))
1219 (setq files (woman-file-name-all-completions (car files)))))
1220 (cond
1221 ((null files) nil) ; no file found for topic.
1222 ((null (cdr files)) (car (car files))) ; only 1 file for topic.
1224 ;; Multiple files for topic, so must select 1.
1225 ;; Unread the command event (TAB = ?\t = 9) that runs the command
1226 ;; `minibuffer-complete' in order to automatically complete the
1227 ;; minibuffer contents as far as possible.
1228 (setq unread-command-events '(9)) ; and delete any type-ahead!
1229 (completing-read "Manual file: " files nil 1
1230 (try-completion "" files) 'woman-file-history)))
1233 (defun woman-select (predicate list)
1234 "Select unique elements for which PREDICATE is true in LIST.
1235 \(Note that this function changes the value of LIST.)"
1236 ;; Intended to be fast by avoiding recursion and list copying.
1237 (while (and list
1239 (member (car list) (cdr list))
1240 (not (funcall predicate (car list)))))
1241 (setq list (cdr list)))
1242 (if list
1243 (let ((newlist list) cdr_list)
1244 (while (setq cdr_list (cdr list))
1245 (if (and
1246 (not (member (car cdr_list) (cdr cdr_list)))
1247 (funcall predicate (car cdr_list)))
1248 (setq list cdr_list)
1249 (setcdr list (cdr cdr_list)))
1251 newlist)))
1253 (defun woman-file-readable-p (dir)
1254 "Return t if DIR is readable, otherwise log a warning."
1255 (or (file-readable-p dir)
1256 (WoMan-warn "Ignoring unreadable `manpath' directory tree `%s'!" dir)))
1258 (defun woman-directory-files (head dir)
1259 "Return a sorted list of files in directory HEAD matching regexp in DIR.
1260 Value is a sorted list of the absolute pathnames of all the files in
1261 directory HEAD, or the current directory if HEAD is nil, that match the
1262 regexp that is the final component of DIR. Log a warning if list is empty."
1263 (or (directory-files
1264 (or head (directory-file-name default-directory)) ; was "."
1266 (file-name-nondirectory dir))
1267 (WoMan-warn "No directories match `woman-path' entry `%s'!" dir)))
1269 (defun woman-file-accessible-directory-p (dir)
1270 "Return t if DIR is accessible, otherwise log a warning."
1271 (or (file-accessible-directory-p dir)
1272 (WoMan-warn "Ignoring inaccessible `man-page' directory `%s'!" dir)))
1274 (defun woman-expand-directory-path (woman-manpath woman-path)
1275 "Expand the manual directories in WOMAN-MANPATH and WOMAN-PATH.
1276 WOMAN-MANPATH should be a list of general manual directories, while
1277 WOMAN-PATH should be a list of specific manual directory regexps.
1278 Ignore any paths that are unreadable or not directories."
1279 ;; Allow each path to be a single string or a list of strings:
1280 (if (not (listp woman-manpath)) (setq woman-manpath (list woman-manpath)))
1281 (if (not (listp woman-path)) (setq woman-path (list woman-path)))
1282 (let (dir head dirs)
1283 (while woman-manpath
1284 (setq dir (car woman-manpath)
1285 woman-manpath (cdr woman-manpath))
1286 (if (and dir (woman-file-readable-p dir))
1287 ;; NB: `parse-colon-path' creates null elements for
1288 ;; redundant (semi-)colons and trailing `/'s!
1289 ;; If does not actually matter here if dir ends with `/'.
1290 ;; Need regexp "man" here to avoid "cat?", `.', `..', etc.
1291 (setq dir (woman-canonicalize-dir dir)
1292 dirs (nconc dirs (directory-files
1293 dir t woman-manpath-man-regexp)))))
1294 (while woman-path
1295 (setq dir (car woman-path)
1296 woman-path (cdr woman-path))
1297 (if (or (null dir)
1298 (null (setq dir (woman-canonicalize-dir dir)
1299 head (file-name-directory dir)))
1300 (woman-file-readable-p head))
1301 (setq dirs
1302 (if dir
1303 (nconc dirs (woman-directory-files head dir))
1304 (cons (directory-file-name default-directory) dirs))
1305 ;; was "." -- at head of list for later filtering
1307 (woman-select 'woman-file-accessible-directory-p dirs)))
1309 (defun woman-canonicalize-dir (dir)
1310 "Canonicalize the directory name DIR.
1311 Any UN*X-style environment variables are evaluated first."
1312 (setq dir (expand-file-name (substitute-in-file-name dir)))
1313 ;; A path that ends with / matches all directories in it,
1314 ;; including `.' and `..', so remove any trailing / !!!
1315 (if (string= (substring dir -1) "/")
1316 (setq dir (substring dir 0 -1)))
1317 (if (memq system-type '(windows-nt ms-dos)) ; what else?
1318 ;; Match capitalization used by `file-name-directory':
1319 (setq dir (concat (file-name-directory dir)
1320 (file-name-nondirectory dir))))
1321 dir)
1323 (defsubst woman-not-member (dir path)
1324 "Return t if DIR is not a member of the list PATH, nil otherwise.
1325 If DIR is `.' it is first replaced by the current directory."
1326 (not (member dir path)))
1328 (defun woman-topic-all-completions (path)
1329 "Return an alist of the man files in all man directories in the list PATH.
1330 The cdr of each alist element is the path-index / filename."
1331 ;; Support 3 levels of caching: each element of the alist `files'
1332 ;; will be a list of the first `woman-cache-level' elements of the
1333 ;; following list: (topic path-index filename). This alist `files'
1334 ;; is re-processed by `woman-topic-all-completions-merge'.
1335 (let (dir files (path-index 0)) ; indexing starts at zero
1336 (while path
1337 (setq dir (car path)
1338 path (cdr path))
1339 (if (woman-not-member dir path) ; use each directory only once!
1340 (setq files
1341 (nconc files
1342 (woman-topic-all-completions-1 dir path-index))))
1343 (setq path-index (1+ path-index)))
1344 ;; Uniquefy topics:
1345 (woman-topic-all-completions-merge files)))
1347 (defun woman-topic-all-completions-1 (dir path-index)
1348 "Return an alist of the man topics in directory DIR with index PATH-INDEX.
1349 A topic is a filename sans type-related extensions.
1350 Support 3 levels of caching: each element of the alist will be a list
1351 of the first `woman-cache-level' elements from the following list:
1352 \(topic path-index filename)."
1353 ;; This function used to check that each file in the directory was
1354 ;; not itself a directory, but this is very slow and should be
1355 ;; unnecessary. So let us assume that `woman-file-regexp' will
1356 ;; filter out any directories, which probably should not be there
1357 ;; anyway, i.e. it is a user error!
1358 (mapcar
1359 (lambda (file)
1360 (cons
1361 (file-name-sans-extension
1362 (if (string-match woman-file-compression-regexp file)
1363 (file-name-sans-extension file)
1364 file))
1365 (if (> woman-cache-level 1)
1366 (cons
1367 path-index
1368 (if (> woman-cache-level 2)
1369 (cons file nil))))))
1370 (directory-files dir nil woman-file-regexp)))
1372 (defun woman-topic-all-completions-merge (alist)
1373 "Merge the alist ALIST so that the keys are unique.
1374 Also make each path-info component into a list.
1375 \(Note that this function changes the value of ALIST.)"
1376 ;; Intended to be fast by avoiding recursion and list copying.
1377 (if (> woman-cache-level 1)
1378 (let ((newalist alist))
1379 (while newalist
1380 (let ((tail newalist) (topic (car (car newalist))))
1381 ;; Make the path-info into a list:
1382 (setcdr (car newalist) (list (cdr (car newalist))))
1383 (while tail
1384 (while (and tail (not (string= topic (car (car (cdr tail))))))
1385 (setq tail (cdr tail)))
1386 (if tail ; merge path-info into (car newalist)
1387 (let ((path-info (cdr (car (cdr tail)))))
1388 (if (member path-info (cdr (car newalist)))
1390 ;; Make the path-info into a list:
1391 (nconc (car newalist) (list path-info)))
1392 (setcdr tail (cdr (cdr tail))))
1394 (setq newalist (cdr newalist))))
1395 alist)
1396 ;; woman-cache-level = 1 => elements are single-element lists ...
1397 (while (and alist (member (car alist) (cdr alist)))
1398 (setq alist (cdr alist)))
1399 (if alist
1400 (let ((newalist alist) cdr_alist)
1401 (while (setq cdr_alist (cdr alist))
1402 (if (not (member (car cdr_alist) (cdr cdr_alist)))
1403 (setq alist cdr_alist)
1404 (setcdr alist (cdr cdr_alist)))
1406 newalist))))
1408 (defun woman-file-name-all-completions (topic)
1409 "Return an alist of the files in all man directories that match TOPIC."
1410 ;; Support 3 levels of caching: each element of
1411 ;; woman-topic-all-completions is a list of one of the forms:
1412 ;; (topic)
1413 ;; (topic (path-index) (path-index) ... )
1414 ;; (topic (path-index filename) (path-index filename) ... )
1415 ;; where the are no duplicates in the value lists.
1416 ;; Topic must match first `word' of filename, so ...
1417 (let ((topic-regexp
1418 (concat
1419 "\\`" (regexp-quote topic) ; first `word'
1420 "\\(\\..+\\)*" ; optional subsequent `words'
1421 woman-file-regexp)) ; extension
1422 (topics woman-topic-all-completions)
1423 (path woman-expanded-directory-path)
1424 dir files)
1425 (if (cdr (car topics))
1426 ;; Use cached path-info to locate files for each topic:
1427 (let ((path-info (cdr (assoc topic topics)))
1428 filename)
1429 (while path-info
1430 (setq dir (nth (car (car path-info)) path)
1431 filename (car (cdr (car path-info)))
1432 path-info (cdr path-info)
1433 files (nconc files
1434 ;; Find the actual file name:
1435 (if filename
1436 (list (concat dir "/" filename))
1437 (directory-files dir t topic-regexp)
1438 )))))
1439 ;; Search path for the files for each topic:
1440 (while path
1441 (setq dir (car path)
1442 path (cdr path))
1443 (if (woman-not-member dir path) ; use each directory only once!
1444 (setq files (nconc files
1445 (directory-files dir t topic-regexp))))
1447 (mapcar 'list files)
1451 ;;; dired support
1453 (defun woman-dired-define-key (key)
1454 "Bind the argument KEY to the command `woman-dired-find-file'."
1455 (define-key dired-mode-map key 'woman-dired-find-file))
1457 (defsubst woman-dired-define-key-maybe (key)
1458 "If KEY is undefined in Dired, bind it to command `woman-dired-find-file'."
1459 (if (eq (lookup-key dired-mode-map key) 'undefined)
1460 (woman-dired-define-key key)))
1462 (defun woman-dired-define-keys ()
1463 "Define dired keys to run WoMan according to `woman-dired-keys'."
1464 (if woman-dired-keys
1465 (if (listp woman-dired-keys)
1466 (mapcar 'woman-dired-define-key woman-dired-keys)
1467 (woman-dired-define-key-maybe "w")
1468 (woman-dired-define-key-maybe "W")))
1469 (define-key-after (lookup-key dired-mode-map [menu-bar immediate])
1470 [woman] '("Read Man Page (WoMan)" . woman-dired-find-file) 'view))
1472 (if (featurep 'dired)
1473 (woman-dired-define-keys)
1474 (add-hook 'dired-mode-hook 'woman-dired-define-keys))
1476 ;;;###autoload
1477 (defun woman-dired-find-file ()
1478 "In dired, run the WoMan man-page browser on this file."
1479 (interactive)
1480 ;; dired-get-filename is defined in dired.el
1481 (woman-find-file (dired-get-filename)))
1484 ;;; tar-mode support
1486 (defun woman-tar-extract-file ()
1487 "In tar mode, run the WoMan man-page browser on this file."
1488 (interactive)
1489 (or (eq major-mode 'tar-mode)
1490 (error "`woman-tar-extract-file' can be used only in `tar-mode'"))
1491 (buffer-disable-undo)
1492 (let (global-font-lock-mode)
1493 (funcall (symbol-function 'tar-extract)) ; defined in tar-mode
1494 (let ((WoMan-current-file buffer-file-name)) ; used for message logging
1495 (rename-buffer
1496 (woman-make-bufname (file-name-nondirectory buffer-file-name)))
1497 (woman-process-buffer)
1498 (goto-char (point-min)))))
1500 ;; There is currently no `tar-mode-hook' so use ...
1501 (eval-after-load "tar-mode"
1502 '(progn
1503 (define-key tar-mode-map "w" 'woman-tar-extract-file)
1504 (define-key-after (lookup-key tar-mode-map [menu-bar immediate])
1505 [woman] '("Read Man Page (WoMan)" . woman-tar-extract-file) 'view)))
1508 (defvar woman-last-file-name nil
1509 "The full pathname of the last file formatted by WoMan.")
1511 (defun woman-reformat-last-file ()
1512 "Reformat last file, e.g. after changing fill column."
1513 (interactive)
1514 (if woman-last-file-name
1515 (woman-find-file woman-last-file-name t)
1516 (call-interactively 'woman-find-file)))
1518 ;;;###autoload
1519 (defun woman-find-file (file-name &optional reformat)
1520 "Find, decode and browse a specific UN*X man-page source file FILE-NAME.
1521 Use existing buffer if possible; reformat only if prefix arg given.
1522 When called interactively, optional argument REFORMAT forces reformatting
1523 of an existing WoMan buffer formatted earlier.
1524 No external programs are used, except that `gunzip' will be used to
1525 decompress the file if appropriate. See the documentation for the
1526 `woman' command for further details."
1527 (interactive "fBrowse UN*X manual file: \nP")
1528 (setq woman-last-file-name
1529 (setq file-name (expand-file-name file-name))) ; to canonicalize
1530 (let ((alist-tail woman-buffer-alist) exists)
1531 (setq woman-buffer-number 0)
1532 (while (and alist-tail (not (string= file-name (car (car alist-tail)))))
1533 (setq alist-tail (cdr alist-tail)
1534 woman-buffer-number (1+ woman-buffer-number)))
1535 (or (and (setq exists
1536 (and alist-tail (WoMan-find-buffer))) ; buffer exists
1537 (not reformat))
1538 ;; Format new buffer or reformat current buffer:
1539 (let* ((bufname (file-name-nondirectory file-name))
1540 (case-fold-search t)
1541 (compressed
1542 (not (not (string-match woman-file-compression-regexp bufname)))))
1543 (if compressed
1544 (setq bufname (file-name-sans-extension bufname)))
1545 (setq bufname (if exists
1546 (buffer-name)
1547 (woman-make-bufname bufname)))
1548 (woman-really-find-file file-name compressed bufname)
1549 (or exists
1550 (setq woman-buffer-alist
1551 (cons (cons file-name bufname) woman-buffer-alist)
1552 woman-buffer-number 0))
1554 (Man-build-section-alist)
1555 (Man-build-references-alist)
1556 (goto-char (point-min)))
1558 (defun woman-make-bufname (bufname)
1559 "Create an unambiguous buffer name from BUFNAME."
1560 (let ((dot (string-match "\\." bufname)))
1561 (if dot (setq bufname (concat
1562 (substring bufname (1+ dot)) " "
1563 (substring bufname 0 dot))))
1564 (generate-new-buffer-name ; ensure uniqueness
1565 (concat "*WoMan " bufname "*"))))
1567 (defvar woman-frame nil
1568 "Dedicated frame used for displaying WoMan windows.")
1570 (defun woman-really-find-file (filename compressed bufname)
1571 "Find, decompress, and decode a UN*X man page FILENAME.
1572 If COMPRESSED is non-nil, turn on auto-compression mode to decompress
1573 the file if necessary. Set buffer name BUFNAME and major mode.
1574 Do not call directly!"
1575 (let ((WoMan-current-file filename)) ; used for message logging
1576 (if woman-use-own-frame
1577 (select-frame
1578 (or (and (frame-live-p woman-frame) woman-frame)
1579 (setq woman-frame (make-frame)))))
1580 (switch-to-buffer (get-buffer-create bufname))
1581 (buffer-disable-undo)
1582 (setq buffer-read-only nil)
1583 (erase-buffer) ; NEEDED for reformat
1584 (woman-insert-file-contents filename compressed)
1585 ;; Set buffer's default directory to that of the file.
1586 (setq default-directory (file-name-directory filename))
1587 (set (make-local-variable 'backup-inhibited) t)
1588 (set-visited-file-name "")
1589 (woman-process-buffer)))
1591 (defun woman-process-buffer ()
1592 "The second half of `woman-really-find-file'!"
1593 (interactive)
1594 ;; Check (crudely) that this really is likely to be in UN*X
1595 ;; man-page source format, assuming we are at point-min:
1596 (goto-char (point-min))
1597 (if (re-search-forward "^[.']" 1000 t)
1598 (woman-decode-buffer)
1599 (message
1600 "File appears to be pre-formatted -- using source file may be better.")
1601 (woman-man-buffer))
1602 (woman-mode))
1604 (defun woman-man-buffer ()
1605 "Post-process an nroff-preformatted man buffer."
1606 ;; Kill all leading whitespace:
1607 (if (looking-at "\\s-+") (woman-delete-match 0))
1608 ;; Delete all page footer/header pairs:
1609 (re-search-forward ".*") ; match header
1610 ;; Footer conventionally has page number at right, so ...
1611 (let ((regex (concat
1612 "^.*[0-9]\n\\s-*" ; footer and following blank lines
1613 (regexp-quote (match-string 0)) ; header
1614 "\\s-*\n"))) ; following blank lines
1615 (while (re-search-forward regex nil 1) ; finish at eob
1616 (woman-delete-match 0)))
1617 ;; Delete last text line (footer) and all following blank lines:
1618 (re-search-backward "\\S-")
1619 (beginning-of-line)
1620 (if (looking-at ".*[0-9]$")
1621 (delete-region (point) (point-max)))
1623 ;; Squeeze multiple blank lines:
1624 (goto-char (point-min))
1625 (while (re-search-forward "^[ \t]*\n\\([ \t]*\n\\)+" nil t)
1626 (replace-match "\n" t t))
1628 ;; CJK characters are underlined by double-sized "__".
1629 ;; (Code lifted from man.el, with trivial changes.)
1630 (if (< (buffer-size) (position-bytes (point-max)))
1631 ;; Multibyte characters exist.
1632 (progn
1633 (goto-char (point-min))
1634 (while (search-forward "__\b\b" nil t)
1635 (backward-delete-char 4)
1636 (woman-set-face (point) (1+ (point)) 'woman-italic-face))
1637 (goto-char (point-min))
1638 (while (search-forward "\b\b__" nil t)
1639 (backward-delete-char 4)
1640 (woman-set-face (1- (point)) (point) 'woman-italic-face))))
1642 ;; Interpret overprinting to indicate bold face:
1643 (goto-char (point-min))
1644 (while (re-search-forward "\\(.\\)\\(\\(\b+\\1\\)+\\)" nil t)
1645 (woman-delete-match 2)
1646 (woman-set-face (1- (point)) (point) 'woman-bold-face))
1648 ;; Interpret underlining to indicate italic face:
1649 ;; (Must be AFTER emboldening to interpret bold _ correctly!)
1650 (goto-char (point-min))
1651 (while (search-forward "_\b" nil t)
1652 (delete-char -2)
1653 (woman-set-face (point) (1+ (point)) 'woman-italic-face))
1655 ;; Leave any other uninterpreted ^H's in the buffer for now! (They
1656 ;; might indicate composite special characters, which could be
1657 ;; interpreted if I knew what to expect.)
1659 ;; Optionally embolden section and subsection headings
1660 ;; (cf. `woman-imenu-generic-expression'):
1661 (cond
1662 (woman-bold-headings
1663 (goto-char (point-min))
1664 (forward-line)
1665 (while (re-search-forward "^\\( \\)?\\([A-Z].*\\)" nil t)
1666 (woman-set-face (match-beginning 2) (match-end 2) 'woman-bold-face))))
1669 (defun woman-insert-file-contents (filename compressed)
1670 "Insert file FILENAME into the current buffer.
1671 If COMPRESSED is t, or is non-nil and the filename implies compression,
1672 then turn on auto-compression mode to decompress the file.
1673 Leave point at end of new text. Return length of inserted text."
1674 ;; Leaves point at end of inserted text in GNU Emacs 20.3, but at
1675 ;; start in 19.34!
1676 (save-excursion
1677 (let ((case-fold-search t))
1678 ;; Co-operate with auto-compression mode:
1679 (if (and compressed
1680 (or (eq compressed t)
1681 (string-match woman-file-compression-regexp filename))
1682 ;; (not auto-compression-mode)
1683 (not (rassq 'jka-compr-handler file-name-handler-alist)) )
1684 ;; (error "Compressed file requires Auto File Decompression turned on")
1685 (auto-compression-mode 1))
1686 (nth 1
1687 (condition-case ()
1688 (insert-file-contents filename nil)
1689 (file-error
1690 ;; Run find-file-not-found-hooks until one returns non-nil.
1691 ;; (run-hook-with-args-until-success 'find-file-not-found-hooks)
1692 (insert "\n***** File " filename " not found! *****\n\n")
1697 ;;; Major mode (Man) interface:
1699 (defvar woman-mode-map nil "Keymap for woman mode.")
1701 (if woman-mode-map
1703 ;; Set up the keymap, mostly inherited from Man-mode-map:
1704 (setq woman-mode-map (make-sparse-keymap))
1705 (set-keymap-parent woman-mode-map Man-mode-map)
1706 ;; Above two lines were
1707 ;; (setq woman-mode-map (cons 'keymap Man-mode-map))
1708 (define-key woman-mode-map "R" 'woman-reformat-last-file)
1709 (define-key woman-mode-map "w" 'woman)
1710 (define-key woman-mode-map "\en" 'WoMan-next-manpage)
1711 (define-key woman-mode-map "\ep" 'WoMan-previous-manpage)
1712 (define-key woman-mode-map [mouse-2] 'woman-mouse-2)
1713 (define-key woman-mode-map [M-mouse-2] 'woman-mouse-2))
1715 (defun woman-mouse-2 (event)
1716 "Run WoMan with word under mouse as topic.
1717 Require it to be mouse-highlighted unless Meta key used.
1718 Argument EVENT is the invoking mouse event."
1719 (interactive "e") ; mouse event
1720 (let ((pos (cadr (cadr event)))) ; extract buffer position
1721 (when (or (eq (car event) 'M-mouse-2)
1722 (get-text-property pos 'mouse-face))
1723 (goto-char pos)
1724 (woman (current-word t)))))
1726 ;; WoMan menu bar and pop-up menu:
1727 (easy-menu-define ; (SYMBOL MAPS DOC MENU)
1728 woman-menu
1729 woman-mode-map
1730 "WoMan Menu"
1731 `("WoMan"
1732 ["WoMan..." woman t] ; [NAME CALLBACK ENABLE]
1733 "--"
1734 ["Next Section" Man-next-section t]
1735 ["Previous Section" Man-previous-section t]
1736 ["Goto Section..." Man-goto-section t]
1737 ["Goto See-Also Section" Man-goto-see-also-section t]
1738 ["Follow Reference..." Man-follow-manual-reference t]
1739 "--"
1740 ["Previous WoMan Buffer" WoMan-previous-manpage t]
1741 ["Next WoMan Buffer" WoMan-next-manpage t]
1742 ["Bury WoMan Buffer" Man-quit t]
1743 ["Kill WoMan Buffer" Man-kill t]
1744 "--"
1745 ;; ["Toggle Fill Frame Width" woman-toggle-fill-frame t]
1746 ["Use Full Frame Width" woman-toggle-fill-frame
1747 :active t :style toggle :selected woman-fill-frame]
1748 ["Reformat Last Man Page" woman-reformat-last-file t]
1749 ["Use Monochrome Main Faces" woman-monochrome-faces t]
1750 ["Use Default Main Faces" woman-default-faces t]
1751 ["Make Contents Menu" (woman-imenu t) (not woman-imenu-done)]
1752 "--"
1753 ["Describe (Wo)Man Mode" describe-mode t]
1754 ["Mini Help" woman-mini-help t]
1755 ,@(if (fboundp 'customize-group)
1756 '(["Customize..." (customize-group 'woman) t]))
1757 ["Show Version" (message "WoMan %s" woman-version) t]
1758 "--"
1759 ("Advanced"
1760 ["View Source" (view-file woman-last-file-name) woman-last-file-name]
1761 ["Show Log" (switch-to-buffer-other-window "*WoMan-Log*" t) t]
1762 ["Extended Font" woman-toggle-use-extended-font
1763 :included woman-font-support
1764 :active t :style toggle :selected woman-use-extended-font]
1765 ["Symbol Font" woman-toggle-use-symbol-font
1766 :included woman-font-support
1767 :active t :style toggle :selected woman-use-symbol-font]
1768 ["Font Map" woman-display-extended-fonts
1769 :included woman-font-support
1770 :active woman-use-symbol-font]
1771 "--"
1772 "Emulation"
1773 ["nroff" (woman-reset-emulation 'nroff)
1774 :active t :style radio :selected (eq woman-emulation 'nroff)]
1775 ["troff" (woman-reset-emulation 'troff)
1776 :active t :style radio :selected (eq woman-emulation 'troff)]
1780 (defun woman-toggle-use-extended-font ()
1781 "Toggle `woman-use-extended-font' and reformat, for menu use."
1782 (interactive)
1783 (setq woman-use-extended-font (not woman-use-extended-font))
1784 (woman-reformat-last-file))
1786 (defun woman-toggle-use-symbol-font ()
1787 "Toggle `woman-use-symbol-font' and reformat, for menu use."
1788 (interactive)
1789 (setq woman-use-symbol-font (not woman-use-symbol-font))
1790 (woman-reformat-last-file))
1792 (defun woman-reset-emulation (value)
1793 "Reset `woman-emulation' to VALUE and reformat, for menu use."
1794 (interactive)
1795 (setq woman-emulation value)
1796 (woman-reformat-last-file))
1798 (defun woman-mode ()
1799 "Turn on (most of) Man mode to browse a buffer formatted by WoMan.
1800 WoMan is an ELisp emulation of much of the functionality of the Emacs
1801 `man' command running the standard UN*X man and ?roff programs.
1802 WoMan author: F.J.Wright@Maths.QMW.ac.uk
1803 WoMan version: see `woman-version'.
1804 See `Man-mode' for additional details."
1805 (let ((Man-build-page-list (symbol-function 'Man-build-page-list))
1806 (Man-strip-page-headers (symbol-function 'Man-strip-page-headers))
1807 (Man-unindent (symbol-function 'Man-unindent))
1808 (Man-goto-page (symbol-function 'Man-goto-page)))
1809 ;; Prevent inappropriate operations:
1810 (fset 'Man-build-page-list 'ignore)
1811 (fset 'Man-strip-page-headers 'ignore)
1812 (fset 'Man-unindent 'ignore)
1813 (fset 'Man-goto-page 'ignore)
1814 (unwind-protect
1815 (progn
1816 (set (make-local-variable 'Man-mode-map) woman-mode-map)
1817 ;; Install Man mode:
1818 (Man-mode)
1819 ;; Reset inappropriate definitions:
1820 (setq mode-line-format woman-mode-line-format)
1821 (put 'Man-mode 'mode-class 'special))
1822 ;; Restore the status quo:
1823 (fset 'Man-build-page-list Man-build-page-list)
1824 (fset 'Man-strip-page-headers Man-strip-page-headers)
1825 (fset 'Man-unindent Man-unindent)
1826 (fset 'Man-goto-page Man-goto-page)
1828 ;; Imenu support:
1829 (set (make-local-variable 'imenu-generic-expression)
1830 ;; `make-local-variable' in case imenu not yet loaded!
1831 woman-imenu-generic-expression)
1832 (set (make-local-variable 'imenu-space-replacement) " ")
1833 ;; For reformat ...
1834 ;; necessary when reformatting a file in its old buffer:
1835 (setq imenu--last-menubar-index-alist nil)
1836 ;; necessary to avoid re-installing the same imenu:
1837 (setq woman-imenu-done nil)
1838 (if woman-imenu (woman-imenu))
1839 (setq buffer-read-only nil)
1840 (WoMan-highlight-references)
1841 (setq buffer-read-only t)
1842 (set-buffer-modified-p nil)))
1844 (defun woman-imenu (&optional redraw)
1845 "Add a \"Contents\" menu to the menubar.
1846 Optional argument REDRAW, if non-nil, forces mode line to be updated."
1847 (interactive)
1848 (if woman-imenu-done
1849 ;; This is PRIMARILY to avoid a bug in imenu-add-to-menubar that
1850 ;; causes it to corrupt the menu bar if it is run more than once
1851 ;; in the same buffer.
1853 (setq woman-imenu-done t)
1854 (imenu-add-to-menubar woman-imenu-title)
1855 (if redraw (force-mode-line-update))))
1857 (defun woman-toggle-fill-frame ()
1858 "Toggle formatting to fill (most of) the width of the current frame."
1859 (interactive)
1860 (setq woman-fill-frame (not woman-fill-frame))
1861 (message "Woman fill column set to %s."
1862 (if woman-fill-frame "frame width" woman-fill-column)
1865 (defun woman-mini-help ()
1866 "Display WoMan commands and user options in an `apropos' buffer."
1867 ;; Based on apropos-command in apropos.el
1868 (interactive)
1869 (require 'apropos)
1870 (let ((message
1871 (let ((standard-output (get-buffer-create "*Apropos*")))
1872 (print-help-return-message 'identity))))
1873 (setq apropos-accumulator
1874 (apropos-internal "woman"
1875 (lambda (symbol)
1876 (or (commandp symbol)
1877 (user-variable-p symbol)))))
1878 ;; Filter out any inhibited symbols:
1879 (let ((tem apropos-accumulator))
1880 (while tem
1881 (if (get (car tem) 'apropos-inhibit)
1882 (setq apropos-accumulator (delq (car tem) apropos-accumulator)))
1883 (setq tem (cdr tem))))
1884 ;; Find documentation strings:
1885 (let ((p apropos-accumulator)
1886 doc symbol)
1887 (while p
1888 (setcar p (list ; must have 3 elements:
1889 (setq symbol (car p)) ; 1. name
1890 (if (functionp symbol) ; 2. command doc
1891 (if (setq doc (documentation symbol t))
1892 (substring doc 0 (string-match "\n" doc))
1893 "(not documented)"))
1894 (if (user-variable-p symbol) ; 3. variable doc
1895 (if (setq doc (documentation-property
1896 symbol 'variable-documentation t))
1897 (substring doc 0 (string-match "\n" doc))))))
1898 (setq p (cdr p))))
1899 ;; Output the result:
1900 (and (apropos-print t nil)
1901 message
1902 (message message))))
1905 (defun WoMan-getpage-in-background (topic)
1906 "Use TOPIC to start WoMan from `Man-follow-manual-reference'."
1907 ;; topic is a string, generally of the form "section topic"
1908 (let ((s (string-match " " topic)))
1909 (if s (setq topic (substring topic (1+ s))))
1910 (woman topic)))
1912 (defvar WoMan-Man-start-time nil
1913 "Used to record formatting time used by the `man' command.")
1915 (defadvice Man-getpage-in-background
1916 (around Man-getpage-in-background-advice (topic) activate)
1917 "Use WoMan unless invoked outside a WoMan buffer or invoked explicitly.
1918 Otherwise use Man and record start of formatting time."
1919 (if (and (eq mode-line-format woman-mode-line-format)
1920 (not (eq (caar command-history) 'man)))
1921 (WoMan-getpage-in-background topic)
1922 ;; Initiates man processing
1923 (setq WoMan-Man-start-time (current-time))
1924 ad-do-it))
1926 (defadvice Man-bgproc-sentinel
1927 (after Man-bgproc-sentinel-advice activate)
1928 ;; Terminates man processing
1929 "Report formatting time."
1930 (let* ((time (current-time))
1931 (time (+ (* (- (car time) (car WoMan-Man-start-time)) 65536)
1932 (- (cadr time) (cadr WoMan-Man-start-time)))))
1933 (message "Man formatting done in %d seconds" time)))
1935 (defun WoMan-highlight-references ()
1936 "Highlight the references (in the SEE ALSO section) on mouse-over."
1937 ;; Based on `Man-build-references-alist' in `man'.
1938 (when (Man-find-section Man-see-also-regexp)
1939 (forward-line 1)
1940 (let ((end (save-excursion
1941 (Man-next-section 1)
1942 (point))))
1943 (back-to-indentation)
1944 (while (re-search-forward Man-reference-regexp end t)
1945 ;; Highlight reference when mouse is over it.
1946 ;; (NB: WoMan does not hyphenate!)
1947 ;; [See (elisp)Clickable Text]
1948 (put-text-property (match-beginning 1) (match-end 1)
1949 'mouse-face 'highlight)
1950 ))))
1953 ;;; Buffer handling:
1955 (defun WoMan-previous-manpage ()
1956 "Find the previous WoMan buffer."
1957 ;; Assumes currently in a WoMan buffer!
1958 (interactive)
1959 (WoMan-find-buffer) ; find current existing buffer
1960 (if (null (cdr woman-buffer-alist))
1961 (error "No previous WoMan buffer"))
1962 (if (>= (setq woman-buffer-number (1+ woman-buffer-number))
1963 (length woman-buffer-alist))
1964 (setq woman-buffer-number 0))
1965 (if (WoMan-find-buffer)
1967 (if (< (setq woman-buffer-number (1- woman-buffer-number)) 0)
1968 (setq woman-buffer-number (1- (length woman-buffer-alist))))
1969 (WoMan-previous-manpage)))
1971 (defun WoMan-next-manpage ()
1972 "Find the next WoMan buffer."
1973 ;; Assumes currently in a WoMan buffer!
1974 (interactive)
1975 (WoMan-find-buffer) ; find current existing buffer
1976 (if (null (cdr woman-buffer-alist))
1977 (error "No next WoMan buffer"))
1978 (if (< (setq woman-buffer-number (1- woman-buffer-number)) 0)
1979 (setq woman-buffer-number (1- (length woman-buffer-alist))))
1980 (if (WoMan-find-buffer)
1982 (WoMan-next-manpage)))
1984 (defun WoMan-find-buffer ()
1985 "Switch to buffer corresponding to `woman-buffer-number' and return it.
1986 If such a buffer does not exist then remove its association from the
1987 alist in `woman-buffer-alist' and return nil."
1988 (if (zerop woman-buffer-number)
1989 (let ((buffer (get-buffer (cdr (car woman-buffer-alist)))))
1990 (if buffer
1991 (switch-to-buffer buffer)
1992 ;; Delete alist element:
1993 (setq woman-buffer-alist (cdr woman-buffer-alist))
1994 nil))
1995 (let* ((prev-ptr (nthcdr (1- woman-buffer-number) woman-buffer-alist))
1996 (buffer (get-buffer (cdr (car (cdr prev-ptr))))))
1997 (if buffer
1998 (switch-to-buffer buffer)
1999 ;; Delete alist element:
2000 (setcdr prev-ptr (cdr (cdr prev-ptr)))
2001 (if (>= woman-buffer-number (length woman-buffer-alist))
2002 (setq woman-buffer-number 0))
2003 nil)
2007 ;;; Syntax and display tables:
2009 (defconst woman-escaped-escape-char ?\x1c
2010 ;; An arbitrary unused control character
2011 "Internal character representation of escaped escape characters.")
2012 (defconst woman-escaped-escape-string
2013 (char-to-string woman-escaped-escape-char)
2014 "Internal string representation of escaped escape characters.")
2016 (defconst woman-unpadded-space-char ?\x1d
2017 ;; An arbitrary unused control character
2018 "Internal character representation of unpadded space characters.")
2019 (defconst woman-unpadded-space-string
2020 (char-to-string woman-unpadded-space-char)
2021 "Internal string representation of unpadded space characters.")
2023 (defvar woman-syntax-table nil
2024 "Syntax table to support special characters used internally by WoMan.")
2026 (if woman-syntax-table
2028 (setq woman-syntax-table (make-syntax-table))
2029 ;; The following internal chars must NOT have whitespace syntax:
2030 (modify-syntax-entry woman-unpadded-space-char "." woman-syntax-table)
2031 (modify-syntax-entry woman-escaped-escape-char "." woman-syntax-table)
2034 (defun woman-set-buffer-display-table ()
2035 "Set up a display table for a WoMan buffer.
2036 This display table is used for displaying internal special characters, but
2037 does not interfere with any existing display table, e.g. for displaying
2038 European characters."
2039 (setq buffer-display-table
2040 ;; The following test appears to be necessary on some
2041 ;; non-Windows platforms, e.g. Solaris 2.6 when running on a
2042 ;; tty. Thanks to T. V. Raman <raman@Adobe.COM>.
2043 ;; The MS-DOS terminal also sets standard-display-table to
2044 ;; a non-nil value.
2045 (if standard-display-table ; default is nil !!!
2046 (copy-sequence standard-display-table)
2047 (make-display-table)))
2048 ;; Display the following internal chars correctly:
2049 (aset buffer-display-table woman-unpadded-space-char [?\ ])
2050 (aset buffer-display-table woman-escaped-escape-char [?\\]))
2053 ;;; The main decoding driver:
2055 (defvar font-lock-mode) ; for the compiler
2057 (defun woman-decode-buffer ()
2058 "Decode a buffer in UN*X man-page source format.
2059 No external programs are used."
2060 (interactive) ; mainly for testing
2061 (WoMan-log-begin)
2062 (run-hooks 'woman-pre-format-hook)
2063 (and (boundp 'font-lock-mode) font-lock-mode (font-lock-mode -1))
2064 ;; (fundamental-mode)
2065 (let ((start-time (current-time)) ; (HIGH LOW MICROSEC)
2066 time) ; HIGH * 2**16 + LOW seconds
2067 (message "WoMan formatting buffer...")
2068 ; (goto-char (point-min))
2069 ; (cond
2070 ; ((re-search-forward "^\\.[ \t]*TH" nil t) ; wrong format if not found?
2071 ; (beginning-of-line)
2072 ; (delete-region (point-min) (point))) ; potentially dangerous!
2073 ; (t (message "WARNING: .TH request not found -- not man-page format?")))
2074 (woman-decode-region (point-min) (point-max))
2075 (setq time (current-time)
2076 time (+ (* (- (car time) (car start-time)) 65536)
2077 (- (cadr time) (cadr start-time))))
2078 (message "WoMan formatting buffer...done in %d seconds" time)
2079 (WoMan-log-end time))
2080 (run-hooks 'woman-post-format-hook))
2082 (defvar woman-string-alist ; rebound in woman-decode-region
2083 '(("S" . "") ("R" . "(Reg.)") ("Tm" . "(TM)")
2084 ("lq" . "\"") ("rq" . "\"")
2085 ("''" . "\"") ; needed for gcc.1
2086 (".T" . "") ; output device from -T option?
2088 "Alist of strings predefined in the -man macro package `tmac.an'.")
2090 (defvar woman-negative-vertical-space nil ; rebound in woman-decode-region
2091 "Set to t if .sp N with N < 0 encountered.")
2093 (defun woman-pre-process-region (from to)
2094 "Pre-process escapes and comments in the region of text between FROM and TO.
2095 To be called on original buffer and any .so insertions."
2096 ;; Hide escaped escapes \\ and printable escapes \e very early
2097 ;; (to be re-instated as just \ very late!):
2098 (goto-char from)
2099 ;; .eo turns off escape character processing
2100 (while (re-search-forward "\\(\\\\[\\e]\\)\\|^\\.eo" to t) ; \\
2101 (if (match-string 1)
2102 (replace-match woman-escaped-escape-string t t)
2103 (woman-delete-whole-line)
2104 ;; .ec turns on escape character processing (and sets the
2105 ;; escape character to its argument, if any, which I'm ignoring
2106 ;; for now!)
2107 (while (and (re-search-forward "\\(\\\\\\)\\|^\\.ec" to t) ; \
2108 (match-string 1))
2109 (replace-match woman-escaped-escape-string t t))
2110 ;; ***** Need test for .ec arg and warning here! *****
2111 (woman-delete-whole-line)))
2113 ;; Delete comments .\"<anything>, \"<anything>, pre-processor
2114 ;; directives '\"<anything> (should give warning?) and null
2115 ;; requests. (However, should null . requests cause a break?)
2116 (goto-char from)
2117 (while (re-search-forward "^[.'][ \t]*\\(\\\\\".*\\)?\n\\|\\\\\".*" to t)
2118 (woman-delete-match 0))
2121 (defun woman-non-underline-faces ()
2122 "Prepare non-underlined versions of underlined faces."
2123 (let ((face-list (face-list)))
2124 (while face-list
2125 (let* ((face (car face-list))
2126 (face-name (symbol-name face)))
2127 (if (and (string-match "\\`woman-" face-name)
2128 (face-underline-p face))
2129 (let ((face-no-ul (intern (concat face-name "-no-ul"))))
2130 (copy-face face face-no-ul)
2131 (set-face-underline-p face-no-ul nil))))
2132 (setq face-list (cdr face-list)))))
2134 (defun woman-decode-region (from to)
2135 "Decode the region between FROM and TO in UN*X man-page source format."
2136 ;; Suitable for use in format-alist.
2137 ;; But this requires care to control major mode implied font locking.
2138 ;; Must return the new end of file. See format.el for details.
2139 ;; NB: The `to' argument is bogus: it is not currently used, and if
2140 ;; it were it would need to be a marker rather than a position!
2141 ;; First force the correct environment:
2142 (let ((case-fold-search nil) ; This is necessary!
2143 (woman-string-alist woman-string-alist)
2144 (woman-fill-column woman-fill-column)
2145 woman-negative-vertical-space)
2146 (setq woman-left-margin woman-default-indent
2147 woman-prevailing-indent woman-default-indent
2148 woman-interparagraph-distance 1
2149 woman-leave-blank-lines nil
2150 woman-RS-left-margin nil
2151 woman-RS-prevailing-indent nil
2152 woman-adjust woman-adjust-both
2153 woman-justify (nth woman-adjust woman-justify-list)
2154 woman-nofill nil)
2156 (setq woman-if-conditions-true
2157 (cons (string-to-char (symbol-name woman-emulation)) '(?e ?o)))
2159 ;; Prepare non-underlined versions of underlined faces:
2160 (woman-non-underline-faces)
2161 ;; Set font of `woman-symbol-face' to `woman-symbol-font' if
2162 ;; `woman-symbol-font' is well defined.
2163 (and woman-use-symbol-font
2164 (stringp woman-symbol-font)
2165 (set-face-font 'woman-symbol-face woman-symbol-font
2166 (and (frame-live-p woman-frame) woman-frame)))
2168 ;; Set syntax and display tables:
2169 (set-syntax-table woman-syntax-table)
2170 (woman-set-buffer-display-table)
2172 ;; Based loosely on a suggestion by Theodore Jump:
2173 (if (or woman-fill-frame
2174 (not (and (integerp woman-fill-column) (> woman-fill-column 0))))
2175 (setq woman-fill-column (- (frame-width) woman-default-indent)))
2177 (woman-pre-process-region from nil)
2178 ;; Process ignore requests, macro definitions,
2179 ;; conditionals and switch source requests:
2180 (woman0-roff-buffer from)
2182 ;; Process \k escapes BEFORE changing tab width (?):
2183 (goto-char from)
2184 (woman-mark-horizonal-position)
2186 ;; Set buffer-local variables:
2187 (setq fill-column woman-fill-column
2188 tab-width woman-tab-width)
2190 ;; Hide unpaddable and digit-width spaces \(space) and \0:
2191 (goto-char from)
2192 (while (re-search-forward "\\\\[ 0]" nil t)
2193 (replace-match woman-unpadded-space-string t t))
2195 ;; Discard optional hyphen \%; concealed newlines \<newline>;
2196 ;; point-size change function \sN,\s+N, \s-N:
2197 (goto-char from)
2198 (while (re-search-forward "\\\\\\([%\n]\\|s[-+]?[0-9]+\\)" nil t)
2199 (woman-delete-match 0))
2201 ;; BEWARE: THIS SHOULD PROBABLY ALL BE DONE MUCH LATER!!!!!
2202 ;; Process trivial escapes \-, \`, \.
2203 ;; (\' must be done after tab processing!):
2204 (goto-char from)
2205 (while (re-search-forward "\\\\\\([-`.]\\)" nil t)
2206 (replace-match "\\1"))
2207 ;; NB: Must keep ALL zero-width characters \&, \|, and \^ until
2208 ;; ALL requests processed!
2210 ;; Process no-break requests and macros (including font-change macros):
2211 (goto-char from)
2212 (woman1-roff-buffer)
2214 ;; Process strings and special character escapes \(xx:
2215 ;; (Must do this BEFORE fontifying!)
2216 (goto-char from)
2217 (woman-strings)
2218 ;; Special chars moved after translation in
2219 ;; `woman2-process-escapes' (for pic.1):
2220 ; (goto-char from)
2221 ; (woman-special-characters)
2223 ;; Process standard font-change requests and escapes:
2224 (goto-char from)
2225 (woman-change-fonts)
2227 ;; 1/2 em vertical motion \d, \u and general local vertical motion
2228 ;; \v'+/-N' simulated using TeX ^ and _ symbols for now.
2229 (goto-char from)
2230 (let ((first t)) ; assume no nesting!
2231 (while (re-search-forward "\\\\\\([du]\\|v'[^']*'\\)" nil t)
2232 (let* ((esc (match-string 1))
2233 (repl (if (or (= (aref esc 0) ?u)
2234 (and (>= (length esc) 2) (= (aref esc 2) ?-)))
2235 "^" "_")))
2236 (cond (first
2237 (replace-match repl nil t)
2238 (put-text-property (1- (point)) (point)
2239 'face 'woman-addition-face)
2240 (WoMan-warn
2241 "Initial vertical motion escape \\%s simulated" esc)
2242 (WoMan-log
2243 " by TeX `%s' in woman-addition-face!" repl))
2245 (woman-delete-match 0)
2246 (WoMan-warn
2247 "Terminal vertical motion escape \\%s ignored!" esc)))
2248 (setq first (not first))
2251 ; ;; \h'+/-N' local horizontal motion.
2252 ; ;; N may include width escape \w'...'
2253 ; ;; Implement arbitrary forward motion and non-overlapping backward
2254 ; ;; motion.
2255 ; (goto-char from)
2256 ; (while (re-search-forward
2257 ; ;; Delimiter can be a special char escape sequence \(.. or
2258 ; ;; a single normal char (usually '):
2259 ; "\\\\h\\(\\\\(..\\|.\\)\\(|\\)?"
2260 ; nil t)
2261 ; (let ((from (match-beginning 0))
2262 ; (delim (regexp-quote (match-string 1)))
2263 ; (absolute (match-string 2)) ; absolute position?
2264 ; (N (woman-parse-numeric-arg)) ; distance
2265 ; to
2266 ; msg) ; for warning
2267 ; (if (not (looking-at delim))
2268 ; ;; Warn but leave escape in buffer unprocessed:
2269 ; (WoMan-warn
2270 ; "Local horizontal motion (%s) delimiter error!"
2271 ; (buffer-substring from (1+ (point)))) ; point at end of arg
2272 ; (setq to (match-end 0)
2273 ; ;; For possible warning -- save before deleting:
2274 ; msg (buffer-substring from to))
2275 ; (delete-region from to)
2276 ; (if absolute ; make relative
2277 ; (setq N (- N (current-column))))
2278 ; (if (>= N 0)
2279 ; ;; Move forward by inserting hard spaces:
2280 ; (insert-char woman-unpadded-space-char N)
2281 ; ;; Move backwards by deleting space,
2282 ; ;; first backwards then forwards:
2283 ; (while (and
2284 ; (<= (setq N (1+ N)) 0)
2285 ; (cond ((memq (preceding-char) '(?\ ?\t))
2286 ; (delete-backward-char 1) t)
2287 ; ((memq (following-char) '(?\ ?\t))
2288 ; (delete-char 1) t)
2289 ; (t nil))))
2290 ; (if (<= N 0)
2291 ; (WoMan-warn
2292 ; "Negative horizontal motion (%s) would overwrite!" msg))))
2293 ; ))
2295 ;; Process formatting macros
2296 (goto-char from)
2297 (woman2-roff-buffer)
2299 ;; Go back and process negative vertical space if necessary:
2300 (if woman-negative-vertical-space
2301 (woman-negative-vertical-space from))
2303 (if woman-preserve-ascii
2304 ;; Re-instate escaped escapes to just `\' and unpaddable
2305 ;; spaces to just `space', without inheriting any text
2306 ;; properties. This is not necessary, UNLESS the buffer is to
2307 ;; be saved as ASCII.
2308 (progn
2309 (goto-char from)
2310 (while (search-forward woman-escaped-escape-string nil t)
2311 (delete-char -1) (insert ?\\))
2312 (goto-char from)
2313 (while (search-forward woman-unpadded-space-string nil t)
2314 (delete-char -1) (insert ?\ ))
2317 ;; Must return the new end of file if used in format-alist.
2318 (point-max)))
2320 (defun woman-horizontal-escapes (to)
2321 "Process \\h'+/-N' local horizontal motion escapes upto TO.
2322 Implements arbitrary forward and non-overlapping backward motion.
2323 Preserves location of `point'."
2324 ;; Moved from `woman-decode-region' for version 0.50.
2325 ;; N may include width escape \w'...' (but may already be processed!
2326 (let ((from (point)))
2327 (while (re-search-forward
2328 ;; Delimiter can be a special char escape sequence \(.. or
2329 ;; a single normal char (usually '):
2330 "\\\\h\\(\\\\(..\\|.\\)\\(|\\)?"
2331 to t)
2332 (let ((from (match-beginning 0))
2333 (delim (regexp-quote (match-string 1)))
2334 (absolute (match-string 2)) ; absolute position?
2335 (N (woman-parse-numeric-arg)) ; distance
2337 msg) ; for warning
2338 (if (not (looking-at delim))
2339 ;; Warn but leave escape in buffer unprocessed:
2340 (WoMan-warn
2341 "Local horizontal motion (%s) delimiter error!"
2342 (buffer-substring from (1+ (point)))) ; point at end of arg
2343 (setq to (match-end 0)
2344 ;; For possible warning -- save before deleting:
2345 msg (buffer-substring from to))
2346 (delete-region from to)
2347 (if absolute ; make relative
2348 (setq N (- N (current-column))))
2349 (if (>= N 0)
2350 ;; Move forward by inserting hard spaces:
2351 (insert-char woman-unpadded-space-char N)
2352 ;; Move backwards by deleting space,
2353 ;; first backwards then forwards:
2354 (while (and
2355 (<= (setq N (1+ N)) 0)
2356 (cond ((memq (preceding-char) '(?\ ?\t))
2357 (delete-backward-char 1) t)
2358 ((memq (following-char) '(?\ ?\t))
2359 (delete-char 1) t)
2360 (t nil))))
2361 (if (<= N 0)
2362 (WoMan-warn
2363 "Negative horizontal motion (%s) would overwrite!" msg))))
2365 (goto-char from)))
2369 ;; Process ignore requests (.ig), conditionals (.if etc.),
2370 ;; source-switch (.so), macro definitions (.de etc.) and macro
2371 ;; expansions.
2373 (defvar woman0-if-to) ; marker bound in woman0-roff-buffer
2374 (defvar woman0-macro-alist) ; bound in woman0-roff-buffer
2375 (defvar woman0-search-regex) ; bound in woman0-roff-buffer
2376 (defvar woman0-search-regex-start ; bound in woman0-roff-buffer
2377 "^[.'][ \t]*\\(ig\\|if\\|ie\\|el\\|so\\|rn\\|de\\|am")
2378 (defconst woman0-search-regex-end "\\)\\([ \t]+\\|$\\)")
2379 ;; May need other terminal characters, e.g. \, but NOT \n!
2380 ;; Alternatively, force maximal match (Posix?)
2382 (defvar woman0-rename-alist) ; bound in woman0-roff-buffer
2384 (defun woman0-roff-buffer (from)
2385 "Process conditional-type requests and user-defined macros.
2386 Start at FROM and re-scan new text as appropriate."
2387 (goto-char from)
2388 (let ((woman0-if-to (make-marker))
2389 request woman0-macro-alist
2390 (woman0-search-regex-start woman0-search-regex-start)
2391 (woman0-search-regex
2392 (concat woman0-search-regex-start woman0-search-regex-end))
2393 woman0-rename-alist)
2394 (while (re-search-forward woman0-search-regex nil t)
2395 (setq request (match-string 1))
2396 (cond ((string= request "ig") (woman0-ig))
2397 ((string= request "if") (woman0-if "if"))
2398 ((string= request "ie") (woman0-if "ie"))
2399 ((string= request "el") (woman0-el))
2400 ((string= request "so") (woman0-so))
2401 ((string= request "rn") (woman0-rn))
2402 ((string= request "de") (woman0-de))
2403 ((string= request "am") (woman0-de 'append))
2404 (t (woman0-macro request))))
2405 (set-marker woman0-if-to nil)
2406 (woman0-rename)
2407 ;; Should now re-run `woman0-roff-buffer' if any renaming was
2408 ;; done, but let's just hope this is not necessary for now!
2411 (defun woman0-ig ()
2412 ".ig yy -- Discard input up to `.yy', which defaults to `..')."
2413 ;; The terminal request MUST begin with . (not ')!
2414 (looking-at "\\(\\S +\\)?")
2415 (beginning-of-line)
2416 (let ((yy (or (match-string 1) "."))
2417 (from (point)))
2418 (if (re-search-forward
2419 (concat "^\\.[ \t]*" (regexp-quote yy) ".*\n") nil t)
2420 (delete-region from (point))
2421 (WoMan-warn
2422 "ig request ignored -- terminator `.%s' not found!" yy)
2423 (woman-delete-line 1))
2426 (defsubst woman0-process-escapes (from to)
2427 "Process escapes within an if/ie condition between FROM and TO."
2428 (woman-strings to)
2429 (goto-char from) ; necessary!
2430 ;; Strip font-change escapes:
2431 (while (re-search-forward "\\\\f\\((..\\|.\\)" to t)
2432 (woman-delete-match 0))
2433 (goto-char from) ; necessary!
2434 (woman2-process-escapes to 'numeric))
2436 (defun woman0-if (request)
2437 ".if/ie c anything -- Discard unless c evaluates to true.
2438 Remember condition for use by a subsequent `.el'.
2439 REQUEST is the invoking directive without the leading dot."
2440 ;; c evaluates to a one-character built-in condition name or
2441 ;; 'string1'string2' or a number > 0, prefix ! negates.
2442 ;; \{ ... \} for multi-line use.
2443 ;; Leaves point at start of new text.
2444 (woman-delete-match 0)
2445 ;; (delete-horizontal-space)
2446 ;; Process escapes in condition:
2447 (let ((from (point)) negated n (c 0))
2448 (set-marker woman0-if-to
2449 (save-excursion (skip-syntax-forward "^ ") (point)))
2450 ;; Process condition:
2451 (if (setq negated (= (following-char) ?!)) (delete-char 1))
2452 (cond
2453 ;; ((looking-at "[no]") (setq c t)) ; accept n(roff) and o(dd page)
2454 ;; ((looking-at "[te]") (setq c nil)) ; reject t(roff) and e(ven page)
2455 ((looking-at "[ntoe]")
2456 (setq c (memq (following-char) woman-if-conditions-true)))
2457 ;; Unrecognised letter so reject:
2458 ((looking-at "[A-Za-z]") (setq c nil)
2459 (WoMan-warn "%s %s -- unrecognised condition name rejected!"
2460 request (match-string 0)))
2461 ;; Accept strings if identical:
2462 ((save-restriction
2463 (narrow-to-region from woman0-if-to)
2464 ;; String delimiter can be any non-numeric character,
2465 ;; including a special character escape:
2466 (looking-at "\\(\\\\(..\\|[^0-9]\\)\\(.*\\)\\1\\(.*\\)\\1\\'"))
2467 (let ((end1 (copy-marker (match-end 2)))) ; end of first string
2468 ;; Delete 2nd and 3rd delimiters to avoid processing them:
2469 (delete-region (match-end 3) woman0-if-to)
2470 (delete-region (match-end 2) (match-beginning 3))
2471 (goto-char (match-end 1))
2472 (woman0-process-escapes (point) woman0-if-to)
2473 (setq c (string= (buffer-substring (point) end1)
2474 (buffer-substring end1 woman0-if-to)))
2475 (set-marker end1 nil)
2476 (goto-char from)))
2477 ;; Accept numeric value if > 0:
2478 ((numberp (setq n (progn
2479 (woman0-process-escapes from woman0-if-to)
2480 (woman-parse-numeric-arg))))
2481 (setq c (> n 0))
2482 (goto-char from))
2484 (if (eq c 0)
2485 (woman-if-ignore woman0-if-to request) ; ERROR!
2486 (woman-if-body request woman0-if-to (eq c negated)))
2489 (defun woman-if-body (request to delete) ; should be reversed as `accept'?
2490 "Process if-body, including \\{ ... \\}.
2491 REQUEST is the invoking directive without the leading dot.
2492 If TO is non-nil then delete the if-body.
2493 If DELETE is non-nil then delete from point."
2494 ;; Assume concealed newlines already processed.
2495 (let ((from (point)))
2496 (if to (delete-region (point) to))
2497 (delete-horizontal-space)
2498 (cond (;;(looking-at "[^{\n]*\\\\{\\s *") ; multi-line
2499 ;; allow escaped newlines:
2500 (looking-at "[^{\n]*\\(\\\\\n\\)*\\\\{\\s *\\(\\\\\n\\)*") ; multi-line
2501 ;; including preceding .if(s) and following newline
2502 (let ((from (point)))
2503 (woman-delete-match 0)
2504 ;; Allow for nested \{ ... \} -- BUT BEWARE that this
2505 ;; algorithm only supports one level of nesting!
2506 (while
2507 (and (re-search-forward
2508 ;; "\\(\\\\{\\)\\|\\(\n[.']\\)?[ \t]*\\\\}[ \t]*"
2509 ;; Interpret bogus `el \}' as `el \{',
2510 ;; especially for Tcl/Tk man pages:
2511 "\\(\\\\{\\|el[ \t]*\\\\}\\)\\|\\(\n[.']\\)?[ \t]*\\\\}[ \t]*")
2512 (match-string 1))
2513 (re-search-forward "\\\\}"))
2514 (delete-region (if delete from (match-beginning 0)) (point))
2515 (if (looking-at "^$") (delete-char 1))
2517 (delete (woman-delete-line 1)) ; single-line
2519 ;; Process matching .el anything:
2520 (cond ((string= request "ie")
2521 ;; Discard unless previous .ie c `evaluated to false'.
2522 (cond ((re-search-forward "^[.'][ \t]*el[ \t]*" nil t)
2523 (woman-delete-match 0)
2524 (woman-if-body "el" nil (not delete)))))
2525 ;; Got here after processing a single-line `.ie' as a body
2526 ;; clause to be discarded:
2527 ((string= request "el")
2528 (cond ((re-search-forward "^[.'][ \t]*el[ \t]*" nil t)
2529 (woman-delete-match 0)
2530 (woman-if-body "el" nil t))))
2532 (goto-char from)
2535 (defun woman0-el ()
2536 "Isolated .el request -- should not happen!"
2537 (WoMan-warn "el request without matching `ie' rejected!")
2538 (cond (woman-ignore
2539 (woman-delete-match 0)
2540 (delete-horizontal-space)
2541 (woman-if-body "el" nil t))
2542 (t ; Ignore -- leave in buffer
2543 ;; This does not work too well, but it's only for debugging!
2544 (skip-chars-forward "^ \t")
2545 (if (looking-at "[ \t]*\\{") (search-forward "\\}"))
2546 (forward-line 1))))
2548 (defun woman-if-ignore (to request)
2549 "Ignore but warn about an if request ending at TO, named REQUEST."
2550 (WoMan-warn-ignored request "ignored -- condition not handled!")
2551 (if woman-ignore
2552 (woman-if-body request to t)
2553 ;; Ignore -- leave in buffer
2554 ;; This does not work too well, but it's only for debugging!
2555 (skip-chars-forward "^ \t")
2556 (if (looking-at "[ \t]*\\{") (search-forward "\\}"))
2557 (forward-line 1)))
2559 (defun woman0-so ()
2560 ".so filename -- Switch source file. `.so' requests may be nested."
2561 ;; Leaves point at start of new text.
2562 ;; (skip-chars-forward " \t")
2563 (let* ((beg (point))
2564 (end (progn (woman-forward-arg 'unquote) (point)))
2565 (name (buffer-substring beg end))
2566 (filename name))
2567 ;; If the specified file does not exist in this ...
2568 (or (file-exists-p filename)
2569 ;; or the parent directory ...
2570 (file-exists-p
2571 (setq filename (concat "../" name)))
2572 ;; then use the WoMan search mechanism to find the filename ...
2573 (setq filename
2574 (woman-file-name
2575 (file-name-sans-extension
2576 (file-name-nondirectory name))))
2577 ;; Cannot find the file, so ...
2578 (kill-buffer (current-buffer))
2579 (error "File `%s' not found" name))
2580 (beginning-of-line)
2581 (woman-delete-line 1)
2582 (let ((from (point))
2583 (to (make-marker))
2584 (length (woman-insert-file-contents filename 0)))
2585 (set-marker to (+ from length))
2586 (woman-pre-process-region from to)
2587 (set-marker to nil)
2588 (goto-char from)
2592 ;;; Process macro definitions:
2594 (defun woman0-rn ()
2595 "Process .rn xx yy -- rename macro xx to yy."
2596 ;; For now, done backwards AFTER all macro expansion.
2597 ;; Should also allow requests and strings to be renamed!
2598 (if (eolp) ; ignore if no argument
2600 (let* ((beg (point))
2601 (end (progn (woman-forward-arg 'unquote 'concat) (point)))
2602 (old (buffer-substring beg end))
2603 new)
2604 (if (eolp) ; ignore if no argument
2606 (setq beg (point)
2607 end (progn (woman-forward-arg 'unquote) (point))
2608 new (buffer-substring beg end)
2609 woman0-rename-alist (cons (cons new old) woman0-rename-alist)))
2611 (woman-delete-whole-line))
2613 (defun woman0-rename ()
2614 "Effect renaming required by .rn requests."
2615 ;; For now, do this backwards AFTER all macro expansion.
2616 (while woman0-rename-alist
2617 (let* ((new (car woman0-rename-alist))
2618 (old (cdr new))
2619 (new (car new)))
2620 (setq woman0-rename-alist (cdr woman0-rename-alist))
2621 (goto-char (point-min))
2622 (setq new (concat "^[.'][ \t]*" (regexp-quote new)))
2623 (setq old (concat "." old))
2624 (while (re-search-forward new nil t)
2625 (replace-match old nil t)))))
2627 (defconst woman-unescape-regex
2628 (concat woman-escaped-escape-string
2629 "\\(" woman-escaped-escape-string "\\)?"))
2631 (defsubst woman-unescape (macro)
2632 "Replace escape sequences in the body of MACRO.
2633 Replaces || by |, but | by \, where | denotes the internal escape."
2634 (let (start)
2635 (while (setq start (string-match woman-unescape-regex macro start))
2636 (setq macro
2637 (if (match-string 1 macro)
2638 (replace-match "" t t macro 1)
2639 (replace-match "\\" t t macro))
2640 start (1+ start)))
2641 macro))
2643 (defun woman0-de (&optional append)
2644 "Process .de/am xx yy -- (re)define/append macro xx; end at `..'.
2645 \(Should be up to call of yy, which defaults to `.')
2646 Optional argument APPEND, if non-nil, means append macro."
2647 ;; Modelled on woman-strings. BEWARE: Processing of .am is a hack!
2648 ;; Add support for .rm?
2649 ;; (skip-chars-forward " \t")
2650 (if (eolp) ; ignore if no argument
2652 (looking-at "[^ \t\n]+") ; macro name
2653 (let* ((macro (match-string 0)) from
2654 (previous (assoc macro woman0-macro-alist)))
2655 (if (not previous)
2656 (setq woman0-search-regex-start
2657 (concat woman0-search-regex-start "\\|" (regexp-quote macro))
2658 woman0-search-regex
2659 (concat woman0-search-regex-start woman0-search-regex-end)
2661 ;; Macro body runs from start of next line to line
2662 ;; beginning with `..'."
2663 ;; The terminal request MUST begin with `.' (not ')!
2664 (forward-line)
2665 (setq from (point))
2666 (re-search-forward "^\\.[ \t]*\\.")
2667 (beginning-of-line)
2668 (let ((body (woman-unescape (buffer-substring from (point)))))
2669 (if (and append previous)
2670 (setq previous (cdr previous)
2671 body (concat body (cdr previous))
2672 append (car previous)
2674 (setq macro (cons macro (cons append body))))
2675 ;; This should be an update, but consing a new string
2676 ;; onto the front of the alist has the same effect:
2677 (setq woman0-macro-alist (cons macro woman0-macro-alist))
2678 (forward-line)
2679 (delete-region from (point))
2680 (backward-char) ; return to end of .de/am line
2682 (beginning-of-line) ; delete .de/am line
2683 (woman-delete-line 1))
2685 (defun woman0-macro (request)
2686 "Process the macro call named REQUEST."
2687 ;; Leaves point at start of new text.
2688 (let ((macro (assoc request woman0-macro-alist)))
2689 (if macro
2690 (woman-interpolate-macro (cdr macro))
2691 ;; SHOULD DELETE THE UNINTERPRETED REQUEST!!!!!
2692 ;; Output this message once only per call (cf. strings)?
2693 (WoMan-warn "Undefined macro %s not interpolated!" request))))
2695 (defun woman-interpolate-macro (macro)
2696 "Interpolate (.de) or append (.am) expansion of MACRO into the buffer."
2697 ;; Could make this more efficient by checking which arguments are
2698 ;; actually used in the expansion!
2699 (skip-chars-forward " \t")
2700 ;; Process arguments:
2701 (let ((argno 0) (append (car macro))
2702 argno-string formal-arg from actual-arg start)
2703 (setq macro (cdr macro))
2704 (while (not (eolp))
2705 ;; Get next actual arg:
2706 (setq argno (1+ argno))
2707 (setq argno-string (format "%d" argno))
2708 (setq formal-arg (concat "\\\\\\$" argno-string)) ; regexp
2709 (setq from (point))
2710 (woman-forward-arg 'unquote 'noskip)
2711 (setq actual-arg (buffer-substring from (point)))
2712 (skip-chars-forward " \t") ; now skip following whitespace!
2713 ;; Replace formal arg with actual arg:
2714 (setq start nil)
2715 (while (setq start (string-match formal-arg macro start))
2716 (setq macro (replace-match actual-arg t t macro)))
2718 ;; Delete any remaining formal arguments:
2719 (setq start nil)
2720 (while
2721 (setq start (string-match "\\\\\\$." macro start))
2722 (setq macro (replace-match "" t t macro)))
2723 ;; Replace .$ number register with actual arg:
2724 ;; (Do this properly via register mechanism later!)
2725 (setq start nil)
2726 (while
2727 (setq start (string-match "\\\\n(\\.\\$" macro start)) ; regexp
2728 (setq macro (replace-match argno-string t t macro)))
2729 (if append
2730 (forward-char)
2731 (beginning-of-line)
2732 (woman-delete-line 1))
2733 (save-excursion ; leave point at start of new text
2734 (insert macro))))
2737 ;;; Process strings:
2739 (defun woman-strings (&optional to)
2740 "Process ?roff string requests and escape sequences up to buffer position TO.
2741 Strings are defined/updated by `.ds xx string' requests and
2742 interpolated by `\*x' and `\*(xx' escapes."
2743 ;; Add support for .as and .rm?
2744 (while
2745 ;; Find .ds requests and \* escapes:
2746 (re-search-forward "\\(^[.'][ \t]*ds\\)\\|\\\\\\*" to t)
2747 (cond ((match-string 1) ; .ds
2748 (skip-chars-forward " \t")
2749 (if (eolp) ; ignore if no argument
2751 (re-search-forward "[^ \t\n]+")
2752 (let ((string (match-string 0)))
2753 (skip-chars-forward " \t")
2754 ; (setq string
2755 ; (cons string
2756 ; ;; hack (?) for CGI.man!
2757 ; (cond ((looking-at "\"\"") "\"")
2758 ; ((looking-at ".*") (match-string 0)))
2759 ; ))
2760 ;; Above hack causes trouble in arguments!
2761 (looking-at ".*")
2762 (setq string (cons string (match-string 0)))
2763 ;; This should be an update, but consing a new string
2764 ;; onto the front of the alist has the same effect:
2765 (setq woman-string-alist (cons string woman-string-alist))
2767 (beginning-of-line)
2768 (woman-delete-line 1))
2769 (t ; \*
2770 (let ((beg (match-beginning 0)))
2771 (cond ((= (following-char) ?\( )
2772 (forward-char)
2773 (re-search-forward ".."))
2774 (t (re-search-forward ".")))
2775 (let* ((stringname (match-string 0))
2776 (string (assoc stringname woman-string-alist)))
2777 (cond (string
2778 (delete-region beg (point))
2779 ;; Temporary hack in case string starts with a
2780 ;; control character:
2781 (if (bolp) (insert-before-markers "\\&"))
2782 (insert-before-markers (cdr string)))
2784 (WoMan-warn "Undefined string %s not interpolated!"
2785 stringname)
2786 (cond (woman-ignore
2787 ;; Output above message once only per call
2788 (delete-region beg (point))
2789 (setq woman-string-alist
2790 (cons (cons stringname "")
2791 woman-string-alist))))
2798 ;;; Process special character escapes \(xx:
2800 (defconst woman-special-characters
2801 ;; To be built heuristically as required!
2802 ;; MUST insert all characters as strings for correct conversion to
2803 ;; multibyte representation!
2804 '(("em" "--" "\276" . t) ; 3/4 Em dash
2805 ("bu" "*" "\267" . t) ; bullet
2806 ("fm" "'") ; foot mark
2807 ("co" "(C)" "\251") ; copyright
2809 ("pl" "+" "+" . t) ; math plus
2810 ("mi" "-" "-" . t) ; math minus
2811 ("**" "*" "*" . t) ; math star
2812 ("aa" "'" "\242" . t) ; acute accent
2813 ("ul" "_") ; underrule
2815 ("*S" "Sigma" "S" . t) ; Sigma
2817 (">=" ">=" "\263" . t) ; >=
2818 ("<=" "<=" "\243" . t) ; <=
2819 ("->" "->" "\256" . t) ; right arrow
2820 ("<-" "<-" "\254" . t) ; left arrow
2821 ("mu" " x " "\264" . t) ; multiply
2822 ("+-" "+/-" "\261" . t) ; plus-minus
2823 ("bv" "|") ; bold vertical
2825 ;; groff etc. extensions:
2826 ("lq" "\"")
2827 ("rq" "\"")
2828 ("aq" "'")
2829 ("ha" "^")
2830 ("ti" "~")
2832 "Alist of special character codes with ASCII and extended-font equivalents.
2833 Each alist elements has the form
2834 (input-string ascii-string extended-font-string . use-symbol-font)
2835 where
2836 * `\\(input-string' is the ?roff encoding,
2837 * `ascii-string' is the (multi-character) ASCII simulation,
2838 * `extended-font-string' is the single-character string representing
2839 the character position in the extended 256-character font, and
2840 * `use-symbol-font' is t to indicate use of the symbol font or nil,
2841 i.e. omitted, to indicate use of the default font.
2842 Any element may be nil. Avoid control character codes (0 to \\37, \\180
2843 to \\237) in `extended-font-string' for now, since they can be
2844 displayed only with a modified display table.
2846 Use the WoMan command `woman-display-extended-fonts' or a character
2847 map accessory to help construct this alist.")
2849 (defsubst woman-replace-match (newtext &optional face)
2850 "Replace text matched by last search with NEWTEXT and return t.
2851 Set NEWTEXT in face FACE if specified."
2852 (woman-delete-match 0)
2853 (insert-before-markers newtext)
2854 (if face (put-text-property (1- (point)) (point)
2855 'face 'woman-symbol-face))
2858 (defun woman-special-characters (to)
2859 "Process special character escapes \(xx up to buffer position TO.
2860 \(This must be done AFTER translation, which may use special characters.)"
2861 (while (re-search-forward "\\\\(\\(..\\)" to t)
2862 (let ((replacement
2863 (assoc (match-string-no-properties 1) woman-special-characters)))
2864 (if (and
2865 replacement
2866 (cond ((and (cddr replacement)
2867 (if (nthcdr 3 replacement)
2868 ;; Need symbol font:
2869 (if woman-use-symbol-font
2870 (woman-replace-match (nth 2 replacement)
2871 'woman-symbol-face))
2872 ;; Need extended font:
2873 (if woman-use-extended-font
2874 (woman-replace-match (nth 2 replacement))))))
2875 ((cadr replacement) ; Use ASCII simulation
2876 (woman-replace-match (cadr replacement)))))
2878 (WoMan-warn "Special character \\(%s not interpolated!"
2879 (match-string-no-properties 1))
2880 (if woman-ignore (woman-delete-match 0))))
2883 (defun woman-display-extended-fonts ()
2884 "Display table of glyphs of graphic characters and their octal codes.
2885 All the octal codes in the ranges [32..127] and [160..255] are displayed
2886 together with the corresponding glyphs from the default and symbol fonts.
2887 Useful for constructing the alist variable `woman-special-characters'."
2888 (interactive)
2889 (with-output-to-temp-buffer "*WoMan Extended Font Map*"
2890 (save-excursion
2891 (set-buffer standard-output)
2892 (let ((i 32))
2893 (while (< i 256)
2894 (insert (format "\\%03o " i) (string i) " " (string i))
2895 (put-text-property (1- (point)) (point)
2896 'face 'woman-symbol-face)
2897 (insert " ")
2898 (setq i (1+ i))
2899 (when (= i 128) (setq i 160) (insert "\n"))
2900 (if (zerop (% i 8)) (insert "\n")))
2902 (print-help-return-message)))
2905 ;;; Formatting macros that do not cause a break:
2907 (defvar request) ; Bound locally by woman1-roff-buffer
2908 (defvar unquote) ; Bound locally by woman1-roff-buffer
2910 (defun woman-unquote (to)
2911 "Delete any double-quote characters between point and TO.
2912 Leave point at TO (which should be a marker)."
2913 (let (in-quote)
2914 (while (search-forward "\"" to 1)
2915 (if (and in-quote (looking-at "\""))
2916 ;; Repeated double-quote represents single double-quote
2917 (delete-char 1)
2918 (if (or in-quote (looking-at ".*\"")) ; paired
2919 (delete-char -1))
2920 (setq in-quote (not in-quote))
2922 (if in-quote
2923 (WoMan-warn "Unpaired \" in .%s arguments." request))
2926 (defsubst woman-unquote-args ()
2927 "Delete any double-quote characters up to the end of the line."
2928 (woman-unquote (save-excursion (end-of-line) (point-marker))))
2930 (defun woman1-roff-buffer ()
2931 "Process non-breaking requests."
2932 (let ((case-fold-search t)
2933 request fn unquote)
2934 (while
2935 ;; Find next control line:
2936 (re-search-forward woman-request-regexp nil t)
2937 (cond
2938 ;; Construct woman function to call:
2939 ((setq fn (intern-soft
2940 (concat "woman1-"
2941 (setq request (match-string 1)))))
2942 (if (get fn 'notfont) ; not a font-change request
2943 (funcall fn)
2944 ;; Delete request or macro name:
2945 (woman-delete-match 0)
2946 ;; If no args then apply to next line else unquote args
2947 ;; (unquote is used by called function):
2948 (setq unquote (not (eolp)))
2949 (if (eolp) (delete-char 1))
2950 ; ;; Hide leading control character in unquoted argument:
2951 ; (cond ((memq (following-char) '(?. ?'))
2952 ; (insert "\\&")
2953 ; (beginning-of-line)))
2954 ;; Call the appropriate function:
2955 (funcall fn)
2956 ;; Hide leading control character in quoted argument (only):
2957 (if (and unquote (memq (following-char) '(?. ?')))
2958 (insert "\\&"))
2960 )))))
2962 ;;; Font-changing macros:
2964 (defun woman1-B ()
2965 ".B -- Set words of current line in bold font."
2966 (woman1-B-or-I ".ft B\n"))
2968 (defun woman1-I ()
2969 ".I -- Set words of current line in italic font."
2970 (woman1-B-or-I ".ft I\n"))
2972 (defun woman1-B-or-I (B-or-I)
2973 ".B/I -- Set words of current line in bold/italic font.
2974 B-OR-I is the appropriate complete control line."
2975 ;; Should NOT concatenate the arguments!
2976 (insert B-or-I) ; because it might be a control line
2977 ;; Return to bol to process .SM/.B, .B/.if etc.
2978 ;; or start of first arg to hide leading control char.
2979 (save-excursion
2980 (if unquote
2981 (woman-unquote-args)
2982 (while (looking-at "^[.']") (forward-line))
2983 (end-of-line)
2984 (delete-horizontal-space))
2985 (insert "\\fR")))
2987 (defun woman1-SM ()
2988 ".SM -- Set the current line in small font, i.e. IGNORE!"
2989 nil)
2991 (defalias 'woman1-SB 'woman1-B)
2992 ;; .SB -- Set the current line in small bold font, i.e. just embolden!
2993 ;; (This is what /usr/local/share/groff/tmac/tmac.an does. The
2994 ;; Linux man.7 is wrong about this!)
2996 (defun woman1-BI ()
2997 ".BI -- Join words of current line alternating bold and italic fonts."
2998 (woman1-alt-fonts (list "\\fB" "\\fI")))
3000 (defun woman1-BR ()
3001 ".BR -- Join words of current line alternating bold and Roman fonts."
3002 (woman1-alt-fonts (list "\\fB" "\\fR")))
3004 (defun woman1-IB ()
3005 ".IB -- Join words of current line alternating italic and bold fonts."
3006 (woman1-alt-fonts (list "\\fI" "\\fB")))
3008 (defun woman1-IR ()
3009 ".IR -- Join words of current line alternating italic and Roman fonts."
3010 (woman1-alt-fonts (list "\\fI" "\\fR")))
3012 (defun woman1-RB ()
3013 ".RB -- Join words of current line alternating Roman and bold fonts."
3014 (woman1-alt-fonts (list "\\fR" "\\fB")))
3016 (defun woman1-RI ()
3017 ".RI -- Join words of current line alternating Roman and italic fonts."
3018 (woman1-alt-fonts (list "\\fR" "\\fI")))
3020 (defun woman1-alt-fonts (fonts)
3021 "Join words using alternating fonts in FONTS, which MUST be a dynamic list."
3022 (nconc fonts fonts) ; circular list!
3023 (insert (car fonts))
3024 ;; Return to start of first arg to hide leading control char:
3025 (save-excursion
3026 (setq fonts (cdr fonts))
3027 (woman-forward-arg unquote 'concat) ; unquote is bound above
3028 (while (not (eolp))
3029 (insert (car fonts))
3030 (setq fonts (cdr fonts))
3031 (woman-forward-arg unquote 'concat)) ; unquote is bound above
3032 (insert "\\fR")
3035 (defun woman-forward-arg (&optional unquote concat)
3036 "Move forward over one ?roff argument, optionally unquoting and/or joining.
3037 If optional arg UNQUOTE is non-nil then delete any argument quotes.
3038 If optional arg CONCAT is non-nil then join arguments."
3039 (if (eq (following-char) ?\")
3040 (progn
3041 (if unquote (delete-char 1) (forward-char))
3042 (re-search-forward "\"\\|$")
3043 ;; Repeated double-quote represents single double-quote
3044 (while (eq (following-char) ?\") ; paired
3045 (if unquote (delete-char 1) (forward-char))
3046 (re-search-forward "\"\\|$"))
3047 (if (eq (preceding-char) ?\")
3048 (if unquote (delete-backward-char 1))
3049 (WoMan-warn "Unpaired \" in .%s arguments." request)
3051 ;; (re-search-forward "[^\\\n] \\|$") ; inconsistent
3052 (skip-syntax-forward "^ "))
3053 (cond ((null concat) (skip-chars-forward " \t")) ; don't skip eol!
3054 ((eq concat 'noskip)) ; do not skip following whitespace
3055 (t (woman-delete-following-space)))
3059 ;; The following requests are not explicit font-change requests and
3060 ;; so are flagged `notfont' to turn off automatic request deletion
3061 ;; and further processing.
3063 (put 'woman1-TP 'notfont t)
3064 (defun woman1-TP ()
3065 ".TP -- After tag line, reset font to Roman for paragraph body."
3066 ;; Same for .IP, but forward only 1 line?
3067 (save-excursion
3068 ;; May be an `irrelevant' control line in the way, so ...
3069 (forward-line)
3070 (forward-line (if (looking-at "\\.\\S-+[ \t]*$") 2 1))
3071 ;; May be looking at control line, so ...
3072 (insert ".ft R\n")))
3074 (put 'woman1-ul 'notfont t)
3075 (defun woman1-ul ()
3076 ".ul N -- Underline (italicize) the next N input lines, default N = 1."
3077 (let ((N (if (eolp) 1 (woman-parse-numeric-arg)))) ; woman-get-numeric-arg ?
3078 (woman-delete-whole-line)
3079 (insert ".ft I\n")
3080 (forward-line N)
3081 (insert ".ft R\n")
3084 ;;; Other non-breaking requests:
3086 ;; Hyphenation
3087 ;; Warnings commented out.
3089 (put 'woman1-nh 'notfont t)
3090 (defun woman1-nh ()
3091 ".nh -- No hyphenation, i.e. IGNORE!"
3092 ;; Must be handled here to avoid breaking!
3093 ;; (WoMan-log-1 ".nh request ignored -- hyphenation not supported!")
3094 (woman-delete-whole-line))
3096 (put 'woman1-hy 'notfont t)
3097 (defun woman1-hy ()
3098 ".hy N -- Set hyphenation mode to N, i.e. IGNORE!"
3099 ;; (WoMan-log-1 ".hy request ignored -- hyphenation not supported!")
3100 (woman-delete-whole-line))
3102 (put 'woman1-hc 'notfont t)
3103 (defun woman1-hc ()
3104 ".hc c -- Set hyphenation character to c, i.e. delete it!"
3105 (let ((c (char-to-string (following-char))))
3106 ;; (WoMan-log
3107 ;; "Hyphenation character %s deleted -- hyphenation not supported!" c)
3108 (woman-delete-whole-line)
3109 (setq c (concat "\\(" c "\\)\\|^[.'][ \t]*hc"))
3110 (save-excursion
3111 (while (and (re-search-forward c nil t)
3112 (match-string 1))
3113 (delete-char -1)))
3116 (put 'woman1-hw 'notfont t)
3117 (defun woman1-hw ()
3118 ".hw words -- Set hyphenation exception words, i.e. IGNORE!"
3119 ;; (WoMan-log-1 ".hw request ignored -- hyphenation not supported!")
3120 (woman-delete-whole-line))
3122 ;;; Other non-breaking requests correctly ignored by nroff:
3124 (put 'woman1-ps 'notfont t)
3125 (defalias 'woman1-ps 'woman-delete-whole-line)
3126 ;; .ps -- Point size -- IGNORE!
3128 (put 'woman1-ss 'notfont t)
3129 (defalias 'woman1-ss 'woman-delete-whole-line)
3130 ;; .ss -- Space-character size -- IGNORE!
3132 (put 'woman1-cs 'notfont t)
3133 (defalias 'woman1-cs 'woman-delete-whole-line)
3134 ;; .cs -- Constant character space (width) mode -- IGNORE!
3136 (put 'woman1-ne 'notfont t)
3137 (defalias 'woman1-ne 'woman-delete-whole-line)
3138 ;; .ne -- Need vertical space -- IGNORE!
3140 (put 'woman1-vs 'notfont t)
3141 (defalias 'woman1-vs 'woman-delete-whole-line)
3142 ;; .vs -- Vertical base line spacing -- IGNORE!
3144 (put 'woman1-bd 'notfont t)
3145 (defalias 'woman1-bd 'woman-delete-whole-line)
3146 ;; .bd -- Embolden font -- IGNORE!
3148 ;;; Non-breaking SunOS-specific macros:
3150 (defun woman1-TX ()
3151 ".TX t p -- Resolve SunOS abbrev t and join to p (usually punctuation)."
3152 (insert "SunOS ")
3153 (woman-forward-arg 'unquote 'concat))
3155 (put 'woman1-IX 'notfont t)
3156 (defalias 'woman1-IX 'woman-delete-whole-line)
3157 ;; .IX -- Index macro, for Sun internal use -- IGNORE!
3160 ;;; Direct font selection:
3162 (defconst woman-font-alist
3163 '(("R" . default)
3164 ("I" . woman-italic-face)
3165 ("B" . woman-bold-face)
3166 ("P" . previous)
3167 ("1" . default)
3168 ("2" . woman-italic-face)
3169 ("3" . woman-bold-face) ; used in bash.1
3171 "Alist of ?roff font indicators and woman font variables and names.")
3173 (defun woman-change-fonts ()
3174 "Process font changes."
3175 ;; ***** NEEDS REVISING IF IT WORKS OK *****
3176 ;; Paragraph .LP/PP/HP/IP/TP and font .B/.BI etc. macros reset font.
3177 ;; Should .SH/.SS reset font?
3178 ;; Font size setting macros (?) should reset font.
3179 (let ((woman-font-alist woman-font-alist) ; for local updating
3180 (previous-pos (point))
3181 (previous-font 'default)
3182 (current-font 'default))
3183 (while
3184 ;; Find font requests, paragraph macros and font escapes:
3185 (re-search-forward
3186 "^[.'][ \t]*\\(\\(\\ft\\)\\|\\(.P\\)\\)\\|\\(\\\\f\\)" nil 1)
3187 (let (font beg notfont)
3188 ;; Match font indicator and leave point at end of sequence:
3189 (cond ((match-string 2)
3190 ;; .ft request found
3191 (setq beg (match-beginning 0))
3192 (skip-chars-forward " \t")
3193 (if (eolp) ; default is previous font
3194 (setq font previous-font)
3195 (looking-at "[^ \t\n]+"))
3196 (forward-line)) ; end of control line and \n
3197 ((match-string 3)
3198 ;; Macro that resets font found
3199 (setq font 'default))
3200 ((match-string 4)
3201 ;; \f escape found
3202 (setq beg (match-beginning 0))
3203 (cond ((= (following-char) ?\( )
3204 (forward-char)
3205 (re-search-forward ".."))
3206 (t (re-search-forward ".")))
3208 (t (setq notfont t)))
3209 (if notfont
3211 ;; Get font name:
3212 (or font
3213 (let ((fontstring (match-string 0)))
3214 (setq font (assoc fontstring woman-font-alist)
3215 ;; NB: woman-font-alist contains VARIABLE NAMES.
3216 font (if font
3217 (cdr font)
3218 (WoMan-warn "Unknown font %s." fontstring)
3219 ;; Output this message once only per call ...
3220 (setq woman-font-alist
3221 (cons (cons fontstring 'woman-unknown-face)
3222 woman-font-alist))
3223 'woman-unknown-face)
3225 ;; Delete font control line or escape sequence:
3226 (cond (beg (delete-region beg (point))
3227 (if (eq font 'previous) (setq font previous-font))))
3228 (woman-set-face previous-pos (point) current-font)
3229 (if beg
3230 ;; Explicit font control
3231 (setq previous-pos (point)
3232 previous-font current-font)
3233 ;; Macro that resets font
3234 ;; (forward-line) ; DOES NOT WORK! but unnecessary?
3235 ;; Must process font changes in any paragraph tag!
3236 (setq previous-pos (point)
3237 previous-font 'default))
3238 (setq current-font font)
3240 ;; Set font after last request up to eob:
3241 (woman-set-face previous-pos (point) current-font)
3244 (defun woman-set-face (from to face)
3245 "Set the face of the text from FROM to TO to face FACE.
3246 Ignore the default face and underline only word characters."
3247 (or (eq face 'default) ; ignore
3248 (not woman-fontify)
3249 (if (face-underline-p face)
3250 (save-excursion
3251 (let ((face-no-ul (intern (concat (symbol-name face) "-no-ul"))))
3252 (goto-char from)
3253 (while (< (point) to)
3254 (skip-syntax-forward "w" to)
3255 (put-text-property from (point) 'face face)
3256 (setq from (point))
3257 (skip-syntax-forward "^w" to)
3258 (put-text-property from (point) 'face face-no-ul)
3259 (setq from (point))
3261 (put-text-property from to 'face face))
3265 ;;; Output translation:
3267 (defvar translations nil) ; Also bound locally by woman2-roff-buffer
3268 ;; A list of the form (\"[ace]\" (a . b) (c . d) (e . ?\ )) or nil.
3270 (defun woman-get-next-char ()
3271 "Return and delete next char in buffer, including special chars."
3272 (if ;;(looking-at "\\\\(\\(..\\)")
3273 ;; Match special \(xx and strings \*x, \*(xx:
3274 (looking-at "\\\\\\((..\\|\\*\\((..\\|.\\)\\)")
3275 (prog1 (match-string 0)
3276 (woman-delete-match 0))
3277 (prog1 (char-to-string (following-char))
3278 (delete-char 1))))
3280 (defun woman2-tr (to)
3281 ".tr abcde -- Translate a -> b, c -> d, ..., e -> space.
3282 Format paragraphs upto TO. Supports special chars.
3283 \(Breaks, but should not.)"
3284 ;; This should be an update, but consing onto the front of the alist
3285 ;; has the same effect and match duplicates should not matter.
3286 ;; Initialize translation data structures:
3287 (let ((matches (car translations))
3288 (alist (cdr translations))
3289 a b)
3290 ;; `matches' must be a string:
3291 (setq matches
3292 (concat (if matches (substring matches 1 -1)) "]"))
3293 ;; Process .tr arguments:
3294 (while (not (eolp)) ; (looking-at "[ \t]*$") ???
3295 (setq a (woman-get-next-char))
3296 (if (eolp)
3297 (setq b " ")
3298 (setq b (woman-get-next-char)))
3299 (setq matches
3300 (if (= (length a) 1)
3301 (concat a matches)
3302 (concat matches "\\|\\" a))
3303 alist (cons (cons a b) alist)))
3304 (delete-char 1) ; no blank line
3305 ;; Rebuild translations list:
3306 (setq matches
3307 (if (= (string-to-char matches) ?\])
3308 (substring matches 3)
3309 (concat "[" matches))
3310 translations (cons matches alist))
3311 ;; Format any following text:
3312 (woman2-format-paragraphs to)
3315 (defsubst woman-translate (to)
3316 "Translate up to marker TO. Do this last of all transformations."
3317 (if translations
3318 (let ((matches (car translations))
3319 (alist (cdr translations)))
3320 (while (re-search-forward matches to t)
3321 ;; Done like this to retain text properties and
3322 ;; support translation of special characters:
3323 (insert-before-markers-and-inherit
3324 (cdr (assoc
3325 (buffer-substring-no-properties
3326 (match-beginning 0) (match-end 0))
3327 alist)))
3328 (woman-delete-match 0))
3332 ;;; Registers:
3334 (defvar woman-registers ; these are all read-only
3335 '((".H" 24) (".V" 48) ; resolution in basic units
3336 (".g" 0) ; not groff
3337 ;; (Iff emulating groff need to implement groff italic correction
3338 ;; \/, e.g. for pic.1)
3339 (".i" left-margin) ; current indent
3340 (".j" woman-adjust) ; current adjustment
3341 (".l" fill-column) ; current line length
3342 (".s" 12) ; current point size
3343 (".u" (if woman-nofill 0 1)) ; 1/0 in fill/nofill mode
3344 (".v" 48) ; current vertical line spacing
3346 "Register alist: the key is the register name as a string.
3347 Each element has the form (KEY VALUE . INC) -- inc may be nil.
3348 Also bound locally in `woman2-roff-buffer'.")
3350 (defun woman-mark-horizonal-position ()
3351 "\\kx -- Store current horizontal position in INPUT LINE in register x."
3352 (while (re-search-forward "\\\\k\\(.\\)" nil t)
3353 (goto-char (match-beginning 0))
3354 (setq woman-registers
3355 (cons (list (match-string 1) (current-column))
3356 woman-registers))
3357 (woman-delete-match 0)))
3359 (defsubst woman2-process-escapes-to-eol (&optional numeric)
3360 "Process remaining escape sequences up to eol.
3361 Handle numeric arguments specially if optional argument NUMERIC is non-nil."
3362 (woman2-process-escapes
3363 (save-excursion (end-of-line) (point-marker))
3364 numeric))
3366 (defun woman2-nr (to)
3367 ".nr R +/-N M -- Assign +/-N (wrt to previous value, if any) to register R.
3368 The increment for auto-incrementing is set to M.
3369 Format paragraphs upto TO. (Breaks, but should not!)"
3370 (let* ((name (buffer-substring
3371 (point)
3372 (progn (skip-syntax-forward "^ ") (point))))
3373 (pm (progn ; increment
3374 (skip-chars-forward " \t")
3375 (when (memq (char-after) '(?+ ?-))
3376 (forward-char) (char-before))))
3377 (value (if (eolp) ; no value
3378 nil ; to be interpreted as zero
3379 (woman2-process-escapes-to-eol 'numeric)
3380 (woman-parse-numeric-arg)))
3381 (inc (progn ; auto-increment
3382 (skip-chars-forward " \t")
3383 (if (eolp) ; no value
3384 nil ; to be interpreted as zero ???
3385 (woman-parse-numeric-arg))))
3386 (oldvalue (assoc name woman-registers)))
3387 (when oldvalue
3388 (setq oldvalue (cdr oldvalue)) ; (value . inc)
3389 (unless inc (setq inc (cdr oldvalue))))
3390 (cond ((null value)
3391 (setq value 0) ; correct?
3392 (WoMan-warn "nr %s -- null value assigned as zero!" name))
3393 ((symbolp value)
3394 (setq value (list 'quote value))))
3395 (if pm ; increment old value
3396 (setq oldvalue (if oldvalue (car oldvalue) 0)
3397 value (if (eq pm ?+)
3398 (+ oldvalue value)
3399 (- oldvalue value))))
3400 (setq woman-registers
3401 (cons (cons name (cons value inc)) woman-registers))
3402 (woman-delete-whole-line)
3403 (woman2-format-paragraphs to)))
3406 ;;; Numeric (and "non-text") request arguments:
3408 (defsubst woman-get-numeric-arg ()
3409 "Get the value of a numeric argument at or after point.
3410 The argument can include the width function and scale indicators.
3411 Assumes 10 characters per inch. Does not move point."
3412 (woman2-process-escapes-to-eol 'numeric)
3413 (save-excursion (woman-parse-numeric-arg)))
3415 (defun woman-parse-numeric-arg ()
3416 "Get the value of a numeric expression at or after point.
3417 Unlike `woman-get-numeric-arg', leaves point after the argument.
3418 The expression may be an argument in quotes."
3419 (if (= (following-char) ?\") (forward-char))
3420 ;; Allow leading +/-:
3421 (let ((value (if (looking-at "[+-]") 0 (woman-parse-numeric-value)))
3423 (while (cond
3424 ((looking-at "[+-/*%]") ; arithmetic operators
3425 (forward-char)
3426 (setq op (intern-soft (match-string 0)))
3427 (setq value (funcall op value (woman-parse-numeric-value))))
3428 ((looking-at "[<=>]=?") ; relational operators
3429 (goto-char (match-end 0))
3430 (setq op (or (intern-soft (match-string 0))
3431 (intern-soft "=")))
3432 (setq value (if (funcall op value (woman-parse-numeric-value))
3433 1 0)))
3434 ((memq (setq op (following-char)) '(?& ?:)) ; Boolean and / or
3435 (forward-char)
3436 (setq value
3437 ;; and / or are special forms, not functions, in ELisp
3438 (if (eq op ?&)
3439 ;; and
3440 (if (> value 0)
3441 (if (> (woman-parse-numeric-value) 0) 1 0)
3442 ;; skip second operand
3443 (prog1 0 (woman-parse-numeric-value)))
3444 ;; or
3445 (if (> value 0)
3446 ;; skip second operand
3447 (prog1 1 (woman-parse-numeric-value))
3448 (if (> (woman-parse-numeric-value) 0) 1 0))
3451 ; (if (looking-at "[ \t\nRC\)\"]") ; R, C are tab types
3452 ; ()
3453 ; (WoMan-warn "Unimplemented numerical operator `%c' in %s"
3454 ; (following-char)
3455 ; (buffer-substring
3456 ; (save-excursion (beginning-of-line) (point))
3457 ; (save-excursion (end-of-line) (point))))
3458 ; (skip-syntax-forward "^ "))
3459 value
3462 (defun woman-parse-numeric-value ()
3463 "Get a single numeric value at or after point.
3464 The value can be a number register or width function (which assumes 10
3465 characters per inch) and can include scale indicators. It may be an
3466 expression in parentheses. Leaves point after the value."
3467 ;; Must replace every \' by some different single character first
3468 ;; before calling this function by calling
3469 ;; (woman2-process-escapes-to-eol 'numeric)
3470 (if (eq (following-char) ?\()
3471 ;; Treat parenthesized expression as a single value.
3472 (let (n)
3473 (forward-char)
3474 (setq n (woman-parse-numeric-arg))
3475 (skip-syntax-forward " ")
3476 (if (eq (following-char) ?\))
3477 (forward-char)
3478 (WoMan-warn "Parenthesis confusion in numeric expression!"))
3480 (let ((n (cond ((looking-at "[-+]?[.0-9]+") ; single number
3481 ;; currently needed to set match-end, even though
3482 ;; string-to-number returns 0 if number not parsed.
3483 (string-to-number (match-string 0)))
3484 ((looking-at "\\\\n\\([-+]\\)?\\(\(\\(..\\)\\|\\(.\\)\\)")
3485 ;; interpolate number register, maybe auto-incremented
3486 (let* ((pm (match-string-no-properties 1))
3487 (name (or (match-string-no-properties 3)
3488 (match-string-no-properties 4)))
3489 (value (assoc name woman-registers)))
3490 (if value
3491 (let (inc)
3492 (setq value (cdr value) ; (value . inc)
3493 inc (cdr value)
3494 ;; eval internal (.X) registers
3495 ;; stored as lisp variable names:
3496 value (eval (car value)))
3497 (if (and pm inc) ; auto-increment
3498 (setq value
3499 (funcall (intern-soft pm) value inc)
3500 woman-registers
3501 (cons (cons name (cons value inc))
3502 woman-registers)))
3503 value)
3504 (WoMan-warn "Undefined register %s defaulted to 0."
3505 name)
3506 0) ; default to zero
3508 ((re-search-forward
3509 ;; Delimiter can be special char escape \(.. or
3510 ;; single normal char (usually '):
3511 "\\=\\\\w\\(\\\\(..\\|.\\)" nil t)
3512 (let ((from (match-end 0))
3513 (delim (regexp-quote (match-string 1))))
3514 (if (re-search-forward delim nil t)
3515 ;; Return width of string:
3516 (- (match-beginning 0) from)
3517 (WoMan-warn "Width escape delimiter error!"))))
3519 (if (null n)
3520 ;; ERROR -- should handle this better!
3521 (progn
3522 (WoMan-warn "Numeric/register argument error: %s"
3523 (buffer-substring
3524 (point)
3525 (save-excursion (end-of-line) (point))))
3526 (skip-syntax-forward "^ ")
3528 (goto-char (match-end 0))
3529 ;; Check for scale factor:
3531 (cond
3532 ((looking-at "\\s ") nil) ; stay put!
3533 ((looking-at "[mnuv]")) ; ignore for now
3534 ((looking-at "i") (setq n (* n 10))) ; inch
3535 ((looking-at "c") (setq n (* n 3.9))) ; cm
3536 ((looking-at "P") (setq n (* n 1.7))) ; Pica
3537 ((looking-at "p") (setq n (* n 0.14))) ; point
3538 ;; NB: May be immediately followed by + or -, etc.,
3539 ;; in which case do nothing and return nil.
3541 (goto-char (match-end 0)))
3542 (if (numberp n) (round n) n))
3546 ;;; VERTICAL FORMATTING -- Formatting macros that cause a break:
3548 ;; Vertical spacing philosophy:
3549 ;; Delete all vertical space as it is encountered. Then insert
3550 ;; vertical space only before text, as required.
3552 (defun woman2-roff-buffer ()
3553 "Process breaks. Format paragraphs and headings."
3554 (let ((case-fold-search t)
3555 (to (make-marker))
3556 (canonically-space-region
3557 (symbol-function 'canonically-space-region))
3558 (insert-and-inherit (symbol-function 'insert-and-inherit))
3559 (set-text-properties (symbol-function 'set-text-properties))
3560 (woman-registers woman-registers)
3561 fn request translations
3562 tab-stop-list)
3563 ;; ?roff does not squeeze multiple spaces, but does fill, so...
3564 (fset 'canonically-space-region 'ignore)
3565 ;; Try to avoid spaces inheriting underlines from preceding text!
3566 (fset 'insert-and-inherit (symbol-function 'insert))
3567 (fset 'set-text-properties 'ignore)
3568 (unwind-protect
3569 (while
3570 ;; Find next control line:
3571 (re-search-forward woman-request-regexp nil t)
3572 (cond
3573 ;; Construct woman function to call:
3574 ((setq fn (intern-soft
3575 (concat "woman2-"
3576 (setq request (match-string 1)))))
3577 ;; Delete request or macro name:
3578 (woman-delete-match 0))
3579 ;; Unrecognised request:
3580 ((prog1 nil
3581 ;; (WoMan-warn ".%s request ignored!" request)
3582 (WoMan-warn-ignored request "ignored!")
3583 ;; (setq fn 'woman2-LP)
3584 ;; AVOID LEAVING A BLANK LINE!
3585 ;; (setq fn 'woman2-format-paragraphs)
3587 ;; .LP assumes it is at eol and leaves a (blank) line,
3588 ;; so leave point at end of line before paragraph:
3589 ((or (looking-at "[ \t]*$") ; no argument
3590 woman-ignore) ; ignore all
3591 ;; (beginning-of-line) (kill-line)
3592 ;; AVOID LEAVING A BLANK LINE!
3593 (beginning-of-line) (woman-delete-line 1))
3594 (t (end-of-line) (insert ?\n))
3596 (if (not (or fn
3597 (and (not (memq (following-char) '(?. ?')))
3598 (setq fn 'woman2-format-paragraphs))))
3600 ;; Find next control line:
3601 (set-marker to (woman-find-next-control-line))
3602 ;; Call the appropriate function:
3603 (funcall fn to)))
3604 (if (not (eobp)) ; This should not happen, but ...
3605 (woman2-format-paragraphs (point-max-marker) woman-left-margin))
3606 (fset 'canonically-space-region canonically-space-region)
3607 (fset 'set-text-properties set-text-properties)
3608 (fset 'insert-and-inherit insert-and-inherit)
3609 (set-marker to nil))))
3611 (defun woman-find-next-control-line ()
3612 "Find and return start of next control line."
3613 ; (let ((to (save-excursion
3614 ; (re-search-forward "^\\." nil t))))
3615 ; (if to (1- to) (point-max)))
3616 (let (to)
3617 (save-excursion
3618 ;; Must handle
3619 ;; ...\c
3620 ;; .br (and other requests?)
3621 ;; by deleting both the \c and the following request.
3622 ;; BEWARE THAT THIS CODE MAY BE UNRELIABLE!!!!!
3623 (while
3624 (and
3625 (setq to (re-search-forward "\\(\\\\c\\)?\n[.']" nil t))
3626 (match-string 1)
3627 (looking-at "br"))
3628 (goto-char (match-beginning 0))
3629 (woman-delete-line 2)))
3630 (if to (1- to) (point-max))))
3632 (defun woman2-PD (to)
3633 ".PD d -- Set the interparagraph distance to d.
3634 Round to whole lines, default 1 line. Format paragraphs upto TO.
3635 (Breaks, but should not.)"
3636 ;; .ie \\n[.$] .nr PD (v;\\$1)
3637 ;; .el .nr PD .4v>?\n[.V]
3638 (woman-set-interparagraph-distance)
3639 (woman2-format-paragraphs to))
3641 (defun woman-set-interparagraph-distance ()
3642 "Set the interparagraph distance from a .PD request at point."
3643 (setq woman-interparagraph-distance
3644 (if (eolp) 1 (woman-get-numeric-arg)))
3645 ;; Should allow .PD 0 to set zero line spacing
3646 (woman-delete-line 1)) ; ignore remaining args
3648 (defsubst woman-interparagraph-space ()
3649 "Set variable `woman-leave-blank-lines' from `woman-interparagraph-distance'."
3650 ; (if (> woman-interparagraph-distance 0)
3651 ; (forward-line 1) ; leave 1 blank line
3652 ; (woman-delete-line 1)) ; do not leave blank line
3653 (setq woman-leave-blank-lines woman-interparagraph-distance)
3656 (defun woman2-TH (to)
3657 ".TH n c x v m -- Begin a man page. Format paragraphs upto TO.
3658 n is the name of the page in chapter c\; x is extra commentary\;
3659 v alters page foot left; m alters page head center.
3660 \(Should set prevailing indent and tabs to 5.)"
3661 (woman-forward-arg 'unquote 'concat)
3662 (insert ?\()
3663 (woman-forward-arg 'unquote 'concat)
3664 (insert ?\))
3665 (let ((start (point)) here)
3666 (while (not (eolp))
3667 (cond ((looking-at "\"\"[ \t]")
3668 (delete-char 2)
3669 ;; (delete-horizontal-space)
3671 (delete-horizontal-space)
3672 (setq here (point))
3673 (insert " -- ")
3674 (woman-forward-arg 'unquote 'concat)
3675 ;; Delete repeated arguments:
3676 (if (string-match (buffer-substring here (point))
3677 (buffer-substring start here))
3678 (delete-region here (point)))
3680 ;; Embolden heading (point is at end of heading):
3681 (woman-set-face
3682 (save-excursion (beginning-of-line) (point)) (point) 'woman-bold-face)
3683 (forward-line)
3684 (delete-blank-lines)
3685 (setq woman-left-margin woman-default-indent)
3686 (setq woman-prevailing-indent woman-default-indent)
3687 (woman2-format-paragraphs to woman-left-margin))
3689 (defun woman2-SH (to)
3690 ".SH -- Sub-head. Leave blank line and subhead.
3691 Format paragraphs upto TO. Set prevailing indent to 5."
3692 (if (eolp) ; If no args then
3693 (delete-char 1) ; apply to next line
3694 (woman-unquote-args) ; else unquote to end of heading
3695 (beginning-of-line))
3696 (woman2-process-escapes-to-eol)
3697 (woman-leave-blank-lines woman-interparagraph-distance)
3698 (setq woman-leave-blank-lines nil)
3699 ;; Optionally embolden heading (point is at beginning of heading):
3700 (if woman-bold-headings
3701 (woman-set-face
3702 (point) (save-excursion (end-of-line) (point)) 'woman-bold-face))
3703 (forward-line)
3704 (setq woman-left-margin woman-default-indent
3705 woman-nofill nil) ; fill output lines
3706 (setq woman-prevailing-indent woman-default-indent)
3707 (woman2-format-paragraphs to woman-left-margin))
3709 (defun woman2-SS (to)
3710 ".SS -- Sub-sub-head. Like .SH but indent heading 3 spaces.
3711 Format paragraphs upto TO."
3712 (if (eolp) ; If no args then
3713 (delete-char 1)) ; apply to next line.
3714 (insert " ")
3715 (beginning-of-line)
3716 (woman2-SH to))
3718 (defun woman2-LP (to)
3719 ".LP,.PP -- Begin paragraph. Set prevailing indent to 5.
3720 Leave 1 blank line. Format paragraphs upto TO."
3721 (woman-delete-line 1) ; ignore any arguments
3722 (woman-interparagraph-space)
3723 (setq woman-prevailing-indent woman-default-indent)
3724 (woman2-format-paragraphs to woman-left-margin))
3726 (defalias 'woman2-PP 'woman2-LP)
3727 (defalias 'woman2-P 'woman2-LP)
3729 (defun woman2-ns (to)
3730 ".ns -- Turn on no-space mode. Format paragraphs upto TO."
3731 ;; Should not cause a break!
3732 (woman-delete-line 1) ; ignore argument(s)
3733 (setq woman-nospace t)
3734 (woman2-format-paragraphs to))
3736 (defun woman2-rs (to)
3737 ".rs -- Turn off no-space mode. Format paragraphs upto TO."
3738 ;; Should not cause a break!
3739 (woman-delete-line 1) ; ignore argument(s)
3740 (setq woman-nospace nil)
3741 (woman2-format-paragraphs to))
3743 (defun woman2-sp (to)
3744 ".sp N -- If N > 0 then leave 1 blank line. Format paragraphs upto TO."
3745 (let ((N (if (eolp) 1 (woman-get-numeric-arg))))
3746 (if (>= N 0)
3747 (woman-delete-line 1) ; ignore argument(s)
3748 (setq woman-negative-vertical-space t)
3749 (insert ".sp ")
3750 (forward-line))
3751 (setq woman-leave-blank-lines N)
3752 (woman2-format-paragraphs to)))
3754 (defun woman-negative-vertical-space (from)
3755 ".sp N with N < 0 => overlap following with preceding lines at FROM."
3756 ;; Run by woman-decode-region if necessary -- not usually required.
3757 (WoMan-warn "Negative vertical spacing support is experimental!")
3758 (goto-char from)
3759 (while
3760 ;; Find next control line:
3761 (re-search-forward "^\\.sp " nil t)
3762 (let ((N (woman-get-numeric-arg))
3763 overlap overwritten)
3764 (woman-delete-whole-line)
3765 (setq from (point)
3766 overlap (buffer-substring from
3767 (progn (forward-line (- N)) (point))))
3768 (delete-region from (point))
3769 (forward-line N)
3770 (let ((imax (length overlap))
3771 (i 0) c)
3772 (while (< i imax)
3773 (setq c (aref overlap i))
3774 (cond ((eq c ?\n) ; skip
3775 (forward-line))
3776 ((eolp) ; extend line
3777 ;; Insert character INCLUDING TEXT PROPERTIES:
3778 ;; (insert (substring overlap i (1+ i)))
3779 (let ((eol (string-match "\n" overlap i)))
3780 (insert (substring overlap i eol))
3781 (setq i (or eol imax)))
3783 ((eq c ?\ ) ; skip
3784 (forward-char))
3785 ((eq c ?\t) ; skip
3786 (if (eq (following-char) ?\t)
3787 (forward-char) ; both tabs, just skip
3788 (let ((i woman-tab-width))
3789 (while (> i 0)
3790 (if (eolp)
3791 (insert ?\ ) ; extend line
3792 (forward-char)) ; skip
3793 (setq i (1- i)))
3796 (if (or (eq (following-char) ?\ ) ; overwrite OK
3797 overwritten) ; warning only once per ".sp -"
3799 (setq overwritten t)
3800 (WoMan-warn
3801 "Character(s) overwritten by negative vertical spacing in line %d"
3802 (count-lines 1 (point))))
3803 (delete-char 1) (insert (substring overlap i (1+ i)))))
3804 (setq i (1+ i))
3809 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3810 ;; The following function should probably do ALL width and number
3811 ;; register interpolation.
3812 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
3814 (defun woman2-process-escapes (to &optional numeric)
3815 "Process remaining escape sequences up to marker TO, preserving point.
3816 Optional argument NUMERIC, if non-nil, means the argument is numeric."
3817 ;; The first two cases below could be merged (maybe)!
3818 (let ((from (point)))
3819 ;; Discard zero width filler character used to hide leading dots
3820 ;; and zero width characters \|, \^:
3821 (while (re-search-forward "\\\\[&|^]" to t)
3822 (woman-delete-match 0))
3823 (goto-char from)
3824 ;; Interrupt text processing -- CONTINUE current text with the
3825 ;; next text line (after any control lines, unless processing to
3826 ;; eol):
3827 (while (re-search-forward "\\\\c.*\n?" to t)
3828 (woman-delete-match 0))
3829 ;; but do not delete the final newline ...
3830 (if (and (or (eobp) (= (point) to)) (not (bolp)))
3831 (insert-before-markers ?\n))
3832 (goto-char from)
3833 (woman-translate to)
3834 (goto-char from)
3835 (woman-special-characters to)
3836 (goto-char from)
3837 ;; Printable version of the current escape character, ASSUMED to be `\'
3838 ;; This must be done LAST of all escape processing!
3839 ;; Done like this to preserve any text properties of the `\'
3840 (while (search-forward "\\" to t)
3841 (let ((c (following-char)))
3842 (cond ((eq c ?') ; \' -> '
3843 (delete-char -1)
3844 (cond (numeric ; except in numeric args, \' -> `
3845 (delete-char 1)
3846 (insert ?`))))
3847 ((eq c ?\( )) ; uninterpreted special character
3848 ; \(.. -- do nothing
3849 ((eq c ?t) ; non-interpreted tab \t
3850 (delete-char 1)
3851 (delete-char -1)
3852 (insert "\t"))
3853 ((and numeric
3854 (memq c '(?w ?n ?h)))) ; leave \w, \n, \h (?????)
3855 ((eq c ?l) (woman-horizontal-line))
3857 ;; \? -> ? where ? is any remaining character
3858 (WoMan-warn "Escape ignored: \\%c -> %c" c c)
3859 (delete-char -1))
3861 (goto-char from)
3862 ;; Process non-default tab settings:
3863 (cond (tab-stop-list
3864 (while (search-forward "\t" to t)
3865 (woman-tab-to-tab-stop))
3866 (goto-char from)))
3868 ;; Must replace \' by something before processing \w, done above.
3870 ;; Replace all `\w' and `\n' escapes:
3871 ;; (This may be a bit too recursive!)
3872 (while (re-search-forward "\\\\[nw]" to t)
3873 (let ((from (match-beginning 0)) N)
3874 (goto-char from)
3875 (setq N (woman-parse-numeric-value))
3876 (delete-region from (point))
3877 ;; Interpolate value:
3878 (insert-before-markers (number-to-string N))))
3879 (goto-char from)))
3881 (defun woman-horizontal-line ()
3882 "\\l'Nc' -- Draw a horizontal line of length N using character c, default _."
3883 (delete-char -1)
3884 (delete-char 1)
3885 (looking-at "\\(.\\)\\(.*\\)\\1")
3886 (let ((to (make-marker)) from N c)
3887 (set-marker to (match-end 2))
3888 (delete-char 1)
3889 (setq from (point)
3890 N (woman-parse-numeric-arg))
3891 (setq c (if (< (point) to) (following-char) ?_))
3892 (delete-region from to)
3893 (delete-char 1)
3894 (set-marker to nil)
3895 (insert (make-string N c))
3898 ;;; 4. Text Filling, Adjusting, and Centering
3900 (defun woman2-br (to)
3901 ".br -- Break. Leave no blank line. Format paragraphs upto TO."
3902 (woman-delete-line 1) ; ignore any arguments
3903 (woman2-format-paragraphs to))
3905 (defun woman2-fi (to)
3906 ".fi -- Fill subsequent output lines. Leave no blank line.
3907 Format paragraphs upto TO."
3908 (setq woman-nofill nil)
3909 (woman-delete-line 1) ; ignore any arguments
3910 ;; Preserve any final blank line in the nofill region:
3911 (save-excursion
3912 (forward-line -1)
3913 (if (looking-at "[ \t]*$") (setq woman-leave-blank-lines 1)))
3914 (woman2-format-paragraphs to))
3916 (defun woman2-nf (to)
3917 ".nf -- Nofill. Subsequent lines are neither filled nor adjusted.
3918 Input text lines are copied directly to output lines without regard
3919 for the current line length. Format paragraphs upto TO."
3920 (setq woman-nofill t)
3921 (woman-delete-line 1) ; ignore any arguments
3922 (woman2-format-paragraphs to))
3924 (defun woman2-ad (to)
3925 ".ad c -- Line adjustment is begun (once fill mode is on).
3926 Set justification mode to c if specified.
3927 Format paragraphs upto TO. (Breaks, but should not.)"
3928 ;; c = l -- left, r -- right, c -- center, b or n -- both,
3929 ;; absent -- unchanged. Initial mode adj,both.
3930 (setq woman-adjust
3931 (cond ((eolp) woman-adjust-previous)
3932 ((eq (following-char) ?l) woman-adjust-left)
3933 ((eq (following-char) ?r) woman-adjust-right)
3934 ((eq (following-char) ?c) woman-adjust-center)
3935 ((memq (following-char) '(?b ?n)) woman-adjust-both)
3936 (t (woman-get-numeric-arg))
3938 woman-justify (nth woman-adjust woman-justify-list))
3939 (woman-delete-line 1) ; ignore any remaining arguments
3940 (woman2-format-paragraphs to))
3942 (defun woman2-na (to)
3943 ".na -- No adjusting. Format paragraphs upto TO.
3944 (Breaks, but should not.)"
3945 (setq woman-adjust-previous woman-adjust
3946 woman-justify-previous woman-justify
3947 woman-adjust woman-adjust-left ; fill but do not adjust
3948 woman-justify (nth woman-adjust woman-justify-list))
3949 (woman-delete-line 1) ; ignore any arguments
3950 (woman2-format-paragraphs to))
3952 ;;; The main formatting functions:
3954 (defun woman-leave-blank-lines (&optional leave)
3955 "Delete all blank lines around point.
3956 Leave one blank line if optional argument LEAVE is non-nil and
3957 non-zero, or if LEAVE is nil and variable `woman-leave-blank-lines' is
3958 non-nil and non-zero."
3959 ;; ***** It may suffice to delete only lines ABOVE point! *****
3960 ;; NOTE: Function arguments are evaluated left to right
3961 ;; (*note (elisp)Function Forms::.).
3962 (delete-region
3963 (save-excursion
3964 (if (not (eq (skip-syntax-backward " ") 0))
3965 (forward-line)) ; forward-char ?
3966 (point))
3967 (progn (skip-syntax-forward " ")
3968 (beginning-of-line)
3969 (point)))
3970 (if woman-nospace
3972 (if (or (null leave) (eq leave 0))
3973 ;; output any `pending' vertical space ...
3974 (setq leave woman-leave-blank-lines))
3975 (if (and leave (> leave 0)) (insert-before-markers ?\n))
3977 (setq woman-leave-blank-lines nil)
3980 ;; `fill-region-as-paragraph' in `fill.el' appears to be the principal
3981 ;; text filling function, so that is what I use here.
3983 (defvar woman-temp-indent nil)
3985 (defun woman2-format-paragraphs (to &optional new-left)
3986 "Indent, fill and adjust paragraphs upto TO to current left margin.
3987 If optional arg NEW-LEFT is non-nil then reset current left margin.
3988 If `woman-nofill' is non-nil then indent without filling or adjusting."
3989 ;; Blank space should only ever be output before text.
3990 (if new-left (setq left-margin new-left))
3991 (if (looking-at "^\\s *$")
3992 ;; A blank line should leave a space like .sp 1 (p. 14).
3993 (setq woman-leave-blank-lines 1))
3994 (skip-syntax-forward " ")
3995 ;; Successive control lines are sufficiently common to be worth a
3996 ;; special case (maybe):
3997 (if (>= (point) to) ; >= as a precaution!
3999 ;; (woman-leave-blank-lines)
4000 (woman-reset-nospace)
4001 ;; (woman2-process-escapes to) ; 7 October 1999
4002 (woman2-process-escapes to 'numeric)
4003 (if woman-nofill
4004 ;; Indent without filling or adjusting ...
4005 (progn
4006 (woman-leave-blank-lines)
4007 (cond (woman-temp-indent
4008 (indent-to woman-temp-indent)
4009 (forward-line)))
4010 (indent-rigidly (point) to left-margin)
4011 (woman-horizontal-escapes to)) ; 7 October 1999
4012 ;; Fill and justify ...
4013 ;; Blank lines and initial spaces cause a break.
4014 ; (cond ((and (= (point) to) (not (looking-at ".nf"))) ; Yuk!!!
4015 ; ;; No text after a request that caused a break, so delete
4016 ; ;; any spurious blank line left:
4017 ; (forward-line -1)
4018 ; (if (looking-at "^\\s *$") (kill-line) (forward-line))))
4019 (while (< (point) to)
4020 (woman-leave-blank-lines)
4021 (let ((from (point)))
4022 ;; Indent first lin of paragraph:
4023 (indent-to (or woman-temp-indent left-margin))
4024 (woman-horizontal-escapes to) ; 7 October 1999
4025 ;; Find the beginning of the next paragraph:
4026 (forward-line)
4027 ; (if (re-search-forward "\\(^\\s *$\\)\\|\\(^\\s +\\)" to 1)
4028 ; ;; A blank line should leave a space like .sp 1 (p. 14).
4029 ; (if (eolp)
4030 ; (progn
4031 ; (skip-syntax-forward " ")
4032 ; (setq woman-leave-blank-lines 1))
4033 ; (setq woman-leave-blank-lines nil)))
4034 (and (re-search-forward "\\(^\\s *$\\)\\|\\(^\\s +\\)" to 1)
4035 ;; A blank line should leave a space like .sp 1 (p. 14).
4036 (eolp)
4037 (skip-syntax-forward " ")
4038 (setq woman-leave-blank-lines 1))
4039 (beginning-of-line)
4040 ;; If a single short line then just leave it.
4041 ;; This is necessary to preserve some table layouts.
4042 ;; PROBABLY NOT NECESSARY WITH SQUEEZE MODIFICATION !!!!!
4043 (if (or (> (count-lines from (point)) 1)
4044 (save-excursion
4045 (backward-char)
4046 (> (current-column) fill-column)))
4047 ;; ?roff does not squeeze multiple spaces
4048 ;; (fill-region-as-paragraph from (point) woman-justify t)
4049 ;; NOSQUEEZE has no effect if JUSTIFY is full, so
4050 ;; redefine canonically-space-region, see above.
4051 (progn
4052 ;; Needs a re-write of the paragraph formatter to
4053 ;; avoid this nonsense to handle temporary indents!
4054 (if (and woman-temp-indent (< woman-temp-indent left-margin))
4055 (let ((left-margin woman-temp-indent))
4056 (fill-region-as-paragraph from (point) woman-justify)
4057 (save-excursion
4058 (goto-char from)
4059 (forward-line)
4060 (setq from (point)))))
4061 (fill-region-as-paragraph from (point) woman-justify))
4063 ;; A blank line should leave a space like .sp 1 (p. 14).
4064 ;; Delete all but 1 trailing blank lines:
4065 ;;(woman-leave-blank-lines 1)
4068 (setq woman-temp-indent nil)
4069 ;; Non-white-space text has been processed, so ...
4070 ;;(setq woman-leave-blank-lines nil)
4074 ;;; Tagged, indented and hanging paragraphs:
4076 (defun woman2-TP (to)
4077 ".TP i -- Set prevailing indent to i. Format paragraphs upto TO.
4078 Begin indented paragraph with hanging tag given by next text line.
4079 If tag doesn't fit, place it on a separate line."
4080 (let ((i (woman2-get-prevailing-indent)))
4081 (woman-leave-blank-lines woman-interparagraph-distance)
4082 (woman2-tagged-paragraph to i)))
4084 (defun woman2-IP (to)
4085 ".IP x i -- Same as .TP with tag x. Format paragraphs upto TO."
4086 (woman-interparagraph-space)
4087 (if (eolp) ; no args
4088 ;; Like LP without resetting prevailing indent
4089 (woman2-format-paragraphs to (+ woman-left-margin
4090 woman-prevailing-indent))
4091 (woman-forward-arg 'unquote)
4092 (let ((i (woman2-get-prevailing-indent 'leave-eol)))
4093 (beginning-of-line)
4094 (woman-leave-blank-lines) ; must be here,
4095 (woman2-tagged-paragraph to i))))
4097 (defun woman-find-next-control-line-carefully ()
4098 "Find and return start of next control line, even if already there!"
4099 (if (looking-at "^[.']")
4100 (point)
4101 (woman-find-next-control-line)))
4103 (defun woman2-tagged-paragraph (to i)
4104 "Begin indented paragraph with hanging tag given by current text line.
4105 If tag doesn't fit, leave it on separate line.
4106 Format paragraphs upto TO. Set prevailing indent to I."
4107 (if (not (looking-at "\\s *$")) ; non-empty tag
4108 (setq woman-leave-blank-lines nil))
4110 ;; Temporary hack for bash.1 and groff_mmse.7 until code is revised
4111 ;; to process all requests uniformly:
4112 (cond ((and (= (point) to) (looking-at "^[.'][ \t]*\\(PD\\|br\\|ta\\) *"))
4113 (if (string= (match-string 1) "br")
4114 (woman-delete-line 1)
4115 (woman-delete-match 0)
4116 (if (string= (match-string 1) "ta") ; for GetInt.3
4117 (woman2-ta to)
4118 (woman-set-interparagraph-distance)))
4119 (set-marker to (woman-find-next-control-line-carefully))
4122 (let ((tag (point)))
4123 (woman-reset-nospace)
4124 ;; Format the tag:
4125 (woman2-process-escapes-to-eol)
4126 ;; TIDY UP THE FOLLOWING CODE
4127 ;; (indent-to woman-left-margin)
4128 (setq left-margin woman-left-margin)
4129 (forward-line)
4130 (fill-region-as-paragraph (save-excursion (forward-line -1) (point))
4131 (point) woman-justify)
4133 ;; Temporary hack for bash.1 until all requests processed uniformly:
4134 (cond ((and (= (point) to) (looking-at "^[.'][ \t]*PD *"))
4135 (woman-delete-match 0)
4136 (woman-set-interparagraph-distance)
4137 (set-marker to (woman-find-next-control-line-carefully))
4140 ;; Format the paragraph body, if there is one! Set indented left
4141 ;; margin anyway, because the paragraph body may begin with a
4142 ;; control line:
4143 (setq left-margin (+ woman-left-margin i))
4144 (cond ((< (point) to)
4145 (woman2-format-paragraphs to)
4146 (goto-char tag) (end-of-line)
4147 (cond ((> (setq i (- left-margin (current-column))) 0)
4148 (delete-char 1)
4149 (delete-horizontal-space)
4150 ;; Necessary to avoid spaces inheriting underlines.
4151 ;; Cannot simply delete (current-column) whitespace
4152 ;; characters because some may be tabs!
4153 (while (> i 0) (insert ? ) (setq i (1- i)))))
4154 (goto-char to) ; necessary ???
4158 (defun woman2-HP (to)
4159 ".HP i -- Set prevailing indent to i. Format paragraphs upto TO.
4160 Begin paragraph with hanging indent."
4161 (let ((i (woman2-get-prevailing-indent)))
4162 (woman-interparagraph-space)
4163 (setq woman-temp-indent woman-left-margin)
4164 (woman2-format-paragraphs to (+ woman-left-margin i))
4167 (defun woman2-get-prevailing-indent (&optional leave-eol)
4168 "Set prevailing indent to integer argument at point, and return it.
4169 If no argument then return the existing prevailing indent.
4170 Delete line from point and eol unless LEAVE-EOL is non-nil."
4171 (if (eolp)
4172 (or leave-eol (delete-char 1))
4173 (let ((i (woman-get-numeric-arg)))
4174 (woman-delete-line) (or leave-eol (delete-char 1))
4175 ;; i = 0 if the argument was not a number
4176 (if (> i 0) (setq woman-prevailing-indent i))))
4177 woman-prevailing-indent)
4179 (defmacro woman-push (value stack)
4180 "Push VALUE onto STACK."
4181 `(setq ,stack (cons ,value ,stack)))
4183 (defmacro woman-pop (variable stack)
4184 "Pop into VARIABLE the value at the top of STACK.
4185 Allow for mismatched requests!"
4186 `(if ,stack
4187 (setq ,variable (car ,stack)
4188 ,stack (cdr ,stack))))
4190 (defun woman2-RS (to)
4191 ".RS i -- Start relative indent, move left margin in distance i.
4192 Set prevailing indent to 5 for nested indents. Format paragraphs upto TO."
4193 (woman-push woman-left-margin woman-RS-left-margin)
4194 (woman-push woman-prevailing-indent woman-RS-prevailing-indent)
4195 (setq woman-left-margin (+ woman-left-margin
4196 (woman2-get-prevailing-indent))
4197 woman-prevailing-indent woman-default-indent)
4198 (woman2-format-paragraphs to woman-left-margin))
4200 (defun woman2-RE (to)
4201 ".RE -- End of relative indent. Format paragraphs upto TO.
4202 Set prevailing indent to amount of starting .RS."
4203 (woman-pop woman-left-margin woman-RS-left-margin)
4204 (woman-pop woman-prevailing-indent woman-RS-prevailing-indent)
4205 (woman-delete-line 1) ; ignore any arguments
4206 (woman2-format-paragraphs to woman-left-margin))
4209 ;;; Line Length and Indenting:
4211 (defun woman-set-arg (arg &optional previous)
4212 "Reset, increment or decrement argument ARG, which must be quoted.
4213 If no argument then use value of optional arg PREVIOUS if non-nil,
4214 otherwise set PREVIOUS. Delete the whole remaining control line."
4215 (if (eolp) ; space already skipped
4216 (set arg (if previous (eval previous) 0))
4217 (if previous (set previous (eval arg)))
4218 (woman2-process-escapes-to-eol 'numeric)
4219 (let ((pm (if (looking-at "[+-]")
4220 (prog1 (following-char)
4221 (forward-char 1))))
4222 (i (woman-parse-numeric-arg)))
4223 (cond ((null pm) (set arg i))
4224 ((= pm ?+) (set arg (+ (eval arg) i)))
4225 ((= pm ?-) (set arg (- (eval arg) i)))
4227 (beginning-of-line))
4228 (woman-delete-line 1)) ; ignore any remaining arguments
4230 ;; NEED TO RATIONALIZE NAMES FOR PREVIOUS VALUES!
4231 (defvar woman-ll-fill-column woman-fill-column)
4232 (defvar woman-in-left-margin woman-left-margin)
4234 (defun woman2-ll (to)
4235 ".ll +/-N -- Set, increment or decrement line length.
4236 Format paragraphs upto TO. (Breaks, but should not.)"
4237 (woman-set-arg 'fill-column 'woman-ll-fill-column)
4238 (woman2-format-paragraphs to))
4240 (defun woman2-in (to)
4241 ".in +/-N -- Set, increment or decrement the indent.
4242 Format paragraphs upto TO."
4243 (woman-set-arg 'left-margin 'woman-in-left-margin)
4244 (woman2-format-paragraphs to))
4246 (defun woman2-ti (to)
4247 ".ti +/-N -- Temporary indent. Format paragraphs upto TO."
4248 ;; Ignore if no argument.
4249 ;; Indent next output line only wrt current indent.
4250 ;; Current indent is not changed.
4251 (setq woman-temp-indent left-margin)
4252 (woman-set-arg 'woman-temp-indent)
4253 (woman2-format-paragraphs to nil))
4256 ;;; Tabs, Leaders, and Fields:
4258 (defun woman2-ta (to)
4259 ".ta Nt ... -- Set tabs, left type, unless t=R(right), C(centered).
4260 \(Breaks, but should not.) The tab stops are separated by spaces\;
4261 a value preceded by + represents an increment to the previous stop value.
4262 Format paragraphs upto TO."
4263 (setq tab-stop-list nil)
4264 (woman2-process-escapes-to-eol 'numeric)
4265 (save-excursion
4266 (let ((tab-stop 0))
4267 (while (not (eolp))
4268 (let ((plus (cond ((eq (following-char) ?+) (forward-char 1) t)))
4269 (i (woman-parse-numeric-arg)))
4270 (setq tab-stop (if plus (+ tab-stop i) i)))
4271 (if (memq (following-char) '(?R ?C))
4272 (setq tab-stop (cons tab-stop (following-char))))
4273 (setq tab-stop-list (cons tab-stop tab-stop-list))
4274 (skip-syntax-forward "^ ") ; skip following R, C, `;', etc.
4275 (skip-chars-forward " \t")
4277 (woman-delete-line 1) ; ignore any remaining arguments
4278 (setq tab-stop-list (reverse tab-stop-list))
4279 (woman2-format-paragraphs to))
4281 (defsubst woman-get-tab-stop (tab-stop-list)
4282 "If TAB-STOP-LIST is a cons, return its car, else return TAB-STOP-LIST."
4283 (if (consp tab-stop-list) (car tab-stop-list) tab-stop-list))
4285 (defun woman-tab-to-tab-stop ()
4286 "Insert spaces to next defined tab-stop column.
4287 The variable `tab-stop-list' is a list whose elements are either left
4288 tab stop columns or pairs (COLUMN . TYPE) where TYPE is R or C."
4289 ;; Based on tab-to-tab-stop in indent.el.
4290 ;; R & C tabs probably not quite right!
4291 (delete-backward-char 1)
4292 (let ((tabs tab-stop-list))
4293 (while (and tabs (>= (current-column)
4294 (woman-get-tab-stop (car tabs))))
4295 (setq tabs (cdr tabs)))
4296 (if tabs
4297 (let* ((tab (car tabs))
4298 (type (and (consp tab) (cdr tab)))
4299 eol n)
4300 (if type
4301 (setq tab (woman-get-tab-stop tab)
4302 eol (save-excursion (end-of-line) (point))
4303 n (save-excursion
4304 (search-forward "\t" eol t))
4305 n (- (if n (1- n) eol) (point))
4306 tab (- tab (if (eq type ?C) (/ n 2) n))) )
4307 (setq n (- tab (current-column)))
4308 (while (> n 0)
4309 (insert ?\ )
4310 (setq n (1- n))))
4311 (insert ?\ ))))
4313 (defun woman2-DT (to)
4314 ".DT -- Restore default tabs. Format paragraphs upto TO.
4315 \(Breaks, but should not.)"
4316 ;; Currently just terminates special tab processing.
4317 (setq tab-stop-list nil)
4318 (woman-delete-line 1) ; ignore any arguments
4319 (woman2-format-paragraphs to))
4321 (defun woman2-fc (to)
4322 ".fc a b -- Set field delimiter a and pad character b.
4323 Format paragraphs upto TO.
4324 A VERY FIRST ATTEMPT to make fields at least readable!
4325 Needs doing properly!"
4326 (if (eolp)
4327 (woman-delete-whole-line) ; ignore!
4328 (let ((delim (following-char))
4329 (pad ?\ ) end) ; pad defaults to space
4330 (forward-char)
4331 (skip-chars-forward " \t")
4332 (or (eolp) (setq pad (following-char)))
4333 (woman-delete-whole-line)
4334 (save-excursion
4335 (if (re-search-forward "^[.'][ \t]*fc\\s " nil t)
4336 (setq end (match-beginning 0))))
4337 ;; A field is contained between a pair of field delimiter
4338 ;; characters and consists of sub-strings separated by padding
4339 ;; indicator characters:
4340 (setq delim (string delim ?[ ?^ delim ?] ?* delim))
4341 (save-excursion
4342 (while (re-search-forward delim end t)
4343 (goto-char (match-beginning 0))
4344 (delete-char 1)
4345 (insert woman-unpadded-space-char)
4346 (goto-char (match-end 0))
4347 (delete-backward-char 1)
4348 (insert-before-markers woman-unpadded-space-char)
4349 (subst-char-in-region
4350 (match-beginning 0) (match-end 0)
4351 pad woman-unpadded-space-char t)
4354 (woman2-format-paragraphs to))
4357 ;;; WoMan message logging:
4359 ;; The basis for this logging code was shamelessly pirated from bytecomp.el
4360 ;; by Jamie Zawinski <jwz@lucid.com> & Hallvard Furuseth <hbf@ulrik.uio.no>
4362 (defvar WoMan-current-file nil) ; bound in woman-really-find-file
4363 (defvar WoMan-Log-header-point-max nil)
4365 (defun WoMan-log-begin ()
4366 "Log the beginning of formatting in *WoMan-Log*."
4367 (let ((WoMan-current-buffer (buffer-name)))
4368 (save-excursion
4369 (set-buffer (get-buffer-create "*WoMan-Log*"))
4370 (or (eq major-mode 'view-mode) (view-mode 1))
4371 (setq buffer-read-only nil)
4372 (goto-char (point-max))
4373 (insert "\n\^L\nFormatting "
4374 (if (stringp WoMan-current-file)
4375 (concat "file " WoMan-current-file)
4376 (concat "buffer " WoMan-current-buffer))
4377 " at " (current-time-string) "\n")
4378 (setq WoMan-Log-header-point-max (point-max))
4381 (defun WoMan-log (format &rest args)
4382 "Log a message out of FORMAT control string and optional ARGS."
4383 (WoMan-log-1 (apply 'format format args)))
4385 (defun WoMan-warn (format &rest args)
4386 "Log a warning message out of FORMAT control string and optional ARGS."
4387 (setq format (apply 'format format args))
4388 (WoMan-log-1 (concat "** " format)))
4390 (defun WoMan-warn-ignored (request ignored)
4391 "Log a warning message about ignored directive REQUEST.
4392 IGNORED is a string appended to the log message."
4393 (let ((tail
4394 (buffer-substring (point)
4395 (save-excursion (end-of-line) (point)))))
4396 (if (and (> (length tail) 0)
4397 (/= (string-to-char tail) ?\ ))
4398 (setq tail (concat " " tail)))
4399 (WoMan-log-1
4400 (concat "** " request tail " request " ignored))))
4402 (defun WoMan-log-end (time)
4403 "Log the end of formatting in *WoMan-Log*.
4404 TIME specifies the time it took to format the man page, to be printed
4405 with the message."
4406 (WoMan-log-1 (format "Formatting time %d seconds." time) 'end))
4408 (defun WoMan-log-1 (string &optional end)
4409 "Log a message STRING in *WoMan-Log*.
4410 If optional argument END is non-nil then make buffer read-only after
4411 logging the message."
4412 (save-excursion
4413 (set-buffer (get-buffer-create "*WoMan-Log*"))
4414 (goto-char (point-max))
4415 (or end (insert " ")) (insert string "\n")
4416 (if end
4417 (setq buffer-read-only t)
4418 (if woman-show-log
4419 (select-window ; to return to
4420 (prog1 (selected-window) ; WoMan window
4421 (select-window (display-buffer (current-buffer)))
4422 (cond (WoMan-Log-header-point-max
4423 (goto-char WoMan-Log-header-point-max)
4424 (forward-line -1)
4425 (recenter 0)))
4426 )))))
4427 nil) ; for woman-file-readable-p etc.
4429 (provide 'woman)
4431 ;; RECENT CHANGE LOG
4432 ;; =================
4434 ;; Changes in version 0.50 ([*] => user interface change)
4435 ;; [*] Requires GNU Emacs 20.3+.
4436 ;; [*] `defface' used to define faces.
4437 ;; [*] Follow `see also' references with mouse-2 click.
4438 ;; Number register increment support added (woman-registers).
4439 ;; .j must be a NUMBER acceptable by .ad request.
4440 ;; Very crude field support added.
4441 ;; Vertical unit specifier `v' added to register handling.
4442 ;; Improvement to local horizontal motion processing.
4443 ;; Minor fix to handle negative numeric arguments.
4444 ;; Handle horizontal motion escapes `\h' better.
4445 ;; Allow arbitrary delimiters in `.if', inc. special character escapes.
4446 ;; Allow `\n' within `.if' string comparisons.
4447 ;; Allow arbitrary delimiters in `\w', inc. special character escapes.
4448 ;; Processing of `\h' moved much later -- after indenting etc!
4450 ;; Changes in version 0.51 ([*] => user interface change)
4451 ;; [*] Improved handling of underlined faces (mainly for "italics").
4452 ;; [*] Allow environment variables in directory path elements.
4453 ;; Display of pre-formatted files improved.
4454 ;; [*] Unintentional interaction with standard Man mode reduced.
4455 ;; [*] bzip2 decompression support added. All decompression now
4456 ;; works by turning on `auto-compression-mode' to decompress the
4457 ;; file if necessary, rather than decompressing explicitly.
4458 ;; Filename and compression regexps are now customizable user
4459 ;; options.
4461 ;; Changes in version 0.52 ([*] => user interface change)
4462 ;; Speeded up handling of underlined faces (mainly for "italics").
4463 ;; [*] WoMan formatting time display and log added. Emacs `man'
4464 ;; formatting time display advice added. (This suggests that
4465 ;; WoMan formatting is faster than Emacs `man' *formatting*,
4466 ;; i.e. when man is not using `catman' caching. E.g. `woman
4467 ;; bash' takes 27s whereas `man bash' takes 35s and for smaller
4468 ;; files `woman' can be relatively much faster than `man'.)
4469 ;; [*] Experimental support for non-ASCII characters from the
4470 ;; default and symbol fonts added, initially only for MS-Windows.
4471 ;; NOTE: It is off by default, mainly because it may increase the
4472 ;; line spacing; customize `woman-use-symbols' to `on' to use it.
4473 ;; Pad character handling for .fc fixed.
4474 ;; Tested: see `woman.status'.
4476 ;; Changes in version 0.53 ([*] => user interface change)
4477 ;; [*] Customization option to use a separate frame for WoMan windows.
4478 ;; [*] Experimental option to emulate nroff (default) or troff (not tested).
4479 ;; [*] Separation of extended and symbol font options.
4480 ;; Only symbol font size 16 seems to work, and only with Win 95, not NT!
4481 ;; [*] `Advanced' sub-menu containing:
4482 ;; `View Source' option;
4483 ;; `Show Log' option;
4484 ;; `Extended Font' toggle and reformat;
4485 ;; `Symbol Font' toggle and reformat;
4486 ;; `Font Map' option;
4487 ;; `Emulation' radio buttons.
4488 ;; [*] Support for man config file added for default manpath.
4490 ;; Changes in version 0.54
4491 ;; Revised for distribution with Emacs 21.
4492 ;; Comment order and doc strings changed substantially.
4493 ;; MS-DOS support added (by Eli Zaretskii).
4494 ;; checkdoc run: no real errors.
4495 ;; woman topic interface speeded up.
4497 ;;; woman.el ends here