{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:
· It only supports one kind of list (unordered).  It's also a little tricky to enter lists; it's easy to accidentally generate illegal list text.  Lists generally work well when surrounded by plain untagged Roman text on both ends; when they abut headers, links, or other tagged text, often a list tag ends up missing or in the wrong place.
· It sometimes inserts superfluous <p> or <br> tags.
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.  You can, however, import an HTML document into a .jhtml document with the `Import...' command.

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

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

The HTML Menu
The `jhtml' menu has commands for applying hypertext tags to your text and managing them.  (You'll also want to use the commands on the `Font' menu, for instance, to create section headings.)

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 Web browsers.

Remember that this information is currently not written out in the HTML file, so links that use it will fail in the HTML document.  I hope to fix this in the future.

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.

Link to URL...
This command prompts you for the full or partial URL of a document to link to.  The editor tries to guess a likely document name based on the selected text, but as with `Local Cross Reference...' you will usually 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.html#Preferences'.  (Remember that this currently does not work with links to other HTML documents generated by jhtml-mode because the anchors are not written out in the HTML; I hope to fix this in the future.  You can, however, link to internal anchors of other HTML documents.)

Incidentally, the `Local Cross Reference...' and `Link to URL...' 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 command lets you include arbitrary literal HTML in your document:

Literal HTML Text
This command turns the selected text into literal HTML markup to be included in the generated HTML document verbatim.  This lets you use HTML features, such as inline images or definition lists, which are not directly supported by jhtml-mode.  For instance, to include the an inline image called foo.gif in the same location as your HTML document, you'd type the text
	<img src="foo.gif">
and select the entire line.  Then you'd choose `Literal HTML Text', and that line would be marked as verbatim HTML to be inserted into your generated HTML document.

In order to make it visually distinguishable from surrounding text, literal HTML text is displayed on­screen in a bold fixed­pitch font, against a sunken background.  (The latter may be difficult to see if your background is black or white.

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

Setting Document Attributes
The last few commands on the HTML menu allow you to specify the title, background image, and colours of the generated HTML document.  (Currently, there's no interface to remove one of these attributes once you've set it.)

Except for title, all these attributes are only effective on graphical web browsers that support HTML 3.2 or compatible standards.  (They work with Netscape Navigator 3.0, for instance.)

A note about colour
If you set any of the colour attributes, you should set all of them.  This insures that your text is legible, no matter what the viewer's colour preferences are.  For instance, if you specify deep sea green text for your page about algae, but you don't specify a background, your page will be rather difficult to read for someone who's set their default Web browser background to deep sea green.  For similar reasons, you should set the colour preferences if you specify a background image (to ensure that your text is legible against that image).

Document Title
You can set the document's title with the `Document Title' command, which prompts you for a title.  If you don't specify a title, the first line tagged as a level 0 heading is used as the title, if any; otherwise the document is titled `Untitled'.

The last several commands let you control the appearance of your HTML document using HTML 3.2 <BODY> tag attributes.

Background Image
`Background Image' lets you choose a background image displayed behind your text.  It prompts you for an image name, which must be a legal URL, either full or relative to the location of the HTML document.

If you use this, you should also set the text and background colours, as described below.  You should set the text colour to ensure that the text of your page is legible against the background you have specified, and you should set the background colour to ensure that the text is also legible for users who have background images or image loading turned off.

The image you choose is not actually displayed in the editing window, but will be specified when the HTML is generated.

Background and Text Colour
The `Background Colour' and `Text Colour' commands allow you to specify the colour of your text and background in the <BODY> tag of the generated HTML.  The colours you specify are reflected in your editing window.  Be warned, however, that different systems and even different monitors can display colours very differently; the colours you specify may be much lighter or darker on somebody else's display.  Make sure you have enough contrast between text and background.

Link Colour
The `Link Colour' lets you specify a colour to use for unvisited hypertext links in the document.  Like text and background colour, it's reflected in the editing window.  If you specify a link colour, then links won't be underlined (it's assumed you can distinguish them by colour); otherwise, they'll be displayed in the same colour as the rest of your text, and underlined to distinguish them.

Visited and Active Link Colour
The `Visited Link Colour' command lets you set the colour of visited links - hypertext links that the viewer has already seen (within the memory of the viewer's Web browser history mechanism).  It should probably be less eye­catching than the (unvisited) link colour, but distinguishable from ordinary text.

The `Active Link Colour' command lets you set the colour a link changes to while the user is activating it.

Neither of these options is reflected in the editor window as you edit the file; all links will be displayed in the colour you've selected for `Link Colour', if any.

Importing HTML
The `Import...' command lets you read in an existing HTML file, interpreting the HTML tags appropriately.  It is not a full HTML parser, but it understands a reasonably useful subset of HTML.  The files so produced will need some hand-editing.  In particular,
· the title is inserted as plain text (surrounded by <title> tags) in the body of the document; you'll need to set the document title by hand using the `Document Title...' command on the HTML menu,
· ordered lists and definition lists are turned into unordered lists,
· extraneous blanks and newlines are often inserted, especially blanks at the ends of lines, and
· a lot of tags are just nut understood at all
Many of the latter will be turned into literal HTML text, though, so you may find that the result of importing HTML is actually resonably usable even if not all the tags are interpreted.

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 special positions in the file, and by metainformation such as the document title or background colour.

(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 convenience 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
} {{{list:level:1 {7.0 9.0 99.0 103.0}} {jdoc:anchor:anchorname {3.0 4.0 15.0 16.0 18.0 19.0 97.0 97.14 105.0 106.0 108.0 109.0 111.0 112.0 120.0 121.0 123.0 124.0}} {sel {11.820 11.843}} {jdoc:xref:link {4.18 4.23 4.104 4.118 11.198 11.202 11.207 11.216 11.820 11.843 16.6 16.14 16.25 16.33 16.38 16.44 16.140 16.165 112.78 112.86 114.35 114.60 114.65 114.90 114.109 114.122 121.26 121.41 121.54 121.71 124.1 124.16 125.1 125.20}} {richtext:font:roman {2.0 3.0 4.0 4.4 4.9 4.18 4.23 8.35 8.38 8.42 8.46 11.39 11.44 11.109 11.115 11.120 11.124 11.150 11.157 11.198 11.202 11.207 11.211 11.263 11.267 11.295 11.300 11.305 11.309 11.381 11.386 11.544 11.549 11.572 11.577 11.640 11.645 11.733 11.738 11.799 11.805 13.28 13.33 13.73 13.78 15.0 16.0 16.6 16.14 18.0 19.0 21.0 22.0 24.0 25.0 26.0 27.0 27.109 27.115 31.44 31.76 33.0 34.0 34.140 34.141 36.124 36.127 36.145 36.151 38.0 39.0 39.302 39.305 41.105 41.106 41.164 41.188 41.222 41.235 41.284 41.294 45.0 46.0 48.122 48.130 52.0 52.74 54.0 55.0 55.231 55.241 55.296 55.303 61.0 62.0 62.94 62.98 64.0 65.0 65.170 65.176 69.0 70.0 70.11 70.14 72.0 73.0 73.107 73.112 75.94 75.100 77.0 78.0 84.0 85.0 85.118 85.124 87.0 87.11 90.0 91.0 97.0 98.0 98.113 98.116 99.53 99.60 103.73 103.76 105.0 106.0 108.0 109.0 109.38 109.43 109.130 109.133 109.327 109.334 111.0 112.0 112.16 112.21 112.78 112.86 112.121 112.129 112.193 112.198 112.220 112.226 112.232 112.236 112.256 112.264 112.286 112.290 114.35 114.60 114.65 114.90 114.109 114.122 116.19 116.24 116.58 116.63 116.141 116.146 116.166 116.172 116.217 116.222 116.241 116.245 116.290 116.294 116.442 116.446 118.66 118.71 118.121 118.126 118.279 118.284 120.0 121.0 121.153 121.158 123.0 124.0 124.1 124.16 125.1 125.20 126.0}} {richtext:font:italic {11.263 11.267 24.0 25.0 27.109 27.115 36.124 36.127 48.122 48.130 52.0 52.74 65.170 65.176 70.11 70.14 73.107 73.112 109.130 109.133}} {richtext:font:bold {11.150 11.157 39.302 39.305 55.296 55.303 109.327 109.334 114.109 114.122}} {richtext:font:bolditalic {31.44 31.76 41.222 41.235 124.1 124.16 125.1 125.20}} {richtext:font:typewriter {4.4 4.9 4.18 4.23 8.35 8.38 8.42 8.46 11.39 11.44 11.109 11.115 11.120 11.124 11.198 11.202 11.207 11.211 11.295 11.300 11.305 11.309 11.381 11.386 11.544 11.549 11.572 11.577 11.640 11.645 11.733 11.738 11.799 11.805 13.28 13.33 13.73 13.78 16.6 16.14 34.140 34.141 36.145 36.151 41.105 41.106 41.164 41.188 41.284 41.294 55.231 55.241 62.94 62.98 75.94 75.100 85.118 85.124 99.53 99.60 109.38 109.43 112.16 112.21 112.78 112.86 112.121 112.129 112.193 112.198 112.220 112.226 112.232 112.236 112.256 112.264 112.286 112.290 114.35 114.60 114.65 114.90 116.19 116.24 116.58 116.63 116.141 116.146 116.166 116.172 116.217 116.222 116.241 116.245 116.290 116.294 116.442 116.446 118.66 118.71 118.121 118.126 118.279 118.284 121.153 121.158}} {richtext:font:heading0 {1.0 2.0}} {richtext:font:heading1 {3.0 4.0 15.0 16.0 18.0 19.0 105.0 106.0 108.0 109.0 111.0 112.0 120.0 121.0 123.0 124.0}} {richtext:font:heading2 {21.0 22.0 26.0 27.0 33.0 34.0 38.0 39.0 45.0 46.0 54.0 55.0 61.0 62.0 64.0 65.0 97.0 98.0}} {richtext:font:heading3 {69.0 70.0 72.0 73.0 77.0 78.0 84.0 85.0 87.0 87.11 90.0 91.0}} {richtext:font:l_em {98.113 98.116 103.73 103.76}} {jdoc:anchorname:Introduction {3.0 4.0}} {jdoc:link:jedit.jdoc {4.18 4.23}} {jdoc:link:jedit.jdoc#Mode­Specific_Preferences {16.140 16.165}} {jdoc:link:jedit.jdoc#The_Format_Menu {16.25 16.33 121.54 121.71}} {jdoc:anchorname:Saving_and_Loading_Files {111.0 112.0}} {jdoc:link:jtexttags.tcl.jdoc {114.109 114.122}} {jdoc:link:jtexttags.tcl.jdoc#j:tag:restore_text_widget {114.65 114.90}} {jdoc:link:jtexttags.tcl.jdoc#j:tag:archive_text_widget {114.35 114.60}} {jdoc:anchorname:See_Also {123.0 124.0}} {jdoc:link:jdoc.jdoc {11.198 11.202}} {jdoc:link:jeditmodes/richtext-mode.jdoc {16.6 16.14 112.78 112.86 125.1 125.20}} {jdoc:anchorname:The_Sections_Menu {105.0 106.0}} {jdoc:anchorname:Converting_File_Formats {120.0 121.0}} {jdoc:link:jedit.jdoc#Rich_Save_As {121.26 121.41}} {jdoc:anchorname:Following_Links {108.0 109.0}} {jdoc:link:http://www.w3.org/ {4.104 4.118}} {list:1:ul {7.0 9.0 99.0 103.0}} {jdoc:link:jeditmodes/jdoc-mode.jdoc {11.207 11.216 124.1 124.16}} {jdoc:anchorname:The_Format_and_Font_Menus {15.0 16.0}} {jdoc:link:jedit.jdoc#The_Font_Menu {16.38 16.44}} {jdoc:anchorname:The_HTML_Menu {18.0 19.0}} {special:list_item:1 {7.0 7.1 8.0 8.1 99.0 99.1 100.0 100.1 101.0 101.1 102.0 102.1}} {jdoc:anchorname:Importing_HTML {97.0 97.14}} {jdoc:link:Importing_HTML {11.820 11.843}}} {{richptr 110.0} {abbrevstart 11.844} {matchend 39.134} {abbrevend 11.844} {insert 11.843} {insert_save 102.46} {anchor 11.821} {matchstart 39.129} {current 1.0}}} {}