Mercurial > hg > xemacs-beta

comparison lisp/packages/man.el @ 189:489f57a838ef r20-3b21

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r20-3b21
author cvs
date Mon, 13 Aug 2007 09:57:07 +0200
parents e121b013d1f0
children f53b5ca2e663
comparison
equal deleted inserted replaced
188:e29a8e7498d9 189:489f57a838ef
29 ;; 29 ;;
30 ;; [ older changelog entries removed, since they're all about code that 30 ;; [ older changelog entries removed, since they're all about code that
31 ;; I've deleted. ] 31 ;; I've deleted. ]
32 32
33 (defgroup man nil 33 (defgroup man nil
34 "Browse manual pages" 34 "Browse Unix manual pages"
35 :group 'help) 35 :group 'help)
36 36
37 (defcustom Manual-program "man" "\ 37 (defcustom Manual-program "man" "\
38 *Name of the program to invoke in order to format the source man pages." 38 *Name of the program to invoke in order to format the source man pages."
39 :type 'string 39 :type 'string
42 (defcustom Manual-buffer-view-mode t "\ 42 (defcustom Manual-buffer-view-mode t "\
43 *Whether manual buffers should be placed in view-mode. 43 *Whether manual buffers should be placed in view-mode.
44 nil means leave the buffer in fundamental-mode in another window. 44 nil means leave the buffer in fundamental-mode in another window.
45 t means use `view-buffer' to display the man page in the current window. 45 t means use `view-buffer' to display the man page in the current window.
46 Any other value means use `view-buffer-other-window'." 46 Any other value means use `view-buffer-other-window'."
47 :type '(choice (const :tag "fundamental-mode other window" nil) 47 :type '(radio (const :tag "Fundamental-mode other window" nil)
48 (const :tag "view-mode current window" t) 48 (const :tag "View-mode current window" t)
49 (const :tag "view-mode other window" other)) 49 (sexp :format "%t\n" :tag "View-mode other window" other))
50 :group 'man) 50 :group 'man)
51 51
52 (defcustom Manual-mode-hook nil 52 (defcustom Manual-mode-hook nil
53 "Function or functions run on entry to Manual-mode." 53 "Function or functions run on entry to Manual-mode."
54 :type 'hook 54 :type 'hook
75 Otherwise, they are not if `buffers-menu-submenus-for-groups-p' is T, 75 Otherwise, they are not if `buffers-menu-submenus-for-groups-p' is T,
76 so that Manual-mode buffers will have their own submenu." 76 so that Manual-mode buffers will have their own submenu."
77 :type 'boolean 77 :type 'boolean
78 :group 'man) 78 :group 'man)
79 79
80 ;;Here is information on RosettaMan, from Neal.Becker@comsat.com (Neal Becker):
81
82 ;;RosettaMan is a filter for UNIX manual pages. It takes as input man
83 ;;pages formatted for a variety of UNIX flavors (not [tn]roff source)
84 ;;and produces as output a variety of file formats. Currently
85 ;;RosettaMan accepts man pages as formatted by the following flavors of
86 ;;UNIX: Hewlett-Packard HP-UX, AT&T System V, SunOS, Sun Solaris, OSF/1,
87 ;;DEC Ultrix, SGI IRIX, Linux, SCO; and produces output for the following
88 ;;formats: printable ASCII only (stripping page headers and footers),
89 ;;section and subsection headers only, TkMan, [tn]roff, Ensemble, RTF,
90 ;;SGML (soon--I finally found a DTD), HTML, MIME, LaTeX, LaTeX 2e, Perl 5's pod.
91
92 ;;RosettaMan improves on other man page filters in several ways: (1) its
93 ;;analysis recognizes the structural pieces of man pages, enabling high
94 ;;quality output, (2) its modular structure permits easy augmentation of
95 ;;output formats, (3) it accepts man pages formatted with the varient
96 ;;macros of many different flavors of UNIX, and (4) it doesn't require
97 ;;modification or cooperation with any other program.
98
99 ;;RosettaMan is a rewrite of TkMan's man page filter, called bs2tk. (If
100 ;;you haven't heard about TkMan, a hypertext man page browser, you
101 ;;should grab it via anonymous ftp from ftp.cs.berkeley.edu:
102 ;;/ucb/people/phelps/tkman.tar.Z.) Whereas bs2tk generated output only for
103 ;;TkMan, RosettaMan generalizes the process so that the analysis can be
104 ;;leveraged to new output formats. A single analysis engine recognizes
105 ;;section heads, subsection heads, body text, lists, references to other
106 ;;man pages, boldface, italics, bold italics, special characters (like
107 ;;bullets), tables (to a degree) and strips out page headers and
108 ;;footers. The engine sends signals to the selected output functions so
109 ;;that an enhancement in the engine improves the quality of output of
110 ;;all of them. Output format functions are easy to add, and thus far
111 ;;average about about 75 lines of C code each.
112
113
114
115 ;;*** NOTES ON CURRENT VERSION ***
116
117 ;;Help! I'm looking for people to help with the following projects.
118 ;;\(1) Better RTF output format. The current one works, but could be
119 ;;made better. (2) Roff macros that produce text that is easily
120 ;;parsable. RosettaMan handles a great variety, but some things, like
121 ;;H-P's tables, are intractable. If you write an output format or
122 ;;otherwise improve RosettaMan, please send in your code so that I may
123 ;;share the wealth in future releases.
124
125 ;;This version can try to identify tables (turn this on with the -T
126 ;;switch) by looking for lines with a large amount of interword spacing,
127 ;;reasoning that this is space between columns of a table. This
128 ;;heuristic doesn't always work and sometimes misidentifies ordinary
129 ;;text as tables. In general I think it is impossible to perfectly
130 ;;identify tables from nroff formatted text. However, I do think the
131 ;;heuristics can be tuned, so if you have a collection of manual pages
132 ;;with unrecognized tables, send me the lot, in formatted form (i.e.,
133 ;;after formatting with nroff -man), and uuencode them to preserve the
134 ;;control characters. Better, if you can think of heuristics that
135 ;;distinguish tables from ordinary text, I'd like to hear them.
136
137 ;;Notes for HTML consumers: This filter does real (heuristic)
138 ;;parsing--no <PRE>! Man page references are turned into hypertext links.
139
80 (defcustom Manual-use-rosetta-man (not (null (locate-file "rman" exec-path))) "\ 140 (defcustom Manual-use-rosetta-man (not (null (locate-file "rman" exec-path))) "\
81 If non-nil, use RosettaMan (rman) to filter man pages. 141 If non-nil, use RosettaMan (rman) to filter man pages.
82 This makes man-page cleanup virtually instantaneous, instead of 142 This makes man-page cleanup virtually instantaneous, instead of
83 potentially taking a long time. 143 potentially taking a long time."
84
85 Here is information on RosettaMan, from Neal.Becker@comsat.com (Neal Becker):
86
87 RosettaMan is a filter for UNIX manual pages. It takes as input man
88 pages formatted for a variety of UNIX flavors (not [tn]roff source)
89 and produces as output a variety of file formats. Currently
90 RosettaMan accepts man pages as formatted by the following flavors of
91 UNIX: Hewlett-Packard HP-UX, AT&T System V, SunOS, Sun Solaris, OSF/1,
92 DEC Ultrix, SGI IRIX, Linux, SCO; and produces output for the following
93 formats: printable ASCII only (stripping page headers and footers),
94 section and subsection headers only, TkMan, [tn]roff, Ensemble, RTF,
95 SGML (soon--I finally found a DTD), HTML, MIME, LaTeX, LaTeX 2e, Perl 5's pod.
96
97 RosettaMan improves on other man page filters in several ways: (1) its
98 analysis recognizes the structural pieces of man pages, enabling high
99 quality output, (2) its modular structure permits easy augmentation of
100 output formats, (3) it accepts man pages formatted with the varient
101 macros of many different flavors of UNIX, and (4) it doesn't require
102 modification or cooperation with any other program.
103
104 RosettaMan is a rewrite of TkMan's man page filter, called bs2tk. (If
105 you haven't heard about TkMan, a hypertext man page browser, you
106 should grab it via anonymous ftp from ftp.cs.berkeley.edu:
107 /ucb/people/phelps/tkman.tar.Z.) Whereas bs2tk generated output only for
108 TkMan, RosettaMan generalizes the process so that the analysis can be
109 leveraged to new output formats. A single analysis engine recognizes
110 section heads, subsection heads, body text, lists, references to other
111 man pages, boldface, italics, bold italics, special characters (like
112 bullets), tables (to a degree) and strips out page headers and
113 footers. The engine sends signals to the selected output functions so
114 that an enhancement in the engine improves the quality of output of
115 all of them. Output format functions are easy to add, and thus far
116 average about about 75 lines of C code each.
117
118
119
120 *** NOTES ON CURRENT VERSION ***
121
122 Help! I'm looking for people to help with the following projects.
123 \(1) Better RTF output format. The current one works, but could be
124 made better. (2) Roff macros that produce text that is easily
125 parsable. RosettaMan handles a great variety, but some things, like
126 H-P's tables, are intractable. If you write an output format or
127 otherwise improve RosettaMan, please send in your code so that I may
128 share the wealth in future releases.
129
130 This version can try to identify tables (turn this on with the -T
131 switch) by looking for lines with a large amount of interword spacing,
132 reasoning that this is space between columns of a table. This
133 heuristic doesn't always work and sometimes misidentifies ordinary
134 text as tables. In general I think it is impossible to perfectly
135 identify tables from nroff formatted text. However, I do think the
136 heuristics can be tuned, so if you have a collection of manual pages
137 with unrecognized tables, send me the lot, in formatted form (i.e.,
138 after formatting with nroff -man), and uuencode them to preserve the
139 control characters. Better, if you can think of heuristics that
140 distinguish tables from ordinary text, I'd like to hear them.
141
142
143 Notes for HTML consumers: This filter does real (heuristic)
144 parsing--no <PRE>! Man page references are turned into hypertext links."
145 :type 'boolean 144 :type 'boolean
146 :group 'man) 145 :group 'man)
147 146
148 (defface man-italic '((t (:italic t))) 147 (defface man-italic '((t (:italic t)))
149 "Manual italics face" 148 "Manual italics face"