The `jhtml' Mode
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), and a fixed
level of list nesting (currently up to three levels of lists).
It's also a little tricky to enter lists; it's easy to accidentally
generate illegal list text.
- It sometimes inserts superfluous
<p> or
<br> tags.
- It doesn't support documentinternal links (i.e., links to
another place in the same document). It lets you enter them,
but doesn't save them in the HTML it generates.
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
jstoolsspecific 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 handediting) 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.4 of
jedit.
As in
richtext mode, the
`Format' and
`Font' menus are available by default. (Of course, you can change
which menus are available with the
ModeSpecific Preferences panel, as with any mode.)
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 onscreen in a bold fixedpitch
font, against a sunken background. (The latter may be difficult
to see if your background is black or white.
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 next few commands allow you to create unordered lists - lists
of bulletted items. Three levels of unordered lists are available;
only the first level is described here.
To start a list, choose `Make 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 `Make 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 list text
is on a raised background. 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 `Make Unordered
List', just to make sure. (Then click somewhere else and choose
`End Unordered List' before you continue typing normal text.)
I hope to fix this in future versions.
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 eyecatching 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.
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.
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.
The file format
jhtml files are saved in is internally identical to that that
richtextmode 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.)
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.)
The `jdoc' Mode
The `richtext' Mode