5. Customization

You should be able to use the package after its installation without any further customization. But it contains a lot of user variables to adapt the package better to your special needs. How to do this is described in this chapter.

Since the XEmacs 19.15 and 20.2 a special package can be used for the customization of lisp packages. This package uses now also this feature. Therefore you can set all user variables with the help of the Customize submenu, which can be selected in the Option menu. If you use it, the variables will currently be saved in a special customization file and not in one of the configuration files (see section Customization (Configuration) Files) of this package. Please look at the `NEWS' file or the info manuals of the XEmacs to find out more about the customization package.

5.1 Customization (Configuration) Files

This package uses 3 different files to customize the mode, but you need not use all of them. Only one of them, the file `hm--html-configuration.el' is delivered together with the package. The reason for three different files is to provide the opportunity to have different customization for the package, the site and the user. There's also a pulldown menu item to reload all customization files. The files are described in the following sections.

5.1.1 Where Are All The Customization Variables Defined

All variables which can be used to customize the mode are defined in the package configuration file `hm--configuration.el'. You should take a look at this file if you don't find how to customize a feature in this documentation (the documentation of a program is never as complete as its program code :-).

This file is searched in one of your lisp load directories. You can change this by setting the environment variable HTML_CONFIG_FILE to another file. But I don't recommend this.

Note: This file is loaded before the other customization files, so that its definitions could be overwritten. All variables are set by defvar, so that its values could also be overwritten with setq in any standard emacs customization files (e.g. in `.emacs').

5.1.2 Where To Put Site Specific Customization

In general all users at a site are writing their html pages for the same WWW server. Therefore it is very likely that most of the customizations are site specific, and only a few are user specific. However, you don't have to use a site specific customization if you don't want one.

If you'd like to make a site specific customization of hm--html-mode, it's possible to put it in a special file called `hm--site-configuration-file.el'. If you do this, you have to set either the lisp variable hm--html-site-config-file or the environment variable HTML_SITE_CONFIG_FILE to the file and its path. If you write the filename without its extension (.el), emacs tries first to load a compiled version of the file.

The environment variables overwrite the lisp variables.

You can prevent the loading of the site specific customization file by starting the emacs with the -no-site-file flag.

You can also put the site specific customization in any standard emacs customization file like, `default.el'. But an advantage to using `hm--site-configuration-file.el' is that it is very likely you will be able to use this file with future versions of the package. I'll try to make it as backward compatible as possible.

Note: This file is loaded after the package customization file and before the user customization file.

5.1.3 Where To Put User Specific Customization

User specific customization can be put in the file `.hm--html-configuration.el', which is searched by default in the home directory of the user. This can be overwritten by setting either the environment variable HTML_USER_CONFIG_FILE or the lisp variable hm--html-user-config-file to the name of the file and its path. If you write the filename without its extension (.el), emacs tries first to load a compiled version of the file.

If neither the environment variable nor the lisp variable is set, the variable init-file-user will be respected. Therefore you'll get `~other-user/.hm--html-configuration.el', if you've started the emacs with the options -u other-user. In all cases, no user specific customization file will be loaded, if the -q option was given to the emacs.

You can also put the user specific customization in your `.emacs'. It's up to you to decide which way is better.

Note: This file is loaded after the package and the site specific one. Therefore it overwrites all other customization files.

5.2 Customization Variables

In the following subsections the main customization variables are described.

5.2.1 User Name/Signature

• hm--html-username: Your real name. This is used as the name of the signature links. You need only specify it if your name in the file `/etc/passwd' isn't the one you'd like to see in the html files. Otherwise this may be set to nil.
• hm--html-signature-file: The link used in your signature. In general this should be a link to your home page.

5.2.2 Switching Between Expert And Novice Menus

• hm--html-expert: If you're a html novice and don't want to be bothered with lots of possible html elements, then you should use the novice popup menus. For that, set this variable to nil, which is the default. But if you are more familiar with html and would like to use more html elements, then you should use the expert menus and set this variable to t.

5.2.3 HTML Doctype

• hm--html-html-doctype-version: The HTML version. This is used in the doctype element. Change this if you use non HTML 3.2 elements. This package (See section version.) defines by default only HTML 3.2 elements.

5.2.4 Defaults Used For Generating Links

One of the main features of hm--html-mode is its easy ways to insert special links to html pages, ftp servers, news servers and so on. I think that most people will have their own (this may be site specific. See section Where To Put Site Specific Customization.) favourite servers, directories and so on. You may customize the default values and the alists with useful alternatives, which are used from the mode in the inserting functions for the links.

5.2.4.1 Your Favourite HTTP Server

• hm--html-favorite-http-server-host-name: The name of your favorite http server host. It must be specified! This variable is used in many other variables.

5.2.4.2 Links to WWW Server

• hm--html-html-hostname:port-default: Default hostname with port for http links to a HTML server.
• hm--html-html-hostname:port-alist: Alist with hostnames and ports for http links to HTML servers. It contains useful alternatives.
• hm--html-html-path-alist: Alist with directories for the HTML server. Each alist element must consist of a number and a directory string. The number is used to select the directory during the query about the directory for an http link.

5.2.4.3 Links To Files

• hm--html-file-path-alist: Alist with directories for the file gateway. Each alist element must consist of a number and a directory string. The number is used to select the directory during the query about the directory for a file link.

5.2.4.4 Links To FTP Servers

• hm--html-ftp-hostname:port-default: Default hostname with port for links to an ftp server. This is for the default FTP server. In general you don't need to specify a port for this.
• hm--html-ftp-hostname:port-alist: Alist with hostnames and ports for links to ftp servers. It contains useful alternatives. In general you don't need to specify ports for the ftp servers.
• hm--html-ftp-path-alist: Alist with directories for the ftp server links. It contains useful alternatives with /pub, /pub/gnu and so on. Each alist element must consist of a number and a directory string. The number is used to select the directory during the query about the directory for an ftp link.

5.2.4.5 Links To Emacs Info Files

• hm--html-info-hostname:port-default: Default hostname with port for the Info gateway.
• hm--html-info-hostname:port-alist: Alist with hostnames and ports for Info gateways. It contains useful alternatives.
• hm--html-info-path-alist: Alist with directories for the Info gateway. This may be a list with all of your emacs info directories.

5.2.4.6 Links To Gopher Servers

There are a lot of useful gopher information servers on the Internet. You can access them with a gopher browser or with a WWW browser. In the latter case you have to use the gopher gateway.

• hm--html-gopher-hostname:port-default: Default hostname with port for links to the default gopher server.
• hm--html-gopher-hostname:port-alist: Alist with hostnames and ports for links to gopher servers. It contains useful alternatives.
• hm--html-gopher-doctype-default: For gopher links you have to specify the doctype. In most cases this should be the string \"/1\". Therefore this is the default doctype, but you can change it to another.
• hm--html-gopher-doctype-alist: Alist with doctype strings for links to a gopher server. The strings \"/1\", \"/11\" and \"/00\" are the only doctype strings that I know. Please let me know if there are other strings.
• hm--html-gopher-anchor-alist: Alist with directories for links to a gopher server. It contains useful alternatives for the main gopher servers. Each alist element must consist of a number and a directory string. The number is used to select the directory during the query about the directory for a local program gateway link.

5.2.4.7 Links To WAIS Gateways

You can either make a link direct to a WAIS server (it may be that not all WWW browsers support this) or an http link to a server (relay host) which queries the WAIS server. The variables hm--html-wais-hostname:port-default and hm--html-wais-hostname refer to these relay hosts and the variables hm--html-wais-servername:port-default and hm--html-wais-servername:port-alist refer to the WAIS servers.

• hm--html-wais-hostname:port-default: Default hostname of the relay host with port for the WAIS gateway.
• hm--html-wais-hostname:port-alist: Alist with hostnames of possible relay hosts and ports for the WAIS gateway. It contains useful alternatives.
• hm--html-wais-servername:port-default: Default WAIS servername with port for the WAIS gateway.
• hm--html-wais-servername:port-alist: Alist with WAIS servernames and ports for the WAIS gateway. It contains useful alternatives.
• hm--html-wais-path-alist: Alist with directories for the wais gateway.

5.2.4.8 Links To The Mail Gateway

The following variables are for customizing the insertion of links to a mail folder. You need a special server for this, which sends the email back to the browser.

• hm--html-mail-hostname:port-default: Default hostname with port for the mail gateway.
• hm--html-mail-hostname:port-alist: Alist with hostnames and ports for the mail gateway. It contains useful alternatives.
• hm--html-mail-path-alist: Alist with directories for the mail gateway. In these directories you'll probably find mail folders. Each alist element must consist of a number and a directory string. The number is used to select the directory during the query about the directory for a mail folder link.

5.2.4.9 Links For Sending Mail

• hm--html-mailto-alist: Alist with mail addresses for the mailto alist. The value of `user-mail-address' will also be added by the package to this alist.

5.2.4.10 Links to CGI scripts

CGI scripts are available on many WWW servers to start special programs (eg: cgi-man, to display man pages). Creating these links can be customized with the following varoables.

• hm--html-cgi-hostname:port-alist: Alist with hostnames and ports for the cgi server.
• hm--html-cgi-hostname:port-default: Default hostname with port for the cgi server.
• hm--html-cgi-script-alist: Alist with CGI scripts, which are available on your server.
• hm--html-cgi-script-default: Default CGI script.

5.2.4.11 Links To The Program Gateway

The program gateway is a special TNT site specific gateway for starting programs out of a html page. The programs are started by a special server, which looks in an allowed file to determine if it is allowed to start the program. This is necessary because the programs are running under the user id of the server. We're only allowed to start simple display programs like man, ls and so on.

• hm--html-proggate-hostname:port-default: Default hostname with port for the proggate server.
• hm--html-proggate-hostname:port-alist: Alist with hostnames and ports for the proggate server. It contains useful alternatives.
• hm--html-proggate-allowed-file: The filename (with path) of the proggate allowed file.

5.2.4.12 Links To The Local Program Gateway

Another TNT site specific way to start programs from a html page. These programs are started with the id of the user on the host where the client (browser) is running. Therefore no restriction about the allowed programs is made. With this you can start only programs and do only things, which you can do also without the WWW browser.

• hm--html-local-proggate-path-alist: Alist with directories for the local program gateway. Contains directories, where you can find programs.

5.2.4.13 URL For Forms And Image Tags

• hm--html-url-alist: Alist with URL's for FORMS and IMAGE tags. The cdr of each list contains symbols, which specifies the use of the URL.

5.2.4.14 Marking Of Examples

The following variables are for marking the examples in the help buffer.

• hm--html-help-foreground: The foreground color for highlighting examples.
• hm--html-help-background: The background color for highlighting examples.
• hm--html-help-font: The font for highlighting examples.

5.2.5 Templates

For inserting html template files you can customize where you keep your templates.

• hm--html-template-dir: A directory with template files. It is now also possible to use it as a list of directories. Look at the variable tmpl-template-dir-list for further descriptions. If this variable is set to a non-existent directory, then it defaults to the directory where the package is in XEmacs. This is done during loading the file `hm--html-configuration.el' (See section Where Are All The Customization Variables Defined.). This may only be useful in XEmacs >= 19.12.
• hm--html-frame-template-file: File which is used as template for a html frame. An example is in the package hm--html-menus. See section Contents.
• hm--html-automatic-expand-templates: Automatic expansion of templates. This feature needs the file `tmpl-minor-mode.el' from Heiko Münkel (muenkel@tnt.uni-hannover.de), which is distributed with the package hm--html-menus.
• hm--html-template-filter-regexp: Regexp for filtering out non (html) template files in a directory.

5.2.6 Deleting Automounter Path Prefix

• hm--html-delete-wrong-path-prefix: If non-nil, it specifies path-prefixes which should be deleted in paths. The Sun automounter adds a temporary prefix to the automounted directories (at our site the prefix is /tmp_mnt). But you can't select such a path if the automounter has currently not mounted the directory, and so you can't follow an html link which consists of such a path. To overcome this behaviour, you can set this variable to the prefix (e.g. "/tmp_mnt"). After that, the prefix should be stripped from the paths during the creation of the links. ATTENTION: This variable is used as a regular expression! It can be set to a string or to a list of strings.

5.2.7 Automatic Insert Of Information

The hm--html-mode automatically inserts some useful information in html pages. This behaviour can be changed by the following variables.

• hm--html-automatic-create-title-date: t => A date string will be inserted in the title line. This will be updated each time before file saving, if hm--html-automatic-update-title-date is also set to t.
• hm--html-automatic-update-title-date: t => The date in the title line will be updated before file saving. nil => No automatic update of the date.
• hm--html-title-date-format: Default output format for date and time in the title and main header line. WARNING: Don't use the character < in this string! The format is used as argument of the function format-time-string. The following describes the meanings of special %-sequences, as described in the function documentation of format-time-string:
  • %a This stands for the abbreviated name of the day of week.
  • %A This stands for the full name of the day of week.
  • %b This stands for the abbreviated name of the month.
  • %B This stands for the full name of the month.
  • %c This is a synonym for `%x %X'.
  • %C This has a locale-specific meaning. In the default locale (named C), it is equivalent to `%A, %B %e, %Y'.
  • %d This stands for the day of month, zero-padded.
  • %D This is a synonym for `%m/%d/%y'.
  • %e This stands for the day of month, blank-padded.
  • %h This is a synonym for `%b'.
  • %H This stands for the hour (00-23).
  • %I This stands for the hour (00-12).
  • %j This stands for the day of the year (001-366).
  • %k This stands for the hour (0-23), blank padded.
  • %l This stands for the hour (1-12), blank padded.
  • %m This stands for the month (01-12).
  • %M This stands for the minute (00-59).
  • %n This stands for a newline.
  • %p This stands for `AM' or `PM', as appropriate.
  • %r This is a synonym for `%I:%M:%S %p'.
  • %R This is a synonym for `%H:%M'.
  • %S This stands for the seconds (00-60).
  • %t This stands for a tab character.
  • %T This is a synonym for `%H:%M:%S'.
  • %U This stands for the week of the year (01-52), assuming that weeks start on Sunday.
  • %w This stands for the numeric day of week (0-6). Sunday is day 0.
  • %W This stands for the week of the year (01-52), assuming that weeks start on Monday.
  • %x This has a locale-specific meaning. In the default locale (named C), it is equivalent to `%D'.
  • %X This has a locale-specific meaning. In the default locale (named C), it is equivalent to `%T'.
  • %y This stands for the year without century (00-99).
  • %Y This stands for the year with century.
  • %Z This stands for the time zone abbreviation.

• hm--html-log-date-format: Default output format string for date and time in the log lines. WARNING: Don't use the character < in this string! The log lines are the lines with the created and changed comments. The format string is used as argument of the function format-time-string. Please look at the description of the function format-time-string or of the variable hm--html-title-date-format for a description of the format string.
• hm--hmtl-include-time-after-date: This variable isn't longer supported. It is replaced by hm--html-log-date-format. It's old description was:

  t => The time of day will be appended to the date in the created and changed comment lines, as well as in the visible modified line if these lines are present; the time will never be appended to the date in the title. The separator between date and title is defined with hm--html-date-time-separator.

• hm--html-date-time-separator: This variable isn't longer supported. It is replaced by hm--html-log-date-format. It's old description was:

  The value of the separator between date and time in the created and modified comment lines and in the visible modified line. This is only used if hm--hmtl-include-time-after-date is t. Eg.: " at ".

• hm--html-automatic-created-comment: t => A "created comment" line will be added. nil => No automatic insert of a "created comment" line.
• hm--html-created-comment-prefix: The prefix text of the "created comment" lines. By default this is set to "Created by: ".
• hm--html-comment-infix: The infix (second part) of the "created comment" and the "changed comment" lines. By default, if this variable is nil, the value of hm--html-username or, if this variable is also nil, the return value of (user-full-name) will be used. In these cases the infix looks like "Heiko Münkel, ".

  Set it to an empty string, if you don't want to have your name in the comments.

• hm--html-automatic-changed-comment: t => A "changed comment" line will be added before file saving. nil => No automatic insert of a "changed comment" line.
• hm--html-changed-comment-prefix: The prefix text of the "changed comment" lines. By default this is set to "Changed by: ".
• hm--html-automatic-create-modified-line: t => Some commands will insert a visible "modified" line with the current date, if such a line does not exist already. If it already exist, the date in the line will be updated. Visible means, that it is not a HTML comment. By default it looks like the following: `<EM>Modified 24-May-1997</EM>'
• hm--html-automatic-update-modified-line: t => The visible "modified" line will be updated with the current date before file saving. If such a line does not exist, nothing will be done.
• hm--html-modified-prefix: Prefix of the "modified" line. By default it is set to `"Modified: "'.
• hm--html-modified-start-tag: Start tag of the modified line. By default it is `<EM>'. If you change this, you'll need to change also hm--html--modified-end-tag.
• hm--html-modified-end-tag: End tag of the modified line. By default it is `</EM>'. If you change this, you'll need to change also hm--html-modified-start-tag.
• hm--html-modified-insert-before: The "modified line" will be inserted before this string. The search will be done from the end to the beginning. And the "modified line" will be put at least before the `</HTML>' and the `</BODY>' tags.

5.2.8 Latin 1 Characters

• hm--html-bind-latin-1-char-entities: Set this to nil, if you don't want to use the ISO Latin 1 character entities. This is only useful if hm--html-use-old-keymap is set to nil. It is only used when loading the html package the first time.

5.2.9 Drag And Drop

• hm--html-idd-create-relative-links: If t, then the hm--html-idd-* functions create relative links. Otherwise absolute links are used. The idd functions are used for drag and drop.
• hm--html-idd-actions: The action list for the destination mode hm--html-mode. Look at the description of the variable idd-actions.

5.2.10 Font Lock Keywords

• hm--html-font-lock-keywords-1: Subdued level highlighting for hm--html-mode.
• hm--html-font-lock-keywords-2: Gaudy level highlighting for hm--html-mode.
• hm--html-font-lock-keywords: Default expressions to highlight in the hm--html-mode.

5.2.11 Prefix Keys

• hm--html-minor-mode-prefix-key: The prefix key for the key tables in the minor mode hm--html-minor-mode.
• hm--html-mode-prefix-key: The prefix key for the keys in the major mode hm--html-mode.

5.2.12 Pulldown Menu Names

Perhaps you'd like to change the names to get the same menu names in the major and in the minor modes of the hm--html-menus package.

• hm--html-mode-pulldown-menu-name: The name of the pulldown menu in the major html mode.
• hm--html-minor-mode-pulldown-menu-name: The name of the pulldown menu in the minor html mode.

5.2.13 Hook Variables

You may use the following two variables, if you'd like to call special functions each time the major html mode is entered or the package is loaded.

• hm--html-mode-hook: This hook will be called each time hm--html-mode is invoked.
• hm--html-load-hook: Hook variable to execute functions after loading the package.

5.2.14 Previewing HTML Files

The following two variables are only used, if you preview html documents with Mosaic. There are also some other variables in `html-view.el'. See section Contents. Look at that file if you have trouble with the functions to preview the html document with Mosaic.

• html-view-mosaic-command: The command that runs Mosaic on your system.
• html-sigusr1-signal-value: Value for the SIGUSR1 signal on your system. See, usually, `/usr/include/sys/signal.h'.

  SunOS 4.1.x : (setq html-sigusr1-signal-value 30) SunOS 5.x : (setq html-sigusr1-signal-value 16) Linux : (setq html-sigusr1-signal-value 10))

5.2.15 Meta Element

• hm--html-meta-name-alist: Alist with possible names for the name or http-equiv attribute of meta. Currently I know of the names Expires, Keys and Author. Please send me (muenkel@tnt.uni-hannover.de) an email, if you know other standard html names for the meta element.

5.2.16 Indentation

• hm--html-disable-indentation: Set this to t if you want to disable indentation in hm--html-mode. And maybe send me (muenkel@tnt.uni-hannover.de) a note why you did this.
• hm--html-inter-tag-indent: The indentation after a start tag.
• hm--html-comment-indent: The indentation of a comment.
• hm--html-intra-tag-indent: The indentation after the start of a tag.
• hm--html-tag-name-alist: An alist with tag names known by hm--html-mode. It is used to determine if a tag is a one element tag or not. In the future it should also be used to get possible parameters of the tag. Use lower case characters in this list!!!! If you have problems with the indentation of :hm--html-one-or-two-element-tag elements, then you should set them to either :hm--html-one-element-tag or :hm--html-two-element-tag, depending on how you use these elements. In the future I'll try to implement a better indentation for these elements.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.