# The `html' Mode

## Introduction

The `html` mode of `jedit` is intended for editing HTMLformatted text, used on the World Wide Web. It's not WYSIWYG; while you edit you're looking at the raw HTML tags. However, it does make a number of common HTML idioms quicker to generate.

Note that the `richtext` and `jdoc` modes can also generate limited HTML. They provide a more WYSIWYG environment, but (for instance) `richtext` mode doesn't let you generate hypertext, and neither mode lets you generate lists. I hope to fix that; when I do, `jdoc` mode may become a more attractive option for composing HTML than `html` mode itself.

I make no pretense that `html` mode even approaches completeness. It provides shortcuts for the HTML constructions I use most frequently in my documents, but for many tags (and all entities), you'll have to type raw HTML yourself. See Bugs and Limitations below for the most noticeable absences.

This document describes the `html` mode available with version 4.0/4.0b of `jedit`.

Be warned that `html` mode does not translate the ``<`', ``>`', and ``&`' characters into the corresponding HTML entities as you type; the assumption is that you're typing those characters as part of an HTML tag or entity. If you want to include literal ``<`', ``>`', or ``&`' characters in your document, you'll need to type them as ``&lt;`,' ``&gt;`', or ``&amp;`', respectively.

## Preferences

In `tcl` mode, by default, the Space and Return keys do abbreviation expansion, your text will have newlines inserted automatically as you approach the right margin, and new lines will inherit the indentation of the preceding line. Of course, you can change any of these settings on the ModeSpecific Preferences panel.

## The HTML Menu

The `html` mode provides an `HTML' menu with commands for inserting HTML tags. (You may find them more convenient to invoke from the keyboard, using their underlined Altkey equivalents; for instance, typing Altt, Altm lets you start a new list item without taking your hands off the keyboard.) The commands generally fall into three categories:

* Some commands insert matching tags which surround text. These commands insert the tags around the selected stretch of text if there is one. If no text in the window is selected, then they insert the opening and closing tags around the insert point; i.e., the insert point ends up between the opening and closing tags. (You then need to move past the closing tag, either with the mouse or the keyboard, when you want to go back to typing ordinary, untagged text.) Thus, these commands accommodate the case where you want to apply an HTML tag to text you've just selected, as well as the case where you're about to type text that you wanted to be enclosed in a particular tag. The names of commands in this category start with `Make' (e.g., `Make Emphasized'

* Some commands pop up a prompt for additional information, and then use that information to insert some sort of moreorless complicated HTML construction in the document. These commands have ellipses at the end of their names (e.g. `Insert Image...'). Note that `Make URL Reference...' falls into both this category and the previous one.

* The remaining commands simply insert a single tag or sequence of text in the document. (Among these, `Insert Preformatted Selection' is special in that it uses the current X selection.)

### Particular HTML Commands

I won't go into all the HTML commands here, because many of them are selfexplanatory, but some deserve special comment:

#### Insert HTML Template

This command inserts a skeletal HTML document that you can use as a template. It's probably the first command you should issue when you create a new HTML document.

#### Make URL Reference...

This command prompts you for a URL to link to. It then makes the currentlyselected text a hypertext link to the given URL. If there is no currentlyselected text, it inserts the appropriate opening and closing tags and leaves the insert point between them so you can type the text of the hypertext link.

In the prompt panel this command brings up, pressing the Tab key will do filename completion as in Emacs or `tcsh`; this is convenient when, as is often the case, the URL you want to link to is a relative URL to a file in the same directory (or a subdirectory).

#### Insert Email Reference...

This command prompts you for an email address. The address you provide is inserted into your document, tagged as `sample' text (i.e., typically fixedpitch), surrounded in angle brackets, and tagged with an appropriate `mailto:` link. You might use this command, for instance, when you provide your email address in the `<address>` ... `</address>` section of a page you write.

#### Insert Image...

This command prompts you for a URL, and inserts it as an inline image in your document. As with `Make URL Reference...', the Tab key does filename completion in case the image you wish to display is in the same directory as the document you're editing (or a subdirectory), as it often is.

#### Making Lists

To make a list, you first choose `Make Unordered List', which inserts the beginning and ending list tags around the insert point. Then, for each item in the list, you choose `List Item', which inserts the `<li>` tag, and type the text of that item. When you're done with the list you need to move past the closing `</ul>` tag.

#### Insert Preformatted Selection

This command inserts the current X selection, if any, wrapped in `<pre>` ... `</pre>` tags. This lets you easily paste text from another window preserving the original text layout. (For instance, you could quote a section of program code this way.)

In the selection, occurrences of the characters ``<`', ``>`', and ``&`' are replaced by the corresponding HTML entities, so that you don't have to worry about strings in the selection that might look like HTML tags or entities. (Once you've inserted the selection, you can of course add markup.)

## See Also

The `jdoc Mode

The `richtext' Mode

A Beginner's Guide to HTML (at NCSA)

HTML Quick Reference (at NCSA)

The World Wide Web (at the World Wide Web Consortium)

## Evolution

### Bugs and Limitations

* Only fairly common tags are supported.

* There's no support for automatic insertion of HTML entities (e.g., no way to type ``<`' and have it automatically replaced with ``&lt;`', or to type ``Ö`' and have it automatically replaced with ``&Ouml;`'.

* It's a bit clumsy to use the tagwrapping commands as you type, because you have to move over the closing tag when you're done. There should be a keystroke to do this automatically.

* The document template should be customisable.

* To some extent, `html`mode enforces my own (possibly warped :-) notions of HTML style.

### Future Directions

* It would be nice to be able to automatically generate tables of contents from headings in a document.

* There should be a `Preview' command (either parsing the HTML directly or, more likely, passing it to an external HTML viewer).

* Obviously, the tag support needs to be more complete.

* There should be a way for the user to collect a library of HTML templates for document components on a second modespecific menu, for boilerplate text, graphics, or links.

* Ultimately, I want to replace this mode with a WYSIWYG one, probably closely based on `jdoc`mode.

``