The `jhtml' Mode

The `jhtml' Mode

Introduction

The jhtml mode of jedit is a WYSIWYG mode that allows creation of simple HTML documents, as used on the World Wide Web.

At present, it suffers from a number of limitations in the kind of HTML it can generate. Among the most important:

I hope to fix some of these limitations in future versions.

Another significant limitation is that jhtml mode doesn't edit HTML documents directly. Instead, it edits a .jhtml (or .jht) document, which is in a jstools­specific format similar to that used by jdoc and jdoc mode. Whenever the document is saved, however, it also writes out a corresponding .html (or .htm) document in the same directory. So the HTML is always generated from jedit's internal representation of the text. It follows that (without a lot of hand­editing) you can't take an existing HTML document that you didn't create with jhtml mode and edit it with jhtml mode. It also follows that if you edit the HTML generated by jhtml mode directly, you will lose your changes the next time you edit and save the original jhtml document.

This document describes the jhtml mode available with version 4.1/4.2 of jedit.

The Format Menu

As in richtext mode, the `Format' menu is available by default. (Of course, you can change which menus are available with the Mode­Specific Preferences panel, as with any mode.)

The jhtml Menu

The `jhtml' menu has commands for applying fonts and hypertext tags to your text. The first group of commands applies various fonts to the text. (These commands work identically to the corresponding `Level n Heading' commands, but they may be easier to access, especially if you use the keyboard shortcuts, and their names give a clearer sense of how they should be used in HTML files.)

Make Section Title

This command creates a level 1 heading.

Make Subsection Heading
Make Subsubsection Heading

These commands create level 2 and 3 headings, useful for finer structure in your document.

Make Overall Topic Title

This command makes a level 0 heading. There should be exactly one of these, at the very top of your document. (Nothing enforces this currently, but future versions of jhtml mode may use this as the title, or to generate indices.)

The next command doesn't affect the text at all:

Show Tags at Insert...

This command shows the text widget tags in effect at the insert point. Because these can be related to the names of anchors in your document or hypertext links, you can use this for troubleshooting or to remind yourself what the name of an anchor is.

The next few commands are used for turning the selected text into a hypertext link or anchor:

Anchor Name...

This command prompts you for a name to give to the selected region of text. The name can then be used as an anchor, the target of a hypertext link. A default name will be provided based on the content of the selected text, but you can replace it with whatever you like.

Within the editor, text that's been marked as an anchor is displayed on a stippled background, to give you some visual indication where the anchors are in your document. Anchors are not distinguished visually in jdoc itself.

Local Cross Reference...

This command prompts you for the name of an anchor in the current document. (You need to precede the name of the anchor with a hash mark, `#'.) The editor tries to guess a likely anchor name based on the selected text, but you may need to edit it. The selected text is then turned into a hypertext link to that anchor.

Local cross references are currently not reflected in the generated HTML. This may change in the future, however, and they are preserved in the .jhtml file.

Cross Reference...

This command prompts you for the name of a document to link to, in the same format you would use as an argument to jdoc on the command line. The editor tries to guess a likely document name based on the selected text, but as with `Local Cross Reference...' you may need to edit it. In the panel that prompts you for the document name, you can press the Tab key to do filename completion; this is useful if you are editing several documents in the same directory that have links to each other.

You can link to a particular anchor in another document by following the document name with a hash mark (#) and the name of the anchor within that document, as in `jstools.jdoc#Preferences'. (You can leave the trailing `.jdoc' off a document name and the link will still work, but I suggest you use full names.)

You can also use World Wide Web URL's starting with `http:' or `ftp:'; jdoc will try to use Mosaic to view these.

Incidentally, the `Local Cross Reference...' and `Cross Reference...' commands actually have identical effect; they only differ in the default links they suggest.

Man Page Reference...

This command makes a link to a UNIX manual page. It prompts you for the name of a manual page, making a guess based on the selected text. As a convenience, it also changes the selected text to typewriter font. (In some cases you may want to change this to some other font afterwards.)

Note that the actual text of the manual page is not included in the document, so the manual page will be looked up on the reader's system. You should be aware that the reader may not have the same manual pages (or any at all) available as you do, and that even if the same manual pages are available, they may describe different versions of software than they do on your system.

Currently, this kind of link is not reflected in the generated HTML at all. In the future I may provide a preference setting that would allow you to specify how to map man page entries to URLs, for people who have converted manual pages available.

The next few commands let you add structure to your document:

Horizontal Rule

This command inserts a horizontal line or separator in the document, corresponding to an HTML <hr> tag.

Creating and Editing Lists


The last three commands allow you to create unordered lists - lists of bulletted items.

To start a list, choose `Unordered List' (before typing the contents of the list). The first thing in any list must be a list item marker, so choose `New List Item'. (This is reflected as a bullet.) Type the contents of your list, using `New List Item' whenever you want to start a new item. When you're done, choose `End Unordered List' to go back to typing normal text.

To turn text you've already typed into a list, select the whole text and choose `Unordered List'. Then click at the beginning of the list and insert the first list item marker with `New List Item'. Continue inserting list item markers wherever desired in the list. (Your list will look better as you edit it if each list item marker is on the beginning of a line, although this won't make any difference in the HTML generated.)

You'll notice (if you're using Tk 4.0 or later) that the text of a list is indented with respect to the surrounding text (and that the bullets that mark each list item are indented less than the rest of the list). You'll also notice that the background of the list text is a stippled yellow. This is to allow people using Tk 3.6 and earlier to distinguish list text from normal text, and also to make it easier to tell if text you intend to be within the list isn't marked as belonging to the list.

All text within a list must be marked as part of the list (i.e., it must have the stippled yellow background). If any text within the list is not marked as part of the list, the HTML list generated will look very strange. After you edit text in a list, if you're not certain the entire list is still marked properly, you may find it useful to select the entire list and choose `Unordered List', just to make sure. (Then click somewhere else and choose `End Unordered List' before you continue typing normal text.)

The Sections Menu

The `Sections' menu lets you quickly jump to a particular section in your document, or to the top or bottom of the document. It uses level 1 headings to find the beginnings of sections.

Following Links

Ordinarily, clicking on a link within jhtml mode doesn't follow the link. (It would be hard to select text in a link if clicking did follow the link.) However, you may want to try following a link in your document while you compose it, for instance to see if you spelled a URL correctly. You can do that by holding down the Control key while you click on the link.

Saving and Loading Files

The file format jhtml files are saved in is internally identical to that that richtext­mode files are saved in, although richtext files don't have hypertext information in them. (The names of jhtml files should end in `.jhtml' or `.jht', and the names of richtext files should end in `.jrt'.) The first part of the file contains the actual text, and should be reasonably legible if you look directly at the file contents (with another editor, for example). This is followed by information about stretches of text with various styles - e.g., where all the sequences of boldface text start and end, and by information about special positions in the file, such as where the insert point is or where the last search started from. (This last information isn't normally used.)

(This format is implemented by the j:tag:archive_text_widget and j:tag:restore_text_widget procedures in the jtexttags.tcl library, which see for more information.)

In addition to the jhtml file itself, whenever you save a jhtml file a corresponding HTML file is also saved, in the same directory. If the jhtml file name ends in `.jhtml', the HTML filename will replace that with `.html'. If it ends in `.jht', the HTML filename will replace that with `.htm', for the benefit of people who need to move their HTML files to PC filesystems. Otherwise, the HTML filename will be constructed by tacking `.htm' onto the end of the original filename.

You'll never need to refer to the HTML file directly from withing jedit; it's always saved for you whenever you save the jhtml file. (In fact, you'll probably find it confusing if you try to edit the HTML file directly, because it will be overwritten the next time you save the jhtml file.)

Converting File Formats

You can use the editor's `Rich Save As...' command on the `Format' menu to convert your document to other formats. It's not generally useful to convert jhtml documents to HTML explicitly, since this is done for you automatically. When converting to other formats, some information is lost. (In particular, list formatting, horizontal rules, and hypertext links are lost.)

See Also

The `jdoc' Mode
The `richtext' Mode