The `jdoc' Mode
The
jdoc mode of
jedit is intended for editing multifont hypertext documents to be
viewed with the
jdoc application.
This document describes the
jdoc mode available with version 4.1/4.4 of
jedit.
As in
richtext mode,
the `Format' menu is available by default. (Of course, you can change which
menus are available with the
ModeSpecific Preferences panel, as with any mode.)
The `jdoc' 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
jdoc files.)
Make Section Title
This command creates a level 1 heading.
jdoc (and also
jdoc mode) looks for level 1 headings to construct the `Sections'
menu, so these are the main divisions of your document.
Make Subsection Heading
Make Subsubsection Heading
These commands create level 2 and 3 headings, useful for finer
structure in your document. (jdoc doesn't currently treat these differently from any other font,
but may use them to generate a more detailed table of contents
in the future.)
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
jdoc may use this to generate an index of documents.)
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 group of 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.
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.
The next few commands let you add structure to your document:
Horizontal Rule
This command inserts a horizontal line or separator in the document.
It's not commonly used in
jdoc documents, but could be used to break a long stretch of text
into manageable pieces without using headers.
The `Sections' menu functions identically to the `Sections' menu
in
jdoc; it lets you quickly jump to a particular section in your document,
or to the top or bottom of the document.
Ordinarily, clicking on a link within
jdoc 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 an anchor name correctly. You can do that
by holding down the
Control key while you click on the link.
The file format
jdoc 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
jdoc files should end in `.jdoc', 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.)
You can use the editor's `Rich Save As...' command on
the `Format' menu to convert your document to other formats. Not all formatting
is preserved in every mode. In particular, underlining and
colour changes are not preserved at all, and lists and hypertext
links are only preserved when converting to HTML. I intend
to improve this in the future.
The jdoc Document Viewer
The `richtext' Mode