# The `jdoc' Mode

## Introduction

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`.

## 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 ModeSpecific Preferences panel, as with any mode.)

## The jdoc Menu

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

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.

## Following Links

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.

## Saving and Loading Files

The file format `jdoc` 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 `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.)

## Converting File Formats

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.

## See Also

The jdoc Document Viewer
The `richtext' Mode
`
`