comparison man/hm--html-mode.texi @ 42:8b8b7f3559a2 r19-15b104

Import from CVS: tag r19-15b104
author cvs
date Mon, 13 Aug 2007 08:54:51 +0200
parents
children 6a22abad6937
comparison
equal deleted inserted replaced
41:5d6df4963a99 42:8b8b7f3559a2
1 \input texinfo @c -*-texinfo-*-
2 @comment %**start of header (This is for running Texinfo on a region.)
3 @setfilename hm--html-mode.info
4 @settitle HM HTML Mode
5 @setchapternewpage odd
6 @comment %**end of header (This is for running Texinfo on a region.)
7 @comment $Id: hm--html-mode.texi,v 1.1 1997/03/23 00:28:12 steve Exp $
8 @ifinfo
9 This file documents the Elisp package @code{hm--html-menus}.
10
11 Copyright @copyright{} 1997 Heiko Münkel
12
13 Permission is granted to make and distribute verbatim copies of
14 this manual provided the copyright notice and this permission notice
15 are preserved on all copies.
16
17 @ignore
18 Permission is granted to process this file through TeX and print the
19 results, provided the printed document carries a copying permission
20 notice identical to this one except for the removal of this paragraph
21 (this paragraph not being relevant to the printed manual).
22
23 @end ignore
24 Permission is granted to copy and distribute modified versions of this
25 manual under the conditions for verbatim copying, provided also that the
26 sections entitled ``Distribution'' and ``General Public License'' are
27 included exactly as in the original, and provided that the entire
28 resulting derived work is distributed under the terms of a permission
29 notice identical to this one.
30
31 Permission is granted to copy and distribute translations of this manual
32 into another language, under the above conditions for modified versions,
33 except that the sections entitled ``Distribution'' and ``General Public
34 License'' may be included in a translation approved by the author instead
35 of in the original English.
36
37 @end ifinfo
38 @iftex
39 @input umlaute.texinfo
40 @end iftex
41 @titlepage
42 @sp 10
43 @center @titlefont{The Elisp Package hm---html-menus}
44
45 @sp 4
46 @center by Heiko Münkel
47 @sp 4
48 @center Version 5.4, March 1997
49 @page
50 @vskip 0pt plus 1filll
51 Copyright @copyright{} 1997 Heiko Münkel
52 @sp 4
53 Permission is granted to make and distribute verbatim copies of
54 this manual provided the copyright notice and this permission notice
55 are preserved on all copies.
56
57 @ignore
58 Permission is granted to process this file through TeX and print the
59 results, provided the printed document carries a copying permission
60 notice identical to this one except for the removal of this paragraph
61 (this paragraph not being relevant to the printed manual).
62
63 @end ignore
64 Permission is granted to copy and distribute modified versions of this
65 manual under the conditions for verbatim copying, provided also that the
66 sections entitled ``Distribution'' and ``General Public License'' are
67 included exactly as in the original, and provided that the entire
68 resulting derived work is distributed under the terms of a permission
69 notice identical to this one.
70
71 Permission is granted to copy and distribute translations of this manual
72 into another language, under the above conditions for modified versions,
73 except that the sections entitled ``Distribution'' and ``General Public
74 License'' may be included in a translation approved by the author instead
75 of in the original English.
76
77 @end titlepage
78
79 @comment The Top node contains the master menu for the Info file.
80 @comment This appears only in the Info file, not in the printed manual.
81
82 @node Top, License, (dir), (dir)
83 @comment node-name, next, previous, up
84
85
86
87 @menu
88 * License:: Your rights
89 * Overview:: Overview
90 * Distribution:: How to get the latest version
91 * Installation:: How to install the package
92 * Customization:: How to customize the package
93 * Add New Elements:: How to add new HTML elements
94 * Use With psgml-html:: Use this package as an add-on minor mode
95 * Internal Drag And Drop:: The HTML independent drag and drop package
96 * Template Minor Mode:: The HTML independent template package
97 * Bug Reports:: How and to whom you should send bug reports
98 * Concept Index:: Concept Index
99 * Function Index:: Function Index
100 * Variable Index:: Variable Index
101 @end menu
102
103
104 @node License, Overview, Top, Top
105 @comment node-name, next, previous, up
106 @chapter License
107 @cindex license to copy hm---html-menus
108 @cindex General Public License
109 Copyright (C) 1993 - 1997 Heiko Münkel, muenkel@@tnt.uni-hannover.de
110 @sp 2
111 This program is free software; you can redistribute it and/or modify
112 it under the terms of the GNU General Public License as published by
113 the Free Software Foundation; either version 2, or (at your option)
114 any later version.
115
116 This program is distributed in the hope that it will be useful,
117 but WITHOUT ANY WARRANTY; without even the implied warranty of
118 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
119 GNU General Public License for more details.
120
121 You should have received a copy of the GNU General Public License
122 along with this program; if not, write to the Free Software
123 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
124
125
126 @node Overview, Distribution, License, Top
127 @comment node-name, next, previous, up
128 @chapter Overview
129 @cindex overview
130 @cindex version
131 @findex hm--html-mode
132 @findex hm--html-minor-mode
133
134 This document describes the Elisp package @emph{hm---html-menus 5.4}.
135
136 The version of the document is:@*
137 $Id: hm--html-mode.texi,v 1.1 1997/03/23 00:28:12 steve Exp $
138
139 The package provides commands and various popup and pulldown menus for
140 a HTML mode called @dfn{hm---html-mode}, a mode for writing HTML pages
141 for the World Wide Web (WWW). It provides also a minor mode
142 (@dfn{hm---html-minor-mode}), which can be used together with another
143 HTML major mode, like the psgml-html modes in the XEmacs 19.14.
144
145 You can easily view the HTML documents by calling the browsers w3 (a
146 nice elisp package from William M. Perry), Netscape or Mosaic direct
147 from the pulldown menu of the mode.
148
149 An integrated (emacs internal) drag and drop interface makes it
150 very easy to insert links or images, by just clicking on them.
151
152 If it makes sense, then the commands are working also on selected
153 regions. You'll see the same menu items and can use the same
154 keystrokes, regardless if the region is activated or not, but if it's
155 activated, then the commands are working on the region. Therefore, you
156 don't need to learn different menus or keys for similar functions!
157
158 One major design issue of the package was to make it easier to write a
159 HTML page, even if you don't know much about HTML. For that I've tried
160 to put more knowledge about HTML, URL's and so on in it as an SGML based
161 mode could find out from a DTD file. In most cases the user gets help to
162 construct a specific link by examples or by a completion list with
163 possible input strings. And you can choose between an expert popup menu
164 and an novice popup menu interactively. The novice menu contains only
165 the basic HTML elements, so that you're not bothered by the quantity of
166 different HTML elements. And if you want to use more HTML elements, then
167 you could easily switch to the expert menus.
168
169 You can configure the html mode with a special configuration file for
170 your site and with another file specific for a user. Look at the
171 customization chapter for this, @xref{Customization, Customization}.
172
173
174 @node Distribution, Installation, Overview, Top
175 @comment node-name, next, previous, up
176 @chapter Distribution
177 The name of the distribution file is
178 @file{hm--html-menus-<version>.tar.gz}, where @var{<version>} is the
179 version number. The package is part of the XEmacs. You should find the
180 latest version of the package always on the following ftp server:
181
182 @display
183 @emph{ftp.tnt.uni-hannover.de} in @file{/pub/editors/xemacs/contrib}
184 @end display
185
186 You should also find the package in the USA on the ftp server
187 (which is mirrored on many other servers in the world):
188
189 @display
190 @emph{sunsite.unc.edu} in @file{/pub/Linux/apps/editors/emacs}
191 @end display
192
193 @menu
194 * Contents:: Contents of the distribution
195 @end menu
196
197 @node Contents, , Distribution, Distribution
198 @comment node-name, next, previous, up
199 @section Contents
200 @cindex contents
201
202 The package consists of the following files:
203
204 @table @file
205 @item README
206 Please, read this first.
207 @itemx README-EMACS-19
208 Some special hints only for the GNU Emacs 19 users.
209 @itemx ANNOUNCEMENT
210 Text of the announcement of this package.
211 @itemx LSM
212 Entry for the Linux Software Map.
213 @itemx NEWS
214 The NEWS and Change log file.
215 @itemx adapt.el
216 Provides (emulates XEmacs) functions for the use of this package with
217 the GNU Emacs 19.
218 @itemx hm--html.el
219 Provides functions to write html pages. It defines all commands which
220 inserts html elements and entities.
221 @itemx hm--html-indentation.el
222 Provides the lisp code for the indentation.
223 @itemx hm--html-keys.el
224 Defines the key bindings.
225 @itemx hm--html-menu.el
226 Provides the menus.
227 @itemx hm--html-mode.el
228 Provides the functions for the definition of the hm--html-mode and the
229 hm--html-minor-mode. This is the main file of the package.
230 @itemx hm--html-not-standard.el
231 Provides functions to insert some non standard html elements. This file
232 is not evaluated by default and it may be a bad idea to use it.
233 @itemx hm--html-configuration.el
234 Configuration file for the html mode. All the user variables are defined
235 in this file.
236 @itemx hm--html-drag-and-drop.el
237 Defines the HTML- specific functions for the drag and drop interface.
238 @itemx hm--date.el
239 Defines the function hm--date, which returns the date in the format
240 "day-month-year" like "30-Jun-1993".
241 @itemx html-view.el
242 Ron Tapia's html-view.el to view html-pages in the Mosaic. It is
243 patched for the use with the xemacs.
244 @itemx internal-drag-and-drop.el
245 Provides the general (html mode independent functions) of the drag and
246 drop interface.
247 @itemx templates.doc
248 Describes the syntax of the templates provided in the file
249 @file{tmpl-minor-mode.el}
250 @itemx tmpl-minor-mode.el
251 Provides functions for the tmpl-minor-mode. With this mode you can
252 expand templates, which are described in the file
253 @file{templates-syntax.doc} (look at the files
254 @file{command-description.html.tmpl} and @file{frame.html.tmpl} for
255 examples). Templates can be expanded automatically, if you include a
256 file with templates via the html pulldown menu item "Templates ..." or
257 with the item "Templates (fixed dirs)...".
258 @itemx command-description.html.tmpl
259 Template file for the use with the tmpl-minor-mode.
260 @itemx frame.html.tmpl
261 Template file, provides a simple frame.
262 @itemx doc/hm--html-mode.texinfo
263 Package documentation in the Texinfo format.
264 @itemx doc/umlaute.texinfo
265 Texinfo include file for german vowel mutation (deutsche Umlaute).
266 @end table
267
268 @node Installation, Customization, Distribution, Top
269 @comment node-name, next, previous, up
270 @chapter Installation
271 @cindex installation
272
273
274 @enumerate
275 @item Put all the *.el files in one of your xemacs (or emacs) lisp load
276 directories (i.e. site-lisp/hm--html-menus).
277
278 @item Put the following in your .emacs (or default.el or site-init.el):
279 @lisp
280 (autoload 'hm--html-mode "hm--html-mode" "HTML major mode." t)
281 (autoload 'hm--html-minor-mode "hm--html-mode" "HTML minor mode." t)
282 (or (assoc "\\.html$" auto-mode-alist)
283 (setq auto-mode-alist (cons '("\\.html$" . hm--html-mode)
284 auto-mode-alist)))
285
286 (autoload 'tmpl-expand-templates-in-buffer "tmpl-minor-mode"
287 "Expand all templates in the current buffer." t)
288
289 (autoload 'html-view-start-mosaic "html-view" "Start Xmosaic." t)
290 (autoload 'html-view-view-buffer
291 "html-view"
292 "View the current buffer in Xmosaic."
293 t)
294 (autoload 'html-view-view-file
295 "html-view"
296 "View a file in Xmosaic."
297 t)
298 (autoload 'html-view-goto-url
299 "html-view"
300 "Goto url in Xmosaic."
301 t)
302 (autoload 'html-view-get-display
303 "html-view"
304 "Get the display for Xmosaic (i.e. hostxy:0.0)."
305 t)
306 @end lisp
307
308 The above lines assume that you have not installed already another
309 html mode. If this isn't true, then you should use the following:
310 @lisp
311 (setq auto-mode-alist (cons '("\\.html$" . hm--html-mode)
312 auto-mode-alist))
313 @end lisp
314
315 instead of:
316 @lisp
317 (or (assoc "\\.html$" auto-mode-alist)
318 (setq auto-mode-alist (cons '("\\.html$" . hm--html-mode)
319 auto-mode-alist)))
320 @end lisp
321 If you want to use the hm---html-minor-mode together
322 with the psgml-html modes, then you should add the following
323 line (works only in XEmacs version >= 19.15 and != 20.0):
324 @lisp
325 (add-hook 'html-mode-hook 'hm--html-minor-mode)
326 @end lisp
327 @end enumerate
328
329 @node Customization, Add New Elements, Installation, Top
330 @comment node-name, next, previous, up
331 @chapter Customization
332 @cindex customization
333 @cindex configuration
334
335 You should be able to use the package after it's installation without
336 any further customization. But it contains a lot of user variables to
337 adapt the package better to your special needs. How to do this is
338 described in this chapter.
339
340 @menu
341 * Customization (Configuration) Files::
342 * Customization Variables::
343 @end menu
344
345 @node Customization (Configuration) Files, Customization Variables, Customization, Customization
346 @comment node-name, next, previous, up
347 @section Customization (Configuration) Files
348 @cindex customization files
349 @cindex configuration files
350
351 This package uses 3 different files to customize the mode, but you must
352 not use all of them. Only one of them, the file
353 @file{hm--html-configuration.el} is delivered together with the package.
354 The reason for three different files is to provide the possibility to
355 have different customization for the package, the site and the
356 user. There's also a pulldown menu item to reload all customization
357 files. The files are described in the following sections.
358
359 @menu
360 * Where Are All The Customization Variables Defined::
361 * Where To Put Site Specific Customization::
362 * Where To Put User Specific Customization::
363 @end menu
364
365 @node Where Are All The Customization Variables Defined, Where To Put Site Specific Customization, Customization (Configuration) Files, Customization (Configuration) Files
366 @comment node-name, next, previous, up
367 @subsection Where Are All The Customization Variables Defined
368 @cindex package specific customization
369 @cindex hm--configuration.el
370 @vindex HTML_CONFIG_FILE
371
372 All variables, which can be used to customize the mode, are defined in
373 the package configuration file @file{hm--configuration.el}. You should
374 take a look at this file, if you don't find how to customize a feature
375 in this documentation (the documentation of a program is never as
376 complete as it's program code :-).
377
378 This file is searched in one of your lisp load directories. You can
379 change this by setting the environment variable @code{HTML_CONFIG_FILE}
380 to another file. But I don't recommend this.
381
382 @emph{Note}: This file is loaded before the other customization files,
383 so that it's definitions could be overwritten. All variables are set by
384 @code{defvar}, so that it's values could also be overwritten with
385 @code{setq} in any standard emacs customization files (i.e. in
386 @file{.emacs}).
387
388
389 @node Where To Put Site Specific Customization, Where To Put User Specific Customization, Where Are All The Customization Variables Defined, Customization (Configuration) Files
390 @comment node-name, next, previous, up
391 @subsection Where To Put Site Specific Customization
392 @cindex site specific customization
393 @cindex hm--site-configuration-file.el
394 @vindex HTML_SITE_CONFIG_FILE
395 @vindex hm--html-site-config-file
396
397 In general all users at a site are writing there html pages for the same
398 WWW server. Therefore it is very likely, that most of the customizations
399 are site specific and only a few are user specific. But however, you
400 don't have to use a site specific customization, if you don't like it.
401
402 If you'd like to make a site specific customization of the
403 @code{hm--html-mode}, then it's possible to put it in a special file
404 called @file{hm--site-configuration-file.el}. If you do this, you've to
405 set either the lisp variable @code{hm--html-site-config-file} or the
406 environment variable @code{HTML_SITE_CONFIG_FILE} to the file and it's
407 path. If you write the filename without it's extension (.el), the emacs
408 tries to load at first a compiled version of the file.
409
410 The environment variables overwrites the lisp variable.
411
412 You can also put the site specific customization in any standard emacs
413 customization files like @file{default.el}. But an advantage, if you
414 use @file{hm--site-configuration-file.el} is, that it is very likely,
415 that you can use this file also together with future versions of the
416 package. I'll try to make it as backward compatible as possible.
417
418 @emph{Note}: This file is loaded after the package customization file
419 and before the user customization file.
420
421 @node Where To Put User Specific Customization, , Where To Put Site Specific Customization, Customization (Configuration) Files
422 @comment node-name, next, previous, up
423 @subsection Where To Put User Specific Customization
424 @cindex user specific customization
425 @cindex ~/.hm--configuration-file.el
426 @vindex HTML_USER_CONFIG_FILE
427 @vindex hm--html-user-config-file
428
429 User specific customization can be put in the file
430 @file{.hm--configuration-file.el}, which is searched by default in the
431 home directory of the user. This can be overwritten by setting either
432 the environment variable @code{HTML_USER_CONFIG_FILE} or the lisp
433 variable @code{hm--html-user-config-file} to the name of the file and
434 it's path. If you write the filename without it's extension (.el), the
435 emacs tries to load at first a compiled version of the file.
436
437 You can also put the user specific customization in your
438 @file{.emacs}. It's up to you, to decide which way is the better one.
439
440 @emph{Note}: This file is loaded after the package and the site specific
441 one. Therefore it overwrites all other customization files.
442
443
444 @node Customization Variables, , Customization (Configuration) Files, Customization
445 @comment node-name, next, previous, up
446 @section Customization Variables
447
448 In the following subsections the main customization variables are
449 described.
450
451 @menu
452 * User Name/Signature::
453 * Switching Between Expert And Novice Menus ::
454 * HTML Doctype::
455 * Defaults Used For Generating Links::
456 * Templates::
457 * Deleting Automounter Path Prefix::
458 * Automatic Insert Of Information::
459 * Latin 1 Characters::
460 * Drag And Drop::
461 * Font Lock Keywords::
462 * Prefix Keys::
463 * Pulldown Menu Names::
464 * Hook Variables::
465 * Previewing HTML Files::
466 * Meta Element::
467 * Indentation::
468 @end menu
469
470
471 @node User Name/Signature, Switching Between Expert And Novice Menus , Customization Variables, Customization Variables
472 @comment node-name, next, previous, up
473 @subsection User Name/Signature
474 @cindex user name
475 @cindex signature
476 @vindex hm--html-username
477 @vindex hm--html-signature-file
478
479 @itemize @bullet
480 @item
481 @code{hm--html-username}: Your real name. This is used as the name of
482 the signature links. You have only to specify it, if your name in the
483 file @file{/etc/passwd} isn't the one, you'd like to see in the html
484 files. Otherwise this could be set to nil.
485 @item
486 @code{hm--html-signature-file}: The link, used in your signature. In
487 general this should be a link to your home page.
488 @end itemize
489
490
491 @node Switching Between Expert And Novice Menus , HTML Doctype, User Name/Signature, Customization Variables
492 @comment node-name, next, previous, up
493 @subsection Switching Between Expert And Novice Menus
494 @cindex expert menus
495 @cindex novice menus
496 @vindex hm--html-expert
497
498 @itemize @bullet
499 @item
500 @code{hm--html-expert}: If you're a html novice and don't want to be
501 bothered with lot's of possible html elements, then you should use the
502 novice popup menus. For that you've to set this variable to @code{nil},
503 which is the default. But if you are more familiar with html and would
504 like to use more html elements, then you should use the expert menus and
505 set this variable to @code{t}.
506 @end itemize
507
508
509 @node HTML Doctype, Defaults Used For Generating Links, Switching Between Expert And Novice Menus , Customization Variables
510 @comment node-name, next, previous, up
511 @subsection HTML Doctype
512 @vindex hm--html-html-doctype-version
513 @cindex HTML doctype
514
515 @itemize @bullet
516 @item
517 @code{hm--html-html-doctype-version}: The HTML version. This is used in
518 the doctype element. Change this, if you use non HTML 3.2 elements. This
519 package (@xref{Overview, version}.) defines by default only HTML 3.2 elements.
520 @end itemize
521
522
523 @node Defaults Used For Generating Links, Templates, HTML Doctype, Customization Variables
524 @comment node-name, next, previous, up
525 @subsection Defaults Used For Generating Links
526 @cindex links
527
528 One of the main features of the @code{hm--html-mode} are the easy ways
529 to insert special links to html pages, ftp servers, news servers and so
530 on. I think, that most people will have their own (this may be site
531 specific, @xref{Where To Put Site Specific Customization, Where To Put
532 Site Specific Customization}.) favourite servers, directories and so
533 on. Therefore it should be useful to customize the default values and the
534 alists with useful alternatives, which are used from the mode in the
535 inserting functions for the links.
536
537 @menu
538 * Your Favourite HTTP Server::
539 * Links to WWW Server::
540 * Links To Files::
541 * Links To FTP Server::
542 * Links To Emacs Info Files::
543 * Links To Gopher Server::
544 * Links To WAIS Gateways::
545 * Links To The Mail Gateway::
546 * Links For Sending Mails::
547 * Links To The Program Gateway ::
548 * Links To The Local Program Gateway::
549 * URL For Forms And Image Tags::
550 * Marking Of Examples::
551 @end menu
552
553
554 @node Your Favourite HTTP Server, Links to WWW Server, Defaults Used For Generating Links, Defaults Used For Generating Links
555 @comment node-name, next, previous, up
556 @subsubsection Your Favourite HTTP Server
557 @cindex favourite HTTP server
558 @vindex hm--html-favorite-http-server-host-name
559
560 @itemize @bullet
561 @item
562 @code{hm--html-favorite-http-server-host-name}: The name of your
563 favorite http server host. It must be specified! This variable is used
564 in many other variables.
565 @end itemize
566
567
568 @node Links to WWW Server, Links To Files, Your Favourite HTTP Server, Defaults Used For Generating Links
569 @comment node-name, next, previous, up
570 @subsubsection Links to WWW Server
571 @cindex WWW server links
572 @cindex HTTP links
573 @vindex hm--html-html-hostname:port-default
574 @vindex hm--html-html-hostname:port-alist
575 @vindex hm--html-html-path-alist
576
577 @itemize @bullet
578 @item
579 @code{hm--html-html-hostname:port-default}: Default hostname with port
580 for http links to a HTML server.
581 @item
582 @code{hm--html-html-hostname:port-alist}: Alist with hostnames and ports
583 for http links to HTML servers. It contains useful alternatives.
584 @item
585 @code{hm--html-html-path-alist}: Alist with directories for the HTML
586 server. Each alist element must consist of a number and a directory
587 string. The number is used to select the directory during the query
588 about the directory for a http link.
589 @end itemize
590
591
592 @node Links To Files, Links To FTP Server, Links to WWW Server, Defaults Used For Generating Links
593 @comment node-name, next, previous, up
594 @subsubsection Links To Files
595 @cindex file gateway links
596 @vindex hm--html-file-path-alist
597
598 @itemize @bullet
599 @item
600 @code{hm--html-file-path-alist}: Alist with directories for the file
601 gateway.Each alist element must consist of a number and a directory
602 string. The number is used to select the directory during the query
603 about the directory for a file link.
604 @end itemize
605
606
607 @node Links To FTP Server, Links To Emacs Info Files, Links To Files, Defaults Used For Generating Links
608 @comment node-name, next, previous, up
609 @subsubsection Links To FTP Server
610 @cindex FTP links
611 @vindex hm--html-ftp-hostname:port-default
612 @vindex hm--html-ftp-hostname:port-alist
613 @vindex hm--html-ftp-path-alist
614
615 @itemize @bullet
616 @item
617 @code{hm--html-ftp-hostname:port-default}: Default hostname with port
618 for links to ftp server. This is the default FTP server. In general
619 you've not to specify a port for this.
620 @item
621 @code{hm--html-ftp-hostname:port-alist}: Alist with hostnames and ports
622 for links to ftp servers. It contains useful alternatives. In general
623 you've not to specify ports for the ftp servers.
624 @item
625 @code{hm--html-ftp-path-alist}: Alist with directories for the ftp
626 server links. It contains useful alternatives with /pub, /pub/gnu and
627 so on. Each alist element must consist of a number and a directory
628 string. The number is used to select the directory during the query
629 about the directory for a ftp link.
630 @end itemize
631
632
633 @node Links To Emacs Info Files, Links To Gopher Server, Links To FTP Server, Defaults Used For Generating Links
634 @comment node-name, next, previous, up
635 @subsubsection Links To Emacs Info Files
636 @cindex emacs info links
637 @vindex hm--html-info-hostname:port-alist
638 @vindex hm--html-info-hostname:port-default
639 @vindex hm--html-info-path-alist
640
641 @itemize @bullet
642 @item
643 @code{hm--html-info-hostname:port-default}: Default hostname with port
644 for the Info gateway.
645 @item
646 @code{hm--html-info-hostname:port-alist}: Alist with hostnames and ports
647 for the Info gateway. It contains useful alternatives.
648 @item
649 @code{hm--html-info-path-alist}: Alist with directories for the Info
650 gateway. This may be a list with all of your emacs info directories.
651 @end itemize
652
653
654 @node Links To Gopher Server, Links To WAIS Gateways, Links To Emacs Info Files, Defaults Used For Generating Links
655 @comment node-name, next, previous, up
656 @subsubsection Links To Gopher Server
657 @cindex Gopher gateway links
658 @vindex hm--html-gopher-hostname:port-default
659 @vindex hm--html-gopher-hostname:port-alist
660 @vindex hm--html-gopher-doctype-default
661 @vindex hm--html-gopher-doctype-alist
662 @vindex hm--html-gopher-anchor-alist
663
664 There are a lot of useful gopher information server in the Internet.
665 You can access them with a gopher browser or with a WWW browser. In the
666 second case you've to use the gopher gateway.
667
668 @itemize @bullet
669 @item
670 @code{hm--html-gopher-hostname:port-default}: Default hostname with port
671 for links to gopher server.
672 @item
673 @code{hm--html-gopher-hostname:port-alist}: Alist with hostnames and
674 ports for links to gopher server. It contains useful alternatives.
675 @item
676 @code{hm--html-gopher-doctype-default}: For gopher links you've to
677 specify the doctype. In most cases this should be the string \"/1\".
678 Therefore this is the default doctype, but you might change it to
679 another doctype.
680 @item
681 @code{hm--html-gopher-doctype-alist}: Alist with doctype strings for links
682 to gopher server. The strings \"/1\", \"/11\" and \"/00\" are the only
683 doctype strings that I know. Please let me know, if there are other
684 strings.
685 @item
686 @code{hm--html-gopher-anchor-alist}: Alist with directories for links to
687 gopher server. It contains useful alternatives on the main gopher
688 servers. Each alist element must consist of a number and a directory
689 string. The number is used to select the directory during the query
690 about the directory for a local program gateway link.
691 @end itemize
692
693
694 @node Links To WAIS Gateways, Links To The Mail Gateway, Links To Gopher Server, Defaults Used For Generating Links
695 @comment node-name, next, previous, up
696 @subsubsection Links To WAIS Gateways
697 @cindex WAIS gateway links
698 @vindex hm--html-wais-hostname:port-alist
699 @vindex hm--html-wais-hostname:port-default
700 @vindex hm--html-wais-servername:port-alist
701 @vindex hm--html-wais-servername:port-default
702 @vindex hm--html-wais-path-alist
703
704 You can either make a link direct to a WAIS server (it may be, that not
705 all WWW browsers support this), or a http link to a server (relay host)
706 which queries the WAIS server. The variables
707 @code{hm--html-wais-hostname:port-default} and
708 @code{hm--html-wais-hostname} refers to these relay hosts and the
709 variables @code{hm--html-wais-servername:port-default} and
710 @code{hm--html-wais-servername:port-alist} are refers to the WAIS servers.
711
712 @itemize @bullet
713 @item
714 @code{hm--html-wais-hostname:port-default}: Default hostname of the
715 relay host with port for the WAIS gateway.
716 @item
717 @code{hm--html-wais-hostname:port-alist}: Alist with hostnames of
718 possible relay hosts and ports for the WAIS gateway. It contains
719 useful alternatives.
720 @item
721 @code{hm--html-wais-servername:port-default}: Default WAIS servername
722 with port for the WAIS gateway.
723 @item
724 @code{hm--html-wais-servername:port-alist}: Alist with WAIS servernames
725 and ports for the WAIS gateway. It contains useful alternatives.
726 @item
727 @code{hm--html-wais-path-alist}: Alist with directories for the wais gateway.
728 @end itemize
729
730
731 @node Links To The Mail Gateway, Links For Sending Mails, Links To WAIS Gateways, Defaults Used For Generating Links
732 @comment node-name, next, previous, up
733 @subsubsection Links To The Mail Gateway
734 @cindex Mail gateway links
735 @cindex Mail folder links
736 @vindex hm--html-mail-hostname:port-default
737 @vindex hm--html-mail-hostname:port-alist
738 @vindex hm--html-mail-path-alist
739
740 The following variables are for customizing the insert of links to mail
741 folder. You need a special server for this, which sends the emails back
742 to the browser.
743
744 @itemize @bullet
745 @item
746 @code{hm--html-mail-hostname:port-default}: Default hostname with port
747 for the mail gateway.
748 @item
749 @code{hm--html-mail-hostname:port-alist}: Alist with hostnames and ports
750 for the mail gateway. It contains useful alternatives.
751 @item
752 @code{hm--html-mail-path-alist}: Alist with directories for the mail
753 gateway. In these directories you'll find probably mail folder. Each
754 alist element must consist of a number and a directory string. The
755 number is used to select the directory during the query about the
756 directory for a mail folder link.
757 @end itemize
758
759
760 @node Links For Sending Mails, Links To The Program Gateway , Links To The Mail Gateway, Defaults Used For Generating Links
761 @comment node-name, next, previous, up
762 @subsubsection Links For Sending Mails
763 @cindex mailto links
764 @vindex hm--html-mailto-alist
765
766 @itemize @bullet
767 @item
768 @code{hm--html-mailto-alist}: Alist with mail addresses for the mailto
769 alist. The value of `user-mail-address' will also be added by the
770 package to this alist.
771 @end itemize
772
773
774 @node Links To The Program Gateway , Links To The Local Program Gateway, Links For Sending Mails, Defaults Used For Generating Links
775 @comment node-name, next, previous, up
776 @subsubsection Links To The Program Gateway
777 @cindex program gateway links
778 @vindex hm--html-proggate-hostname:port-default
779 @vindex hm--html-proggate-hostname:port-alist
780 @vindex hm--html-proggate-allowed-file
781
782 The program gateway is a special TNT site specific gateway for starting
783 programs out of a html page. The programs are started by a special
784 server, which looks in an allowed file, to determine if it is allowed to
785 start the program. This is necessary, because the programs are running
786 under the user id of the server. We've only allowed to start simple
787 display programs like man, ls and so on.
788
789 @itemize @bullet
790 @item
791 @code{hm--html-proggate-hostname:port-default}: Default hostname with
792 port for the proggate server.
793 @item
794 @code{hm--html-proggate-hostname:port-alist}: Alist with hostnames and
795 ports for the proggate server. It contains useful alternatives.
796 @item
797 @code{hm--html-proggate-allowed-file}: The filename (with path) of the
798 proggate allowed file.
799 @end itemize
800
801
802 @node Links To The Local Program Gateway, URL For Forms And Image Tags, Links To The Program Gateway , Defaults Used For Generating Links
803 @comment node-name, next, previous, up
804 @subsubsection Links To The Local Program Gateway
805 @cindex local program gateway links
806 @vindex hm--html-local-proggate-path-alist
807
808 Another TNT site specific way to start programs from a html page. These
809 programs are started with the id of the user on the host where the
810 client (browser) is running. Therefore no restriction about the allowed
811 programs is made. With this you can start only programs and do only
812 things, which you can do also without the WWW browser.
813
814 @itemize @bullet
815 @item
816 @code{hm--html-local-proggate-path-alist}: Alist with directories for
817 the local program gateway. Contains directories, where you can find
818 programs.
819 @end itemize
820
821
822 @node URL For Forms And Image Tags, Marking Of Examples, Links To The Local Program Gateway, Defaults Used For Generating Links
823 @comment node-name, next, previous, up
824 @subsubsection URL For Forms And Image Tags
825 @cindex forms URL
826 @cindex image URL
827 @vindex hm--html-url-alist
828
829 @itemize @bullet
830 @item
831 @code{hm--html-url-alist}: Alist with URL's for FORMS and IMAGE tags.
832 The cdr of each list contains symbols, which specifies the use of the
833 URL.
834 @end itemize
835
836
837 @node Marking Of Examples, , URL For Forms And Image Tags, Defaults Used For Generating Links
838 @comment node-name, next, previous, up
839 @subsubsection Marking Of Examples
840 @cindex color of help text
841 @cindex font of help text
842 @vindex hm--html-help-foreground
843 @vindex hm--html-help-background
844 @vindex hm--html-help-font
845
846 The following variables are for marking the examples in the help
847 buffer.
848
849 @itemize @bullet
850 @item
851 @code{hm--html-help-foreground}: The foreground color for highlighting
852 examples.
853 @item
854 @code{hm--html-help-background}: The background color for highlighting
855 examples.
856 @item
857 @code{hm--html-help-font}: The font for highlighting examples.
858 @end itemize
859
860
861 @node Templates, Deleting Automounter Path Prefix, Defaults Used For Generating Links, Customization Variables
862 @comment node-name, next, previous, up
863 @subsection Templates
864 @cindex templates
865 @vindex hm--html-template-dir
866 @vindex hm--html-frame-template-file
867 @vindex hm--html-automatic-expand-templates
868
869 For inserting html template files you can customize, where you've your
870 templates.
871
872 @itemize @bullet
873 @item
874 @code{hm--html-template-dir}: A directory with template files. It is now
875 also possible to use it as a list of directories. Look at the variable
876 @code{tmpl-template-dir-list} for further descriptions. If this
877 variable is set to a non existing directory, than it is set to a
878 directory, where the package in the XEmacs is. This is done during
879 loading the file @file{hm--html-configuration.el} (@xref{Where Are All
880 The Customization Variables Defined, Where Are All The Customization
881 Variables Defined}.). This may only be useful, in the XEmacs >= 19.12.
882 @item
883 @code{hm--html-frame-template-file}: File, which is used as template for
884 a html frame. Such a file is in the package
885 @emph{hm--html-menus}. @xref{Contents, Contents}.
886 @item
887 @code{hm--html-automatic-expand-templates}: Automatic expansion of
888 templates. This feature needs the file @file{tmpl-minor-mode.el} from Heiko
889 Münkel (@cite{muenkel@@tnt.uni-hannover.de}), which is distributed with the
890 package hm--html-menus.
891 @item
892 @code{hm--html-template-filter-regexp}: Regexp for filtering out non
893 (html) template files in a directory.
894 @end itemize
895
896
897 @node Deleting Automounter Path Prefix, Automatic Insert Of Information, Templates, Customization Variables
898 @comment node-name, next, previous, up
899 @subsection Deleting Automounter Path Prefix
900 @cindex automounter path
901 @vindex hm--html-delete-wrong-path-prefix
902
903 @itemize @bullet
904 @item
905 @code{hm--html-delete-wrong-path-prefix}: If non nil, it specifies path-prefixes, which should be deleted in paths.
906 The Sun automounter adds a temporary prefix to the automounted directories
907 (At our site the prefix is /tmp_mnt). But you can't select such a path,
908 if the automounter has currently not mounted the directory and so you
909 can't follow a html-link, which consists of such a path. To overcome
910 this behaviour, you can set this variable to the prefix
911 (eg "/tmp_mnt"). After that, the prefix should be stripped from the
912 paths during the creation of the links. ATTENTION: This variable is
913 used as regular expression ! It can be set to a string or to a list of
914 strings.
915 @end itemize
916
917 @node Automatic Insert Of Information, Latin 1 Characters, Deleting Automounter Path Prefix, Customization Variables
918 @comment node-name, next, previous, up
919 @subsection Automatic Insert Of Information
920 @cindex automatic insert
921 @cindex date
922 @cindex changed comment
923 @cindex created comment
924 @vindex hm--html-automatic-new-date
925 @vindex hm--html-automatic-changed-comment
926 @vindex hm--html-automatic-created-comment
927
928 The @code{hm--html-mode} automatic inserts some useful informations in
929 html pages. This behaviour could be changed by the following variables.
930
931 @itemize @bullet
932 @item
933 @code{hm--html-automatic-new-date}: t => The date in the title line will
934 be updated before file saving. nil => No automatic update of the date.
935 @item
936 @code{hm--html-automatic-changed-comment}: t => A "changed comment"
937 line will be added before file saving. nil => No automatic insert
938 of a "changed comment" line.
939 @item
940 @code{hm--html-automatic-created-comment}: t => A "created comment"
941 line will be added. nil => No automatic insert of a "created
942 comment" line.
943 @end itemize
944
945
946 @node Latin 1 Characters, Drag And Drop, Automatic Insert Of Information, Customization Variables
947 @comment node-name, next, previous, up
948 @subsection Latin 1 Characters
949 @cindex latin 1 characters
950 @vindex hm--html-bind-latin-1-char-entities
951
952 @itemize @bullet
953 @item
954 @code{hm--html-bind-latin-1-char-entities}: Set this to nil, if you
955 don't want to use the ISO Latin 1 character entities. This is only
956 useful, if `hm--html-use-old-keymap' is set to nil. It is only used
957 during loading the html package the first time.
958 @end itemize
959
960
961 @node Drag And Drop, Font Lock Keywords, Latin 1 Characters, Customization Variables
962 @comment node-name, next, previous, up
963 @subsection Drag And Drop
964 @cindex drag and drop
965 @vindex hm--html-idd-create-relative-links
966 @vindex hm--html-idd-actions
967
968 @itemize @bullet
969 @item
970 @code{hm--html-idd-create-relative-links}: If t, then the
971 @code{hm--html-idd-*} functions are creating relative links. Otherwise
972 absolute links are used. The idd functions are used for drag and drop.
973 @item
974 @code{hm--html-idd-actions}: The action list for the destination mode
975 @code{hm--html-mode}. Look at the description of the variable
976 idd-actions.
977 @end itemize
978
979
980 @node Font Lock Keywords, Prefix Keys, Drag And Drop, Customization Variables
981 @comment node-name, next, previous, up
982 @subsection Font Lock Keywords
983 @cindex font lock keywords
984 @vindex hm--html-font-lock-keywords-1
985 @vindex hm--html-font-lock-keywords-2
986 @vindex hm--html-font-lock-keywords
987
988 @itemize @bullet
989 @item
990 @code{hm--html-font-lock-keywords-1}: Subdued level highlighting for
991 @code{hm--html-mode}.
992 @item
993 @code{hm--html-font-lock-keywords-2}: Gaudy level highlighting for
994 @code{hm--html-mode}.
995 @item
996 @code{hm--html-font-lock-keywords}: Default expressions to highlight in
997 the @code{hm--html-mode}.
998 @end itemize
999
1000
1001 @node Prefix Keys, Pulldown Menu Names, Font Lock Keywords, Customization Variables
1002 @comment node-name, next, previous, up
1003 @subsection Prefix Keys
1004 @cindex prefix keys
1005 @kindex prefix keys
1006 @vindex hm--html-minor-mode-prefix-key
1007 @vindex hm--html-mode-prefix-key
1008
1009 @itemize @bullet
1010 @item
1011 @code{hm--html-minor-mode-prefix-key}: The prefix key for the key tables
1012 in the @code{hm--html-minor-mode}.
1013 @item
1014 @code{hm--html-mode-prefix-key}: The prefix key for the hm--html keys in
1015 the @code{hm--html-mode}.
1016 @end itemize
1017
1018
1019 @node Pulldown Menu Names, Hook Variables, Prefix Keys, Customization Variables
1020 @comment node-name, next, previous, up
1021 @subsection Pulldown Menu Names
1022 @cindex pulldown menu names
1023 @vindex hm--html-minor-mode-pulldown-menu-name
1024 @vindex hm--html-mode-pulldown-menu-name
1025
1026 It may be, that You'd like to change the names to get the same menu
1027 names in the major and in the minor modes of the @code{hm--html-menus}
1028 package.
1029
1030 @itemize @bullet
1031 @item
1032 @code{hm--html-mode-pulldown-menu-name}: The name of the pulldown menu
1033 in the major html mode.
1034 @item
1035 @code{hm--html-minor-mode-pulldown-menu-name}: The name of the pulldown
1036 menu in the minor html mode.
1037 @end itemize
1038
1039
1040 @node Hook Variables, Previewing HTML Files, Pulldown Menu Names, Customization Variables
1041 @comment node-name, next, previous, up
1042 @subsection Hook Variables
1043 @vindex hm--html-mode-hook
1044
1045 You may use the following two variables, if you'd like to call special
1046 functions each time the major html mode is entered or the package is
1047 loaded.
1048
1049 @itemize @bullet
1050 @item
1051 @code{hm--html-mode-hook}: This hook will be called each time, when the
1052 @code{hm--html-mode} is invoked.
1053 @item
1054 @code{hm--html-load-hook}: Hook variable to execute functions after
1055 loading the package
1056 @end itemize
1057
1058
1059 @node Previewing HTML Files, Meta Element, Hook Variables, Customization Variables
1060 @comment node-name, next, previous, up
1061 @subsection Previewing HTML Files
1062 @cindex previewing HTML files
1063 @vindex html-view-mosaic-command
1064 @vindex html-sigusr1-signal-value
1065
1066 The following two variables are only used, if you preview the html
1067 documents with @code{Mosaic}. There are also some other variables in
1068 @file{hmtl-view.el}, @xref{Contents, Contents}. Look at that file, if
1069 you've trouble with the functions to preview the html document with the
1070 @code{Mosaic}.
1071
1072 @itemize @bullet
1073 @item
1074 @code{html-view-mosaic-command}: The command that runs @code{Mosaic} on your
1075 system.
1076 @item
1077 @code{html-sigusr1-signal-value}: Value for the SIGUSR1 signal on your
1078 system. See, usually, @file{/usr/include/sys/signal.h}.
1079 @example
1080 SunOS 4.1.x : (setq html-sigusr1-signal-value 30)
1081 SunOS 5.x : (setq html-sigusr1-signal-value 16)
1082 Linux : (setq html-sigusr1-signal-value 10))
1083 @end example
1084 @end itemize
1085
1086
1087 @node Meta Element, Indentation, Previewing HTML Files, Customization Variables
1088 @comment node-name, next, previous, up
1089 @subsection Meta Element
1090 @cindex meta element
1091 @vindex hm--html-meta-name-alist
1092
1093 @itemize @bullet
1094 @item
1095 @code{hm--html-meta-name-alist}: Alist with possible names for the name
1096 or http-equiv attribute of meta. Currently I know of the names
1097 @code{Expires}, @code{Keys} and @code{Author}. Please send me
1098 (@emph{muenkel@@tnt.uni-hannover.de}) an email, if you know other
1099 standard html names for the meta element.
1100 @end itemize
1101
1102
1103 @node Indentation, , Meta Element, Customization Variables
1104 @comment node-name, next, previous, up
1105 @subsection Indentation
1106 @cindex indentation
1107 @vindex hm--html-disable-indentation
1108 @vindex hm--html-inter-tag-indent
1109 @vindex hm--html-comment-indent
1110 @vindex hm--html-intra-tag-indent
1111 @vindex hm--html-tag-name-alist
1112
1113 @itemize @bullet
1114 @item
1115 @code{hm--html-disable-indentation}: Set this to t, if you want to
1116 disable the indentation in the @code{hm--html-mode}. And may be send me
1117 (@emph{muenkel@@tnt.uni-hannover.de}) a note, why you've done this.
1118 @item
1119 @code{hm--html-inter-tag-indent}: The indentation after a start tag.
1120 @item
1121 @code{hm--html-comment-indent}: The indentation of a comment.
1122 @item
1123 @code{hm--html-intra-tag-indent}: The indentation after the start of a
1124 tag.
1125 @item
1126 @code{hm--html-tag-name-alist}: An alist with tag names known by the
1127 @code{hm--html-mode}. It is used to determine, if a tag is a one element
1128 tag or not. In the future it should also be used to get possible
1129 parameters of the tag. Use lower case characters in this list!!!! If
1130 you've problems with the indentation of
1131 @code{:hm--html-one-or-two-element-tag} elements, then you should set
1132 them to either @code{:hm--html-one-element-tag} or
1133 @code{:hm--html-two-element-tag}, depending on how you use these
1134 elements. In the future I'll try to implement a better indentation for
1135 these elements.
1136 @end itemize
1137
1138
1139 @node Add New Elements, Use With psgml-html, Customization, Top
1140 @comment node-name, next, previous, up
1141 @chapter Add New Elements
1142 @cindex add new html elements
1143 @cindex non standard html
1144 @vindex hm--html-tag-name-alist
1145
1146 If you'd like to add new HTML elements to this package, you should take
1147 at first a look at the file @file{hm--html-not-standard.el}, which
1148 contains already some non standard elements. If you find your tags
1149 there, you should uncomment the line @code{(require
1150 'hm--html-not-standard)} in the file @file{hm--html-mode.el}. There are
1151 also menu entries for these elements in the file
1152 @file{hm--html-menu.el}, which are commented out. Don't forget to
1153 recompile the changed lisp files after that!
1154
1155 If you don't find your new elements there, you should do the following
1156 steps to add them:
1157
1158 @enumerate
1159 @item
1160 Search a tag, which is similar to the one you want to add. Similar
1161 means, that it is inserted in the way you want to insert the new
1162 tags. Now let's assume, that you chose @samp{<strong></strong>}.
1163 @item
1164 Look at the file @file{hm--html.el} and search the function(s) which
1165 inserts the "similar tags". If the HTML element consists of only one
1166 tag, then there should be only one function for inserting the tag. If
1167 the element consists of a start and an end tag, there are at least two
1168 functions. Only in some special cases, if it is possible to insert
1169 elements with different attribute values, there are more than two
1170 functions. In the case of @samp{<strong></strong>}, there are the two
1171 functions @code{hm--html-add-strong} and
1172 @code{hm--html-add-strong-to-region}. The first one is used, if no
1173 region is active and the second if a region is active. The naming scheme
1174 of these functions are always @var{hm--html-add-<tagname>} and
1175 @var{hm--html-add-<tagname>-to-region}. @var{<tagname>} is not in all
1176 cases the tagname. Sometimes a more human readable name is used (eg:
1177 bold instead of b).
1178 @item
1179 To get the right indentation for the new tags you should add an entry
1180 for it to the variable @code{hm--html-tag-name-alist}, which is defined
1181 in @file{hm--html-configuration.el}. Lets assume, that the new tagname
1182 is @samp{foo}, then the entry in @code{hm--html-tag-name-alist} should
1183 be
1184 @lisp
1185 ("foo" (:hm--html-one-element-tag t))
1186 @end lisp
1187 if the new element consists only of one tag (@samp{img} is such an
1188 element) or
1189 @lisp
1190 ("foo" (:hm--html-two-element-tag t))
1191 @end lisp
1192 if the new element consists of two tags (@samp{strong} is such an
1193 element) or
1194 @lisp
1195 ("foo" (:hm--html-one-or-two-element-tag t))
1196 @end lisp
1197 if the new element consists of two tags, but it is allowed to use the
1198 start tag without it's end tag (@samp{p} is such an element).
1199 @end enumerate
1200
1201 Now you are ready and able to insert the new tags with
1202 @example
1203 M-x hm--html-add-foo
1204 @end example
1205 and
1206 @example
1207 M-x hm--html-add-foo-to-region
1208 @end example
1209
1210 But if you want to add the new commands also to the popup menu,
1211 then you've to take a look at @file{hm--html-menu.el}, where all the
1212 menus are defined. Look at @code{hm--html-menu-noregion-expert} and
1213 @code{hm--html-menu-region-expert}. The first one is used, if no region is
1214 active and the second, if a region is active (both are only used,
1215 if the "expert menus" are used; this is an option in the pulldown
1216 menu). You should now add an entry like
1217 @lisp
1218 ["Foo" hm--html-add-foo t]
1219 @end lisp
1220 to the @code{hm--html-menu-noregion-expert} variable and an entry
1221 @lisp
1222 ["Foo" hm--html-add-foo-to-region t]
1223 @end lisp
1224 to the @code{hm--html-menu-region-expert} variable (only if
1225 @code{hm--html-add-foo-to-region} exists). You can do this by setting the
1226 whole variable to a new value or by using the function
1227 @code{add-menu-button}. I recommend the last method.
1228
1229 If you'd like to have also a key sequence for inserting the new tag,
1230 then you've to take a look at @file{hm--html-keys.el}. There are
1231 different key tables defined for region and no region cases and for
1232 different sorts of elements, like anchors, frame elements (doesn't mean
1233 the Netscape element frame) and so on. These "groups" are the same as
1234 the sub menu groups.
1235
1236
1237 @node Use With psgml-html, Internal Drag And Drop, Add New Elements, Top
1238 @comment node-name, next, previous, up
1239 @chapter Use With psgml-html
1240 @cindex use with other HTML modes
1241 @findex hm--html-minor-mode
1242
1243 The package provides a minor mode called @code{hm--html-minor-mode},
1244 which could be used to join the features of this package with another
1245 HTML package. Currently this is only tested with the psgml html mode in
1246 the XEmacs. Please let me know, if it works or not with other packages
1247 or in the Emacs 19.
1248
1249 If you'd like to use the minor mode in the psgml html mode, you've to
1250 put the following line in your @file{.emacs}:
1251
1252 @lisp
1253 (add-hook 'html-mode-hook 'hm--html-minor-mode)
1254 @end lisp
1255
1256 Note: This should work only in XEmacs versions greater than 19.14 and not
1257 in 20.0. It doesn't work in other versions, because the hook variable
1258 @code{html-mode-hook} exists not in that versions. Therefore in that
1259 versions you've to called the minor mode either by hand or change the
1260 lisp file of the psgml html mode.
1261
1262
1263 @node Internal Drag And Drop, Template Minor Mode, Use With psgml-html, Top
1264 @comment node-name, next, previous, up
1265 @chapter Internal Drag And Drop
1266 @cindex drag and drop
1267 @cindex internal drag and drop
1268 @vindex idd-actions
1269 @vindex hm--html-idd-actions
1270
1271
1272 The file @file{internal-drag-and-drop.el}, which is shipped with the
1273 @file{hm--html-menus}, provides a general package for internal drag and
1274 drop in the emacs. General means, that it can be used also without the
1275 @code{hm--html-mode} in any other mode.
1276
1277 You can start such an action by clicking with the mouse in the source
1278 buffer and then in the destination buffer. The action could depend on
1279 the points where you've clicked with the mouse, on the state of the
1280 region, the point, the mark and any other properties of the source and
1281 the destination buffers. The actions are defined by the variable
1282 @code{idd-actions}, which is a buffer local variable.
1283
1284
1285 @menu
1286 * Drag And Drop Customization::
1287 * The Drag And Drop Commands::
1288 @end menu
1289
1290 @node Drag And Drop Customization, The Drag And Drop Commands, Internal Drag And Drop, Internal Drag And Drop
1291 @comment node-name, next, previous, up
1292 @section Drag And Drop Customization
1293 @cindex customization
1294 @cindex configuration
1295
1296 The internal drag and drop functions could be used in all
1297 modes. Therefore it's general customization isn't done in
1298 @file{hm--html-configuration.el}. It's variables are defined in the file
1299 @file{internal-drag-and-drop.el} instead. You can set them in your
1300 @file{.emacs} or in one of the other emacs init files (eg:
1301 @file{default.el}). The following subsections describes the main
1302 customization variables.
1303
1304
1305 @menu
1306 * Defining The Drag And Drop Actions::
1307 * The Mouse Bindings::
1308 @end menu
1309
1310 @node Defining The Drag And Drop Actions, The Mouse Bindings, Drag And Drop Customization, Drag And Drop Customization
1311 @comment node-name, next, previous, up
1312 @subsection Defining The Drag And Drop Actions
1313 @cindex actions
1314 @cindex drag and drop actions
1315 @vindex idd-actions
1316
1317 The drag and drop actions are commands, which are called after an
1318 internal drag and drop. They depends from the source and the destination
1319 of the drag and drop. Drag and drop actions must be defined by the
1320 variable:
1321
1322 @itemize @bullet
1323 @item
1324 @code{idd-actions}: A list with actions, depending on the source and the
1325 destination of the drag and drop command.
1326 @end itemize
1327
1328 The list looks like:
1329 @lisp
1330 '((@var{<destination-specification-1>} (@var{<source-specification-1>} @var{<action-1-1>})
1331 (@var{<source-specification-2>} @var{<action-1-2>})
1332 :
1333 )
1334 (@var{<destination-specification-2>} (@var{<source-specification-1>} @var{<action-2-1>})
1335 (@var{<source-specification-2>} @var{<action-2-2>})
1336 :
1337 )
1338 :
1339 )
1340 @end lisp
1341 The @var{<source-specification>} looks like the following:
1342 @lisp
1343 '([(@var{<specification-type>} @var{<value>})])
1344 @end lisp
1345 with
1346 @lisp
1347 @table @var
1348 @item <specification-type> :==
1349 @w{@code{idd-if-minor-mode-p}} | @w{@code{idd-if-buffer-name-p}} |
1350 @w{@code{idd-if-region-active-p}} | @w{@code{idd-if-url-at-point-p}} |
1351 @w{@code{idd-if-major-mode-p}} | @w{@code{idd-if-variable-non-nil-p}} |
1352 @w{@code{idd-if-dired-file-on-line-p}} |
1353 @w{@code{idd-if-dired-no-file-on-line-p}} |
1354 @w{@code{idd-if-local-file-p}} | @w{@code{idd-if-buffer-name-p}} |
1355 @w{@code{idd-if-modifiers-p}} | ...
1356 @end table
1357 @end lisp
1358
1359 The @var{<specification-type>} - functions must have two arguments, the
1360 first one is the source or destination and the second is the
1361 @var{<value>}. It must return @code{nil}, if the test wasn't successful
1362 and a number (in general 1), which specifies the weight of the test
1363 function. The weights of all single tests are added to a summary weight
1364 and assigned to the action. The action with the highest weight is called
1365 from the action handler. Look at the definition of
1366 @w{@code{idd-if-major-mode-p}}, @w{@code{idd-if-minor-mode-p}} and so on for
1367 examples. Look at the function
1368 @code{idd-get-source-or-destination-alist}, if you want to know the
1369 structure of the @code{source-or-destination} argument of these
1370 functions.
1371
1372 The @var{<destination-specification>} looks like
1373 @var{<source-specification>}, but in general it could be set to
1374 @code{nil} in mode specific idd-action lists.
1375
1376 If @var{<destination-specification-1>} or @var{<source-specification-1>}
1377 is set to @code{nil}, then every source or source
1378 matches. @code{idd-actions} is a buffer local variable, which should be
1379 at least mode depended. So if the @var{<destination-specification-1>} is
1380 set to @code{nil} it says, that the destination buffer must only have a
1381 specific mode. But however, it's also possible to define a general
1382 @code{idd-actions} list, where the destination mode is specified by
1383 @code{idd-if-major-mode-p}.
1384
1385 @var{<action>} is a function, which has two arguments, the first
1386 specifies the source and the second the destination. Look at the
1387 function definition of @code{idd-action-copy-region} and
1388 @code{idd-action-copy-replace-region}. They are examples for such
1389 actions.
1390
1391 The following is an example for the @code{hm--html-mode}:
1392
1393 @lisp
1394 (defvar idd-actions
1395 '((nil (((idd-if-major-mode-p . dired-mode)
1396 (idd-if-dired-file-on-line-p . ".*\\.\\(gif\\)\\|\\(jpq\\)"))
1397 hm--html-idd-add-include-image-from-dired-line)
1398 (((idd-if-major-mode-p . dired-mode)
1399 (idd-if-dired-no-file-on-line-p . nil))
1400 hm--html-idd-add-file-link-to-file-on-dired-line)
1401 (((idd-if-major-mode-p . dired-mode)
1402 (idd-if-dired-no-file-on-line-p . t))
1403 hm--html-idd-add-file-link-to-directory-of-buffer)
1404 (((idd-if-major-mode-p . w3-mode)
1405 (idd-if-url-at-point-p . t))
1406 hm--html-idd-add-html-link-from-w3-buffer-point)
1407 (((idd-if-major-mode-p . w3-mode))
1408 hm--html-idd-add-html-link-to-w3-buffer)
1409 (((idd-if-local-file-p . t))
1410 hm--html-idd-add-file-link-to-buffer)))
1411 @end lisp
1412
1413
1414 @node The Mouse Bindings, , Defining The Drag And Drop Actions, Drag And Drop Customization
1415 @comment node-name, next, previous, up
1416 @subsection The Mouse Bindings
1417 @cindex mouse bindings
1418 @vindex idd-global-mouse-keys
1419 @vindex idd-global-help-mouse-keys
1420 @vindex idd-drag-and-drop-mouse-binding-type
1421 @findex idd-mouse-drag-and-drop
1422 @findex idd-help-mouse-drag-and-drop
1423
1424 There are the following three variables, which determines the mouse
1425 bindings and the mouse behaviour for the internal drag and drop package:
1426
1427 @itemize @bullet
1428 @item
1429 @code{idd-global-mouse-keys}: The mouse keys for the command
1430 @code{idd-mouse-drag-and-drop}. The command
1431 @code{idd-mouse-drag-and-drop} is bound during the loading of the
1432 package @file{internal-drag-and-drop} to these keys in the @b{global
1433 keymap}. The drag and drop action @b{must be bound global}, because the
1434 drag and drop action must be started by a click in the source
1435 buffer. Therefore no action will be performed, if the mouse keys are not
1436 bound to @code{idd-mouse-drag-and-drop} in the destination buffer.
1437
1438 Set it to @code{nil}, if you don't want to bind this function during
1439 loading.
1440
1441 If the command is already bound in the global keymap during loading,
1442 then this key sequence will not be bind.
1443
1444 By default the mouse binding is @key{meta} @key{control} @key{button1}.
1445
1446 @item
1447 @code{idd-global-help-mouse-keys}: The mouse keys for the command
1448 @code{idd-help-mouse-drag-and-drop}. The command
1449 @code{idd-help-mouse-drag-and-drop} is bound during the loading of the
1450 package @file{internal-drag-and-drop} to this keys in the @b{global
1451 keymap}.
1452
1453 Set it to @code{nil}, if you don't want to bind this function during
1454 loading.
1455
1456 If the command is already bound in the global keymap during loading,
1457 then this key sequence will not be bind.
1458
1459 By default the mouse binding is @key{meta} @key{control} @key{button3}.
1460
1461 @item
1462 @code{idd-drag-and-drop-mouse-binding-type}: The type of the drag and
1463 drop mouse binding. The value maybe @code{click} or
1464 @code{press-button-during-move}. A value of @code{click} means, that
1465 you've to click over the source, leave the button and click it again
1466 over the destination. A value of @code{press-button-during-move} means,
1467 that you've to press the button down over the source and hold it until
1468 the mouse pointer is over the destination.
1469
1470 The @emph{disadvantage} of the @code{press-button-during-move} type
1471 compared with the @code{click} type is, that you can't select a destination
1472 region and therefore a drag and drop action depending on a selected
1473 region can't be started with that type of mouse binding.
1474 @end itemize
1475
1476 @node The Drag And Drop Commands, , Drag And Drop Customization, Internal Drag And Drop
1477 @comment node-name, next, previous, up
1478 @section The Drag And Drop Commands
1479 @cindex drag and drop commands
1480
1481 There are 2 groups of commands. The first one contains commands, which
1482 performs the drag and drop action and the second displayed a help
1483 message about a possible drag and drop action.
1484
1485
1486 @menu
1487 * Performing The Drag And Drop Action::
1488 * Displaying Help On Drag And Drop::
1489 @end menu
1490
1491 @node Performing The Drag And Drop Action, Displaying Help On Drag And Drop, The Drag And Drop Commands, The Drag And Drop Commands
1492 @comment node-name, next, previous, up
1493 @subsection Performing The Drag And Drop Action
1494 @cindex drag and drop commands
1495 @cindex performing drag and drop
1496 @findex idd-mouse-drag-and-drop
1497 @findex idd-start-mouse-drag-and-drop
1498 @findex idd-mouse-drag-and-drop-press-button-during-move
1499 @findex idd-mouse-drag-and-drop-click
1500 @findex idd-help-start-action
1501 @vindex idd-drag-and-drop-mouse-binding-type
1502
1503 There are the following five different commands, which performs internal
1504 drag and drop actions:
1505
1506 @itemize @bullet
1507 @item
1508 @code{idd-mouse-drag-and-drop}: Performs a drag and drop action. It
1509 calls the command @code{idd-mouse-drag-and-drop-click} or
1510 @code{idd-mouse-drag-and-drop-press-button-during-move} depending on the
1511 value of @code{idd-drag-and-drop-mouse-binding-type}. However you've set
1512 this, you start a drag and drop action with this command by pressing
1513 down it's mouse button over the source. This command is bind by default
1514 to a global mouse key sequence. @xref{The Mouse Bindings}.
1515
1516 @item
1517 @code{idd-start-mouse-drag-and-drop}: Starts a drag and drop command.
1518 This command could be used to start a drag and drop command without a
1519 button event. Therefore this should not be bind direct to a mouse
1520 button. This command can be used to start a drag and drop action with a
1521 click on a menu item or tool bar icon. After that you've to press down a
1522 mouse button over the source. The rest depends on the value of
1523 @code{idd-drag-and-drop-mouse-binding-type}, like with the command
1524 @code{idd-mouse-drag-and-drop}.
1525
1526 @item
1527 @code{idd-help-start-action}: It is possible to display a help buffer
1528 with a message in it, which describes the action instead of performing
1529 it immediately (@pxref{Displaying Help On Drag And Drop}). In this case
1530 you can perform the action by clicking on a special extent in the help
1531 buffer, which runs this command.
1532
1533 @item
1534 @code{idd-mouse-drag-and-drop-press-button-during-move}: Performs a drag
1535 and drop action in a more traditional way than
1536 @code{idd-mouse-drag-and-drop-click}. At first you must press the button
1537 down over the source and then move with the pressed button to the
1538 destination, where you must leave the button up. This must be bind to a
1539 mouse button. The @code{SOURCE-EVENT} must be a
1540 @code{button-press-event}.
1541
1542 The disadvantage of this command compared with the command
1543 @code{idd-mouse-drag-and-drop-click} is, that you can't select a
1544 destination region.
1545
1546 You should bind the command @code{idd-mouse-drag-and-drop} instead of
1547 this one, because it's then possible to switch between both drag and
1548 drop behaviour by changing only one variable.
1549
1550 @item
1551 @code{idd-mouse-drag-and-drop-click}: Performs a drag and drop action in
1552 a more useful way than
1553 @code{idd-mouse-drag-and-drop-press-button-during-move}. At first you
1554 must click on the source and after that on the destination. This must
1555 be bind to a mouse button. The @code{SOURCE-EVENT} must be a
1556 @code{button-press-event}.
1557
1558 You should bind the command @code{idd-mouse-drag-and-drop} instead of
1559 this one, because it's then possible to switch between both drag and
1560 drop behaviour by changing only one variable.
1561 @end itemize
1562
1563
1564 @node Displaying Help On Drag And Drop, , Performing The Drag And Drop Action, The Drag And Drop Commands
1565 @comment node-name, next, previous, up
1566 @subsection Displaying Help On Drag And Drop
1567 @cindex help on drag and drop
1568 @cindex displaying help on drag and drop
1569 @findex idd-help-mouse-drag-and-drop
1570 @findex idd-start-help-mouse-drag-and-drop
1571
1572 It's possible to display a buffer with a help message describing the
1573 action before actually performing it. To perform the action, you've then
1574 to click on a special extent in the help buffer. To get the help buffer,
1575 you've to do the same things, as you've to do to perform the action
1576 direct. Only the mouse key differs. There are two commands for this:
1577
1578 @itemize @bullet
1579 @item
1580 @code{idd-help-mouse-drag-and-drop}: Displays help about the drag and
1581 drop action. It works similar as @code{idd-mouse-drag-and-drop}
1582 (@pxref{Performing The Drag And Drop Action}).
1583
1584 By default this command is global bound to @key{meta} @key{control}
1585 @key{button3}. This could be changed with the variable
1586 @code{idd-global-help-mouse-keys} (@pxref{The Mouse Bindings}).
1587
1588 @item
1589 @code{idd-start-help-mouse-drag-and-drop}: Starts displaying help about
1590 the drag and drop action. It works similar as
1591 @code{idd-start-mouse-drag-and-drop} (@pxref{Performing The Drag And
1592 Drop Action}) and can be used to start the help by clicking on a menu
1593 item or a tool bar icon.
1594 @end itemize
1595
1596
1597 @node Template Minor Mode, Bug Reports, Internal Drag And Drop, Top
1598 @comment node-name, next, previous, up
1599 @chapter Template Minor Mode
1600 @cindex templates
1601
1602 There's a file called @file{tmpl-minor-mode.el} in the distribution
1603 of the package @emph{hm---html-menus}. It provides functions to use
1604 templates for the @code{hm--html-mode} and also for other modes. It
1605 needs nothing from the rest of the package and therefore it can be used
1606 independently of the @code{hm--html-mode}.
1607
1608
1609 @menu
1610 * What Are Templates::
1611 * Syntax Of Templates::
1612 * Template Customization::
1613 * Template Commands::
1614 @end menu
1615
1616 @node What Are Templates, Syntax Of Templates, Template Minor Mode, Template Minor Mode
1617 @comment node-name, next, previous, up
1618 @section What Are Templates
1619 @cindex templates
1620 @findex tmpl-insert-template-file
1621 @findex tmpl-expand-templates-in-buffer
1622 @findex tmpl-expand-templates-in-region
1623
1624 Templates are special pieces of text, which can be expanded by the
1625 emacs. Expansion means, that the template is replaced by something else,
1626 which is determined by evaluating lisp forms or emacs commands. The
1627 expansion can be done automaticly after the insert of templates
1628 with the command @code{tmpl-insert-template-file} in a buffer or by hand
1629 with the commands @code{tmpl-expand-templates-in-buffer} or
1630 @code{tmpl-expand-templates-in-region}.
1631
1632 Templates can be put together with normal text in a so called template
1633 file to provide prototype files. You should name these files with the
1634 following naming scheme:
1635
1636 @example
1637 @var{<file>}.@var{<type>}.tmpl
1638 @end example
1639
1640 where @var{<file>} is a string which describes for what the template
1641 could be used and @var{<type>} the normal file extension, e.g. @samp{c}
1642 for C- files or @samp{html} for HTML- files.
1643
1644
1645 @node Syntax Of Templates, Template Customization, What Are Templates, Template Minor Mode
1646 @comment node-name, next, previous, up
1647 @section Syntax Of Templates
1648 @cindex template syntax
1649 @vindex tmpl-sign
1650
1651 The templates are marked with the sign ^@@, which stands for the null
1652 character (\000). It can be inserted in a buffer with the keys @kbd{C-q
1653 C-SPC}. You can also use any other character or string of characters by
1654 changing the variable @code{tmpl-sign}.
1655
1656 At the moment, there are 3 different mayor types of templates:
1657
1658 @enumerate
1659 @item
1660 @emph{Emacs Lisp function templates}: The expansion of such a template
1661 evals a lisp form. It is possible to use functions or variables as lisp
1662 forms. The following is a simple example:
1663
1664 @lisp
1665 ^@@LISP^@@ (insert-file "~/.emacs") ^@@END LISP^@@
1666 @end lisp
1667
1668 It inserts the contents of the file @file{~/.emacs} in the current
1669 buffer during the expansion.
1670
1671 @item
1672 @emph{Emacs command templates}: The expansion of a command template
1673 evals a template in the same way as an interactive command, which is
1674 invoked with @kbd{M-x command}. For example:
1675
1676 @lisp
1677 ^@@COMMAND^@@ insert-file ^@@END COMMAND^@@
1678 @end lisp
1679
1680 It runs the interactive command @code{insert-file} during the expansion.
1681
1682 @item
1683 @emph{Template comments} Nothing will be evaluated during the expansion
1684 of a template comment. It is only a comment. For example:
1685
1686 @lisp
1687 ^@@C^@@ This is a comment
1688 @end lisp
1689
1690 The end of the comment is the end of the line. Therefore it has the same
1691 syntax as a lisp or C++ comment.
1692 @end enumerate
1693
1694 The default is, that a template will be deleted after its expansion, but
1695 without the linefeed. Look at the following examples:
1696
1697 Before the expansion:
1698
1699 @example
1700 Line before the template
1701 ^@@C^@@ The Text of a comment template
1702 Line after the template
1703 @end example
1704
1705 After the expansion:
1706
1707 Line before the template
1708
1709 Line after the template
1710
1711
1712 Templates can start in every column and only the template will be deleted
1713 after its expansion.
1714
1715
1716 There is also the possibility to put an attribute list in a template. The
1717 attributes of the list are controlling the deletion of the template. It
1718 may be, that this will be extended in the future with other attributes.
1719 The attribute list must be specified as an alist (assoc list) in the start
1720 tag of a template and after its type. Each element of the alist consists
1721 of the name of the attribute following its value.
1722 If no attribute list is specified or if an attribute is missing, then the
1723 default values are used. At the moment there are the following 2 attributes:
1724
1725 @enumerate
1726 @item @emph{don't delete attribute} (@code{DONT_DELETE}): If the value
1727 is t, then the template will not be deleted after its expansion or else
1728 if the value is nil then the template will be deleted. The default is
1729 nil. For example:
1730
1731 Before the expansion:
1732
1733 @example
1734 Line before the template
1735 ^@@LISP ((DONT-DELETE t))^@@ (insert-file "~/.cshrc") ^@@END LISP^@@
1736 Line after the template
1737 @end example
1738
1739 After the expansion:
1740
1741 @example
1742 Line before the template
1743 ^@@LISP ((DONT-DELETE t))^@@ (insert-file "~/.cshrc") ^@@END LISP^@@
1744 Line after the template
1745 @end example
1746
1747 It was assumed, that the file @file{~/.cshrc} was empty !
1748
1749 @item
1750 @emph{delete line attribute} (@code{DELETE-LINE}): If the value is t,
1751 then the linefeed before or after the template will be deleted or else
1752 if the value is nil then no linefeed will be deleted. The default is
1753 nil. For example:
1754
1755 Before the expansion:
1756
1757 @example
1758 Line before the template
1759 ^@@LISP ((DELETE-LINE t))^@@ (insert-file "~/.cshrc") ^@@END LISP^@@
1760 Line after the template
1761 @end example
1762
1763 After the expansion:
1764
1765 @example
1766 Line before the template
1767 Line after the template
1768 @end example
1769
1770 It was assumed, that the file @file{~/.cshrc} was empty !
1771 @end enumerate
1772
1773 The attributes can be combined. For example:
1774
1775 @example
1776 ^@@COMMAND ((DELETE-LINE t) (DONT-DELETE nil))^@@
1777 insert-file
1778 ^@@END COMMAND^@@
1779 @end example
1780
1781 The last examples shows also, that whitespaces (blanks, tabs, linefeeds)
1782 are allowed at the most positions in a template.
1783
1784 Look at the file @file{tmpl-minor-mode.el}, for a description of the
1785 commands to expand templates.
1786
1787
1788 @node Template Customization, Template Commands, Syntax Of Templates, Template Minor Mode
1789 @comment node-name, next, previous, up
1790 @section Template Customization
1791 @cindex customization
1792 @cindex configuration
1793 @vindex tmpl-template-dir-list
1794 @vindex tmpl-automatic-expand
1795 @vindex tmpl-filter-regexp
1796 @vindex tmpl-sign
1797 @vindex tmpl-minor-mode-map
1798
1799 Templates could be used for all editing modes and not only for the
1800 @code{hm--html-mode}. Therefore it's general customization isn't done in
1801 @file{hm--html-configuration.el}. It's variables are defined in the file
1802 @file{tmpl-minor-mode.el} instead. You can set them in your
1803 @file{.emacs} or in one of the other emacs init files (eg:
1804 @file{default.el}). The following are the main variables for
1805 customization.
1806
1807 @itemize @bullet
1808 @item
1809 @code{tmpl-template-dir-list}: A list of directories with template
1810 files. If it is nil, the default-directory will be used. If more than
1811 one directory is specified, then the template filenames should differ
1812 in all directories.
1813
1814 This variable is used in the commands for inserting templates. Look at
1815 @code{tmpl-insert-template-file-from-fixed-dirs} and at
1816 @code{tmpl-insert-template-file}. The command
1817 @code{tmpl-insert-template-file} uses only the car of the list (if it is
1818 a list).")
1819 @item
1820 @code{tmpl-filter-regexp}: It determines an regular expression used for
1821 filtering out non template files in template directories. It is used in
1822 the command @code{tmpl-insert-template-file-from-fixed-dirs} to allow
1823 only the selecting of files, which are matching the regexp. If it is
1824 nil, then the Filter @code{".*\\.tmpl$"} is used. Set it to
1825 @code{\".*\"} if you want to disable the filter function or use the
1826 command @code{tmpl-insert-template-file}.
1827 @item
1828 @code{tmpl-automatic-expand}: If you insert a template file with
1829 @code{tmpl-insert-template-file-from-fixed-dirs} or with
1830 @code{tmpl-insert-template-file}, this variable is used. In this case
1831 the templates in the buffer will be automaticly expanded, if the
1832 variable is set to t, which is the default.
1833 @item
1834 @code{tmpl-sign}: It determines the sign which marks the beginning and
1835 the end of template expressions. By default it is set to the null
1836 character (displayed in the emacs as ^@@). You can also set this to a
1837 string. Be careful, if you change it, so that the templates will not be
1838 mixed up with other non template text! Note: The expansion function
1839 looks at the whole template, so that it is very unlikely that the
1840 function will make a mistake.
1841 @item
1842 @code{tmpl-minor-mode-map}: The keymap for the template minor mode.
1843 @end itemize
1844
1845
1846 @node Template Commands, , Template Customization, Template Minor Mode
1847 @comment node-name, next, previous, up
1848 @section Template Commands
1849 @cindex commands
1850
1851 In this section the commands of the template package are described.
1852
1853
1854 @menu
1855 * Insert Of Template Files::
1856 * Expansion Of Templates::
1857 * Escaping Of Template Signs::
1858 * The Template Minor Mode::
1859 @end menu
1860
1861 @node Insert Of Template Files, Expansion Of Templates, Template Commands, Template Commands
1862 @comment node-name, next, previous, up
1863 @subsection Insert Of Template Files
1864 @cindex template insert
1865 @cindex template files
1866 @findex tmpl-insert-template-file-from-fixed-dirs
1867 @findex tmpl-insert-template-file
1868
1869 The template package provides the following two commands for inserting
1870 template files in an emacs buffer.
1871
1872 @itemize @bullet
1873 @item
1874 @code{tmpl-insert-template-file}: This command can be used to insert a
1875 template file in the current buffer. It will expand the templates in the
1876 buffer, if @code{tmpl-automatic-expand} is set to @code{t}. You can set
1877 a default directory for this command by setting the variable
1878 @code{tmpl-template-dir-list}, @xref{Template Customization}.
1879 @item
1880 @code{tmpl-insert-template-file-from-fixed-dirs}: The difference to the
1881 simpler command @code{tmpl-insert-template-file} is, that this command
1882 will build a list for filename completion from a list of predefined
1883 directories (look at @code{tmpl-template-dir-list}). The filename
1884 completion list will also be filtered with the regular expression
1885 defined by @code{tmpl-filer-regexp}. @xref{Template Customization}. You
1886 can set the directory list and/or the filter different in each mode,
1887 where you use templates, so that you will get only template files in the
1888 completion list, which could be used for the current mode.
1889
1890 If you want to insert a template file with this command, which is not in
1891 one of the directories from @code{tmpl-template-dir-list}, then you've
1892 to enter the string @emph{"Change the directory"} instead of a template
1893 file. This string is also in the completion list.
1894 @end itemize
1895
1896 Both commands can also be used as functions. In this case the template
1897 file with is directory path must be given to them as an parameter.
1898
1899 You can also use commands like @code{insert-file} to insert template
1900 files and expand them by hand (@pxref{Expansion Of Templates}).
1901
1902
1903 @node Expansion Of Templates, Escaping Of Template Signs, Insert Of Template Files, Template Commands
1904 @comment node-name, next, previous, up
1905 @subsection Expansion Of Templates
1906 @cindex template expansion
1907 @cindex expansion
1908 @findex tmpl-expand-templates-in-region
1909 @findex tmpl-expand-templates-in-buffer
1910
1911 You can expand templates by hand or automaticly after their
1912 insert. @xref{Insert Of Template Files}, for automatic
1913 expansion. The expansion by hand can be done with one of the
1914 following two functions:
1915
1916 @itemize @bullet
1917 @item
1918 @code{tmpl-expand-templates-in-region}: Expands the templates in the
1919 region. The region is determined by it's optional arguments @code{BEGIN}
1920 and @code{END}. If the arguments are @code{nil}, or if the function is called
1921 interactive, then the current region will be used.
1922 @item
1923 @code{tmpl-expand-templates-in-buffer}: Expands all templates in the
1924 current buffer.
1925 @end itemize
1926
1927 Both commands are bind to keys in the @code{tmpl-minor-mode}. @xref{The
1928 Template Minor Mode}.
1929
1930
1931 @node Escaping Of Template Signs, The Template Minor Mode, Expansion Of Templates, Template Commands
1932 @comment node-name, next, previous, up
1933 @subsection Escaping Of Template Signs
1934 @cindex template escaping
1935 @cindex escaping
1936 @findex tmpl-escape-tmpl-sign-in-region
1937 @findex tmpl-escape-tmpl-sign-in-buffer
1938
1939 It is possible to escape template signs in a buffer or in a
1940 region. Templates with escaped template signs are not expanded, but they
1941 are un-escaped by the expansion functions. Therefore it is possible to
1942 prevent single templates from the expansion by escaping them. Note:
1943 You can't escape template twice. The commands, which can be used for
1944 this are:
1945
1946 @itemize @bullet
1947 @item
1948 @code{tmpl-escape-tmpl-sign-in-region}: Escapes all @code{tmpl-sign}'s
1949 (@pxref{Template Customization}) with a @code{tmpl-sign} in a
1950 region. The region is determined by it's optional arguments @code{BEGIN}
1951 and @code{END}. If the arguments are @code{nil}, or if the function is
1952 called interactive, then the current region will be used.
1953 @item
1954 @code{tmpl-escape-tmpl-sign-in-buffer}: Same as
1955 @code{tmpl-escape-tmpl-sign-in-region}, but escapes all templates in the
1956 whole buffer.
1957 @end itemize
1958
1959 Both commands are bind to keys in the @code{tmpl-minor-mode}. @xref{The
1960 Template Minor Mode}.
1961
1962
1963 @node The Template Minor Mode, , Escaping Of Template Signs, Template Commands
1964 @comment node-name, next, previous, up
1965 @subsection The Template Minor Mode
1966 @cindex template minor mode
1967 @cindex minor mode
1968 @cindex key bindings
1969 @findex tmpl-minor-mode
1970
1971 The template minor mode can be toggled with the command
1972 @code{tmpl-minor-mode}. The purpose of this mode is only to provide
1973 key bindings for some of the commands of the package
1974 @file{tmpl-minor-mode}. So if you don't want to use the key bindings, you
1975 don't need this minor mode.
1976
1977 Look at the key table @code{tmpl-minor-mode-map} (@pxref{Template
1978 Customization}) for the definition of the keys.
1979
1980 It may be, that I'll provide also a pulldown or popup menu for the minor
1981 mode in a future release.
1982
1983
1984 @node Bug Reports, Concept Index, Template Minor Mode, Top
1985 @comment node-name, next, previous, up
1986 @chapter Bug Reports
1987 @cindex bug report
1988 @findex hm--html-submit-bug-report
1989
1990 There's no software out there without bugs. This package contains
1991 software, therefore it has bus. I (Heiko Münkel
1992 <muenkel@@tnt.uni-hannover.de>) have inserted most of the bugs in this
1993 package by myself, but I've forgotten where. So please help me out of
1994 this disaster and send bug reports, if you've found one of these little
1995 animals. I'll try to do my very best to fix them and to insert new ones.
1996
1997 If it's possible, you should use the command
1998
1999 @lisp
2000 M-x hm--html-submit-bug-report
2001 @end lisp
2002
2003 There's also an entry in the pulldown menu for this.
2004
2005 In some cases a backtrace would also be fine.
2006
2007 If you can't send the report with this function, than you should at
2008 least insert the package version and your @code{Emacs}/@code{XEmacs}
2009 version.
2010
2011 In the best of all worlds you include also a patch to fix the bug.
2012
2013 @emph{Note}: It's not true, that I've inserted the bugs as a marketing trick,
2014 so that you must buy the next version to get some of them fixed. This is
2015 false, because this software is free.
2016
2017
2018 @node Concept Index, Function Index, Bug Reports, Top
2019 @comment node-name, next, previous, up
2020 @unnumbered Concept Index
2021
2022 @printindex cp
2023
2024 @node Function Index, Variable Index, Concept Index, Top
2025 @comment node-name, next, previous, up
2026 @unnumbered Function Index
2027
2028 @printindex fn
2029
2030 @node Variable Index, , Function Index, Top
2031 @comment node-name, next, previous, up
2032 @unnumbered Variable Index
2033
2034 @printindex vr
2035
2036 @summarycontents
2037 @contents
2038 @bye