|
0
|
1 \input texinfo
|
|
|
2 @setfilename ../info/w3.info
|
|
|
3 @settitle Emacs-W3 User's Manual
|
|
|
4 @iftex
|
|
|
5 @finalout
|
|
|
6 @end iftex
|
|
|
7 @c @setchapternewpage odd
|
|
|
8 @c @smallbook
|
|
|
9 @tex
|
|
|
10 \overfullrule=0pt
|
|
|
11 %\global\baselineskip 30pt % for printing in double space
|
|
|
12 @end tex
|
|
|
13 @synindex cp fn
|
|
|
14 @synindex vr fn
|
|
|
15 @ifinfo
|
|
|
16 This file documents the Emacs-W3 World Wide Web browser.
|
|
|
17
|
|
|
18 Copyright (C) 1993, 1994, 1995 William M. Perry
|
|
|
19 Copyright (C) 1996 Free Software Foundation
|
|
|
20
|
|
|
21 Permission is granted to make and distribute verbatim copies of
|
|
|
22 this manual provided the copyright notice and this permission notice
|
|
|
23 are preserved on all copies.
|
|
|
24
|
|
|
25 @ignore
|
|
|
26 Permission is granted to process this file through Tex and print the
|
|
|
27 results, provided the printed document carries copying permission
|
|
|
28 notice identical to this one except for the removal of this paragraph
|
|
|
29 (this paragraph not being relevant to the printed manual).
|
|
|
30
|
|
|
31 @end ignore
|
|
|
32 @end ifinfo
|
|
|
33 @c
|
|
|
34 @titlepage
|
|
|
35 @sp 6
|
|
|
36 @center @titlefont{Emacs-W3}
|
|
|
37 @center @titlefont{User's Manual}
|
|
|
38 @sp 4
|
|
|
39 @center Third Edition, Emacs-W3 Version 2.3.0
|
|
|
40 @sp 1
|
|
|
41 @center February 1996
|
|
|
42 @sp 5
|
|
|
43 @center William M. Perry
|
|
|
44 @center @i{wmperry@@cs.indiana.edu}
|
|
|
45 @page
|
|
|
46 @vskip 0pt plus 1filll
|
|
|
47 Copyright @copyright{} 1993, 1994, 1995 William M. Perry@*
|
|
|
48 Copyright @copyright{} 1996 Free Software Foundation
|
|
|
49
|
|
|
50 Permission is granted to make and distribute verbatim copies of@*
|
|
|
51 this manual provided the copyright notice and this permission notice@*
|
|
|
52 are preserved on all copies.
|
|
|
53
|
|
|
54 @end titlepage
|
|
|
55 @page
|
|
|
56 @ifinfo
|
|
|
57 @node Top, Introduction,, (DIR)
|
|
|
58 This manual documents the Emacs-W3 World Wide Web browser, a Lisp program
|
|
|
59 which runs as a subsystem under Emacs. The manual is divided into the
|
|
|
60 following chapters.
|
|
|
61
|
|
|
62 @menu
|
|
|
63 * Introduction:: What exactly is Emacs-W3?
|
|
|
64 * Setting Up:: How to set up and install Emacs-W3.
|
|
|
65 * Basic Usage:: Basic movement and usage of Emacs-W3.
|
|
|
66 * Compatibility:: Explanation of compatibility with
|
|
|
67 other web browsers.
|
|
|
68 * Controlling Formatting:: How to control HTML formatting
|
|
|
69 * MIME Support:: Support for MIME
|
|
|
70 * Security:: Various forms of security
|
|
|
71 * Non-Unix Operating Systems:: Special considerations necessary to get
|
|
|
72 up and running correctly under non-unix
|
|
|
73 OS's.
|
|
|
74 * Advanced Features:: Some of the more arcane features.
|
|
|
75 * More Help:: How to get more help---mailing lists,
|
|
|
76 newsgroups, etc.
|
|
|
77 * Future Directions:: Plans for future revisions
|
|
|
78 * Programming Interface:: How to use Emacs-W3 from other emacs
|
|
|
79 programs.
|
|
|
80
|
|
|
81 Appendices:
|
|
|
82 * Reporting Bugs:: How to report a bug in Emacs-W3
|
|
|
83 * Installing SSL:: Turning on SSL support
|
|
|
84 * Using PGP/PEM:: Turning on PGP/PEM encryption support
|
|
|
85 * Mailcap Files:: An explanation of Mailcap files
|
|
|
86
|
|
|
87 Indices:
|
|
|
88 * General Index:: General Index
|
|
|
89 * Key Index:: Menus of command keys and their references
|
|
|
90 @end menu
|
|
|
91 @end ifinfo
|
|
|
92
|
|
|
93 @node Introduction, Setting Up, Top, Top
|
|
|
94 @chapter Introduction
|
|
|
95 @cindex World Wide Web
|
|
|
96 Emacs-W3 is an Emacs subsystem that allows the user to browse the wonderful
|
|
|
97 World Wide Web (WWW).
|
|
|
98
|
|
|
99 The World Wide Web was begun at the CERN physics institute in
|
|
|
100 Switzerland in 1991. The project was initiated by Tim Berners-Lee
|
|
|
101 (@i{timbl@@w3.org}) for distributing data between different research
|
|
|
102 groups effectively.
|
|
|
103
|
|
|
104
|
|
|
105 The Web has since grown into the most advanced information system
|
|
|
106 currently on the internet. It is now a global hypertext system with
|
|
|
107 servers and @dfn{browsers} (programs written to interpret the hypertext
|
|
|
108 language and display it correctly, and allow the user to follow links)
|
|
|
109 exist for all major platforms (VMS, Windows, DOS, Unix, VM, NeXTstep,
|
|
|
110 Amiga, and Macintosh).
|
|
|
111
|
|
|
112 The basic concepts used in the Web are @b{hypertext} and @b{hypermedia}.
|
|
|
113 Hypertext is the same as regular text, with one exception---it can
|
|
|
114 contain links (cross-references) to other textual documents. Hypermedia
|
|
|
115 is slightly different---it can contain links to other forms of media
|
|
|
116 (movies, sounds, interactive programs, etc.).
|
|
|
117
|
|
|
118 WWW also allows searches of indices that are located anywhere on the
|
|
|
119 network; in this respect, it mirrors certain capabilities found in both
|
|
|
120 WAIS and Gopher.
|
|
|
121 @iftex
|
|
|
122 @section Client Side View of WWW
|
|
|
123 @end iftex
|
|
|
124 @ifinfo
|
|
|
125 @center ----------------
|
|
|
126 @center CLIENT SIDE VIEW
|
|
|
127 @center ----------------
|
|
|
128 @end ifinfo
|
|
|
129 The WWW consists of documents and links. Indexes are special documents
|
|
|
130 which, rather than being read, may be searched. The result of such a
|
|
|
131 search is another @i{virtual} document containing links to the documents
|
|
|
132 found. A simple protocol, Hypertext Transfer Protocol or @i{HTTP}, is
|
|
|
133 used to allow a browser program to request a keyword search by a remote
|
|
|
134 information server.
|
|
|
135
|
|
|
136
|
|
|
137 The web contains documents in many formats. Those documents which are
|
|
|
138 hypertext, (real or virtual) contain links to other documents, or places
|
|
|
139 within documents. All documents, whether real, virtual or indexes, look
|
|
|
140 similar to the reader and are contained within the same addressing
|
|
|
141 scheme.
|
|
|
142 @iftex
|
|
|
143 @section Information Provider View of WWW
|
|
|
144 @end iftex
|
|
|
145 @ifinfo
|
|
|
146 @center -------------------------
|
|
|
147 @center INFORMATION PROVIDER VIEW
|
|
|
148 @center -------------------------
|
|
|
149 @end ifinfo
|
|
|
150 WWW browsers can access many existing data systems via existing
|
|
|
151 protocols (FTP, NNTP) or via HTTP and a gateway. In this way, the
|
|
|
152 critical mass of data is quickly exceeded, and the increasing use of the
|
|
|
153 system by readers and information suppliers encourage each other.
|
|
|
154
|
|
|
155 Providing information is as simple as running a WWW server and pointing
|
|
|
156 it at an existing directory structure. The server automatically
|
|
|
157 generates a hypertext view of the files to guide the user around.
|
|
|
158
|
|
|
159
|
|
|
160 To personalize it, a few @b{SGML} hypertext files can be written to give
|
|
|
161 an even more friendly view. Also, any file available by anonymous FTP,
|
|
|
162 or any internet newsgroup can be immediately linked into the web. The
|
|
|
163 small start-up effort is designed to allow open contributions. At the
|
|
|
164 other end of the scale, large information providers may provide an HTTP
|
|
|
165 server with full text or keyword indexing. This may allow access to a
|
|
|
166 large existing database without changing the way that database is
|
|
|
167 managed. Such gateways have already been made into Oracle(tm), WAIS,
|
|
|
168 and Digital's VMS/Help systems, to name but a few.
|
|
|
169
|
|
|
170
|
|
|
171 The WWW model gets over the frustrating incompatibilities of data format
|
|
|
172 between suppliers and reader by allowing negotiation of format between a
|
|
|
173 smart browser and a smart server. This provides a basis for extension
|
|
|
174 into multimedia, and allow those who share application standards to make
|
|
|
175 full use of them across the web.
|
|
|
176
|
|
|
177
|
|
|
178 @ifinfo
|
|
|
179 Here is some more specific information about what Emacs-W3 does and does
|
|
|
180 not understand:
|
|
|
181 @menu
|
|
|
182 * Markup Languages Supported:: The different markup languages that
|
|
|
183 Emacs-W3 understands natively.
|
|
|
184 * Supported Protocols:: The different network protocols that
|
|
|
185 Emacs-W3 speaks to.
|
|
|
186 @end menu
|
|
|
187 @end ifinfo
|
|
|
188 @node Markup Languages Supported, Supported Protocols, Introduction, Introduction
|
|
|
189 @chapter Supported Markup Languages
|
|
|
190 Several different markup languages, and various extensions to those
|
|
|
191 languages, are supported by Emacs-W3.
|
|
|
192 @ifinfo
|
|
|
193 @center ----------
|
|
|
194 @center HTML 2.0
|
|
|
195 @center ----------
|
|
|
196 @end ifinfo
|
|
|
197 @iftex
|
|
|
198 @section HTML 2.0
|
|
|
199 @end iftex
|
|
|
200 The Hypertext Markup Language, or HTML, is composed of a set of elements
|
|
|
201 that define a document and guide its display. An HTML element may
|
|
|
202 include a name, some attributes and some text or hypertext, and appears
|
|
|
203 in an HTML document as <tag_name>text</tag_name>, <tag_name
|
|
|
204 attribute_name=argument>text</tag_name>, or just <tag_name>.
|
|
|
205
|
|
|
206
|
|
|
207 For example: @samp{<title>My Useful Document</title>}, and @samp{<pre
|
|
|
208 width=60> A lot of text here. </pre>}.
|
|
|
209
|
|
|
210 An HTML document is composed of a single element: <html>...</html>, that
|
|
|
211 is, in turn, composed of head and body elements: <head>...</head>, and
|
|
|
212 <body>...</body>. To allow older HTML documents to remain readable,
|
|
|
213 <html>, <head>, and <body> are actually optional within HTML
|
|
|
214 documents.
|
|
|
215
|
|
|
216 All the tags and attributes of HTML are fully supported in Emacs-W3.
|
|
|
217
|
|
|
218 The full HTML 2.0 specification is available at any RFC
|
|
|
219 archive@footnote{ftp://ds.internic.net/}. It is RFC 1866.
|
|
|
220
|
|
|
221
|
|
|
222 @ifinfo
|
|
|
223 @center ----------
|
|
|
224 @center HTML 3.0
|
|
|
225 @center ----------
|
|
|
226 @end ifinfo
|
|
|
227 @iftex
|
|
|
228 @section HTML 3.0
|
|
|
229 @end iftex
|
|
|
230 @cindex HTML 3.0
|
|
|
231 The HTML 3.0 language is an extension of HTML, with a large degree of
|
|
|
232 backward compatibility with HTML 2.0. The idea of having one huge HTML
|
|
|
233 3.0 document has been dropped in favor of several smaller supplementatry
|
|
|
234 RFCs. This will allow the standard to be upgraded much more quickly
|
|
|
235 than trying to agree on all the features at once.
|
|
|
236
|
|
|
237 As each new chunk of HTML 3.0 is proposed and agreed upon, Emacs-W3 will
|
|
|
238 support it.
|
|
|
239
|
|
|
240 :: WORK :: List currently supported chunks (embed, etc) ::
|
|
|
241 @itemize @bullet
|
|
|
242 @item Embed
|
|
|
243 Embedding of arbitrary objects into an HTML document. With the <embed>
|
|
|
244 tag, any type of document can be inserted. The most entertaining use of
|
|
|
245 this is with embedding MPEG movies into an emacs buffer. This requires
|
|
|
246 Lucid Emacs 19.10, or XEmacs 19.11, as well as a slightly patched
|
|
|
247 version of mpeg_play 2.0@footnote{The patch is available from
|
|
|
248 ftp://ftp.cs.indiana.edu/pub/elisp/w3/mpeg_patch}.
|
|
|
249
|
|
|
250 @end itemize
|
|
|
251 @ifinfo
|
|
|
252 @center ----------
|
|
|
253 @center Netscape-HTML
|
|
|
254 @center ----------
|
|
|
255 @end ifinfo
|
|
|
256 @iftex
|
|
|
257 @section Netscape-HTML
|
|
|
258 @end iftex
|
|
|
259 I hate to say it, but I broke down and actually included some of the
|
|
|
260 Netscape extensions into Emacs-W3.
|
|
|
261
|
|
|
262 @table @b
|
|
|
263 @item <font>...</font>
|
|
|
264 Changes the font size. Valid values range from 0-7. The default
|
|
|
265 font size is 3. The value given can optionally have a '+' or '-'
|
|
|
266 character in front of it to specify that it is relative to the document
|
|
|
267 basefont. Stylesheets are recommended instead, as they allow much
|
|
|
268 greater control.@xref{Style Sheets}
|
|
|
269 @item <center>...</center>
|
|
|
270 This ugly, ill-thought-out alternative to the HTML 3.0 align attribute on
|
|
|
271 headers and paragraphs was included for compatibility, and as an example
|
|
|
272 of how @b{not} to do things.
|
|
|
273 @item <isindex>
|
|
|
274 The isindex tag can now take a prompt attribute, to get rid of the
|
|
|
275 default 'This is a searchable index' label.
|
|
|
276 @item <hr width=xx align=xx>
|
|
|
277 The width and alignment of a horizontal rule can now be controlled. The
|
|
|
278 WIDTH attribute specifies how wide the rule should be, as a percentage
|
|
|
279 of the window width.
|
|
|
280
|
|
|
281
|
|
|
282 The ALIGN attribute specifies where the horizontal rule is placed.
|
|
|
283 Valid values are left, right, center, and indent.
|
|
|
284 @item <body background=@var{URL} bgcolor=@var{RGB} TEXT=@var{RGB} LINK=@var{RGB} ALINK=@var{RGB} VLINK=@var{RGB}>
|
|
|
285 Various colors can now be set on a document wide basis. This is done
|
|
|
286 with various attributes on the BODY tag. Stylesheets are really a
|
|
|
287 better way to do this, and are recommended. This is just for
|
|
|
288 compatibility. @xref{Style Sheets}
|
|
|
289 @b{NOTE:} Netscape requires that all colors be specified in RGB values -
|
|
|
290 this is not very intuitive for the avergage author, so Emacs-W3 allows
|
|
|
291 you to use logical system colors (ie: @samp{"PaleGoldenrod"} instead of
|
|
|
292 @samp{"#eee8aa"}).
|
|
|
293 @table @b
|
|
|
294 @item BACKGROUND=@var{url}
|
|
|
295 Specifies a graphic to tile in the background of the document. This
|
|
|
296 only works in XEmacs 19.12 or later.
|
|
|
297 @item BGCOLOR=@var{color}
|
|
|
298 Specifies the background of the document, as a color instead of a
|
|
|
299 graphic.
|
|
|
300 @item TEXT=@var{color}
|
|
|
301 Specifies the color of text on the page.
|
|
|
302 @item LINK=@var{color}
|
|
|
303 Specifies the color of hypertext links on the page.
|
|
|
304 @item VLINK=@var{color}
|
|
|
305 Specifies the color of hypertext links that have been visited already.
|
|
|
306 @item ALINK=@var{color}
|
|
|
307 Specifies the color of active hypertext links (links that have been
|
|
|
308 clicked on, but not yet fully retrieved).
|
|
|
309 @end table
|
|
|
310 @end table
|
|
|
311 @ifinfo
|
|
|
312 @center ----------
|
|
|
313 @center SGML Features
|
|
|
314 @center ----------
|
|
|
315 @end ifinfo
|
|
|
316 @iftex
|
|
|
317 @section SGML Features
|
|
|
318 @end iftex
|
|
|
319 @cindex SGML Features
|
|
|
320 @cindex Entity Definitions
|
|
|
321 @cindex Marked Sections
|
|
|
322 :: WORK :: Document marked sections, SGML features
|
|
|
323 @ifinfo
|
|
|
324 @center ----------
|
|
|
325 @center Extras
|
|
|
326 @center ----------
|
|
|
327 @end ifinfo
|
|
|
328 @iftex
|
|
|
329 @section Extra Markup
|
|
|
330 @end iftex
|
|
|
331 @cindex Easter Eggs
|
|
|
332 @cindex Fluff
|
|
|
333 @cindex Pomp & Circumstance
|
|
|
334 There are several different markup elements that are not officially part
|
|
|
335 of HTML or HTML 3.0 that Emacs-W3 supports. These are either items that
|
|
|
336 were dropped from HTML 3.0 after I had implemented them, or experimental
|
|
|
337 parts of HTML that should not be counted as "official" or long
|
|
|
338 lived.
|
|
|
339 @itemize @bullet
|
|
|
340 @item
|
|
|
341 More <HR> improvements. Text can be added into a horizontal rule by
|
|
|
342 using the LABEL and TEXTALIGN attributes.
|
|
|
343
|
|
|
344 @example
|
|
|
345 <hr label="testing" textalign="right">
|
|
|
346 yields
|
|
|
347 ----------------------------------------------------------testing-
|
|
|
348
|
|
|
349 <hr label="testing" textalign="center">
|
|
|
350 yields
|
|
|
351 -----------------------------testing------------------------------
|
|
|
352
|
|
|
353 <hr label="testing" textalign="left">
|
|
|
354 yields
|
|
|
355 -Testing----------------------------------------------------------
|
|
|
356 @end example
|
|
|
357 @item
|
|
|
358 FLAME support. For truly interesting dynamic documents. This is
|
|
|
359 replaced with a random quote from Mr. Angry (see @kbd{M-x flame} for a
|
|
|
360 sample).
|
|
|
361 @item
|
|
|
362 The top ten tags that did not make it into netscape. These tags were
|
|
|
363 posted to the newsgroup comp.infosystems.www.misc by Laura Lemay
|
|
|
364 (@i{lemay@@netcom.com}). Much thanks to her for the humor.
|
|
|
365 @table @b
|
|
|
366 @item <wired>...</wired>
|
|
|
367 Renders the enclosed text in a suitably ugly font/color combination. If
|
|
|
368 no default has been set up by the user, this is the default font, with
|
|
|
369 red text on a yellow background.
|
|
|
370 @item <roach>...</roach>
|
|
|
371 When selected, the enclosed text runs and hides under the nearest
|
|
|
372 window. OR, giggles a lot and demands nachos, depending on the
|
|
|
373 definition of "roach." (the formal definition, of course, to be
|
|
|
374 determined by the Official Honorary Internet Standards Committee For
|
|
|
375 Moving Really Slowly.)
|
|
|
376 @item <pinhead>
|
|
|
377 Inserts "zippyisms" into the enclosed text. Perfect for those professional
|
|
|
378 documents. This is sure to be a favorite of mine!
|
|
|
379 @item <secret>...</secret>
|
|
|
380 Must use secret spy decoder glasses (available direct from Netscape for
|
|
|
381 a reasonable fee) in order to read the enclosed text. Can also be read
|
|
|
382 by holding the computer in front of a full moon during the autumn
|
|
|
383 solstice.
|
|
|
384
|
|
|
385 In Emacs-W3, this displays the text using rot13 encoding.
|
|
|
386 @item <hype>
|
|
|
387 Causes Marc Andreesen to magically appear and grant an interview (wanted
|
|
|
388 or not). Please use this tag sparingly.
|
|
|
389 @item <peek>....</peek>
|
|
|
390 @item <poke>...</poke>
|
|
|
391 Need more control over screen layout in HTML? Well, here ya go.
|
|
|
392
|
|
|
393 Actually, <peek> could almost be considered useful. The VARIABLE
|
|
|
394 attribute can be used to insert the value of an emacs variable into the
|
|
|
395 current document. Things like 'Welcome to my page, <peek
|
|
|
396 variable=user-mail-address>' can be useful in freaking people
|
|
|
397 out.
|
|
|
398 @item <yogsothoth>
|
|
|
399 @cindex Gates Bill
|
|
|
400 @cindex Yogsothoth
|
|
|
401 Summons the elder gods to suck away your immortal soul. Or Bill Gates,
|
|
|
402 if the elder gods are busy. Unpredictable (but amusing) results occur
|
|
|
403 when the <YOGSOTHOTH> and <HYPE> tags are used in close proximity.
|
|
|
404
|
|
|
405 @item <blink>...</blink>
|
|
|
406 Causes the enclosed text to .... ooops that one made it in.
|
|
|
407 @end table
|
|
|
408 @end itemize
|
|
|
409 @node Supported Protocols, , Markup Languages Supported, Introduction
|
|
|
410 @chapter Supported Protocols
|
|
|
411 @cindex Network Protocols
|
|
|
412 @cindex Protocols Supported
|
|
|
413 @cindex Supported Protocols
|
|
|
414 Emacs-W3 supports the following protocols
|
|
|
415 @table @b
|
|
|
416 @item Usenet News
|
|
|
417 Can either display an entire newsgroup or specific articles by
|
|
|
418 Message-ID: header. This supports a unix-style .newsrc file, so the
|
|
|
419 user does not see articles they have read using another newsreader, but
|
|
|
420 due to how news URLs work, the .newsrc file cannot be updated
|
|
|
421 reliably.
|
|
|
422
|
|
|
423 To be more in line with the other URL schemes, the hostname and port of
|
|
|
424 an NNTP server can be specified. URLs of the form
|
|
|
425 news://hostname:port/messageID work, but will not work in most other
|
|
|
426 browsers.
|
|
|
427
|
|
|
428
|
|
|
429 @item HTTP
|
|
|
430 Supports both the HTTP/0.9 and HTTP/1.0 protocols. Fully MIME-compliant
|
|
|
431 with regards to HTTP/1.0.
|
|
|
432 @item Gopher
|
|
|
433 Support for all gopher types, including CSO queries.
|
|
|
434 @item Gopher+
|
|
|
435 Support for Gopher+ retrievals. Support for converting ASK blocks into
|
|
|
436 HTML 3.0 FORMS and submitting them back to the server.
|
|
|
437 @item FTP
|
|
|
438 FTP is handled by either ange-ftp or efs.
|
|
|
439 @item Local files
|
|
|
440 Local files are handled, and MIME content-types are derived from the
|
|
|
441 file extensions.
|
|
|
442 @item Telnet
|
|
|
443 Telnet is handled by running the Emacs Lisp function @code{telnet}, or
|
|
|
444 spawning an xterm running telnet.
|
|
|
445 @item TN3270
|
|
|
446 TN3270 is handled by running a tn3270 program in an Emacs buffer, or
|
|
|
447 spawning an xterm running tn3270.
|
|
|
448 @item Mailto
|
|
|
449 Causes a mail message to be started to a specific address.
|
|
|
450 @item mailserver
|
|
|
451 A more powerful version of mailto, which allows the author to specify
|
|
|
452 the subject and body text of the mail message. This type of link is
|
|
|
453 never fully executed without user confirmation, because it is possible
|
|
|
454 to insert insulting or threatening (and possibly illegal) data into the
|
|
|
455 message. The mail message is displayed, and the user must type 'yes' to
|
|
|
456 send it.
|
|
|
457 @item X-exec
|
|
|
458 A URL can cause a local executable to be run, and its output interpreted
|
|
|
459 as if it had come from an HTTP server. This is very useful, but is
|
|
|
460 still an experimental protocol, hence the X- prefix.
|
|
|
461 @item SSL
|
|
|
462 SSL requires a set of patches to the Emacs C code and SSLRef 2.0, or an
|
|
|
463 external program to run in a subprocess (similar to the @file{tcp.el}
|
|
|
464 package that comes with GNUS. @xref{Installing SSL}
|
|
|
465 @item Secure HTTP
|
|
|
466 Work is in progress to add support for the Secure HTTP specification
|
|
|
467 from Enterprise Information Technologies. The specification for SHTTP
|
|
|
468 can be found on EIT's web server at
|
|
|
469 http://www.commerce.net/information/standards/drafts/shttp.txt.
|
|
|
470 @end table
|
|
|
471
|
|
|
472 @node Setting Up, Retrieving Emacs-W3, Introduction, Top
|
|
|
473 @comment node-name, next, previous, up
|
|
|
474 @chapter Setting Up
|
|
|
475 @cindex Setting Up Emacs-W3
|
|
|
476 @cindex Retrieving Emacs-W3
|
|
|
477 This section of the manual deals with getting, compiling, and
|
|
|
478 configuring @i{Emacs-W3}.
|
|
|
479 @ifinfo
|
|
|
480 @menu
|
|
|
481 * Retrieving Emacs-W3:: Retrieving Emacs-W3 via anonymous ftp
|
|
|
482 * Compiling Emacs-W3:: Compiling Emacs-W3 and its associated files
|
|
|
483 * Basic Setup:: Basic setup that everyone needs to do
|
|
|
484 * Firewalls:: How to set Emacs-W3 up to use a particular
|
|
|
485 firewall setup.
|
|
|
486 * Proxy Gateways:: Using a proxy server
|
|
|
487 @end menu
|
|
|
488 @end ifinfo
|
|
|
489 @node Retrieving Emacs-W3, Compiling Emacs-W3, Setting Up, Setting Up
|
|
|
490 @comment node-name, next, previous, up
|
|
|
491 @section Retrieving Emacs-W3
|
|
|
492
|
|
|
493 :: WORK :: Document that Emacs-W3 now requires the URL package as well
|
|
|
494
|
|
|
495 @node Compiling Emacs-W3, Basic Setup, Retrieving Emacs-W3, Setting Up
|
|
|
496 @comment node-name, next, previous, up
|
|
|
497 @section Compiling Emacs-W3
|
|
|
498 To install Emacs-W3, go into the @file{w3} subdirectory and edit the
|
|
|
499 @file{Makefile}. These variables might need to be changed:
|
|
|
500 @table @code
|
|
|
501 @item EMACS
|
|
|
502 This variable controls what version of Emacs is used to compile the
|
|
|
503 programs. It should be the full path to the Emacs executable on the
|
|
|
504 system. The default is to use GNU Emacs (@file{emacs}).
|
|
|
505 @item LISPDIR
|
|
|
506 This variable controls where the lisp code is copied to when it is
|
|
|
507 installed (with @code{make install}). This is usually the users
|
|
|
508 personal lisp code directory. The value is run through
|
|
|
509 @dfn{expand-file-name} and then added to the load-path. Default is
|
|
|
510 @file{~/lisp}.
|
|
|
511 @item DOTEMACS
|
|
|
512 This variable points to the Emacs customization file, default is
|
|
|
513 @file{~/.emacs}.
|
|
|
514 @item INFODIR
|
|
|
515 This variable points to the local info directory. This can be any valid
|
|
|
516 directory, as long as it is in @code{Info-default-directory-list} so
|
|
|
517 that info-mode can find it. Default is @file{/usr/local/info/}.
|
|
|
518
|
|
|
519 @item MAKEINFO
|
|
|
520 This variables controls how the info files are built. Possible values
|
|
|
521 are @code{makeinfo} or @code{emacs -batch -q -f
|
|
|
522 batch-texinfo-format}. Default is @code{makeinfo}.
|
|
|
523 @end table
|
|
|
524 Once the @file{Makefile} has been modified, several different targets
|
|
|
525 can be built.
|
|
|
526 @table @code
|
|
|
527 @item make w3
|
|
|
528 This compiles all the .el files into the much faster .elc files.
|
|
|
529 @item make install
|
|
|
530 Compiles all the .el files and copies .el and .elc files into the
|
|
|
531 directory specified by @code{LISPDIR}.
|
|
|
532 @item make emacs
|
|
|
533 Modifies the file specified by @code{DOTEMACS}. A statement modifying
|
|
|
534 the load-path variable and several autoload statements are added to the
|
|
|
535 end of the file.
|
|
|
536 @item make all
|
|
|
537 Compiles and installs the .el files, and also modify/create the
|
|
|
538 @code{DOTEMACS} file.
|
|
|
539 @item make w3.info
|
|
|
540 Creates the Emacs-readable info files. The info files are created in
|
|
|
541 the directory specified by @code{INFODIR}. The makefile variable
|
|
|
542 @code{MAKEINFO} determines how the info file is built.
|
|
|
543 @item make w3.dvi
|
|
|
544 Creates the printable documentation, using tex and texindex to properly
|
|
|
545 generate the indices. A @file{w3.dvi} file is left in the current
|
|
|
546 directory.
|
|
|
547 @end table
|
|
|
548 @node Basic Setup, Firewalls, Compiling Emacs-W3, Setting Up
|
|
|
549 @comment node-name, next, previous, up
|
|
|
550 @section Basic Setup
|
|
|
551 There are a few variables that almost all people need to change.
|
|
|
552
|
|
|
553 @table @code
|
|
|
554 @item w3-default-homepage
|
|
|
555 @vindex w3-default-homepage
|
|
|
556 The url to open at startup. This defaults to the environment variable
|
|
|
557 WWW_HOME if it is not set it in the users @file{.emacs} file. If
|
|
|
558 WWW_HOME is undefined, then it defaults to the hypertext documentation
|
|
|
559 for Emacs-W3.
|
|
|
560
|
|
|
561 @item w3-delay-image-loads
|
|
|
562 @vindex w3-delay-image-loads
|
|
|
563 Controls the loading of inlined images. If non-@code{nil}, images are
|
|
|
564 not loaded. If the correct image converters are not installed or the
|
|
|
565 network connection is very slow, it is best to set this to @code{t}.
|
|
|
566 Defaults to @code{nil}.
|
|
|
567 @item url-global-history-file
|
|
|
568 @vindex url-global-history-file
|
|
|
569 The global history file used by both Mosaic/X and Emacs-W3. This file
|
|
|
570 contains a list of all the URLs that have been visited. This file is parsed
|
|
|
571 at startup and used to provide URL completion. Emacs-W3 can read and
|
|
|
572 write Mosaic/X or Netscape 1.x style history files, or use its own
|
|
|
573 internal format (faster). The file type is determined automatically, or
|
|
|
574 prompted for if the file does not exist.
|
|
|
575 @item w3-hotlist-file
|
|
|
576 @vindex w3-hotlist-file
|
|
|
577 Hotlist filename. This should be the name of a file that is stored in
|
|
|
578 NCSA's Mosaic/X or Netscape's format. It is used to keep a listing of
|
|
|
579 commonly accessed URLs.
|
|
|
580 @item w3-personal-annotation-directory
|
|
|
581 @vindex w3-personal-annotation-directory
|
|
|
582 The directory where Emacs-W3 looks for personal annotations. This is a
|
|
|
583 directory that should hold the personal annotations stored in a
|
|
|
584 Mosaic/X-compatible format.
|
|
|
585 @item url-pgp/pem-entity
|
|
|
586 @findex user-real-login-name
|
|
|
587 @findex system-name
|
|
|
588 The name by which the user is known to PGP and/or PEM entities. If this
|
|
|
589 is not set when Emacs-W3 is loaded, it defaults to
|
|
|
590 @code{user-mail-address} if it is set, otherwise @code{(user-real-login-name)}@@@code{(system-name)}.
|
|
|
591 @item url-personal-mail-address
|
|
|
592 @vindex url-personal-mail-address
|
|
|
593 @vindex url-pgp/pem-entity
|
|
|
594 User's full email address. This is what is sent to HTTP/1.0 servers as
|
|
|
595 the FROM header. If this is not set when Emacs-W3 is loaded, then it
|
|
|
596 defaults to the value of @code{url-pgp/pem-entity}.
|
|
|
597
|
|
|
598 @item w3-right-border
|
|
|
599 @vindex w3-right-border
|
|
|
600 @findex window-width
|
|
|
601 Amount of space to leave on right margin of WWW buffers. This amount is
|
|
|
602 subtracted from the width of the window for each new WWW buffer and used
|
|
|
603 as the new @code{fill-column}.
|
|
|
604
|
|
|
605 @item w3-track-mouse
|
|
|
606 @vindex w3-track-mouse
|
|
|
607 Controls whether to track the mouse and message the url under the mouse.
|
|
|
608 If this is non-@code{nil}, then a description of the hypertext area
|
|
|
609 under the mouse is shown in the minibuffer. This shows what type of
|
|
|
610 link (inlined image, form entry area, delayed image, delayed MPEG, or
|
|
|
611 hypertext reference) is under the cursor, and the destination.
|
|
|
612 @item w3-echo-link
|
|
|
613 @vindex w3-echo-link
|
|
|
614 Controls how a URL is shown when a link is reached with @key{f},
|
|
|
615 @key{b}, or the mouse moves over it. Possible values are:
|
|
|
616 @table @b
|
|
|
617 @item url
|
|
|
618 Displays the URL (ie: @samp{http://www.cs.indiana.edu/}).
|
|
|
619 @item text
|
|
|
620 Displays the text of the link (ie: @samp{A link to Indiana University}).
|
|
|
621 @item nil
|
|
|
622 Show nothing.
|
|
|
623 @end table
|
|
|
624 @item w3-use-forms-index
|
|
|
625 @vindex w3-use-forms-index
|
|
|
626 @cindex ISINDEX handling
|
|
|
627 @cindex Forms based searching
|
|
|
628 @cindex Searching with forms
|
|
|
629 Non-@code{nil} means translate <ISINDEX> tags into a hypertext form. A
|
|
|
630 single text entry box is shown where the ISINDEX tag appears.
|
|
|
631 @item url-use-hypertext-gopher
|
|
|
632 @vindex url-use-hypertext-gopher
|
|
|
633 @cindex Gopher+
|
|
|
634 Controls how gopher documents are retrieved. If non-@code{nil}, the
|
|
|
635 gopher pages are converted into HTML and parsed just like any other
|
|
|
636 page. If @code{nil}, the requests are passed off to the
|
|
|
637 @file{gopher.el} package by Scott Snyder. Using the @file{gopher.el}
|
|
|
638 package loses the gopher+ support, and inlined searching.
|
|
|
639 @item url-xterm-command
|
|
|
640 @vindex url-xterm-command
|
|
|
641 Command used to start a windowed shell, similar to an xterm. This
|
|
|
642 string is passed through @code{format}, and should expect four strings:
|
|
|
643 the title of the window, the program name to execute, and the server and
|
|
|
644 port number. The default is for xterm, which is very UNIX and
|
|
|
645 XWindows-centric.
|
|
|
646 @end table
|
|
|
647 @node Firewalls, Proxy Gateways, Basic Setup, Setting Up
|
|
|
648 @comment node-name, next, previous, up
|
|
|
649 @section Firewalls
|
|
|
650 @cindex Gateways
|
|
|
651 There are several different reasons why the gateway support might be
|
|
|
652 required.
|
|
|
653 @enumerate
|
|
|
654 @cindex Firewalls
|
|
|
655 @item
|
|
|
656 Stuck behind a firewall. This is usually the case at large corporations
|
|
|
657 with paranoid system-administrators.
|
|
|
658
|
|
|
659 @cindex TERM
|
|
|
660 @item
|
|
|
661 Using TERM @footnote{TERM is a user-level protocol for emulating IP over
|
|
|
662 a serial line. More information is available at
|
|
|
663 ftp://sunsite.unc.edu/pub/Linux/apps/comm/term} for slip-like access to
|
|
|
664 the internet.
|
|
|
665
|
|
|
666
|
|
|
667 NOTE: Emacs 19.22 has patches to enable native TERM networking. To
|
|
|
668 enable it, #define TERM in the appropriate s/*.h file for the operating
|
|
|
669 system, then change the SYSTEM_LIBS define to include the @file{termnet}
|
|
|
670 library that comes with the latest versions of TERM.
|
|
|
671
|
|
|
672 @item
|
|
|
673 @cindex Faulty hostname resolvers
|
|
|
674 @cindex Broken SUN libc
|
|
|
675 @cindex Can't resolve hostnames
|
|
|
676 Emacs cannot resolve hostnames. This happens quite often on Sun
|
|
|
677 workstations and some ULTRIX machines. Some C libraries do not include
|
|
|
678 the hostname resolver routines in their static libraries. If Emacs was
|
|
|
679 linked statically, this means it won't be able to get to any machines
|
|
|
680 off the local network. This is characterized by being able to reach
|
|
|
681 someplace with a raw ip number, but not its hostname
|
|
|
682 (http://129.79.254.191/ works, but http://www.cs.indiana.edu/ doesn't).
|
|
|
683
|
|
|
684
|
|
|
685 If for some reason it is not feasible to recompile Emacs with the
|
|
|
686 @file{-lresolv} library or dynamic linking, it is just like being behind
|
|
|
687 a firewall. Another alternative is to set the variable
|
|
|
688 @code{url-broken-resolution} - this will use the support in ange-ftp or
|
|
|
689 EFS to use @file{nslookup} in a subprocess to do all hostname resolving.
|
|
|
690 See the variables @code{efs-nslookup-program},
|
|
|
691 @code{efs-nslookup-on-connect}, and @code{efs-nslookup-threshold} if are
|
|
|
692 using EFS, or @code{ange-ftp-nslookup-program} if using Ange-FTP.
|
|
|
693
|
|
|
694 @cindex Connections hanging with XEmacs & solaris
|
|
|
695 @cindex Solaris networking problems
|
|
|
696 @cindex XEmacs & Solaris network problems
|
|
|
697 @item
|
|
|
698 Running XEmacs 19.x and Solaris 2.x (SunOS 5.x). For some reason,
|
|
|
699 network processes under Solaris and XEmacs never get a status of
|
|
|
700 @code{exit} or @code{closed}. This causes retrieval of HTTP and gopher
|
|
|
701 pages to hang indefinitely, with Emacs chewing up large amounts of CPU
|
|
|
702 time.
|
|
|
703
|
|
|
704 @end enumerate
|
|
|
705
|
|
|
706 @vindex url-gateway-local-host-regexp
|
|
|
707 Emacs-W3 has support for using the gateway mechanism for certain
|
|
|
708 domains, and directly connecting to others. To use this, change the
|
|
|
709 value of @code{url-gateway-local-host-regexp}. This should be a regular
|
|
|
710 expression @footnote{Please see the full Emacs distribution for a
|
|
|
711 description of regular expressions} that matches local hosts that do not
|
|
|
712 require the use of a gateway. If @code{nil}, then all connections are
|
|
|
713 made through the gateway.
|
|
|
714
|
|
|
715
|
|
|
716 @vindex url-gateway-method
|
|
|
717 Emacs-W3 supports several methods of getting around gateways. The variable
|
|
|
718 @code{url-gateway-method} controls which of these methods is used. This
|
|
|
719 variable can have several values (use these as symbol names, not
|
|
|
720 strings):
|
|
|
721 @table @dfn
|
|
|
722 @item program
|
|
|
723 Run a program in a subprocess to connect to remote hosts (examples are
|
|
|
724 @i{itelnet}@footnote{Itelnet is a standard name for a telnet executable
|
|
|
725 that is capable of escaping the firewall. Check with system
|
|
|
726 administrators to see if anything similar is available}, an
|
|
|
727 @i{expect}@footnote{Expect is a scripting language that allows control
|
|
|
728 of interactive programs (like telnet) very easily. It is available from
|
|
|
729 gatekeeper.dec.com:/pub/GNU/expect-3.24.0.tar.gz} script, etc.).
|
|
|
730
|
|
|
731 @item host
|
|
|
732 Log into another local computer that has access to the internet, and run
|
|
|
733 a telnet-like program from there.
|
|
|
734 @item tcp
|
|
|
735 Masanobu UMEDA (@i{umerin@@mse.kyutech.ac.jp}) has written a very nice
|
|
|
736 replacement for the standard networking in Emacs. This does basically
|
|
|
737 the same thing that a method of @code{program} does, but is slightly
|
|
|
738 more transparent to the user.
|
|
|
739 @item native
|
|
|
740 This means that Emacs-W3 should use the builtin networking code of Emacs.
|
|
|
741 This should be used only if there is no firewall, or the Emacs source
|
|
|
742 has already been hacked to get around the firewall.
|
|
|
743 @end table
|
|
|
744 Two of these need a bit more explanation than that:
|
|
|
745 @vindex url-gateway-telnet-ready-regexp
|
|
|
746 @vindex url-gateway-telnet-program
|
|
|
747 When running a program in a subprocess to emulate a network connection,
|
|
|
748 a few extra variables need to be set. The variable
|
|
|
749 @code{url-gateway-telnet-program} should point to an executable that
|
|
|
750 accepts a hostname and port # as its arguments, and passes standard
|
|
|
751 input to the remote host. This can be either the full path to the
|
|
|
752 executable or just the basename. The variable
|
|
|
753 @code{url-gateway-telnet-ready-regexp} controls how long Emacs-W3 should
|
|
|
754 wait after spawning the subprocess to start sending to its standard
|
|
|
755 input. This gets around a bug where telnet would miss the beginning of
|
|
|
756 requests becausse it did not buffer its input before opening a
|
|
|
757 connection. This should be a regular expression to watch for that
|
|
|
758 signifies the end of the setup of @code{url-gateway-telnet-program}.
|
|
|
759 The default should work fine for telnet.
|
|
|
760
|
|
|
761
|
|
|
762 @cindex Host-based gateways
|
|
|
763 @cindex Hair-pulling gateway-headaches
|
|
|
764 @vindex url-gateway-host
|
|
|
765 When using the @code{host}-based gatway method, things get a bit more
|
|
|
766 complicated. This is basically my attempt to do some of the basic stuff
|
|
|
767 of @i{expect} within elisp. First off, set the variable
|
|
|
768 @code{url-gateway-host} to be the name of the gateway machine.
|
|
|
769
|
|
|
770
|
|
|
771 @vindex url-gateway-connect-program
|
|
|
772 The variable @code{url-gateway-connect-program} controls how the host is
|
|
|
773 reached. The easiest way is to have a program that does not require a
|
|
|
774 username and password to login. The most common of these is the
|
|
|
775 @dfn{rsh} command.
|
|
|
776
|
|
|
777
|
|
|
778 @vindex url-gateway-program-interactive
|
|
|
779 @vindex url-gateway-handholding-password-regexp
|
|
|
780 @vindex url-gateway-handholding-login-regexp
|
|
|
781 @vindex url-gateway-host-username
|
|
|
782 @vindex url-gateway-host-password
|
|
|
783 If @i{rsh} is not available, then things get very ugly. First, set the
|
|
|
784 variable @code{url-gateway-program-interactive} to non-@code{nil}. Then
|
|
|
785 set the variables @code{url-gateway-host-username} and
|
|
|
786 @code{url-gateway-host-password} to be the username and password
|
|
|
787 necessary to log into the gateway machine. The regular expressions in
|
|
|
788 the variables @code{url-gateway-handholding-login-regexp} and
|
|
|
789 @code{url-gateway-handholding-password-regexp} should match the login
|
|
|
790 and password prompts on the gateway system respectively. For example:
|
|
|
791
|
|
|
792
|
|
|
793 @example
|
|
|
794 (setq url-gateway-connect-program "telnet"
|
|
|
795 url-gateway-host-program "telnet"
|
|
|
796 url-gateway-program-interactive t
|
|
|
797 url-gateway-host-username "wmperry"
|
|
|
798 url-gateway-host-password "yeahrightkeepdreaming"
|
|
|
799 url-gateway-host "moose.cs.indiana.edu"
|
|
|
800 url-gateway-host-program-ready-regexp "Escape character is .*"
|
|
|
801 url-gateway-handholding-login-regexp "ogin:"
|
|
|
802 url-gateway-handholding-password-regexp "ord:")
|
|
|
803 @end example
|
|
|
804
|
|
|
805 @vindex url-gateway-host-prompt-pattern
|
|
|
806 This should take care of logging in to the remote system. The variable
|
|
|
807 @code{url-gateway-host-prompt-pattern} should contain a regular
|
|
|
808 expression that matches the shell prompt on the remote machine. This
|
|
|
809 should appear @b{no where} in the login banner/setup, or things could
|
|
|
810 get very confused.
|
|
|
811
|
|
|
812
|
|
|
813 @vindex url-gateway-host-program-ready-regexp
|
|
|
814 @vindex url-gateway-host-program
|
|
|
815 The variable @code{url-gateway-host-program-ready-regexp} should contain
|
|
|
816 a regular expression that matches the end of the setup of
|
|
|
817 @code{url-gateway-host-program} when it tries to make a connection to an
|
|
|
818 off-firewall machine. (Basically the same as
|
|
|
819 @code{url-gateway-telnet-ready-regexp}.
|
|
|
820
|
|
|
821
|
|
|
822 Emacs-W3 should now be able to get outside the local network. If none
|
|
|
823 of this makes sense, its probably my fault. Please check with the
|
|
|
824 network administrators to see if they have a program that does most of
|
|
|
825 this already, since somebody somewhere at the company has probably been
|
|
|
826 through something similar to this before, and would be much more
|
|
|
827 helpful/knowledgeable about the local setup than I would be. But feel
|
|
|
828 free to mail me as a last resort.
|
|
|
829
|
|
|
830
|
|
|
831 @node Proxy Gateways, Basic Usage, Firewalls, Setting Up
|
|
|
832 @comment node-name, next, previous, up
|
|
|
833 @section Proxy Gateways
|
|
|
834 In late January 1993, Kevin Altis and Lou Montulli proposed and implemented a
|
|
|
835 new proxy service. This service requires the use of environment
|
|
|
836 variables to specify a gateway server/port # to send protocol requests
|
|
|
837 to. Each protocol (HTTP, WAIS, gopher, FTP, etc.@:) can have a
|
|
|
838 different gateway server. The environment variables are
|
|
|
839 @var{PROTOCOL}_proxy, where @var{PROTOCOL} is one of gopher, file, HTTP,
|
|
|
840 FTP, or WAIS.
|
|
|
841
|
|
|
842 :: WORK ::
|
|
|
843
|
|
|
844 @node Basic Usage, , Proxy Gateways, Top
|
|
|
845 @comment node-name, next, previous, up
|
|
|
846 @chapter Basic Usage
|
|
|
847 Emacs-W3 is similar to the Info package all Emacs users hold near and dear to
|
|
|
848 their hearts (@xref{Top,,Info,info, The Info Manual}, for a description
|
|
|
849 of Info). Basically, @kbd{space} and @kbd{backspace} control scrolling,
|
|
|
850 and @kbd{return} or @kbd{mouse2} follows a hypertext link. The @kbd{f}
|
|
|
851 and @kbd{b} keys maneuver around the various links on the page.
|
|
|
852
|
|
|
853 @b{NOTE:} To enter data into a form entry area, select it using
|
|
|
854 @kbd{return} or the middle mouse button, just like a hypertext link.
|
|
|
855
|
|
|
856
|
|
|
857 On non-graphic terminals (VT100, DOS, etc.), hypertext links are
|
|
|
858 surrounded by '[[' and ']]' by default. On a graphics terminal, the
|
|
|
859 links are in bold print. @xref{Controlling Formatting} for information
|
|
|
860 on how to change this, or for help on getting the highlighting to work
|
|
|
861 on graphics terminals.
|
|
|
862
|
|
|
863 There are approximately 50 keys bound to special Emacs-W3 functions.
|
|
|
864 The basic rule of thumb regarding keybindings in Emacs-W3 is that a
|
|
|
865 lowercase key takes an action on the @b{current document}, and an
|
|
|
866 uppercase key takes an action on the document pointed to by the
|
|
|
867 hypertext link @b{under the cursor}.
|
|
|
868
|
|
|
869 There are several areas that the keybindings fall into: movement,
|
|
|
870 information, action, and miscellaneous.
|
|
|
871
|
|
|
872 @ifinfo
|
|
|
873 @menu
|
|
|
874 * Movement:: Moving around in a Emacs-W3 buffer
|
|
|
875 * Information:: Getting information about the Emacs-W3 document being
|
|
|
876 viewed, and/or links within that document.
|
|
|
877 * Action:: Taking actions in a Emacs-W3 buffer (following links,
|
|
|
878 printing, etc.)
|
|
|
879 * Miscellaneous:: Miscellaneous keybindings
|
|
|
880 @end menu
|
|
|
881 @end ifinfo
|
|
|
882 @node Movement, Information, Basic Usage, Basic Usage
|
|
|
883 @section Movement
|
|
|
884 :: WORK :: Document the 'h' and 'a' keymaps
|
|
|
885 @table @kbd
|
|
|
886 @findex scroll-up
|
|
|
887 @kindex SPC
|
|
|
888 @item SPC
|
|
|
889 Scroll downward in the buffer. With prefix arg, scroll down that many
|
|
|
890 screenfuls.
|
|
|
891 @kindex DEL
|
|
|
892 @findex scroll-down
|
|
|
893 @item DEL
|
|
|
894 Scroll upward in the buffer. With prefix arg, scroll up that many
|
|
|
895 screenfuls.
|
|
|
896 @kindex <
|
|
|
897 @findex w3-start-of-document
|
|
|
898 @item <
|
|
|
899 Goes to the start of document
|
|
|
900 @kindex >
|
|
|
901 @findex w3-end-of-document
|
|
|
902 @item >
|
|
|
903 Goes to the end of document
|
|
|
904 @kindex b
|
|
|
905 @kindex Shift-TAB
|
|
|
906 @findex w3-back-link
|
|
|
907 @item Shift-TAB, b
|
|
|
908 Attempts to move backward one link area in the current document.
|
|
|
909 Signals an error if no previous links are found.
|
|
|
910 @kindex hl
|
|
|
911 @findex w3-show-hotlist
|
|
|
912 @item hl
|
|
|
913 Displays a complete listing of the items in the hotlist.
|
|
|
914 @kindex hu
|
|
|
915 @findex w3-use-hotlist
|
|
|
916 @item hu
|
|
|
917 Go to a link in the hotlist.
|
|
|
918 @kindex m
|
|
|
919 @findex w3-complete-link
|
|
|
920 @item m
|
|
|
921 Choose a link from the current buffer and follow it. A completing-read
|
|
|
922 is done on all the links, so @kbd{space} and @kbd{TAB} can be used for
|
|
|
923 completion.
|
|
|
924 @kindex f
|
|
|
925 @kindex TAB
|
|
|
926 @kindex n
|
|
|
927 @findex w3-forward-link
|
|
|
928 @item TAB, f, n
|
|
|
929 Attempts to move forward one link area in the current document. Signals
|
|
|
930 an error if no more links are found.
|
|
|
931 @end table
|
|
|
932 @node Information, Action, Movement, Basic Usage
|
|
|
933 @section Information
|
|
|
934 These functions relate information about one or more links on the
|
|
|
935 current document.
|
|
|
936 @table @kbd
|
|
|
937 @kindex v
|
|
|
938 @findex url-view-url
|
|
|
939 @item v
|
|
|
940 This shows the URL of the current document in the minibuffer.
|
|
|
941 @kindex V
|
|
|
942 @findex w3-view-this-url
|
|
|
943 @item V
|
|
|
944 This shows the URL of the hypertext link under point in the minibuffer.
|
|
|
945 If there is not a hypertext link under point, then it shows the type of
|
|
|
946 form entry area under point. If there is no form entry area under
|
|
|
947 point, then it shows the inlined image's URL that is under point, if
|
|
|
948 any.
|
|
|
949 @kindex i
|
|
|
950 @findex w3-document-information
|
|
|
951 @item i
|
|
|
952 Shows miscellaneous information about the currently displayed document.
|
|
|
953 This includes the URL, the last modified date, MIME headers, the HTTP
|
|
|
954 response code, and any relationships to other documents. Any security
|
|
|
955 information is also displayed.
|
|
|
956 @kindex I
|
|
|
957 @findex w3-document-information-this-url
|
|
|
958 @item I
|
|
|
959 Shows information about the URL at point.
|
|
|
960 @kindex s
|
|
|
961 @findex w3-source-document
|
|
|
962 @item s
|
|
|
963 This shows the HTML source of the current document in a separate buffer.
|
|
|
964 The buffer's name is based on the document's URL.
|
|
|
965 @kindex S
|
|
|
966 @findex w3-source-document-at-point
|
|
|
967 @item S
|
|
|
968 Shows the HTML source of the hypertext link under point in a separate
|
|
|
969 buffer. The buffer's name is based on the document's URL.
|
|
|
970 @kindex k
|
|
|
971 @findex w3-save-url
|
|
|
972 @item k
|
|
|
973 This stores the current document's URL in the kill ring, and also in the
|
|
|
974 current window-system's clipboard, if possible.
|
|
|
975 @kindex K
|
|
|
976 @findex w3-save-this-url
|
|
|
977 @item K
|
|
|
978 Stores the URL of the document under point in the kill ring, and also in
|
|
|
979 the current window-system's clipboard, if possible.
|
|
|
980 @end table
|
|
|
981 @node Action, Miscellaneous, Information, Basic Usage
|
|
|
982 @section Action
|
|
|
983 First, here are the keys and functions that bring up a new hypertext
|
|
|
984 page, usually creating a new buffer.
|
|
|
985 @table @kbd
|
|
|
986 @kindex return
|
|
|
987 @findex w3-follow-link
|
|
|
988 @item return
|
|
|
989 Pressing return when over a hyperlink attempts to follow the link
|
|
|
990 under the cursor. With a prefix argument (@kbd{C-u}), this forces the
|
|
|
991 file to be saved to disk instead of being passed off to other viewers
|
|
|
992 or being parsed as HTML.
|
|
|
993
|
|
|
994 Pressing return when over a form input field will prompt in the
|
|
|
995 minibuffer for the data to insert into the input field. Type checking
|
|
|
996 is done, and the data is only entered into the form when data of the
|
|
|
997 correct type is entered (ie: cannot enter 44 for 'date' field, etc).
|
|
|
998
|
|
|
999 @kindex Middle Mouse Button
|
|
|
1000 @findex w3-follow-mouse
|
|
|
1001 @item Middle Mouse Button
|
|
|
1002 Attempt to follow a hypertext link under the mouse cursor. Clicking on
|
|
|
1003 a form input field will prompt in the minibuffer for the data to insert
|
|
|
1004 into the input field. Type checking is done, and the data is only
|
|
|
1005 entered into the form when data of the correct type is entered (ie:
|
|
|
1006 cannot enter 44 for 'date' field, etc).
|
|
|
1007
|
|
|
1008 @kindex Control Middle Mouse Button
|
|
|
1009 @kindex Meta return
|
|
|
1010 @findex w3-follow-inlined-image
|
|
|
1011 @item Control Middle Mouse Button, Meta return
|
|
|
1012 Tries to retrieve the inlined image that is under point. It ignores any
|
|
|
1013 form entry areas or hyperlinks, and blindly follows any inlined image.
|
|
|
1014 Useful for seeing images that are meant to be used as hyperlinks when
|
|
|
1015 not on a terminal capable of displaying graphics.
|
|
|
1016
|
|
|
1017 @kindex p
|
|
|
1018 @findex w3-print-this-url
|
|
|
1019 @item p
|
|
|
1020 Prints out the current buffer in a variety of formats, including
|
|
|
1021 PostScript, HTML source, or formatted text.
|
|
|
1022 @kindex P
|
|
|
1023 @findex w3-print-url-under-point
|
|
|
1024 @item P
|
|
|
1025 Prints out the URL under point in a variety of formats, including
|
|
|
1026 PostScript, HTML source, or formatted text.
|
|
|
1027 @kindex m
|
|
|
1028 @findex w3-complete-link
|
|
|
1029 @item m
|
|
|
1030 Selects a destination from a list of all the hyperlinks in the current
|
|
|
1031 buffer. Use @kbd{space} and @kbd{tab} to complete on the links.
|
|
|
1032
|
|
|
1033 @kindex r
|
|
|
1034 @kindex g
|
|
|
1035 @findex w3-reload-document
|
|
|
1036 @item r, g
|
|
|
1037 Reloads the current document. The position within the buffer remains
|
|
|
1038 the same (unless the document has changed since it was last retrieved,
|
|
|
1039 in which case it should be relatively close). This causes an
|
|
|
1040 unconditional reload from the remote server - the locally cached copy is
|
|
|
1041 not consulted.
|
|
|
1042 @kindex C-o
|
|
|
1043 @findex w3-fetch
|
|
|
1044 @item C-o
|
|
|
1045 Prompts for a URL in the minibuffer, and attempts to fetch
|
|
|
1046 it. If there are any errors, or Emacs-W3 cannot understand the type of link
|
|
|
1047 requested, the errors are displayed in a hypertext buffer.
|
|
|
1048 @kindex o
|
|
|
1049 @findex w3-open-local
|
|
|
1050 @vindex url-use-hypertext-dired
|
|
|
1051 @item o
|
|
|
1052 Opens a local file, interactively. This prompts for a local file name
|
|
|
1053 to open. The file must exist, and may be a directory. If the requested
|
|
|
1054 file is a directory and @code{url-use-hypertext-dired} is @code{nil},
|
|
|
1055 then a dired-mode buffer is displayed. If non@code{nil}, then Emacs-W3
|
|
|
1056 automatically generates a hypertext listing of the directory. The
|
|
|
1057 hypertext mode is the default, so that all the keys and functions remain
|
|
|
1058 the same.
|
|
|
1059
|
|
|
1060 @kindex M-s
|
|
|
1061 @findex w3-search
|
|
|
1062 @item M-s
|
|
|
1063 Perform a search, if this is a searchable index. Searching requires a
|
|
|
1064 server - Emacs-W3 can not do local file searching, as there are too many
|
|
|
1065 possible types of searches people could want to do. Generally, the only
|
|
|
1066 URL types that allow searching are HTTP, gopher, and X-EXEC.
|
|
|
1067 @kindex Hv
|
|
|
1068 @findex w3-show-history-list
|
|
|
1069 @vindex w3-keep-history
|
|
|
1070 @item Hv
|
|
|
1071 If @code{url-keep-history} is non-@code{nil}, then Emacs-W3 keeps track
|
|
|
1072 of all the URLs visited in an Emacs session. This function takes all
|
|
|
1073 the links that are in that internal list, and formats them as hypertext
|
|
|
1074 links in a list.
|
|
|
1075 @end table
|
|
|
1076
|
|
|
1077 @cindex Buffer movement
|
|
|
1078 And here are the commands to move around between Emacs-W3 buffers:
|
|
|
1079
|
|
|
1080 @table @kbd
|
|
|
1081 @kindex l
|
|
|
1082 @findex w3-goto-last-buffer
|
|
|
1083 @item l
|
|
|
1084 Goes to the last WWW buffer seen.
|
|
|
1085 @kindex q
|
|
|
1086 @findex w3-quit
|
|
|
1087 @item q
|
|
|
1088 Quits WWW mode. This kills the current buffer and goes to the most
|
|
|
1089 recently visited buffer.
|
|
|
1090 @kindex Q
|
|
|
1091 @findex w3-leave-buffer
|
|
|
1092 @item u
|
|
|
1093 This is similar to w3-quit, but the buffer is not killed, it is moved to
|
|
|
1094 the bottom of the buffer list (so it is the least likely to show up as
|
|
|
1095 the default with switch-to-buffer). This is different from
|
|
|
1096 @code{w3-goto-last-buffer} in that it does not return to the last WWW
|
|
|
1097 page visited - it is the same as using @code{switch-to-buffer} - the
|
|
|
1098 buffer left in the window is fairly random.
|
|
|
1099 @kindex HB
|
|
|
1100 @kindex B
|
|
|
1101 @findex w3-backward-in-history
|
|
|
1102 @item HB, B
|
|
|
1103 Takes one step back along the path in the current history. Has no
|
|
|
1104 effect if at the beginning of the session history.
|
|
|
1105 @kindex HF
|
|
|
1106 @kindex F
|
|
|
1107 @findex w3-forward-in-history
|
|
|
1108 @item HF, F
|
|
|
1109 Takes one step forward along the path in the current history. Has no
|
|
|
1110 effect if at the end of the session history.
|
|
|
1111 @end table
|
|
|
1112
|
|
|
1113 @node Miscellaneous, , Action, Basic Usage
|
|
|
1114 @section Miscellaneous
|
|
|
1115 @table @kbd
|
|
|
1116 @kindex M-m
|
|
|
1117 @findex w3-mail-current-document
|
|
|
1118 @item M-m
|
|
|
1119 Mails the current document to someone. Choose from several different
|
|
|
1120 formats to mail: formatted text, HTML source, PostScript, or LaTeX source.
|
|
|
1121 When the HTML source is mailed, then an appropriate <base> tag is inserted
|
|
|
1122 at the beginning of the document so that relative links may be followed
|
|
|
1123 correctly by whoever receives the mail.
|
|
|
1124 @kindex M-M
|
|
|
1125 @findex w3-mail-document-under-point
|
|
|
1126 @item M-M
|
|
|
1127 Mails the document pointed to by the hypertext link under point to someone.
|
|
|
1128 Choose from several different formats to mail: formatted text, HTML source,
|
|
|
1129 PostScript, or LaTeX source. When the HTML source is mailed, then an
|
|
|
1130 appropriate <base> tag is inserted at the beginning of the document so that
|
|
|
1131 relative links may be followed correctly by whoever receives the
|
|
|
1132 mail.
|
|
|
1133 @kindex p
|
|
|
1134 @findex w3-print-this-url
|
|
|
1135 @item p
|
|
|
1136 Prints the current document. Choose from several different formats to
|
|
|
1137 print: formatted text, HTML source, PostScript (with ps-print), or by using
|
|
|
1138 LaTeX and dvips).
|
|
|
1139
|
|
|
1140 @findex lpr-buffer
|
|
|
1141 @vindex lpr-command
|
|
|
1142 @vindex lpr-switches
|
|
|
1143 When the formatted text is printed, the normal @code{lpr-buffer} function
|
|
|
1144 is called, and the variables @code{lpr-command} and @code{lpr-switches}
|
|
|
1145 control how the document is printed.
|
|
|
1146
|
|
|
1147 When the HTML source is printed, then an appropriate <base> tag is
|
|
|
1148 inserted at the beginning of the document.
|
|
|
1149 @vindex w3-use-html2latex
|
|
|
1150 @vindex w3-html2latex-prog
|
|
|
1151 @vindex w3-html2latex-args
|
|
|
1152 @vindex w3-print-commnad
|
|
|
1153 @vindex w3-latex-docstyle
|
|
|
1154 When postscript is printed, then the HTML source of the document is
|
|
|
1155 converted into LaTeX source. If the variable @code{w3-use-html2latex}
|
|
|
1156 is non-@code{nil}, then the program specified by
|
|
|
1157 @code{w3-html2latex-prog} is run in a subprocess with the arguments in
|
|
|
1158 @code{w3-html2latex-args}. The @code{w3-html2latex-prog} must accept
|
|
|
1159 HTML source on its standard input and send the LaTeX output to standard
|
|
|
1160 output. If @code{w3-use-html2latex} is @code{nil}, then an Emacs Lisp
|
|
|
1161 function uses regular expressions to replace the HTML code with LaTeX
|
|
|
1162 markup. The variable @code{w3-latex-docstyle} controls how the document
|
|
|
1163 is laid out in this case, and postscript figures are printed as
|
|
|
1164 well.
|
|
|
1165 @kindex P
|
|
|
1166 @findex w3-print-url-under-point
|
|
|
1167 @item P
|
|
|
1168 Prints the document pointed to by the hypertext link under point.
|
|
|
1169 Please see the previous item for more information.
|
|
|
1170 @kindex M-x w3-insert-formatted-url
|
|
|
1171 @findex w3-insert-formatted-url
|
|
|
1172 @item M-x w3-insert-formatted-url
|
|
|
1173 Insert a fully formatted HTML link into another buffer. This gets the
|
|
|
1174 name and URL of either the current buffer, or, with a prefix arg, of the
|
|
|
1175 link under point, and construct the appropriate <a...>...</a> markup and
|
|
|
1176 insert it into the desired buffer.
|
|
|
1177 @kindex M-tab
|
|
|
1178 @findex w3-insert-this-url
|
|
|
1179 @item M-tab
|
|
|
1180 Inserts the URL of the current document into another buffer. Buffer is
|
|
|
1181 prompted for in the minibuffer. With prefix arg, uses the URL of the
|
|
|
1182 link under point.
|
|
|
1183 @kindex U
|
|
|
1184 @findex w3-use-links
|
|
|
1185 @item U
|
|
|
1186 Selects one of the <LINK> tags from this document and fetch it. Links
|
|
|
1187 are attributes of a specific document, and can tell such things as who
|
|
|
1188 made the document, where a table of contents is located, etc.
|
|
|
1189
|
|
|
1190 Link tags specify relationships between documents in two ways. Normal
|
|
|
1191 (forward) relationships (where the link has a REL="xxx" attribute), and
|
|
|
1192 reverse relationships (where the link has a REV="xxx" attribute). This
|
|
|
1193 first asks what type of link to follow (Normal or Reverse), then does
|
|
|
1194 a @code{completing-read} on only the links that have that type of
|
|
|
1195 relationship.
|
|
|
1196 @end table
|
|
|
1197
|
|
|
1198 @node Compatibility, , , Top
|
|
|
1199 @comment node-name, next, previous, up
|
|
|
1200 @chapter Compatibility with other Browsers
|
|
|
1201 Due to the popularity of several other browsers, Emacs-W3 offers an easy
|
|
|
1202 transition to its much better way of life. This ranges from being able
|
|
|
1203 to share the same preferences files and disk cache to actually emulating
|
|
|
1204 the keybindings used in other browsers.
|
|
|
1205
|
|
|
1206 @ifinfo
|
|
|
1207 @menu
|
|
|
1208 * Emulation:: Emacs-W3 can emulate the keybindings and
|
|
|
1209 other behaviours of other browsers.
|
|
|
1210 * Hotlist Handling:: A hotlist is an easy way to keep track of
|
|
|
1211 interesting Web pages without having to
|
|
|
1212 remember the exact path to get there.
|
|
|
1213 * Session History:: Keeping a history of documents visited
|
|
|
1214 in one Emacs sessions allows the use of
|
|
|
1215 'forward' and 'back' buttons easily.
|
|
|
1216 * Global History:: Keeping a history of all the places ever
|
|
|
1217 visited on the web.
|
|
|
1218 * Annotations:: Annotations allow comments on other
|
|
|
1219 people's Web documents without needing
|
|
|
1220 to change the document.
|
|
|
1221 @end menu
|
|
|
1222 @end ifinfo
|
|
|
1223 @node Emulation, Hotlist Handling, Compatibility, Compatibility
|
|
|
1224 @section Emulation
|
|
|
1225 :: WORK :: Document lynx emulation
|
|
|
1226 :: WORK :: Document netscape emulation
|
|
|
1227 @cindex Browser emulation
|
|
|
1228 @cindex Emulation of other browsers
|
|
|
1229 @cindex Netscape emulation
|
|
|
1230 @cindex Lynx emulation
|
|
|
1231 @findex turn-on-netscape-emulation
|
|
|
1232 @findex turn-on-lynx-emulation
|
|
|
1233 @findex w3-netscape-emulation-minor-mode
|
|
|
1234 @findex w3-lynx-emulation-minor-mode
|
|
|
1235 @vindex w3-mode-hook
|
|
|
1236
|
|
|
1237 @node Hotlist Handling, Session History, Emulation, Compatibility
|
|
|
1238 @section Hotlist Handling
|
|
|
1239 :: WORK :: Document that it supports different types of hotlist formats
|
|
|
1240 :: WORK :: Make sure everything hotlist related can be accessed via 'h'
|
|
|
1241 In order to avoid having to traverse many documents to get to the same
|
|
|
1242 document over and over, Emacs-W3 supports a ``hotlist'' like Mosaic. This is
|
|
|
1243 a file that contains URLs and aliases. Hotlists allow quick access to any
|
|
|
1244 document in the Web, providing it has been visited and added to the hotlist.
|
|
|
1245 The variable @code{w3-hotlist-file} determines where this information
|
|
|
1246 is saved. The structure of the file is compatible with Mosaic's
|
|
|
1247 hotlist file, so this defaults to @file{~/.mosaic-hotlist-default}.
|
|
|
1248
|
|
|
1249 Hotlist commands are:
|
|
|
1250 @table @kbd
|
|
|
1251 @kindex hi
|
|
|
1252 @findex w3-hotlist-add-document
|
|
|
1253 @vindex w3-hotlist-file
|
|
|
1254 @item a
|
|
|
1255 Adds the current document to the hotlist, with the buffer name as its
|
|
|
1256 identifier. Modifies the file specified by @code{w3-hotlist-file}. If
|
|
|
1257 this is given a @var{prefix-argument} (via @kbd{C-u}), the title is
|
|
|
1258 prompted for instead of automatically defaulting to the
|
|
|
1259 document title.
|
|
|
1260
|
|
|
1261 @findex w3-hotlist-refresh
|
|
|
1262 @vindex w3-hotlist-file
|
|
|
1263 @kindex hR
|
|
|
1264 @item hR
|
|
|
1265 This rereads the default hostlist file specified by
|
|
|
1266 @code{w3-hotlist-file}.
|
|
|
1267 @findex w3-hotlist-delete
|
|
|
1268 @vindex w3-hotlist-file
|
|
|
1269 @kindex hd
|
|
|
1270 @item d
|
|
|
1271 Prompts for the alias of the entry to kill. Pressing the spacebar or
|
|
|
1272 tab will list out partial completions. The internal representation of
|
|
|
1273 the hotlist and the file specified by @code{w3-hotlist-file} are
|
|
|
1274 updated.
|
|
|
1275 @item hr
|
|
|
1276 @kindex hr
|
|
|
1277 @findex w3-hotlist-rename-entry
|
|
|
1278 @vindex w3-hotlist-file
|
|
|
1279 Some hotlist item names can be very unwieldy (`Mosaic for X level 2 fill
|
|
|
1280 out form support'), or uninformative (`Index of /'). Prompts for the
|
|
|
1281 item to rename in the minibuffer---use the spacebar or tab key for
|
|
|
1282 completion. After having chosen an item to rename, prompts for a new
|
|
|
1283 title until a unique title is entered. Modifies the file specified by
|
|
|
1284 @code{w3-hotlist-file}.
|
|
|
1285
|
|
|
1286 @item hu
|
|
|
1287 @kindex hu
|
|
|
1288 @findex w3-use-hotlist
|
|
|
1289 Prompts for the alias to jump to. Pressing the @key{spacebar} or
|
|
|
1290 @key{tab} key shows partial completions.
|
|
|
1291
|
|
|
1292 @item hv
|
|
|
1293 @kindex hv
|
|
|
1294 @findex w3-show-hotlist
|
|
|
1295 Converts the hotlist into HTML and displays it.
|
|
|
1296 @item ha
|
|
|
1297 @kindex ha
|
|
|
1298 @findex w3-hotlist-apropos
|
|
|
1299 Shows the hotlist entries matching a regular expression.
|
|
|
1300 @item hA
|
|
|
1301 @kindex hA
|
|
|
1302 @findex w3-hotlist-append
|
|
|
1303 Appends another hotlist file to the one currently in memory.
|
|
|
1304 @end table
|
|
|
1305 @node Session History, Global History, Hotlist Handling, Compatibility
|
|
|
1306 @section History
|
|
|
1307 @cindex History Lists
|
|
|
1308 Almost all web browsers keep track of the URLs followed from a page, so
|
|
|
1309 that it can provide @b{forward} and @b{back} buttons to keep a @i{path}
|
|
|
1310 of URLs that can be traversed easily.
|
|
|
1311 @vindex url-keep-history
|
|
|
1312 If the variable @code{url-keep-history} is @code{t}, then Emacs-W3
|
|
|
1313 keeps a list of all the URLs visited in a session.
|
|
|
1314 @findex w3-show-history
|
|
|
1315 To view a listing of the history for this session of Emacs-W3, use
|
|
|
1316 @code{M-x w3-show-history} from any buffer, and Emacs-W3 generates an
|
|
|
1317 HTML document showing every URL visited since Emacs started (or
|
|
|
1318 cleared the history list), and then format it. Any of the links can
|
|
|
1319 be chosen and followed to the original document. To clear the history
|
|
|
1320 list, choose 'Clear History' from the 'Options' menu.
|
|
|
1321
|
|
|
1322 @findex w3-forward-in-history
|
|
|
1323 @findex w3-backward-in-history
|
|
|
1324 @findex w3-fetch
|
|
|
1325 Another twist on the history list mechanism is the fact that all
|
|
|
1326 Emacs-W3 buffers remember what URL, buffer, and buffer position of the
|
|
|
1327 last document, and also keeps track of the next location jumped @b{to}
|
|
|
1328 from that buffer. This means that the user can go forwards and
|
|
|
1329 backwards very easily along the path taken to reach a particular
|
|
|
1330 document. To go forward, use the function @code{w3-forward-in-history},
|
|
|
1331 to go backward, use the function @code{w3-backward-in-history}.
|
|
|
1332
|
|
|
1333 @node Global History, Annotations, Session History, Compatibility
|
|
|
1334 @section Global History
|
|
|
1335 :: WORK :: Document that the global history can have diff. formats
|
|
|
1336 Most web browsers also support the idea of a ``history'' of URLs the
|
|
|
1337 user has visited, and it displays them in a different style than normal
|
|
|
1338 URLs.
|
|
|
1339
|
|
|
1340 @vindex url-keep-history
|
|
|
1341 @vindex url-global-history-file
|
|
|
1342 If the variable @code{url-keep-history} is @code{t}, then Emacs-W3
|
|
|
1343 keeps a list of all the URLs visited in a session. The file is
|
|
|
1344 automatically written to disk when exiting emacs. The list is added to
|
|
|
1345 those already in the file specified by @code{url-global-history-file},
|
|
|
1346 which defaults to @file{~/.mosaic-global-history}.
|
|
|
1347
|
|
|
1348 If any URL in the list is found in the file, it is not saved, but new
|
|
|
1349 ones are added at the end of the file.
|
|
|
1350
|
|
|
1351 The function that saves the global history list is smart enough to
|
|
|
1352 notice what style of history list is being used (Netscape, Emacs-W3, or
|
|
|
1353 XMosaic), and writes out the new additions appropriately.
|
|
|
1354
|
|
|
1355 @cindex Completion of URLs
|
|
|
1356 @cindex Usefulness of global history
|
|
|
1357 One of the nice things about keeping a global history files is that Emacs-W3
|
|
|
1358 can use it as a completion table. When doing @kbd{M-x w3-fetch}, pressing
|
|
|
1359 the @kbd{tab} or @kbd{space} key will show all completions for a
|
|
|
1360 partial URL. This is very useful, especially for very long URLs that
|
|
|
1361 are not in a hotlist, or for seeing all the pages from a particular web
|
|
|
1362 site before choosing which to retrieve.
|
|
|
1363
|
|
|
1364 @node Annotations, Group Annotations, Global History, Compatibility
|
|
|
1365 @section Annotations
|
|
|
1366 @cindex Annotations
|
|
|
1367 Mosaic can @i{annotate} documents. Annotations are comments about the
|
|
|
1368 current document, and these annotations appear as a link to the comments
|
|
|
1369 at the end of the document. The original file is not changed.
|
|
|
1370
|
|
|
1371 @ifinfo
|
|
|
1372 @menu
|
|
|
1373 * Group Annotations:: Annotations accessible by everyone
|
|
|
1374 * Personal Annotations:: Private annotations only accessible
|
|
|
1375 to the user who created them
|
|
|
1376 @end menu
|
|
|
1377 @end ifinfo
|
|
|
1378 @node Group Annotations, Personal Annotations, Annotations, Annotations
|
|
|
1379 @subsection Group Annotations
|
|
|
1380 @cindex Group Annotations
|
|
|
1381 @b{@i{NOTE}}: The group annotation experiment has been terminated. It
|
|
|
1382 will be replaced with support on the server side for adding <LINK> tags
|
|
|
1383 to documents.
|
|
|
1384
|
|
|
1385 @node Personal Annotations, , Group Annotations, Annotations
|
|
|
1386 @subsection Personal Annotations
|
|
|
1387 @cindex Personal Annotations
|
|
|
1388 @vindex w3-personal-annotation-directory
|
|
|
1389 Emacs-W3 looks in the directory specified by
|
|
|
1390 @code{w3-personal-annotation-directory} (defaults to
|
|
|
1391 @file{~/.mosaic-personal-annotations}). Any personal annotations for a
|
|
|
1392 document are automatically appended when it is retrieved.
|
|
|
1393
|
|
|
1394 :: WORK :: Document the new 'a' prefix keymap
|
|
|
1395 :: WORK :: Tell where the annotations are stored
|
|
|
1396
|
|
|
1397 @findex w3-add-personal-annotation
|
|
|
1398 @vindex w3-annotation-mode
|
|
|
1399 To add a new personal annotation, type @kbd{M-x
|
|
|
1400 w3-add-personal-annotation}. This creates a new buffer, in the mode
|
|
|
1401 specified by @code{w3-annotation-mode}. This defaults to
|
|
|
1402 @code{html-mode}. If this variable is @code{nil}, or it points to an
|
|
|
1403 undefined function, then @code{default-major-mode} is consulted.
|
|
|
1404
|
|
|
1405 A minor mode redefines @kbd{C-c C-c} to complete the annotation and
|
|
|
1406 store it on the local disk.
|
|
|
1407
|
|
|
1408 @findex w3-delete-personal-annotation
|
|
|
1409 To delete a personal annotation, it must be the current page. Once
|
|
|
1410 reading the annotation, @kbd{M-x w3-delete-personal-annotation} will
|
|
|
1411 remove it. This deletes the file containing the annotation, and any
|
|
|
1412 references to it in the annotation log file.
|
|
|
1413
|
|
|
1414 Editing personal annotations is not yet supported.
|
|
|
1415
|
|
|
1416 @node Controlling Formatting, General Formatting, Top, Top
|
|
|
1417 @comment node-name, next, previous, up
|
|
|
1418 @chapter Controlling Formatting
|
|
|
1419 @cindex Customizing formatting
|
|
|
1420 @cindex Specifying Fonts
|
|
|
1421 @cindex Fonts
|
|
|
1422 @cindex Colors
|
|
|
1423 How Emacs-W3 formats a document is very customizable. How a document is
|
|
|
1424 displayed depends on whether the user is on a terminal
|
|
|
1425 capable of graphics and a few variables.
|
|
|
1426
|
|
|
1427 The following sections describe in more detail how to change the
|
|
|
1428 formatting of a document.
|
|
|
1429
|
|
|
1430 @ifinfo
|
|
|
1431 @menu
|
|
|
1432 * General Formatting:: Changing general things about a
|
|
|
1433 document.
|
|
|
1434 * Character based terminals:: Changing how a document is
|
|
|
1435 displayed on a non-graphics
|
|
|
1436 terminal (vt100, etc.@:) or if
|
|
|
1437 @code{w3-delimit-emphasis} is @code{t}.
|
|
|
1438 * Graphics workstations:: Changing how a document is
|
|
|
1439 displayed on a graphics terminal
|
|
|
1440 (Xwindows, Windows, NeXTstep,
|
|
|
1441 OS/2, etc.)
|
|
|
1442 * Inlined images:: How to specify how Emacs-W3
|
|
|
1443 handles inlined images/mpegs.
|
|
|
1444 @end menu
|
|
|
1445 @end ifinfo
|
|
|
1446 @node General Formatting, Character based terminals, Controlling Formatting, Controlling Formatting
|
|
|
1447 @section General formatting conventions
|
|
|
1448 @iftex
|
|
|
1449 @heading Setting the fill column
|
|
|
1450 @end iftex
|
|
|
1451 @ifinfo
|
|
|
1452 @center --------------------
|
|
|
1453 @center Setting the fill column
|
|
|
1454 @center --------------------
|
|
|
1455 @end ifinfo
|
|
|
1456 @vindex fill-column
|
|
|
1457 @vindex w3-right-border
|
|
|
1458 Each time a document is parsed, the @code{fill-column} is recalculated
|
|
|
1459 using @code{window-width} and @code{w3-right-border}.
|
|
|
1460 @code{w3-right-border} is an integer specifying how much room at the
|
|
|
1461 right edge of the screen to leave blank. The @code{fill-column} is set
|
|
|
1462 to @code{(- (window-width) @code{w3-right-border})}.
|
|
|
1463 @iftex
|
|
|
1464 @heading Formatting of hypertext links
|
|
|
1465 @end iftex
|
|
|
1466 @ifinfo
|
|
|
1467 @center --------------------
|
|
|
1468 @center Formatting of hypertext links
|
|
|
1469 @center --------------------
|
|
|
1470 @end ifinfo
|
|
|
1471 @vindex w3-delimit-links
|
|
|
1472 @vindex w3-link-start-delimiter
|
|
|
1473 @vindex w3-link-end-delimiter
|
|
|
1474 If the variable @code{w3-delimit-links} is non-@code{nil} (the default
|
|
|
1475 for text-terminals), then hypertext links are surrounded by text
|
|
|
1476 specified by the user. The variables @code{w3-link-start-delimiter} and
|
|
|
1477 @code{w3-link-end-delimiter} control what text is at the start and end
|
|
|
1478 of a hypertext link. These variables are cons-pairs of two
|
|
|
1479 strings.
|
|
|
1480
|
|
|
1481 If a link has never been visited before (it is not in the @i{global
|
|
|
1482 history}), then the @code{car} of these variables is inserted at the
|
|
|
1483 start and end of the link. If the link has been visited before, then
|
|
|
1484 the @code{cdr} is inserted. So, links look like:
|
|
|
1485
|
|
|
1486 @example
|
|
|
1487 [[This is a hypertext link]] that has never been visited.
|
|
|
1488 @{@{This one, however@}@} has been seen before at some point in time.
|
|
|
1489 @end example
|
|
|
1490
|
|
|
1491 @iftex
|
|
|
1492 @heading Formatting of lists
|
|
|
1493 @end iftex
|
|
|
1494 @ifinfo
|
|
|
1495 @center --------------------
|
|
|
1496 @center Formatting of lists
|
|
|
1497 @center --------------------
|
|
|
1498 @end ifinfo
|
|
|
1499 @cindex Indentation
|
|
|
1500 @vindex w3-indent-level
|
|
|
1501 There are several different ways to control the formatting of lists.
|
|
|
1502 The most obvious is how deeply they are indented relative to the rest of
|
|
|
1503 the paragraphs in the document. To control this, set the
|
|
|
1504 variable @code{w3-indent-level}. This is the number of spaces to
|
|
|
1505 indent lists and other items requiring special margins.
|
|
|
1506
|
|
|
1507 @vindex w3-list-chars-assoc
|
|
|
1508 Another thing that is easy to change about lists is the bullet character
|
|
|
1509 put at the front of each list item. This is controlled by the variable
|
|
|
1510 @code{w3-list-chars-assoc}, which is an assoc list. This is a list of
|
|
|
1511 lists, each sublist describing what to put at the start of each
|
|
|
1512 particular list type. The @code{car} of this list should be a symbol
|
|
|
1513 (@b{not} a string) representing the type of list (e.g., @samp{ul}).
|
|
|
1514 The rest of the list should consist of strings to insert at certain
|
|
|
1515 levels of lists. The @code{n}th element of this list is used when the
|
|
|
1516 list is nested @code{n + 1} levels. If the list is not long enough to
|
|
|
1517 define a string for a certain nesting level, then it defaults to either
|
|
|
1518 a '*' or a '.'.
|
|
|
1519 @iftex
|
|
|
1520 @heading Formatting of directory listings
|
|
|
1521 @end iftex
|
|
|
1522 @ifinfo
|
|
|
1523 @center --------------------
|
|
|
1524 @center Formatting of directory listings
|
|
|
1525 @center --------------------
|
|
|
1526 @end ifinfo
|
|
|
1527 @vindex url-use-hypertext-dired
|
|
|
1528 When Emacs-W3 encounters a link to a directory (whether by local file access
|
|
|
1529 or via FTP), it can either create an HTML document on the fly, or use
|
|
|
1530 @code{dired-mode} to peruse the listing. The variable
|
|
|
1531 @code{url-use-hypertext-dired} controls this behavior.
|
|
|
1532
|
|
|
1533 If the value is @code{t}, Emacs-W3 uses @code{directory-files} to list them
|
|
|
1534 out and transform the directory into a hypertext document, then pass it
|
|
|
1535 through the parser like any other document.
|
|
|
1536
|
|
|
1537 If the value is @code{nil}, just pass the directory off to dired using
|
|
|
1538 @code{find-file}. Using this option loses all the hypertext abilities
|
|
|
1539 of Emacs-W3, and the users is unable to load documents in the directory
|
|
|
1540 directly into Emacs-W3 by clicking with the mouse, etc.
|
|
|
1541
|
|
|
1542 @ignore
|
|
|
1543 @cindex Downloading multiple files
|
|
|
1544 @cindex FTP'ing multiple files
|
|
|
1545 @vindex url-forms-based-ftp
|
|
|
1546 A new option in the 2.2 series is @code{url-forms-based-ftp} - this is
|
|
|
1547 still in the experimental stages, but can be useful. If
|
|
|
1548 @code{url-forms-based-ftp} is @code{t}, then all automatically generated
|
|
|
1549 directory listings will have a form mixed in with the file listing.
|
|
|
1550 Each file will have a checkbox next to it, and a row of buttons at the
|
|
|
1551 bottom of the screen. Selecting one of the buttons at the bottom of the
|
|
|
1552 screen will take the designated action on all the marked files.
|
|
|
1553 Currently, only deleting and copying marked files is supported.
|
|
|
1554 @end ignore
|
|
|
1555 @iftex
|
|
|
1556 @heading Formatting of gopher directories
|
|
|
1557 @end iftex
|
|
|
1558 @ifinfo
|
|
|
1559 @center --------------------
|
|
|
1560 @center Formatting of gopher directories
|
|
|
1561 @center --------------------
|
|
|
1562 @end ifinfo
|
|
|
1563 @vindex w3-use-hypertext-gopher
|
|
|
1564 @cindex Gopher+
|
|
|
1565 @cindex ASK blocks
|
|
|
1566 There are two different ways of viewing gopher links. The built-in
|
|
|
1567 support that converts gopher directories into HTML, or the
|
|
|
1568 @file{gopher.el} package by Scott Snyder (@i{snyder@@fnald0.fnal.gov}).
|
|
|
1569 The variable that controls this is @code{w3-use-hypertext-gopher}. If
|
|
|
1570 set to @code{nil}, then @file{gopher.el} is used. Any other value
|
|
|
1571 causes Emacs-W3 to use its internal gopher support. If using
|
|
|
1572 @file{gopher.el}, all the hypertext capabilities of Emacs-W3 are lost.
|
|
|
1573 All the functionality of @file{gopher.el} is now available in the
|
|
|
1574 hypertext version, and the hypertext version supports Gopher+ and ASK
|
|
|
1575 blocks.
|
|
|
1576
|
|
|
1577 @vindex w3-gopher-labels
|
|
|
1578 The main way to control the display of gopher directories is by the
|
|
|
1579 variable @code{w3-gopher-labels}. This variable controls the text that
|
|
|
1580 is inserted at the front of each item. This is an assoc list of gopher
|
|
|
1581 types (as one character strings), and a string to insert just after the
|
|
|
1582 list item. All the normal gopher types are defined. Entries should be
|
|
|
1583 similar to: @samp{("0" . "(TXT)")}. I have tried to keep all the tags
|
|
|
1584 to three characters plus two parentheses.
|
|
|
1585 @iftex
|
|
|
1586 @heading Creating a horizontal rule
|
|
|
1587 @end iftex
|
|
|
1588 @ifinfo
|
|
|
1589 @center --------------------
|
|
|
1590 @center Creating a horizontal rule
|
|
|
1591 @center --------------------
|
|
|
1592 @end ifinfo
|
|
|
1593 @vindex w3-horizontal-rule-char
|
|
|
1594 Horizontal rules (@b{<HR>} tags in HTML[+]) are used to separate chunks
|
|
|
1595 of a document, and is meant to be rendered as a solid line across the
|
|
|
1596 page. Some terminals display characters differently, so the variable
|
|
|
1597 @code{w3-horizontal-rule-char} controls which character is used to draw a
|
|
|
1598 horizontal bar. This variable must be the ASCII value of the character,
|
|
|
1599 @b{not a string}. The variable is passed through make-string whenever a
|
|
|
1600 horizontal rule of a certain width is necessary.
|
|
|
1601
|
|
|
1602 @node Character based terminals, Graphics workstations, General Formatting, Controlling Formatting
|
|
|
1603 @section On character based terminals
|
|
|
1604 @vindex w3-delimit-emphasis
|
|
|
1605 On character based terminals, there is no easy way to show that a
|
|
|
1606 certain range of text is in bold or italics. If the variable
|
|
|
1607 @code{w3-delimit-emphasis} is non-@code{nil}, then Emacs-W3 can insert
|
|
|
1608 characters before and after character formatting commands in HTML
|
|
|
1609 documents. The defaul value of @code{w3-delimit-emphasis} is
|
|
|
1610 automatically set based on the type of window system and version of
|
|
|
1611 Emacs being used.
|
|
|
1612
|
|
|
1613 @vindex w3-header-chars-assoc
|
|
|
1614 :: WORK ::
|
|
|
1615
|
|
|
1616 @findex w3-upcase-region
|
|
|
1617 @code{w3-header-chars-assoc} is an assoc list of header tags and a list
|
|
|
1618 of formatting instructions. The @code{car} of the list is the level of
|
|
|
1619 the header (1--6). The rest of the list should contain three items.
|
|
|
1620 The first item is text to insert before the header. The second item is
|
|
|
1621 text to insert after the header. Both should have reserved characters
|
|
|
1622 converted to their HTML[+] entity definitions. The third item is a
|
|
|
1623 function to call on the area the header is in. This function is called
|
|
|
1624 with arguments specifying the start and ending character positions of
|
|
|
1625 the header. The starting point is always first. To convert a region to
|
|
|
1626 upper case, please use @code{w3-upcase-region} instead of
|
|
|
1627 @code{upcase-region}, so that entities are converted properly.
|
|
|
1628
|
|
|
1629 @node Graphics workstations, Inlined images, Character based terminals, Controlling Formatting
|
|
|
1630 @section With graphics workstations
|
|
|
1631 Starting with the first public release of version 2.3.0, all formatting
|
|
|
1632 is controlled by the use of stylesheets.
|
|
|
1633
|
|
|
1634 :: WORK :: Graphic workstation stuff - redo for stylesheets
|
|
|
1635
|
|
|
1636 @node Inlined images, , Graphics workstations, Controlling Formatting
|
|
|
1637 @cindex Inlined images
|
|
|
1638 @cindex Images
|
|
|
1639 @cindex Movies
|
|
|
1640 @cindex Inlined MPEGs
|
|
|
1641 @cindex MPEGs
|
|
|
1642 When running in Lucid Emacs 19.10 or XEmacs 19.11 and higher, Emacs-W3 can
|
|
|
1643 display inlined images and MPEG movies. There are several variables that
|
|
|
1644 control how and when the images are displayed.
|
|
|
1645
|
|
|
1646 @cindex Netpbm
|
|
|
1647 @cindex Pbmplus
|
|
|
1648 @vindex w3-graphic-converter-alist
|
|
|
1649 Since Lucid/XEmacs only natively understands XPixmaps and XBitmaps, GIFs
|
|
|
1650 and other image types must first be converted to one of these formats.
|
|
|
1651 To do this, the @b{netpbm utilities}@footnote{Available via anonymous
|
|
|
1652 ftp from ftp.x.org:/R5contrib/netpbm-1mar1994.tar.gz, and most large ftp
|
|
|
1653 sites.} programs are normally used. This is a suite of freeware image
|
|
|
1654 conversion tools. The variable @code{w3-graphic-converter-alist}
|
|
|
1655 controls how each image type is converted. This is an assoc list, keyed
|
|
|
1656 on the MIME content-type. The @code{car} is the content-type, and the
|
|
|
1657 @code{cdr} is a string suitable to pass to @code{format}. A %s in this
|
|
|
1658 string will be replaced with a converter from the ppm image format to an
|
|
|
1659 XPixmap (or XBitmap, if being run on a monochrome display). By default,
|
|
|
1660 the Emacs-W3 browser has converters for:
|
|
|
1661
|
|
|
1662 @enumerate
|
|
|
1663 @item
|
|
|
1664 image/x-xbitmap
|
|
|
1665 @item
|
|
|
1666 image/xbitmap
|
|
|
1667 @item
|
|
|
1668 image/xbm
|
|
|
1669 @item
|
|
|
1670 image/gif
|
|
|
1671 @item
|
|
|
1672 image/jpeg
|
|
|
1673 @item
|
|
|
1674 image/x-fax
|
|
|
1675 @item
|
|
|
1676 image/x-raster
|
|
|
1677 @item
|
|
|
1678 image/windowdump
|
|
|
1679 @item
|
|
|
1680 image/x-icon
|
|
|
1681 @item
|
|
|
1682 image/portable-graymap
|
|
|
1683 @item
|
|
|
1684 image/portable-pixmap
|
|
|
1685 @item
|
|
|
1686 image/x-pixmap
|
|
|
1687 @item
|
|
|
1688 image/x-xpixmap
|
|
|
1689 @item
|
|
|
1690 image/pict
|
|
|
1691 @item
|
|
|
1692 image/x-macpaint
|
|
|
1693 @item
|
|
|
1694 image/x-targa
|
|
|
1695 @item
|
|
|
1696 image/tiff
|
|
|
1697 @end enumerate
|
|
|
1698
|
|
|
1699 @vindex w3-color-max-blue
|
|
|
1700 @vindex w3-color-max-green
|
|
|
1701 @vindex w3-color-max-red
|
|
|
1702 @vindex w3-color-use-reducing
|
|
|
1703 @vindex w3-color-filter
|
|
|
1704 Since most displays are (sadly) not 24-bit, Emacs-W3 can automatically
|
|
|
1705 dither an image, so that it does not fill up the application' colormap too
|
|
|
1706 quickly. If @code{w3-color-use-reducing} is non-@code{nil}, then the
|
|
|
1707 images will use reduced colors. If @code{w3-color-filter} is @code{eq} to
|
|
|
1708 @code{'ppmquant}, then the ppmquant program will be used. If @code{eq} to
|
|
|
1709 @code{'ppmdither}, then the ppmdither program will be used. The ppmdither
|
|
|
1710 program tends to give better results. The values of
|
|
|
1711 @code{w3-color-max-red}, @code{w3-color-max-blue}, and
|
|
|
1712 @code{w3-color-max-green} control how many colors the inlined images can
|
|
|
1713 use. If using ppmquant, then the product of these three variables is used
|
|
|
1714 as the maximum number of colors per image. If using ppmdither, then only
|
|
|
1715 the set number of color cells can be allocated per image. See the man
|
|
|
1716 pages for ppmdither and ppmquant for more information on how the dithering
|
|
|
1717 is actually done. @code{w3-color-filter} may also be a string, specifying
|
|
|
1718 exactly what external filter to use. An example is: @samp{ppmquant -fs
|
|
|
1719 -map ~/pixmaps/colormap.ppm}.
|
|
|
1720
|
|
|
1721 @cindex MPEGs
|
|
|
1722 @cindex Inlined animations
|
|
|
1723 When running in XEmacs 19.11 or XEmacs 19.12, Emacs-W3 can insert an
|
|
|
1724 MPEG movie in the middle of a buffer.
|
|
|
1725
|
|
|
1726 :: WORK :: Need a pointer to the new EMBED Internet Draft ::
|
|
|
1727
|
|
|
1728 The basic syntax is:
|
|
|
1729 @example
|
|
|
1730 <embed href="somevideo.mpg" type="video/mpeg">
|
|
|
1731 @end example
|
|
|
1732
|
|
|
1733 @vindex w3-mpeg-args
|
|
|
1734 @vindex w3-mpeg-program
|
|
|
1735 This requires a special version of the standard @file{mpeg_play} mpeg
|
|
|
1736 player. Patches against the 2.0 version are available at
|
|
|
1737 ftp://ftp.cs.indiana.edu/pub/elisp/w3/mpeg_patch. The variable
|
|
|
1738 @code{w3-mpeg-program} should point to this executable, and
|
|
|
1739 @code{w3-mpeg-args} should be a list of any additional arguments to be
|
|
|
1740 passed to the player. By default, this includes @var{-loop}, so the
|
|
|
1741 mpeg plays continuously.
|
|
|
1742
|
|
|
1743 @cindex Delaying inlined images
|
|
|
1744 @cindex Delaying inlined animations
|
|
|
1745 @vindex w3-delay-image-loads
|
|
|
1746 @vindex w3-delay-mpeg-loads
|
|
|
1747 Because images and movies can take up an incredible amount of bandwidth,
|
|
|
1748 it is useful to be able to control whether they are loaded or not. By
|
|
|
1749 default, images and movies are loaded automatically, but the variables
|
|
|
1750 @code{w3-delay-image-loads} and @code{w3-delay-mpeg-loads} control this.
|
|
|
1751 If set to non-@code{nil}, then the images or movies are not
|
|
|
1752 loaded until explicitly requested by the user.
|
|
|
1753
|
|
|
1754 @cindex Loading delayed images
|
|
|
1755 @cindex Loading delayed movies
|
|
|
1756 @findex w3-load-delayed-images
|
|
|
1757 @findex w3-load-delayed-mpegs
|
|
|
1758 To load any delayed images, use the function
|
|
|
1759 @code{w3-load-delayed-images}. Its counterpart for delayed movies is
|
|
|
1760 @code{w3-load-delayed-mpegs}
|
|
|
1761
|
|
|
1762 @node MIME Support, Adding MIME types based on file extensions, , Top
|
|
|
1763 @chapter MIME Support
|
|
|
1764 MIME is an emerging standard for multimedia mail. It offers a very
|
|
|
1765 flexible typing mechanism. The type of a file or message is specified
|
|
|
1766 in two parts, separated by a '/'. The first part is the general
|
|
|
1767 category of the data (text, application, image, etc.). The second part
|
|
|
1768 is the specific type of data (postscript, gif, jpeg, etc.). So
|
|
|
1769 @samp{text/html} specifies an HTML document, whereas
|
|
|
1770 @samp{image/x-xwindowdump} specifies an image of an Xwindow taken with
|
|
|
1771 the @file{xwd} program.
|
|
|
1772
|
|
|
1773
|
|
|
1774 This typing allows much more flexibility in naming files. HTTP/1.0
|
|
|
1775 servers can now send back content-type headers in response to a request,
|
|
|
1776 and not have the client second-guess it based on file extensions. HTML
|
|
|
1777 files can now be named @file{something.gif} (not a great idea, but
|
|
|
1778 possible).
|
|
|
1779
|
|
|
1780 @ifinfo
|
|
|
1781 @menu
|
|
|
1782 * Adding MIME types based on file extensions:: How to map file
|
|
|
1783 extensions onto MIME
|
|
|
1784 types (e.g., @samp{.gif ->
|
|
|
1785 image/gif)}.
|
|
|
1786 * Specifying Viewers:: How to specify external and internal viewers
|
|
|
1787 for files that Emacs-W3 cannot handle natively.
|
|
|
1788 @end menu
|
|
|
1789 @end ifinfo
|
|
|
1790
|
|
|
1791 @node Adding MIME types based on file extensions, Specifying Viewers, MIME Support, MIME Support
|
|
|
1792 @section Adding MIME types based on file extensions
|
|
|
1793 @vindex mm-mime-extensions
|
|
|
1794 For some protocols however, it is still necessary to guess the content
|
|
|
1795 of a file based on the file extension. This type of guess-work should
|
|
|
1796 only be needed when accessing files via FTP, local file access, or old
|
|
|
1797 HTTP/0.9 servers.
|
|
|
1798
|
|
|
1799 Instead of specifying how to view things twice, once based on
|
|
|
1800 content-type and once based on the file extension, it is easier to map
|
|
|
1801 file extensions to MIME content-types. The variable that controls this
|
|
|
1802 is @code{mm-mime-extensions}.
|
|
|
1803
|
|
|
1804 This variable is an assoc list of file extensions and the corresponding
|
|
|
1805 MIME content-type. A sample entry looks like: @samp{(".movie"
|
|
|
1806 . "video/x-sgi-movie")} This makes all files that end in @file{.movie}
|
|
|
1807 (@file{foo.movie} and @file{bar.movie}) be interpreted as SGI animation
|
|
|
1808 files. If a content-type is defined for the document, then this is
|
|
|
1809 over-ridden. Regular expressions can @b{NOT} be used.
|
|
|
1810
|
|
|
1811 @cindex mime-types file
|
|
|
1812 @findex mm-parse-mimetypes
|
|
|
1813 Both Mosaic and the NCSA HTTP daemon rely on a separate file for mapping
|
|
|
1814 file extensions to MIME types. Instead of having the users of Emacs-W3
|
|
|
1815 duplicate this in lisp, this file can be parsed using the
|
|
|
1816 @code{url-parse-mimetypes} function. This function is called each time
|
|
|
1817 w3 is loaded. It tries to locate mimetype files in several places. If
|
|
|
1818 the environment variable @code{MIMETYPES} is nonempty, then this is
|
|
|
1819 assumed to specify a UNIX-like path of mimetype files (this is a colon
|
|
|
1820 separated string of pathnames). If the @code{MIMETYPES} environment
|
|
|
1821 variable is empty, then Emacs-W3 looks for these files:
|
|
|
1822
|
|
|
1823 @enumerate
|
|
|
1824 @item
|
|
|
1825 @file{~/.mime-types}
|
|
|
1826 @item
|
|
|
1827 @file{/etc/mime-types}
|
|
|
1828 @item
|
|
|
1829 @file{/usr/etc/mime-types}
|
|
|
1830 @item
|
|
|
1831 @file{/usr/local/etc/mime-types}
|
|
|
1832 @item
|
|
|
1833 @file{/usr/local/www/conf/mime-types}
|
|
|
1834 @end enumerate
|
|
|
1835
|
|
|
1836 Each line contains information for one http type. These types resemble
|
|
|
1837 MIME types. To add new ones, use subtypes beginning with x-, such as
|
|
|
1838 application/x-myprogram. Lines beginning with # are comment lines, and
|
|
|
1839 suitably ignored. Each line consists of:
|
|
|
1840
|
|
|
1841 type/subtype ext1 ext2 ... ext@var{n}
|
|
|
1842
|
|
|
1843 type/subtype is the MIME-like type of the document. ext* is any number
|
|
|
1844 of space-separated filename extensions which correspond to the MIME
|
|
|
1845 type.
|
|
|
1846
|
|
|
1847 @node Specifying Viewers, ,Adding MIME types based on file extensions, MIME Support
|
|
|
1848 @section Specifying Viewers
|
|
|
1849 Not all files look as they should when parsed as an HTML document
|
|
|
1850 (whitespace is stripped, paragraphs are reformatted, and lots of little
|
|
|
1851 changes that make the document look unrecognizable). Files may be
|
|
|
1852 passed to external programs or Emacs Lisp functions to be viewed.
|
|
|
1853
|
|
|
1854 Not all files can be viewed accurately from within an Emacs session (GIF
|
|
|
1855 files for example, or audio files). For this reason, the user can
|
|
|
1856 specify file "viewers" based on MIME content-types. This is done with
|
|
|
1857 a standard mailcap file. @xref{Mailcap Files}
|
|
|
1858
|
|
|
1859 @findex mm-add-mailcap-entry
|
|
|
1860 As an alternative, the function @code{mm-add-mailcap-entry} can also be
|
|
|
1861 used from an appropriate hook.@xref{Hooks} This functions takes three
|
|
|
1862 arguments, the major type ("@i{image}"), the minor type ("@i{gif}"), and
|
|
|
1863 an assoc list of information about the viewer. Please see the URL
|
|
|
1864 documentation for more specific information on what this assoc list
|
|
|
1865 should look like.
|
|
|
1866
|
|
|
1867 @node Security, Non-Unix Operating Systems, , Top
|
|
|
1868 @chapter Security
|
|
|
1869 @cindex Security
|
|
|
1870 @cindex Paranoia
|
|
|
1871 There are an increasing number of ways to authenticate a user to a web
|
|
|
1872 service. Emacs-W3 tries to support as many as possible. Emacs-W3
|
|
|
1873 currently supports:
|
|
|
1874
|
|
|
1875 @table @b
|
|
|
1876 @item Basic Authentication
|
|
|
1877 @cindex Security, Basic
|
|
|
1878 @cindex HTTP/1.0 Authentication
|
|
|
1879 @cindex Authentication, Basic
|
|
|
1880 The weakest authentication available, not recommended if serious
|
|
|
1881 security is necessary. This is simply a string that looks like
|
|
|
1882 @samp{user:password} that has been Base64 encoded, as defined in RFC
|
|
|
1883 1421.
|
|
|
1884 @item Digest Authentication
|
|
|
1885 @cindex Security, Digest
|
|
|
1886 @cindex HTTP/1.0 Authentication
|
|
|
1887 @cindex Authentication, Digest
|
|
|
1888 Jeffery L. Hostetler, John Franks, Philip Hallam-Baker, Ari Luotonen,
|
|
|
1889 Eric W. Sink, and Lawrence C. Stewart have an internet draft for a new
|
|
|
1890 authentication mechanism. For the complete specification, please see
|
|
|
1891 draft-ietf-http-digest-aa-01.txt in the nearest internet drafts
|
|
|
1892 archive@footnote{One is ftp://ds.internic.net/internet-drafts}.
|
|
|
1893 @item SSL Encryption
|
|
|
1894 @cindex HTTP/1.0 Authentication
|
|
|
1895 @cindex Secure Sockets Layer
|
|
|
1896 @cindex SSL
|
|
|
1897 @cindex Gag Puke Retch
|
|
|
1898 @cindex Exportability
|
|
|
1899 @cindex Export Restrictions
|
|
|
1900 SSL is the @code{Secure Sockets Layer} interface developed by Netscape
|
|
|
1901 Communications @footnote{http://www.netscape.com/}. Emacs-W3 supports
|
|
|
1902 HTTP transfers over an SSL encrypted channel, if the appropriate files
|
|
|
1903 have been installed.@xref{Installing SSL}
|
|
|
1904 @item PGP/PEM
|
|
|
1905 @cindex HTTP/1.0 Authentication
|
|
|
1906 @cindex Public Key Cryptography
|
|
|
1907 @cindex Authentication, PGP
|
|
|
1908 @cindex Authentication, PEM
|
|
|
1909 @cindex RIPEM
|
|
|
1910 @cindex Public Key Cryptography
|
|
|
1911 @cindex PGP
|
|
|
1912 @cindex Pretty Good Privacy
|
|
|
1913 @cindex Encryption
|
|
|
1914 @cindex Security
|
|
|
1915 @cindex ITAR must die
|
|
|
1916 @cindex Stupid export restrictions
|
|
|
1917 @cindex Support your local crypto-anarchist
|
|
|
1918 @cindex NSA freaks
|
|
|
1919 A few servers still support this method of authentication, but it has
|
|
|
1920 been superseded by SSL and Secure-HTTP.@xref{Using PGP/PEM}
|
|
|
1921 @end table
|
|
|
1922
|
|
|
1923 @node Non-Unix Operating Systems, VMS, Security, Top
|
|
|
1924 @chapter Non-Unix Operating Systems
|
|
|
1925 @cindex Non-Unix Operating Systems
|
|
|
1926 @ifinfo
|
|
|
1927 @menu
|
|
|
1928 * VMS:: The wonderful world of VAX|AXP-VMS!
|
|
|
1929 * OS/2:: The next-best thing to Unix.
|
|
|
1930 * MS-DOS:: The wonderful world of MS-DOG!
|
|
|
1931 * 16-Bit Windows:: Windows 3.1, 3.11, and WFW 3.11.
|
|
|
1932 * 32-Bit Windows:: Windows NT, Chicago/Windows 95.
|
|
|
1933 * Amiga:: The Amiga, for those who still love them.
|
|
|
1934 @end menu
|
|
|
1935 @end ifinfo
|
|
|
1936
|
|
|
1937 @node VMS, OS/2, Non-Unix Operating Systems, Non-Unix Operating Systems
|
|
|
1938 @section VMS
|
|
|
1939 @cindex VAX-VMS
|
|
|
1940 @cindex AXP-VMS
|
|
|
1941 @cindex Digital VMS
|
|
|
1942 @cindex VMS
|
|
|
1943 :: WORK :: VMS Specific instriuctions
|
|
|
1944
|
|
|
1945 @node OS/2, MS-DOS, VMS, Non-Unix Operating Systems
|
|
|
1946 @section OS/2
|
|
|
1947 @cindex OS/2
|
|
|
1948 @cindex Warp
|
|
|
1949 :: WORK :: OS/2 Specific instructions
|
|
|
1950
|
|
|
1951 @node MS-DOS, 16-Bit Windows, OS/2, Non-Unix Operating Systems
|
|
|
1952 @section MS-DOS
|
|
|
1953 @cindex MS-DOS
|
|
|
1954 @cindex Microsloth
|
|
|
1955 @cindex DOS
|
|
|
1956 @cindex MS-DOG
|
|
|
1957 :: WORK :: DOS Specific instructions
|
|
|
1958
|
|
|
1959 @node 16-Bit Windows, 32-Bit Windows, MS-DOS, Non-Unix Operating Systems
|
|
|
1960 @section 16-Bit Windows
|
|
|
1961 @cindex 16-Bit Windows
|
|
|
1962 @cindex Microsloth
|
|
|
1963 @cindex Windows (16-Bit)
|
|
|
1964 @cindex Windows For Workgroups
|
|
|
1965 :: WORK :: 16bit Windows Specific instructions
|
|
|
1966
|
|
|
1967 @node 32-Bit Windows, Amiga, 16-Bit Windows, Non-Unix Operating Systems
|
|
|
1968 @section 32-Bit Windows
|
|
|
1969 @cindex Chicago
|
|
|
1970 @cindex Windows (32-Bit)
|
|
|
1971 @cindex 32-Bit Windows
|
|
|
1972 @cindex Microsloth
|
|
|
1973 @cindex Windows '95
|
|
|
1974 :: WORK :: 32bit Windows Specific instructions
|
|
|
1975
|
|
|
1976 @node Amiga, Advanced Features, 32-Bit Windows, Non-Unix Operating Systems
|
|
|
1977 @section Amiga
|
|
|
1978 @cindex Amiga
|
|
|
1979 @cindex Commodore
|
|
|
1980 :: WORK :: Amiga specific instructions
|
|
|
1981
|
|
|
1982 @node Advanced Features, Style Sheets, Amiga, Top
|
|
|
1983 @comment node-name, next, previous, up
|
|
|
1984 @chapter Advanced Features
|
|
|
1985
|
|
|
1986 @ifinfo
|
|
|
1987 @menu
|
|
|
1988 * Style Sheets:: Formatting control, the right way
|
|
|
1989 * Disk Caching:: Improving performance by using a local disk cache
|
|
|
1990 * Interfacing to Mail/News:: How to make VM understand hypertext links
|
|
|
1991 * Debugging HTML:: How to make Emacs-W3 display warnings about invalid
|
|
|
1992 HTML/HTML+ constructs.
|
|
|
1993 * Native WAIS Support:: How to make Emacs-W3 understand WAIS links without
|
|
|
1994 using a gateway.
|
|
|
1995 * Rating Links:: How to make Emacs-W3 put an 'interestingness' value
|
|
|
1996 next to each link.
|
|
|
1997 * Gopher Plus Support:: How Emacs-W3 makes use of the Gopher+ protocol.
|
|
|
1998 * Hooks:: Various hooks to use throughout Emacs-W3
|
|
|
1999 * Other Variables:: Miscellaneous variables that control the real
|
|
|
2000 guts of Emacs-W3.
|
|
|
2001 @end menu
|
|
|
2002 @end ifinfo
|
|
|
2003
|
|
|
2004 @node Style Sheets, Disk Caching, Advanced Features, Advanced Features
|
|
|
2005 @section Style Sheets
|
|
|
2006 @cindex Formatting control
|
|
|
2007 @cindex Style sheets
|
|
|
2008 @cindex Look and Feel
|
|
|
2009 @cindex Layout control
|
|
|
2010 @cindex Experimental style sheet mechanism
|
|
|
2011 Emacs-W3 currently supports the experimental style sheet mechanism
|
|
|
2012 proposed by H&kon W. Lie of the W3 Consortium. This allows for the
|
|
|
2013 author to specify what a document should look like, and yet allow the
|
|
|
2014 end user to override any of the stylistic changes. This allows for
|
|
|
2015 people with special needs (most notably the visually impaired) to
|
|
|
2016 override style bindings that could make a document totally
|
|
|
2017 unreadable.
|
|
|
2018
|
|
|
2019 @example
|
|
|
2020 <style notation="css">
|
|
|
2021 /* This is a comment
|
|
|
2022 ** These will be ignored, up to the terminating end-of-line
|
|
|
2023 #
|
|
|
2024 h1 @{ align: center,
|
|
|
2025 color: yellow,
|
|
|
2026 background: red,
|
|
|
2027 font-size: 24pt
|
|
|
2028 @}
|
|
|
2029 h2 @{ align: right,
|
|
|
2030 font-family: palatino,
|
|
|
2031 font-size: 18pt
|
|
|
2032 @}
|
|
|
2033 </style>
|
|
|
2034 @end example
|
|
|
2035
|
|
|
2036 :: WORK :: Much more information on stylesheets
|
|
|
2037
|
|
|
2038 @cindex <style>
|
|
|
2039 To include a stylesheet into a document, simply use the <style> tag.
|
|
|
2040 Use the @b{notation} attribute to specify what language the stylesheet
|
|
|
2041 is specified in. The default is @b{css}. The data between the <style>
|
|
|
2042 and </style> tags is the stylsheet proper - no HTML parsing is done to
|
|
|
2043 this data - it is treated similar to an <XMP> section of text. To
|
|
|
2044 reference an external stylesheet, use the <link> tag.
|
|
|
2045 @example
|
|
|
2046 <link rel="stylesheet" href="/bill.style">
|
|
|
2047 @end example
|
|
|
2048 If these two mechanisms are mixed, then the URL is resolved first, and
|
|
|
2049 the contents of the <style> tag take precedence if there are any
|
|
|
2050 conflicting directives.
|
|
|
2051
|
|
|
2052 @cindex DSSSL
|
|
|
2053 @cindex DSSSL-lite
|
|
|
2054 In the future, DSSSL and DSSSL-lite will be supported as valid
|
|
|
2055 stylesheet languages, but not in this release. For more information on
|
|
|
2056 DSSSL-lite see http://www.falch.no/~pepper/DSSSL-Lite/ - for more
|
|
|
2057 information on full DSSSL, see
|
|
|
2058 ftp://ftp.jclark.com/pub/dsssl/dsssl.ps.gz
|
|
|
2059
|
|
|
2060 @node Disk Caching, Interfacing to Mail/News, Style Sheets, Advanced Features
|
|
|
2061 @section Disk Caching
|
|
|
2062 @cindex Caching
|
|
|
2063 @cindex Persistent Cache
|
|
|
2064 @cindex Disk Cache
|
|
|
2065 A cache stores the information on a page on the local machine. When
|
|
|
2066 requesting a page that is in the cache, Emacs-W3 can retrieve the page
|
|
|
2067 from the cache more quickly than retrieving the page again from its
|
|
|
2068 location out on the network. With a well-populated cache, browsing the
|
|
|
2069 web is dramatically faster.
|
|
|
2070
|
|
|
2071 The first time a page is requested, Emacs-W3 retrieves the page from the
|
|
|
2072 network. When requesting a page that is in the cache, Emacs-W3 checks
|
|
|
2073 to see if the page has changed since it was last retrieved from the
|
|
|
2074 remote machine. If it has not changed, the local copy is used, saving
|
|
|
2075 the transmission of the file over the network.
|
|
|
2076
|
|
|
2077 @vindex url-automatic-caching
|
|
|
2078 @cindex Turning on caching
|
|
|
2079 @cindex Cleaning the cache
|
|
|
2080 @cindex Clearing the cache
|
|
|
2081 @cindex Cache cleaning
|
|
|
2082 @cindex Limiting the size of the cache
|
|
|
2083 To turn on disk caching, set the variable @code{url-automatic-caching}
|
|
|
2084 to non-@code{nil}, or choose the 'Caching' menu item (under `Options').
|
|
|
2085 That is all there is to it. Running the @code{clean-cache} shell script
|
|
|
2086 fist is recommended, to allow for future cleaning of the cache. This
|
|
|
2087 shell script will remove all files that have not been accessed since it
|
|
|
2088 was last run. To keep the cache pared down, it is recommended that this
|
|
|
2089 script be run from @i{at} or @i{cron} (see the manual pages for
|
|
|
2090 crontab(5) or at(1) for more information)
|
|
|
2091
|
|
|
2092
|
|
|
2093 @cindex Relying on cache
|
|
|
2094 @cindex Cache only mode
|
|
|
2095 @cindex Standalone mode
|
|
|
2096 @cindex Browsing with no network connection
|
|
|
2097 @cindex Netless browsing
|
|
|
2098 @vindex url-standalone-mode
|
|
|
2099 With a large cache of documents on the local disk, it can be very handy
|
|
|
2100 when traveling, or any other time the network connection is not active
|
|
|
2101 (a laptop with a dial-on-demand PPP connection, etc). Emacs-W3 can rely
|
|
|
2102 solely on its cache, and avoid checking to see if the page has changed
|
|
|
2103 on the remote server. In the case of a dial-on-demand PPP connection,
|
|
|
2104 this will keep the phone line free as long as possible, only bringing up
|
|
|
2105 the PPP connection when asking for a page that is not located in the
|
|
|
2106 cache. This is very useful for demonstrations as well. To turn this
|
|
|
2107 feature on, set the variable @code{url-standalone-mode} to
|
|
|
2108 non-@code{nil}, or choose the `Use Cache Only' menu item (under
|
|
|
2109 `Options')
|
|
|
2110
|
|
|
2111 @cindex Caching options
|
|
|
2112 @cindex Alternate caching method
|
|
|
2113 Emacs-W3 caches files under the temporary directory specified by
|
|
|
2114 @code{url-temporary-directory}, in a user-specific subdirectory
|
|
|
2115 (determined by the @code{user-real-login-name} function). The cache
|
|
|
2116 files are stored under their original names, so a URL like:
|
|
|
2117 http://www.spry.com/foo/bar/baz.html would be stored in a cache file
|
|
|
2118 named: /tmp/wmperry/com/spry/www/foo/bar/baz.html. Sometimes, espcially
|
|
|
2119 with gopher links, there will be name conflicts, and an error will be
|
|
|
2120 signalled. This cannot be avoided, and still have reasonable
|
|
|
2121 performance at startup time (reading in an index file of all the cached
|
|
|
2122 pages can take a long time on slow machines, or even fast machines with
|
|
|
2123 large caches). When running XEmacs 19.12 or later, a different naming
|
|
|
2124 scheme can be used. This avoids name conflicts, but loses the human
|
|
|
2125 readability of the cache file names. The cache files will look like:
|
|
|
2126 /tmp/wmperry/acbd18db4cc2f85cedef654fccc4a4d8, which is certainly
|
|
|
2127 unique, but not very user-friendly. To turn this on, add this to the
|
|
|
2128 @file{.emacs} file:
|
|
|
2129
|
|
|
2130
|
|
|
2131 @example
|
|
|
2132 (add-hook 'w3-load-hooks '(lambda ()
|
|
|
2133 (fset 'url-create-cached-filename
|
|
|
2134 'url-create-cached-filename-using-md5)))
|
|
|
2135 @end example
|
|
|
2136
|
|
|
2137 If other versions of emacs will not be sharing the cache, I highly
|
|
|
2138 recommend this method of creating the cache filename.
|
|
|
2139
|
|
|
2140
|
|
|
2141 @node Interfacing to Mail/News, Debugging HTML, Disk Caching, Advanced Features
|
|
|
2142 @section Interfacing to Mail/News
|
|
|
2143 @cindex Interfacing to Mail/News
|
|
|
2144 @cindex VM
|
|
|
2145 @cindex Using Emacs-W3 with VM
|
|
|
2146 @cindex GNUS
|
|
|
2147 @cindex Using Emacs-W3 with GNUS
|
|
|
2148 @cindex RMAIL
|
|
|
2149 @cindex Using Emacs-W3 with RMAIL
|
|
|
2150 More and more people are including URLs in their signatures, and within
|
|
|
2151 the body of mail messages. It can get quite tedious to type these into
|
|
|
2152 the minibuffer to follow one.
|
|
|
2153
|
|
|
2154 With the latest versions of VM (the 5.9x series of betas), URLs are
|
|
|
2155 highlighted, and can be followed with the mouse or the return
|
|
|
2156 key.
|
|
|
2157
|
|
|
2158 To access URLs from within RMAIL, the following hook should do the
|
|
|
2159 trick.
|
|
|
2160 @example
|
|
|
2161 (add-hook 'rmail-mode-hook
|
|
|
2162 (function
|
|
|
2163 (lambda ()
|
|
|
2164 (define-key rmail-mode-map [mouse-2] 'w3-maybe-follow-link-mouse)
|
|
|
2165 (define-key rmail-mode-map "\r" 'w3-maybe-follow-link))))
|
|
|
2166 @end example
|
|
|
2167
|
|
|
2168 To access URLs from within GNUS, the following hook should do the
|
|
|
2169 trick.
|
|
|
2170 @example
|
|
|
2171 (add-hook 'gnus-article-mode-hook
|
|
|
2172 (function
|
|
|
2173 (lambda ()
|
|
|
2174 (define-key gnus-article-mode-map [mouse-2]
|
|
|
2175 'w3-maybe-follow-link-mouse)
|
|
|
2176 (define-key gnus-article-mode-map "\r"
|
|
|
2177 'w3-maybe-follow-link))))
|
|
|
2178 @end example
|
|
|
2179
|
|
|
2180 @node Debugging HTML, Native WAIS Support, Interfacing to Mail/News, Advanced Features
|
|
|
2181 @section Debugging HTML
|
|
|
2182 @cindex Debugging
|
|
|
2183 @cindex Invalid HTML
|
|
|
2184 @cindex Bad HTML
|
|
|
2185 @vindex w3-debug-buffer
|
|
|
2186 @vindex w3-debug-html
|
|
|
2187 For those people that are adventurous, or are just as anal as I am about
|
|
|
2188 people writing valid HTML, set the variable @code{w3-debug-html} to
|
|
|
2189 @code{t} and see what happens.
|
|
|
2190
|
|
|
2191
|
|
|
2192 If a Emacs-W3 thinks it has encountered invalid HTML, then a debugging
|
|
|
2193 message is displayed.
|
|
|
2194
|
|
|
2195 :: WORK :: Need to list the different values w3-debug-html can have, and
|
|
|
2196 :: WORK :: what they do ::
|
|
|
2197
|
|
|
2198 @node Native WAIS Support, Rating Links, Debugging HTML, Advanced Features
|
|
|
2199 @section Native WAIS Support
|
|
|
2200 This version of Emacs-W3 supports native WAIS querying (earlier
|
|
|
2201 versions required the use of a gateway program). In order to use the
|
|
|
2202 native WAIS support, a working @dfn{waisq} binary is required. I
|
|
|
2203 recommend the distribution from think.com -
|
|
|
2204 ftp://think.com/wais/wais-8-b6.1.tar.Z is a good place to start.
|
|
|
2205
|
|
|
2206 @vindex url-waisq-prog
|
|
|
2207 @vindex url-wais-gateway-server
|
|
|
2208 @vindex url-wais-gateway-port
|
|
|
2209 The variable @code{url-waisq-prog} must point to this executable, and
|
|
|
2210 one of @code{url-wais-gateway-server} or @code{url-wais-gateway-port}
|
|
|
2211 should be @code{nil}.
|
|
|
2212
|
|
|
2213 When a WAIS URL is encountered, a form will be automatically generated
|
|
|
2214 and displayed. After typing in the search term, the query will be sent
|
|
|
2215 to the server by running the @code{url-waisq-prog} in a subprocess. The
|
|
|
2216 results will be converted into HTML and displayed.
|
|
|
2217
|
|
|
2218 @node Rating Links, Gopher Plus Support, Native WAIS Support, Advanced Features
|
|
|
2219 @section Rating Links
|
|
|
2220 The @code{w3-link-info-display-function} variable can be used to 'rate' a URL
|
|
|
2221 when it shows up in an HTML page. If non-@code{nil}, then this should
|
|
|
2222 be a list specifying (or a symbol specifying the name) of a function.
|
|
|
2223 This function should expect one argument, a fully specified URL, and
|
|
|
2224 should return a string. This string is inserted after the link
|
|
|
2225 text.
|
|
|
2226
|
|
|
2227 If a user has decided that all links served from blort.com are too laden
|
|
|
2228 with images, and wants to be warned that a link points at this host,
|
|
|
2229 they could do something like this:
|
|
|
2230
|
|
|
2231 @example
|
|
|
2232 (defun check-url (url)
|
|
|
2233 (if (string-match "://[^/]blort.com" url)
|
|
|
2234 "[SLOW!]" ""))
|
|
|
2235
|
|
|
2236 (setq w3-link-info-display-function 'check-url)
|
|
|
2237 @end example
|
|
|
2238
|
|
|
2239 So that all links pointing to any site at blort.com shows up as "Some
|
|
|
2240 link[SLOW!]" instead of just "Some link".
|
|
|
2241
|
|
|
2242 @node Gopher Plus Support, Hooks, Rating Links, Advanced Features
|
|
|
2243 @section Gopher+ Support
|
|
|
2244 @cindex Gopher+
|
|
|
2245 The gopher+ support in Emacs-W3 is limited to the conversion of ASK
|
|
|
2246 blocks into HTML 3.0 forms, and the usage of the content-length given by
|
|
|
2247 the gopher+ server to give a nice status bar on the bottom of the
|
|
|
2248 screen.
|
|
|
2249
|
|
|
2250 This will hopefully be extended to include the Gopher+ method of
|
|
|
2251 content-type negotiation, but this may be a while.
|
|
|
2252
|
|
|
2253 @node Hooks, Other Variables, Gopher Plus Support, Advanced Features
|
|
|
2254 @section Hooks
|
|
|
2255 @cindex Hooks
|
|
|
2256 These are the various hooks that can be used to customize some of
|
|
|
2257 Emacs-W3's behavior. They are arranged in the order in which they would
|
|
|
2258 happen when retrieving a document. All of these are functions (or lists
|
|
|
2259 of functions) that are called consecutively.
|
|
|
2260
|
|
|
2261 @table @code
|
|
|
2262 @vindex w3-load-hooks
|
|
|
2263 @item w3-load-hooks
|
|
|
2264 These hooks are run by @code{w3-do-setup} the first time a URL is
|
|
|
2265 fetched. All the w3 variables are initialized before this hook is
|
|
|
2266 run.
|
|
|
2267 @item w3-file-done-hooks
|
|
|
2268 These hooks are run by @code{w3-prepare-buffer} after all parsing on a
|
|
|
2269 document has been done. All @code{url-current-}@var{*} and
|
|
|
2270 @code{w3-current-}@var{*} variables are initialized when this hook is run.
|
|
|
2271 This is run before the buffer is shown, and before any inlined images
|
|
|
2272 are downloaded and converted.
|
|
|
2273 @item w3-file-prepare-hooks
|
|
|
2274 These hooks are run by @code{w3-prepare-buffer} before any parsing is
|
|
|
2275 done on the HTML file. The HTTP/1.0 headers specified by
|
|
|
2276 @code{w3-show-headers} have been inserted, the syntax table has been set
|
|
|
2277 to @code{w3-parse-args-syntax-table}, and any personal annotations have
|
|
|
2278 been inserted by the time this hook is run.
|
|
|
2279 @item w3-mode-hooks
|
|
|
2280 These hooks are run after a buffer has been parsed and displayed, but
|
|
|
2281 before any inlined images are downloaded and converted.
|
|
|
2282 @item w3-source-file-hooks
|
|
|
2283 These hooks are run after displaying a document's source
|
|
|
2284 @end table
|
|
|
2285
|
|
|
2286 @node Other Variables, , Hooks, Advanced Features
|
|
|
2287 @section Miscellaneous variables
|
|
|
2288 There are lots of variables that control the real nitty-gritty of Emacs-W3
|
|
|
2289 that the beginning user probably shouldn't mess with. Here they are.
|
|
|
2290
|
|
|
2291 @table @code
|
|
|
2292 @item url-bad-port-list
|
|
|
2293 @vindex url-bad-port-list
|
|
|
2294 List of ports to warn the user about connecting to. Defaults to just
|
|
|
2295 the mail and NNTP ports so a malicious HTML author cannot spoof mail or
|
|
|
2296 news to other people.
|
|
|
2297 @item url-confirmation-func
|
|
|
2298 @vindex url-confirmation-func
|
|
|
2299 What function to use for asking yes or no functions. Possible values
|
|
|
2300 are @code{'yes-or-no-p} or @code{'y-or-n-p}, or any function that takes
|
|
|
2301 a single argument (the prompt), and returns @code{t} only if a positive
|
|
|
2302 answer is gotten. Defaults to @code{'yes-or-no-p}.
|
|
|
2303 @item w3-delimit-links
|
|
|
2304 @vindex w3-delimit-links
|
|
|
2305 :: WORK :: This is going away, and should be specified with stylesheets instead
|
|
|
2306 @item w3-delimit-emphasis
|
|
|
2307 @vindex w3-delimit-emphasis
|
|
|
2308 :: WORK :: This is going away, and should be specified with stylesheets instead
|
|
|
2309 @item w3-default-action
|
|
|
2310 @vindex w3-default-action
|
|
|
2311 A lisp symbol specifying what action to take for files with extensions
|
|
|
2312 that are not in the @code{mm-mime-extensions} assoc list. This is
|
|
|
2313 useful in case Emacs-W3 ever run across files with weird extensions
|
|
|
2314 (.foo, .README, .READMEFIRST, etc.). In most circumstances, this should
|
|
|
2315 not be required anymore.
|
|
|
2316
|
|
|
2317 Possible values: any lisp symbol. Should be a function that takes no
|
|
|
2318 arguments. The return value does not matter, it is ignored. Some examples
|
|
|
2319 are @code{'w3-prepare-buffer} or @code{'indented-text-mode}.
|
|
|
2320 @ignore
|
|
|
2321 @item w3-icon-directory-list
|
|
|
2322 @vindex w3-icon-directory-list
|
|
|
2323 A list of directorys to look in for the w3 standard icons... must end
|
|
|
2324 in a /! If the directory @code{data-directory}/w3 exists, then this is
|
|
|
2325 automatically added to the default value of
|
|
|
2326 http://cs.indiana.edu/elisp/w3/icons/.
|
|
|
2327 @end ignore
|
|
|
2328 @item w3-keep-old-buffers
|
|
|
2329 @vindex w3-keep-old-buffers
|
|
|
2330 Whether to keep old buffers around when following links. To avoid lots
|
|
|
2331 of buffers in one Emacs session, set this variable to @code{nil}. I
|
|
|
2332 recommend setting it to @code{t}, so that backtracking from one link to
|
|
|
2333 another is faster.
|
|
|
2334
|
|
|
2335 @item url-passwd-entry-func
|
|
|
2336 @vindex url-passwd-entry-func
|
|
|
2337 This is a symbol indicating which function to call to read in a
|
|
|
2338 password. If this variable is @code{nil} at startup, it is initialized
|
|
|
2339 depending on whether @dfn{EFS} or @dfn{ange-ftp} is being used. This
|
|
|
2340 function should accept the prompt string as its first argument, and the
|
|
|
2341 default value as its second argument.
|
|
|
2342
|
|
|
2343 @item w3-reuse-buffers
|
|
|
2344 @vindex w3-reuse-buffers
|
|
|
2345 Determines what happens when @code{w3-fetch} is called on a document
|
|
|
2346 that has already been loaded into another buffer. Possible values are:
|
|
|
2347 @code{nil}, @code{yes}, and @code{no}. @code{nil} will ask the user if
|
|
|
2348 Emacs-W3 should reuse the buffer (this is the default value). A value of
|
|
|
2349 @code{yes} means assume the user wants to always reuse the buffer. A
|
|
|
2350 value of @code{no} means assume the user always wants to re-fetch the
|
|
|
2351 document.
|
|
|
2352 @item w3-show-headers
|
|
|
2353 @vindex w3-show-headers
|
|
|
2354 This is a list of HTTP/1.0 headers to show at the end of a buffer. All
|
|
|
2355 the headers should be in lowercase. They are inserted at the end of the
|
|
|
2356 buffer in a <UL> list. Alternatively, if this is simply @code{t}, then
|
|
|
2357 all the HTTP/1.0 headers are shown. The default value is
|
|
|
2358 @code{nil}.
|
|
|
2359 @item w3-show-status, url-show-status
|
|
|
2360 @vindex url-show-status
|
|
|
2361 @vindex w3-show-status
|
|
|
2362 Whether to show progress messages in the minibuffer.
|
|
|
2363 @code{w3-show-status} controls if messages about the parsing are
|
|
|
2364 displayed, and @code{url-show-status} controls if a running total of the
|
|
|
2365 number of bytes transferred is displayed. These Can cause a large
|
|
|
2366 performance hit if using a remote X display over a slow link, or a
|
|
|
2367 terminal with a slow modem.
|
|
|
2368 @item mm-content-transfer-encodings
|
|
|
2369 @vindex mm-content-transfer-encodings
|
|
|
2370 An assoc list of @var{Content-Transfer-Encodings} or
|
|
|
2371 @var{Content-Encodings} and the appropriate decoding algorithms for each.
|
|
|
2372 If the @code{cdr} of a node is a list, then this specifies the decoder is
|
|
|
2373 an external program, with the program as the first item in the list, and
|
|
|
2374 the rest of the list specifying arguments to be passed on the command line.
|
|
|
2375 If using an external decoder, it must accept its input from @code{stdin}
|
|
|
2376 and send its output to @code{stdout}.
|
|
|
2377
|
|
|
2378 If the @code{cdr} of a node is a symbol whose function definition is
|
|
|
2379 non-@code{nil}, then that encoding can be handled internally. The function
|
|
|
2380 is called with 2 arguments, buffer positions bounding the region to be
|
|
|
2381 decoded. The function should completely replace that region with the
|
|
|
2382 unencoded information.
|
|
|
2383
|
|
|
2384 Currently supported transfer encodings are: base64, x-gzip, 7bit, 8bit,
|
|
|
2385 binary, x-compress, x-hqx, and quoted-printable.
|
|
|
2386 @item url-uncompressor-alist
|
|
|
2387 @vindex url-uncompressor-alist
|
|
|
2388 An assoc list of file extensions and the appropriate uncompression
|
|
|
2389 programs for each. This is used to build the Accept-encoding header for
|
|
|
2390 HTTP/1.0 requests.
|
|
|
2391 @item url-waisq-prog
|
|
|
2392 @vindex url-waisq-prog
|
|
|
2393 Name of the waisq executable on this system. This should be the
|
|
|
2394 @file{waisq} program from think.com's wais8-b5.1 distribution.
|
|
|
2395 @end table
|
|
|
2396
|
|
|
2397 @node More Help, Future Directions, , Top
|
|
|
2398 @chapter More Help
|
|
|
2399 @cindex Relevant Newsgroups
|
|
|
2400 @cindex Newsgroups
|
|
|
2401 @cindex Support
|
|
|
2402 For more help on Emacs-W3, please send me mail
|
|
|
2403 (@i{wmperry@@cs.indiana.edu}). Several discussion lists have also been
|
|
|
2404 created for Emacs-W3. To subscribe, send mail to
|
|
|
2405 @i{majordomo@@indiana.edu}, with the body of the message 'subscribe
|
|
|
2406 @var{listname} @var{<email addres>}'. All other mail should go to
|
|
|
2407 @i{<listname>@@indiana.edu}.
|
|
|
2408
|
|
|
2409
|
|
|
2410 @itemize @bullet
|
|
|
2411 @item
|
|
|
2412 w3-announce -- this list is for anyone interested in Emacs-W3, and
|
|
|
2413 should in general only be used by me. The gnu.emacs.sources newsgroup
|
|
|
2414 and a few other mailing lists are included on this. Please only use
|
|
|
2415 this list for major package releases related to Emacs-W3.
|
|
|
2416 (@i{www-announce@@w3.org} is included on this list).
|
|
|
2417 @item
|
|
|
2418 w3-beta -- this list is for beta testers of Emacs-W3. These brave souls test
|
|
|
2419 out not-quite stable code.
|
|
|
2420 @item
|
|
|
2421 w3-dev -- a list consisting of myself and a few other people who are
|
|
|
2422 interested in the internals of Emacs-W3, and doing active development work.
|
|
|
2423 Pretty dead right now, but I hope it will grow.
|
|
|
2424 @end itemize
|
|
|
2425
|
|
|
2426 For more help on the World Wide Web in general, please refer to the
|
|
|
2427 comp.infosystems.www.* newsgroups. There are also several discussion
|
|
|
2428 lists concerning the Web. Send mail to @i{<listname>-request@@w3.org}
|
|
|
2429 with a subject line of 'subscribe <listname>'. All mail should go to
|
|
|
2430 @i{<listname>@@w3.org}. Administrative mail should go to
|
|
|
2431 @i{www-admin@@w3.org}. The lists are:
|
|
|
2432
|
|
|
2433
|
|
|
2434 @itemize @bullet
|
|
|
2435 @item
|
|
|
2436 www-talk -- for general discussion of the World Wide Web, where its
|
|
|
2437 going, new features, etc. All the major developers are subscribed to
|
|
|
2438 this list.
|
|
|
2439 @item
|
|
|
2440 www-announce -- for announcements concerning the World Wide Web. Server
|
|
|
2441 changes, new servers, new software, etc.
|
|
|
2442 @end itemize
|
|
|
2443
|
|
|
2444 As a last resort, mail me. I'll try to answer as quickly as I can.
|
|
|
2445
|
|
|
2446 @node Future Directions, Programming Interface, More Help, Top
|
|
|
2447 @chapter Future Directions
|
|
|
2448 Changes are constantly being made to the Emacs browser (hopefully all
|
|
|
2449 for the better). This is a list of the things that are being worked on
|
|
|
2450 right now.
|
|
|
2451
|
|
|
2452 :: WORK :: Revamp the todo list
|
|
|
2453 @node Programming Interface, Generalized ZONES, Future Directions, Top
|
|
|
2454 @comment node-name, next, previous, up
|
|
|
2455 @chapter Internals of Emacs-W3
|
|
|
2456 @cindex Internals of Emacs-W3
|
|
|
2457 @cindex Using Emacs-W3 from other programs
|
|
|
2458 This chapter attempts to explain some of the internal workings of
|
|
|
2459 Emacs-W3 and various data structures that are used. It also details
|
|
|
2460 some functions that are useful for using some of the Emacs-W3
|
|
|
2461 functionality from within other programs, or extending the current
|
|
|
2462 capabilities of Emacs-W3.
|
|
|
2463
|
|
|
2464 @ifinfo
|
|
|
2465 @menu
|
|
|
2466 * Generalized ZONES:: A generic interface to 'zones' of text
|
|
|
2467 that can contain information.
|
|
|
2468 * Global Variables:: Global variables used throughout Emacs-W3
|
|
|
2469 * Data Structures:: The various data structures used in Emacs-W3
|
|
|
2470 * Miscellaneous Functions:: Miscellaneous functions to interface
|
|
|
2471 with w3 and access its data structures
|
|
|
2472 * MIME functions:: MIME functions---parsing messages,
|
|
|
2473 mailcap files, and more.
|
|
|
2474 @end menu
|
|
|
2475 @end ifinfo
|
|
|
2476 @node Generalized ZONES, Global Variables,Programming Interface, Programming Interface, Programming Interface
|
|
|
2477 @comment node-name, next, previous, up
|
|
|
2478 @section Generalized ZONES
|
|
|
2479 Due to the many different @i{flavors} of Emacs in existence, the
|
|
|
2480 addition of data and font information to arbitrary regions of text has
|
|
|
2481 been generalized. The following functions are defined for
|
|
|
2482 using/manipulating these @dfn{zones} of data.
|
|
|
2483
|
|
|
2484 @table @code
|
|
|
2485 @findex w3-add-zone
|
|
|
2486 @item w3-add-zone (start end style data &optional highlight)
|
|
|
2487 Creates a zone between buffer positions start and end, with font
|
|
|
2488 information specified by style, and a data segment of data. If the
|
|
|
2489 optional argument highlight is non-@code{nil}, then the region
|
|
|
2490 highlights when the mouse moves over it.
|
|
|
2491
|
|
|
2492
|
|
|
2493 @findex w3-zone-at
|
|
|
2494 @item w3-zone-at (point)
|
|
|
2495 Returns the zone at @var{point}. Preference is given to hypertext
|
|
|
2496 links, then to form entry areas, then to inlined images. So if an
|
|
|
2497 inlined image was part of a hypertext link, this would always return the
|
|
|
2498 hypertext link.
|
|
|
2499
|
|
|
2500 @findex w3-zone-data
|
|
|
2501 @item w3-zone-data (zone)
|
|
|
2502 Returns the zone's data segment. The data structures used in Emacs-W3 are
|
|
|
2503 relatively simple. They are just list structures that follow a certain
|
|
|
2504 format. The two main data types are @dfn{form objects}, @dfn{link
|
|
|
2505 objects},and @dfn{inlined images}. All the information for these types
|
|
|
2506 of links are stored as lists.
|
|
|
2507
|
|
|
2508 @findex w3-zone-hidden-p
|
|
|
2509 @item w3-zone-hidden-p (zone)
|
|
|
2510 Returns @code{t} if and only if a zone is currently invisible.
|
|
|
2511 @findex w3-hide-zone
|
|
|
2512 @item w3-hide-zone (start end)
|
|
|
2513 Makes a region of text from @code{start} to @code{end} invisible.
|
|
|
2514 @findex w3-unhide-zone
|
|
|
2515 @item w3-unhide-zone (start end)
|
|
|
2516 Makes a region of text from @code{start} to @code{end} visible
|
|
|
2517 again.
|
|
|
2518 @findex w3-zone-start
|
|
|
2519 @item w3-zone-start (zone)
|
|
|
2520 Returns an integer that is the start of zone, as a buffer position. In
|
|
|
2521 Emacs 18.xx, this returns a marker instead of an integer, but it can be
|
|
|
2522 used just like an integer.
|
|
|
2523 @findex w3-zone-end
|
|
|
2524 @item w3-zone-end (zone)
|
|
|
2525 Returns an integer that is the end of zone, as a buffer position. In
|
|
|
2526 Emacs 18.xx, this returns a marker instead of an integer, but it can be
|
|
|
2527 used just like an integer.
|
|
|
2528 @findex w3-zone-eq
|
|
|
2529 @item w3-zone-eq (zone1 zone2)
|
|
|
2530 Returns @code{t} if and only if zone1 and zone2 represent the same
|
|
|
2531 region of text in the same buffer, with the same properties and
|
|
|
2532 data.
|
|
|
2533 @findex w3-delete-zone
|
|
|
2534 @item w3-delete-zone (zone)
|
|
|
2535 Removes zone from its buffer (or current buffer). The return value is
|
|
|
2536 irrelevant, and varies for each version of Emacs.
|
|
|
2537 @findex w3-all-zones
|
|
|
2538 @item w3-all-zones ()
|
|
|
2539 Returns a list of all the zones contained in the current buffer. Useful
|
|
|
2540 for extracting information about hypertext links or form entry
|
|
|
2541 areas. Programs should not rely on this list being sorted, as the order
|
|
|
2542 varies with each version of Emacs.
|
|
|
2543 @item w3-zone-at (pt)
|
|
|
2544 Returns the zone at character position PT in the current buffer that is
|
|
|
2545 either a link or a forms entry area. Returns @code{nil} if no link at
|
|
|
2546 point.
|
|
|
2547
|
|
|
2548 @end table
|
|
|
2549 @findex w3-zone-data
|
|
|
2550 These data structures are what is generally returned by
|
|
|
2551 @code{w3-zone-data}.
|
|
|
2552
|
|
|
2553 @node Global Variables, Data Structures , Generalized ZONES, Programming Interface
|
|
|
2554 @comment node-name, next, previous, up
|
|
|
2555 @section Global variables
|
|
|
2556 There are also some variables that may be useful when writing a program
|
|
|
2557 or function that interacts with Emacs-W3. All of the
|
|
|
2558 @code{w3-current-*} variables are local to each buffer.
|
|
|
2559
|
|
|
2560
|
|
|
2561 @table @code
|
|
|
2562 @vindex url-current-mime-headers
|
|
|
2563 @item url-current-mime-headers
|
|
|
2564 An assoc list of all the MIME headers for the current document. Keyed
|
|
|
2565 on the lowercase MIME header (e.g., @samp{content-type} or
|
|
|
2566 @samp{content-encoding}.
|
|
|
2567 @vindex url-current-server
|
|
|
2568 @item url-current-server
|
|
|
2569 Server that the current document was retrieved from.
|
|
|
2570 @vindex url-current-file
|
|
|
2571 @item url-current-file
|
|
|
2572 Filename of the current document
|
|
|
2573 @vindex url-current-type
|
|
|
2574 @item url-current-type
|
|
|
2575 A string representing what network protocol was used to retrieve the
|
|
|
2576 current buffer's document. Can be one of http, gopher, file, ftp, news,
|
|
|
2577 or mailto.
|
|
|
2578 @vindex url-current-port
|
|
|
2579 @item url-current-port
|
|
|
2580 Port # of the current document.
|
|
|
2581 @vindex w3-current-last-buffer
|
|
|
2582 @item w3-current-last-buffer
|
|
|
2583 The last buffer seen before this one.
|
|
|
2584 @vindex w3-running-FSF19
|
|
|
2585 @item w3-running-FSF19
|
|
|
2586 This is @code{t} if and only if we are running in FSF Emacs 19.
|
|
|
2587 @vindex w3-running-xemacs
|
|
|
2588 @item w3-running-xemacs
|
|
|
2589 This is @code{t} if and only if we are running in Lucid Emacs, WinEmacs, or
|
|
|
2590 XEmacs.
|
|
|
2591 @end table
|
|
|
2592
|
|
|
2593 @node Data Structures, Miscellaneous Functions, Global Variables, Programming Interface
|
|
|
2594 @comment node-name, next, previous, up
|
|
|
2595 @section Data Structures
|
|
|
2596 Form objects are used to store information about a FORM data entry area.
|
|
|
2597 @enumerate
|
|
|
2598 @item
|
|
|
2599 @code{'w3form}
|
|
|
2600 @item
|
|
|
2601 A cons pair of (METHOD . URL), where METHOD specifies what method to use
|
|
|
2602 to retrieve the form when it is submitted (e.g., @samp{GET}) and URL is a
|
|
|
2603 fully specified URL pointing at where to submit the FORM data to.
|
|
|
2604 @item
|
|
|
2605 The type of input area this is. (e.g., @samp{CHECKBOX} or
|
|
|
2606 @samp{RADIO})
|
|
|
2607 @item
|
|
|
2608 The name of the input tag. This is used when sending the form to the
|
|
|
2609 server, so that the server can tell what data is what.
|
|
|
2610 @item
|
|
|
2611 The default value of the input area. Gotten from the INPUT tag at
|
|
|
2612 creation time.
|
|
|
2613 @item
|
|
|
2614 The current value of the input area.
|
|
|
2615 @item
|
|
|
2616 Whether the item is checked or not. Only used for RADIO or CHECKBOX
|
|
|
2617 items.
|
|
|
2618 @item
|
|
|
2619 The size (in characters) of the input area. Not used for CHECKBOX,
|
|
|
2620 RADIO, or TEXTAREA input areas.
|
|
|
2621 @item
|
|
|
2622 The maximum length of the input. Only used for TEXT or PASSWORD input
|
|
|
2623 areas.
|
|
|
2624 @item
|
|
|
2625 The form that this input area belongs to. Each form in the same buffer
|
|
|
2626 has a unique identifier assigned when the document is parsed. It is
|
|
|
2627 used when the form is submitted to get only the data for the correct
|
|
|
2628 form.
|
|
|
2629 @item
|
|
|
2630 A list of strings that represent the choices for this input area. Only
|
|
|
2631 used for SELECT tags.
|
|
|
2632 @item
|
|
|
2633 A string or @code{nil}, specifying the ID attribute on this input
|
|
|
2634 tag.
|
|
|
2635 @end enumerate
|
|
|
2636
|
|
|
2637 A new development in the World Wide Web is the concept of collapsible
|
|
|
2638 areas of text. If a zone controls one of these regions, it is marked
|
|
|
2639 with the @b{w3expandlist} property. The format of this structure
|
|
|
2640 is:
|
|
|
2641
|
|
|
2642 @enumerate
|
|
|
2643 @item
|
|
|
2644 @code{'w3expandlist}
|
|
|
2645 @item
|
|
|
2646 A marker representing the start of the hidden text as a buffer position.
|
|
|
2647 @item
|
|
|
2648 A marker representing the end of the hidden text as a buffer position.
|
|
|
2649 @end enumerate
|
|
|
2650
|
|
|
2651 A zone with the @b{w3graphic} property is a link to an inlined image's
|
|
|
2652 source file.
|
|
|
2653 @enumerate
|
|
|
2654 @item
|
|
|
2655 @code{'w3graphic}
|
|
|
2656 @item
|
|
|
2657 @findex w3-follow-inlined-image
|
|
|
2658 The full URL of the inlined image. This is only ever returned if the
|
|
|
2659 inlined image is the only extent under point, or
|
|
|
2660 @code{w3-follow-inlined-image} is invoked.
|
|
|
2661 @end enumerate
|
|
|
2662
|
|
|
2663 A zone with the @b{w3} property is a full-fledged hypertext link to
|
|
|
2664 another document.
|
|
|
2665 @enumerate
|
|
|
2666 @item
|
|
|
2667 @code{'w3}
|
|
|
2668 @item
|
|
|
2669 The ID attribute of this link. Used for resolving references to
|
|
|
2670 specific points within a document (e.g., @samp{file.html#sectionA}.
|
|
|
2671 @item
|
|
|
2672 The HREF attribute of this link. This is a fully specified URL pointing
|
|
|
2673 at a network resource. All relative directory references should have
|
|
|
2674 been removed before being stored in this structure.
|
|
|
2675 @item
|
|
|
2676 The text between the <A> and </A> tags. This is used to build menus or
|
|
|
2677 to get the text of a link without doing a buffer-substring.
|
|
|
2678 @item
|
|
|
2679 The URN attribute of this link. Currently not used for anything,
|
|
|
2680 waiting for the URN specification to be hammered out.
|
|
|
2681 @item
|
|
|
2682 The REL attribute of this link. Specifies the links relevance to the
|
|
|
2683 current document.
|
|
|
2684 @item
|
|
|
2685 The REV attribute of this link. Specifies the current documents
|
|
|
2686 relevance to the link.
|
|
|
2687 @item
|
|
|
2688 The METHODS attribute, which tells what methods can be used on this
|
|
|
2689 link. (e.g., @samp{GET, HEAD, PUT}.
|
|
|
2690 @end enumerate
|
|
|
2691 @node Miscellaneous Functions, MIME functions, Data Structures, Programming Interface
|
|
|
2692 @comment node-name, next, previous, up
|
|
|
2693 @section Miscellaneous Functions
|
|
|
2694 I have done quite a bit of work trying to make a clean interface to the
|
|
|
2695 internals of Emacs-W3.
|
|
|
2696
|
|
|
2697 @table @code
|
|
|
2698 @findex url-clear-tmp-buffer
|
|
|
2699 @vindex url-working-buffer
|
|
|
2700 @item url-clear-tmp-buffer
|
|
|
2701 Sets the current buffer to be @code{url-working-buffer}, creating it if
|
|
|
2702 necessary, and erase it. This should usually be called before
|
|
|
2703 retrieving URLs.
|
|
|
2704
|
|
|
2705 @findex w3-convert-html-to-latex
|
|
|
2706 @item w3-convert-html-to-latex
|
|
|
2707 Takes a buffer of HTML markup (which should be in
|
|
|
2708 @code{w3-working-buffer}), and convert it into LaTeX. This is an
|
|
|
2709 adaptation of the simple sed scripts from Cern. Does as good a job as
|
|
|
2710 the html2latex program, and I usually prefer its formatting over
|
|
|
2711 html2latex's.
|
|
|
2712
|
|
|
2713 @findex w3-fetch
|
|
|
2714 @item w3-fetch
|
|
|
2715 Takes a URL as its only argument. It then attempts to retrieve the URL.
|
|
|
2716 For example: @samp{(w3-fetch "http://cs.indiana.edu/")} would retrieve
|
|
|
2717 the Indiana University CS home page and parse it as HTML.
|
|
|
2718
|
|
|
2719
|
|
|
2720 @findex url-generate-new-buffer-name
|
|
|
2721 @item url-generate-new-buffer-name
|
|
|
2722 Takes a string, and returns the first unique buffer name using that
|
|
|
2723 string as a base. For example @samp{(url-generate-new-buffer-name
|
|
|
2724 "new-buff")} would return @samp{"new-buff<1>"} if buffer @code{new-buff}
|
|
|
2725 already existed.
|
|
|
2726
|
|
|
2727
|
|
|
2728 @findex url-generate-unique-filename
|
|
|
2729 @item url-generate-unique-filename
|
|
|
2730 Returns a string that represents a unique filename in the /tmp
|
|
|
2731 directory. For example, @samp{(url-generate-unique-filename)} would
|
|
|
2732 return @samp{"/tmp/url-tmp129440"}. The filename is arrived at by using
|
|
|
2733 a unique prefix (url-tmp), the uid of the current user (12944 in my
|
|
|
2734 case), and a number that is incremented if a file already exists.
|
|
|
2735
|
|
|
2736
|
|
|
2737 @findex url-buffer-visiting
|
|
|
2738 @item url-buffer-visiting (url)
|
|
|
2739 Returns the name of a buffer (if any) that is visiting URL.
|
|
|
2740
|
|
|
2741 @findex url-create-mime-request
|
|
|
2742 @vindex url-request-extra-headers
|
|
|
2743 @vindex url-request-data
|
|
|
2744 @vindex url-request-method
|
|
|
2745 @vindex url-mime-accept-string
|
|
|
2746 @vindex url-current-server
|
|
|
2747 @cindex Creating an HTTP request
|
|
|
2748 @item url-create-mime-request (fname ref-url)
|
|
|
2749 Creates a MIME request for the file fname. The Referer: field of the
|
|
|
2750 HTTP/1.0 request is set to the value of ref-url if necessary. Returns a
|
|
|
2751 string that can be sent to an HTTP server. The request uses several
|
|
|
2752 variables that control how the request looks.
|
|
|
2753
|
|
|
2754
|
|
|
2755 If the value of @code{url-request-extra-headers} is non-@code{nil}, then
|
|
|
2756 it is used as extra MIME headers when an HTTP/1.0 request is
|
|
|
2757 created.
|
|
|
2758
|
|
|
2759 @findex url-get-url-at-point
|
|
|
2760 @item url-get-url-at-point
|
|
|
2761 Returns the url at a point specified by an optional argument. If no
|
|
|
2762 argument is given to the function, the current buffer position is used.
|
|
|
2763 Tries to find the URL closest to that point, but does not change the
|
|
|
2764 users position in the buffer. Has a preference for looking backward
|
|
|
2765 when not directly on a URL.
|
|
|
2766
|
|
|
2767
|
|
|
2768 @findex url-hexify-string
|
|
|
2769 @item url-hexify-string
|
|
|
2770 Takes a string and replaces any characters that are not acceptable in a
|
|
|
2771 URL with the "escaped" encoding that is standard for URLs (replaces the
|
|
|
2772 character with a % followed by the hexadecimal representation of the
|
|
|
2773 ASCII value of the character). For example, @samp{(url-hexify-string
|
|
|
2774 "this is a test")} would return @samp{"this%20is%20a%20test"}.
|
|
|
2775
|
|
|
2776
|
|
|
2777 @findex url-open-stream
|
|
|
2778 @item url-open-stream
|
|
|
2779 Takes the same parameters as @code{open-network-stream}, and functions
|
|
|
2780 similarly. It takes a process name, a buffer name, a host name, and a
|
|
|
2781 port number or server name. It attempts to open a network connection to
|
|
|
2782 the remote host on the specified port/service name, with output going to
|
|
|
2783 the buffer. It returns the process object that is the network
|
|
|
2784 connection.
|
|
|
2785
|
|
|
2786
|
|
|
2787 @findex url-retrieve
|
|
|
2788 @item url-retrieve
|
|
|
2789 :: WORK :: Need to describe the url-request-* variables and the no-cache and
|
|
|
2790 expected-md5 arguments to url-retrieve ::
|
|
|
2791
|
|
|
2792
|
|
|
2793 @findex url-unhex-string
|
|
|
2794 @item url-unhex-string
|
|
|
2795 This is the opposite of @code{url-hexify-string}. It removes any %XXX
|
|
|
2796 encoded characters in a string. For example @samp{(url-unhex-string
|
|
|
2797 "this%20is%20a%20test")} would return @samp{"this is a test"}.
|
|
|
2798
|
|
|
2799 @findex w3-view-this-url
|
|
|
2800 @item w3-view-this-url
|
|
|
2801 Returns the URL of the hyperlink under point (if no hyperlink is under
|
|
|
2802 point, then it returns @code{nil}). If the optional argument is
|
|
|
2803 @code{nil}, then the URL is also displayed in the minibuffer.
|
|
|
2804
|
|
|
2805
|
|
|
2806 @findex url-view-url
|
|
|
2807 @item url-view-url
|
|
|
2808 Returns the URL of current document. If the optional argument is
|
|
|
2809 @code{nil}, then the URL is also displayed in the minibuffer.
|
|
|
2810
|
|
|
2811 @end table
|
|
|
2812
|
|
|
2813 @node MIME functions, Reporting Bugs, Miscellaneous Functions, Programming Interface
|
|
|
2814 @section MIME Functions
|
|
|
2815 @table @code
|
|
|
2816 @item mm-compose-type(TYPE)
|
|
|
2817 Composes a body section of MIME-type TYPE. This uses the compose field
|
|
|
2818 of a mailcap entry to generate the data, and returns a string that
|
|
|
2819 contains the data, with a correct content-type header.
|
|
|
2820
|
|
|
2821 @item mm-extension-to-mime(EXTN)
|
|
|
2822 Returns the MIME content-type of the file extension EXTN.
|
|
|
2823 @item mm-mime-info(ST ND REQUEST)
|
|
|
2824 Returns the mime viewer command for a specific MIME type. If ST is a
|
|
|
2825 number, then the MIME type is the @code{buffer-substring} between ST and
|
|
|
2826 ND, otherwise ST should be a string specifying the MIME type and
|
|
|
2827 associated data. Returns @code{nil} if the specified type is not found.
|
|
|
2828
|
|
|
2829
|
|
|
2830 Expects a complete content-type header line as its argument. This can
|
|
|
2831 be simple like text/html, or complex like text/plain; charset=blah; foo=bar
|
|
|
2832
|
|
|
2833
|
|
|
2834 Third argument REQUEST specifies what information to return. If it is
|
|
|
2835 @code{nil} or the empty string, the viewer (second field of the mailcap
|
|
|
2836 entry) is returned. If it is a string, then the mailcap field
|
|
|
2837 corresponding to that string is returned (print, description, whatever).
|
|
|
2838 If a number, then all the information for this specific viewer is
|
|
|
2839 returned.
|
|
|
2840 @item mm-parse-mailcap(FILE)
|
|
|
2841 Parses the mailcap file specified by FILE.
|
|
|
2842 @item mm-parse-mailcaps(PATH)
|
|
|
2843 Parses the default mailcap files. Optional argument PATH specifies a
|
|
|
2844 UNIX-style path of where to find the mailcap files. This function must
|
|
|
2845 be run before the rest of the mm-* functions.
|
|
|
2846 @item mm-parse-mimetype-file(FILE)
|
|
|
2847 Parses out a mime-types file specified by FILE.
|
|
|
2848 @item mm-parse-mimetypes(PATH)
|
|
|
2849 Parses the default mimetypes files. Optional argument PATH specifies a
|
|
|
2850 UNIX-style path of where to find the mimetypes files.
|
|
|
2851 @end table
|
|
|
2852
|
|
|
2853 @node Reporting Bugs, Installing SSL, MIME functions, Top
|
|
|
2854 @appendix Reporting Bugs
|
|
|
2855 @cindex Reporting Bugs
|
|
|
2856 @cindex Bugs
|
|
|
2857 @cindex Contacting the author
|
|
|
2858
|
|
|
2859 :: WORK :: Reporting bugs needs work.
|
|
|
2860
|
|
|
2861 @node Installing SSL, Using PGP/PEM, Reporting Bugs, Top
|
|
|
2862 @appendix Installing SSL
|
|
|
2863 @cindex HTTP/1.0 Authentication
|
|
|
2864 @cindex Secure Sockets Layer
|
|
|
2865 @cindex SSL
|
|
|
2866 @cindex Gag Puke Retch
|
|
|
2867 @cindex Exportability
|
|
|
2868 @cindex Export Restrictions
|
|
|
2869 In order to use SSL in Emacs-W3, an implementation of SSL is necessary.
|
|
|
2870 These are the implementations that I am aware of:
|
|
|
2871
|
|
|
2872 @table @code
|
|
|
2873 @item SSLRef 2.0
|
|
|
2874 Available from Netscape Communications @footnote{http://www.netscape.com/newsref/std/sslref.html}. This requires the
|
|
|
2875 RSARef library, which is not exportable. The RSARef library is
|
|
|
2876 available from ftp://ftp.rsa.com/rsaref/
|
|
|
2877 @item SSLeay 0.4
|
|
|
2878 An implementation by Eric Young (eay@@mincom.oz.au) that is free for
|
|
|
2879 commerial or noncommercial use, and was developed completely outside the
|
|
|
2880 US by a non-US citizen. More information can be found at
|
|
|
2881 ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL/
|
|
|
2882 @end table
|
|
|
2883
|
|
|
2884 @vindex ssl-program-name
|
|
|
2885 Whichever reference implementation is used (I recommend the SSLeay
|
|
|
2886 distribution, just to thumb a nose at the NSA :), there is a program
|
|
|
2887 that can be run in a subprocess that takes a hostname and port number on
|
|
|
2888 the command line, and reads/writes to standard input/output (the
|
|
|
2889 Netscape implementation comes with one of these by default). Set the
|
|
|
2890 variable @code{ssl-program-name} to point to this program.
|
|
|
2891
|
|
|
2892
|
|
|
2893 This should be all the configuration necessary. In the future, I will
|
|
|
2894 be distributing a set of patches to Emacs 19.xx and XEmacs 19.xx to
|
|
|
2895 SSL-enable them, for the sake of speed.
|
|
|
2896
|
|
|
2897 @node Using PGP/PEM, Mailcap Files, Installing SSL, Top
|
|
|
2898 @appendix Using PGP/PEM
|
|
|
2899 @cindex HTTP/1.0 Authentication
|
|
|
2900 @cindex Public Key Cryptography
|
|
|
2901 @cindex Authentication, PGP
|
|
|
2902 @cindex Authentication, PEM
|
|
|
2903 @cindex RIPEM
|
|
|
2904 @cindex Public Key Cryptography
|
|
|
2905 @cindex PGP
|
|
|
2906 @cindex Pretty Good Privacy
|
|
|
2907 @cindex Encryption
|
|
|
2908 @cindex Security
|
|
|
2909 @cindex ITAR must die
|
|
|
2910 @cindex Stupid export restrictions
|
|
|
2911 @cindex Support your local crypto-anarchist
|
|
|
2912 @cindex NSA freaks
|
|
|
2913 Most of this chapter has been reproduced from the original documentation
|
|
|
2914 written by Rob McCool (@i{robm@@netscape.com})@footnote{See
|
|
|
2915 http://hoohoo.ncsa.uiuc.edu/docs/PEMPGP.html for the original}.
|
|
|
2916
|
|
|
2917 RIPEM is 'Riordan's Internet Privacy Enhanced Mail', and is currently on
|
|
|
2918 version 1.2b3. US citizens can ftp it from
|
|
|
2919 ftp://ripem.msu.edu/pub/crypt/ripem.
|
|
|
2920
|
|
|
2921 PGP is 'Pretty Good Privacy', and is currently on version 2.6. The
|
|
|
2922 legal controversies that plagued earlier versions have been resolved, so
|
|
|
2923 this is a competely legal program now. There is also a legal version
|
|
|
2924 for european users, called 2.6ui (the Unofficial International
|
|
|
2925 version).
|
|
|
2926
|
|
|
2927 PGP and PEM are programs that allow two parties to communicate in a way
|
|
|
2928 which does not allow third parties to read them, and which certify that
|
|
|
2929 the person who sent the message is really who they claim they are.
|
|
|
2930
|
|
|
2931
|
|
|
2932 PGP and PEM both use RSA encryption. The U.S. government has strict
|
|
|
2933 export controls over foreign use of this technology, so people outside
|
|
|
2934 the U.S. may have a difficult time finding programs which perform the
|
|
|
2935 encryption.
|
|
|
2936
|
|
|
2937 A working copy of either Pretty Good Privacy or RIPEM is required. You
|
|
|
2938 should be familiar with the program and have generated a public/private
|
|
|
2939 key pair.
|
|
|
2940
|
|
|
2941
|
|
|
2942 Currently, the protocol has been implemented with PEM and PGP using
|
|
|
2943 local key files on the server side, and on the client side with PEM
|
|
|
2944 using finger to retrieve the server's public key.
|
|
|
2945
|
|
|
2946 Parties who wish to use Emacs-W3 with PEM or PGP encryption will need to
|
|
|
2947 communicate beforehand and find a tamper-proof way to exchange their
|
|
|
2948 public keys.
|
|
|
2949
|
|
|
2950 Pioneers get shot full of arrows. This work is currently in the
|
|
|
2951 experimental stages and thus may have some problems that I have
|
|
|
2952 overlooked. The only known problem that I know about is that the
|
|
|
2953 messages are currently not timestamped. This means that a malicious
|
|
|
2954 user could record the encrypted message with a packet sniffer and repeat
|
|
|
2955 it back to the server ad nauseum. Although they would not be able to
|
|
|
2956 read the reply, if the request was for something being charged for, this
|
|
|
2957 could be very inconvenient.
|
|
|
2958
|
|
|
2959 This protocol is almost word-for-word a copy of Tony Sander's RIPEM
|
|
|
2960 based scheme, generalized a little. Below, wherever PEM is used,
|
|
|
2961 replace it with PGP, and the behaviour should remain the same.
|
|
|
2962
|
|
|
2963 @example
|
|
|
2964 *Client:*
|
|
|
2965
|
|
|
2966 GET /docs/protected.html HTTP/1.0
|
|
|
2967 UserAgent: Emacs-W3/2.1.x
|
|
|
2968
|
|
|
2969 *Server:*
|
|
|
2970
|
|
|
2971 HTTP/1.0 401 Unauthorized
|
|
|
2972 WWW-Authenticate: PEM entity="webmaster@@hoohoo.ncsa.uiuc.edu"
|
|
|
2973 Server: NCSA/1.1
|
|
|
2974
|
|
|
2975 *Client:*
|
|
|
2976
|
|
|
2977 GET / HTTP/1.0
|
|
|
2978 Authorization: PEM entity="robm@@ncsa.uiuc.edu"
|
|
|
2979 Content-type: application/x-www-pem-request
|
|
|
2980
|
|
|
2981 --- BEGIN PRIVACY-ENHANCED MESSAGE ---
|
|
|
2982 this is the real request, encrypted
|
|
|
2983 --- END PRIVACY-ENHANCED MESSAGE ---
|
|
|
2984
|
|
|
2985 *Server:*
|
|
|
2986
|
|
|
2987 HTTP/1.0 200 OK
|
|
|
2988 Content-type: application/x-www-pem-reply
|
|
|
2989
|
|
|
2990 --- BEGIN PRIVACY-ENHANCED MESSAGE ---
|
|
|
2991 this is the real reply, encrypted
|
|
|
2992 --- END PRIVACY-ENHANCED MESSAGE ---
|
|
|
2993 That's it.
|
|
|
2994 @end example
|
|
|
2995
|
|
|
2996 @cindex Mailcrypt
|
|
|
2997 Emacs-W3 uses the excellent @i{mailcrypt}@footnote{Available from
|
|
|
2998 http://www.cs.indiana.edu/LCD/cover.html?mailcrypt} package written by
|
|
|
2999 Jin S Choi (@i{jsc@@mit.edu}). This package takes care of calling ripem
|
|
|
3000 and/or pgp with the correct arguments. Please see the documentation at
|
|
|
3001 the top of mailcrypt.el for instructions on using mailcrypt. All bug
|
|
|
3002 reports about mailcrypt should go to Jin S Choi, but bugs about how I
|
|
|
3003 use it in Emacs-W3 should of course be directed to me.
|
|
|
3004
|
|
|
3005 @node Mailcap Files, General Index, Using PGP/PEM, Top
|
|
|
3006 @appendix Mailcap Files
|
|
|
3007 NCSA Mosaic and almost all other WWW browsers rely on a separate file
|
|
|
3008 for mapping MIME types to external viewing programs. This takes some of
|
|
|
3009 the burden off of browser developers, so each browser does not have to
|
|
|
3010 support all image formats, or postscript, etc. Instead of having the
|
|
|
3011 users of Emacs-W3 duplicate this in lisp, this file can be parsed using
|
|
|
3012 the @code{mm-parse-mailcaps} function. This function is called each
|
|
|
3013 time Emacs-W3 is loaded. It tries to locate mimetype files in several
|
|
|
3014 places. If the environment variable @code{MAILCAPS} is nonempty, then
|
|
|
3015 this is assumed to specify a UNIX-like path of mimetype files (this is a
|
|
|
3016 colon separated string of pathnames). If the @code{MAILCAPS}
|
|
|
3017 environment variable is empty, then Emacs-W3 looks for these
|
|
|
3018 files:
|
|
|
3019
|
|
|
3020 @enumerate
|
|
|
3021 @item
|
|
|
3022 @file{~/.mailcap}
|
|
|
3023 @item
|
|
|
3024 @file{/etc/mailcap}
|
|
|
3025 @item
|
|
|
3026 @file{/usr/etc/mailcap}
|
|
|
3027 @item
|
|
|
3028 @file{/usr/local/etc/mailcap}
|
|
|
3029 @end enumerate
|
|
|
3030
|
|
|
3031 This format of this file is specified in RFC 1343, but a brief synopsis
|
|
|
3032 follows (this is taken verbatim from sections of RFC 1343).
|
|
|
3033
|
|
|
3034 Each mailcap file consists of a set of entries that describe the proper
|
|
|
3035 handling of one media type at the local site. For example, one line
|
|
|
3036 might tell how to display a message in Group III fax format. A mailcap
|
|
|
3037 file consists of a sequence of such individual entries, separated by
|
|
|
3038 newlines (according to the operating system's newline
|
|
|
3039 conventions). Blank lines and lines that start with the "#" character
|
|
|
3040 (ASCII 35) are considered comments, and are ignored. Long entries may
|
|
|
3041 be continued on multiple lines if each non-terminal line ends with a
|
|
|
3042 backslash character ('\', ASCII 92), in which case the multiple lines
|
|
|
3043 are to be treated as a single mailcap entry. Note that for such
|
|
|
3044 "continued" lines, the backslash must be the last character on the line
|
|
|
3045 to be continued.
|
|
|
3046
|
|
|
3047 Each mailcap entry consists of a number of fields, separated by
|
|
|
3048 semi-colons. The first two fields are required, and must occur in the
|
|
|
3049 specified order. The remaining fields are optional, and may appear in
|
|
|
3050 any order.
|
|
|
3051
|
|
|
3052 The first field is the content-type, which indicates the type of data
|
|
|
3053 this mailcap entry describes how to handle. It is to be matched against
|
|
|
3054 the type/subtype specification in the "Content-Type" header field of an
|
|
|
3055 Internet mail message. If the subtype is specified as "*", it is
|
|
|
3056 intended to match all subtypes of the named content-type.
|
|
|
3057
|
|
|
3058 The second field, view-command, is a specification of how the message or
|
|
|
3059 body part can be viewed at the local site. Although the syntax of this
|
|
|
3060 field is fully specified, the semantics of program execution are
|
|
|
3061 necessarily somewhat operating system dependent.
|
|
|
3062
|
|
|
3063 The optional fields, which may be given in any order, are as follows:
|
|
|
3064 @itemize @bullet
|
|
|
3065 @item
|
|
|
3066 The "compose" field may be used to specify a program that can be used to
|
|
|
3067 compose a new body or body part in the given format. Its intended use
|
|
|
3068 is to support mail composing agents that support the composition of
|
|
|
3069 multiple types of mail using external composing agents. As with the
|
|
|
3070 view- command, the semantics of program execution are operating system
|
|
|
3071 dependent. The result of the composing program may be data that is not
|
|
|
3072 yet suitable for mail transport---that is, a Content-Transfer-Encoding
|
|
|
3073 may need to be applied to the data.
|
|
|
3074 @item
|
|
|
3075 The "composetyped" field is similar to the "compose" field, but is to be
|
|
|
3076 used when the composing program needs to specify the Content-type header
|
|
|
3077 field to be applied to the composed data. The "compose" field is
|
|
|
3078 simpler, and is preferred for use with existing (non-mail-oriented)
|
|
|
3079 programs for composing data in a given format. The "composetyped" field
|
|
|
3080 is necessary when the Content-type information must include auxilliary
|
|
|
3081 parameters, and the composition program must then know enough about mail
|
|
|
3082 formats to produce output that includes the mail type
|
|
|
3083 information.
|
|
|
3084 @item
|
|
|
3085 The "edit" field may be used to specify a program that can be used to
|
|
|
3086 edit a body or body part in the given format. In many cases, it may be
|
|
|
3087 identical in content to the "compose" field, and shares the
|
|
|
3088 operating-system dependent semantics for program execution.
|
|
|
3089 @item
|
|
|
3090 The "print" field may be used to specify a program that can be used to
|
|
|
3091 print a message or body part in the given format. As with the
|
|
|
3092 view-command, the semantics of program execution are operating system
|
|
|
3093 dependent.
|
|
|
3094 @item
|
|
|
3095 The "test" field may be used to test some external condition (e.g. the
|
|
|
3096 machine architecture, or the window system in use) to determine whether
|
|
|
3097 or not the mailcap line applies. It specifies a program to be run to
|
|
|
3098 test some condition. The semantics of execution and of the value
|
|
|
3099 returned by the test program are operating system dependent. If the
|
|
|
3100 test fails, a subsequent mailcap entry should be sought. Multiple test
|
|
|
3101 fields are not permitted---since a test can call a program, it can
|
|
|
3102 already be arbitrarily complex.
|
|
|
3103 @item
|
|
|
3104 The "needsterminal" field indicates that the view-command must be run on
|
|
|
3105 an interactive terminal. This is needed to inform window-oriented user
|
|
|
3106 agents that an interactive terminal is needed. (The decision is not
|
|
|
3107 left exclusively to the view-command because in some circumstances it
|
|
|
3108 may not be possible for such programs to tell whether or not they are on
|
|
|
3109 interactive terminals.) The needsterminal command should be assumed to
|
|
|
3110 apply to the compose and edit commands, too, if they exist. Note that
|
|
|
3111 this is NOT a test---it is a requirement for the environment in which
|
|
|
3112 the program will be executed, and should typically cause the creation of
|
|
|
3113 a terminal window when not executed on either a real terminal or a
|
|
|
3114 terminal window.
|
|
|
3115 @item
|
|
|
3116 The "copiousoutput" field indicates that the output from the
|
|
|
3117 view-command will be an extended stream of output, and is to be
|
|
|
3118 interpreted as advice to the UA (User Agent mail- reading program) that
|
|
|
3119 the output should be either paged or made scrollable. Note that it is
|
|
|
3120 probably a mistake if needsterminal and copiousoutput are both
|
|
|
3121 specified.
|
|
|
3122 @item
|
|
|
3123 The "description" field simply provides a textual description,
|
|
|
3124 optionally quoted, that describes the type of data, to be used
|
|
|
3125 optionally by mail readers that wish to describe the data before
|
|
|
3126 offering to display it.
|
|
|
3127 @item
|
|
|
3128 The "x11-bitmap" field names a file, in X11 bitmap (xbm) format, which
|
|
|
3129 points to an appropriate icon to be used to visually denote the presence
|
|
|
3130 of this kind of data.
|
|
|
3131 @item
|
|
|
3132 Any other fields beginning with "x-" may be included for local or
|
|
|
3133 mailer-specific extensions of this format. Implementations should
|
|
|
3134 simply ignore all such unrecognized fields to permit such extensions,
|
|
|
3135 some of which might be standardized in a future version of this
|
|
|
3136 document.
|
|
|
3137 @end itemize
|
|
|
3138
|
|
|
3139 @node General Index, Key Index, Mailcap Files, Top
|
|
|
3140 @appendix General Index
|
|
|
3141 @printindex fn
|
|
|
3142 @node Key Index, , General Index, Top
|
|
|
3143 @appendix Key Index
|
|
|
3144 @printindex ky
|
|
|
3145 @contents
|
|
|
3146 @bye
|
