# The jdoc Document Viewer

## Introduction

The `jdoc` application was developed as a tool for displaying online manuals for Tkbased applications. It can be used to display other kinds of multifont hypertext documents as well. In addition to being able to follow hypertext links, you can quickly jump to any major section in the document you're viewing.

The `jdoc` document viewer is distributed as part of the jstools package.

This document describes `jdoc` version 1998.11.04.

Copyright and contact information is available in the jstools documentation.

## Invocation

`jdoc` [topic]

To view a document, type ``jdoc` topic' at the Unix shell prompt, assuming `jdoc` is in your path. You'll get an error message if no file can be found for the topic you specify. If the requested topic can't be found, an alert box will tell you so.

The `jdoc` application is used to display help files for jstools applications, so it is also invoked for you by those applications when you choose their `Help' commands.
`
` See Documents for information on how `jdoc` looks up topic names.

If you don't specify topic, you'll be prompted to choose a document from a list of available topics.

## Buttons

There are three buttons at the bottom of the document window:

### Quit

The `Quit' button closes the window and quits the document viewer. (It's the same as choosing `Quit' from the `Doc Viewer' menu.)

### Load...

The `Load...' button brings up a panel that lets you choose a new document from a list. (It's the same as choosing `Load...' from the `Document' menu.) See Documents for information on how `jdoc` finds the available documents.

### Print

The `Print' button sends the document as PostScript to the current printer, after asking for confirmation. (It's the same as choosing `Print' from the `Document' menu.)

### Find...

The `Find...' button brings up the Find Panel, which lets you search for text in the document you're viewing. (It's the same as choosing `Find...' from the `Document' menu.)

## The Sections Menu

The sections of the document are listed under the `Sections' menu (where each toplevel heading starts a new section), and you can jump to a particular section by choosing it from the menu. The document window will scroll so that the section you chose is displayed at the top. (Of course, you can also scroll through the document with the scrollbar.)

## The Document Menu

### Load...

Choosing `Load...' from the `Document' menu brings up a panel that lets you choose a new document from a list of the available documents. (See for information on how `jdoc` finds the available documents.) To choose a document, click on its name to select it, and then click `OK'. (You can also doubleclick on a title, but there's a bug that sometimes pops up a harmless error message when you do.)

### Save As...

Choosing `Save As...' from the `Document' menu brings up a File Selector Panel that lets you save the current document in one of three formats: TeX source, HTML, or the Tclsyntax richtext format used by the jrichtext.tcl library. If you have TeX available, saving a document as TeX source and typesetting that is probably the best way to get hardcopy of a `jdoc` document.

### Print

Choosing `Print' from the `Document' menu pops up a panel asking you to confirm that you want to print to the current printer, which must be a PostScript printer. If you click OK, the document you're viewing is converted to PostScript and the PostScript is sent to the printer.

If you don't have a PostScript printer, you may be able to generate hardcopy using one of the formats available via the `Save As...' command.

### Find...

Choosing `Find...' from the `Document' menu brings up the Find Panel, which lets you search for text in the document you're viewing.

### Quit

This quits the program (asking for confirmation first if you've chosen `Confirm Actions' on the Global Preferences panel). It's the same as clicking the Quit button.

## The Doc Viewer Menu

### Help with Doc Viewer

You can get help about the `jdoc` application - this file - by choosing `Help with Doc Viewer' from the `Help' menu. This starts up another copy of `jdoc` displaying `jdoc`'s help document.

### About the Doc Viewer...

`About the Doc Viewer' under the `Help' menu displays an information panel with copyright information. The panel also lets you get more information about the author (me), and about the Tk/Tcl scripting environment..

####

### Global Preferences...

This command brings up the jstools Global Preferences panel, which lets you set preferences common to all the jstools applications.

### Doc Viewer Preferences...

This command brings up the `jdoc` preferences panel, described below under Doc Viewer Preferences.

### Issue Tcl Command...

`Issue Tcl Command...' brings up a panel that prompts you for a Tcl command to be executed. This is mainly useful for debugging.

### Issue Unix Command...

This brings up a panel that prompts you for a Unix command to be executed. If the command produces any output, it will be displayed; otherwise you'll see a notice to that effect. If there are any errors in the execution of the command, you'll see an error dialogue box with the error message returned by the command. This command doesn't have any effect on the document you're viewing; it's just a convenience.

## Documents

The documents displayed by `jdoc` are files in a richtext format that can be created and edited by `jedit`'s `jdoc` mode. The actual file format is the same as that used by the `richtext` mode of `jedit`. Their names must end in .jdoc. (By default, `jedit` will open or create files ending in .jdoc in its `jdoc` mode, and it will open or create files ending in .jrt in its `richtext` mode.)

In some circumstances, such as specifying a topic on the command line, you can leave off the trailing .jdoc from a document name; it doesn't hurt to include it, though.

### How Documents Are Found

If a document is specified as a full pathname, that file is opened. If (as is usually the case) a relative pathname is specified, however, the following directories will be searched for the file until it is found:

- the current directory
- tk/jdoc in your home directory
- .tk/jdoc in your home directory
- jdoc in the systemwide jstools library directory (typically /usr/local/lib/jstools)
- jdoc in the systemwide Tk library directory (typically /usr/local/lib/tk)

A relative pathname can include a directory component, so that for instance the document name jeditmodes/jdoc.jdoc would find a file named /usr/local/lib/jstools/jdoc/jeditmodes/jdoc.jdoc. This is useful for grouping related documents together, and for `hiding' documents that are designed to be referenced only from within other documents, rather than being selected by the user.

When you choose `Load...' or invoke `jdoc` without a document name, `jdoc` constructs the list of available documents by looking for files ending in .jdoc in the above directories. (However, it doesn't search subdirectories of the above directories.)

### Creating Documents

Note: This material is covered in more detail in the documentation for `jedit`'s `jdoc` mode.

To create a document for display by `jdoc`, simply edit a file whose name ends in .jdoc with the `jedit` editor. A `jdoc' menu will be available to help you construct crossreferences, and the `Format' menu will let you compose multifont text.

The very first line of your document should be an overall title for the document, and you should use `Make Overall Topic Title' to put this in the right font. (It's possible that future versions of `jdoc` will use this when constructing the list of available topics, or when converting to other formats.) No other text in the document should be marked as an overall topic title.

The document should be divided into sections, and each section should have a section title (created with `Make Section Title'). The user will be able to navigate among these sections with the Sections menu, which is constructed from the section titles. (In the future, some sort of automatic tableofcontents or index may also use this information.)

You can further divide a section by preceding subsections with a subsection heading with `Make Subsection Heading'. If you need further subdivisions, you can use the various heading styles under the `Font' submenu of the `Format' menu.

You can create a cross reference to another document by highlighting the document name (or the phrase you want to link to the document) and choosing `Cross Reference...'. A panel will appear asking you to confirm (or specify) the document to link to. You need to include the trailing .jdoc in the document name.

You can also make a crossreference to another point in the current document by using a hash mark (`#`) followed by an anchor name (for which see below) instead of a document name. For instance, ``#Preferences`' would link to the anchor named ``Preferences`' in the current document.

An anchor is a particular piece of text (typically a heading or subheading) which is given a particular name. The anchor name isn't actually displayed anywhere when the user is viewing the document, and it is entirely arbitrary. It's only used to identify a particular position in the text. (For this reason, it's not useful to have more than one anchor in a document with the same name.)

You can create an anchor by selecting text and choosing `Anchor Name...'; a name will be suggested for you based on the selected text. An anchor name should not have any spaces or ``+`' or ``-`' signs in it.

You can link to a particular point in another document by specifying the document name, then a hash mark, then the anchor name. For instance, ``jstools.jdoc#Usage`' would link to the anchor named ``Usage`' in the document jstools.jdoc.

(You can also create links to `http:` and `ftp:` URL's, as used by the World Wide Web, by specifying the full URL, and to HTML documents by specifying a pathname ending in .html, but these will only be displayed properly if `Mosaic` is available. See also Future Directions.)

You can link to a Unix manual page entry by selecting the manual page name and choosing `Man Page Reference'.

The `Show Tags at Insert' command is useful for figuring out the name of an anchor, or what a crossreference is pointing to.

## Doc Viewer Preferences...

Choosing `Doc Viewer Preferences...' from the `Doc Viewer' menu brings up the Doc Viewer Preferences panel, which lets you customise the appearance of the text window that displays a document. It lets you set the overall width and height of the window (in characters), the colours used to display your text, the width of the raised border drawn around selected text, and the width of the blank border around the entire text window.

The buttons labelled `RGB' let you select a colour by manipulating sliders that represent the individual red, green, and blue components of the colour you're choosing. The buttons labelled `Name' let you select a colour by name, from the list of colours known on your system.

(Note: If the name of the colour database on your system isn't /usr/lib/X11/rgb.txt, then the `Name' colour buttons won't list all the colours available.)
(Many of the preferences you can set in the jstools Global Preferences panel also affect the document viewer. You can bring up the Global Preferences panel by choosing `Global Preferences...' from the `Doc Viewer' menu.)

Doc Viewer preferences are stored in the file ~/.tk/jdoc-defaults. (Global preferences are saved in the file ~/.tk/defaults.)

## Customising jdoc

`jdoc` supports the standard jstools customisation mechanisms. You should consult the general jstools customisation documentation as well as the description below.

### The ~/.tk/jdoc.tcl startup script

The file ~/.tk/jdocrc.tcl can contain Tcl code to customise your document viewing environment. For most purposes, you'll need to know Tcl and Tk, and look at the code for the document viewer, in order to create a useful startup script. (You may also find it useful to look at the documentation for the various jstools libraries, which are used extensively by the file viewer.)

### Sample files

If `jdoc` was installed normally at your site, the directory /usr/local/lib/jstools/samples should contain some example files which you can copy, rename appropriately, and modify to your liking. (You may also find it useful to look at the `jdoc` script itself, and for information about Tcl syntax you should consult the various Tcl and Tk man pages.)

## Bugs and Misfeatures

- The behaviour of the Find panel (searching from an invisible insert point) is confusing.
- If you move the mouse while doubleclicking on a title in the `Load...' panel, a bug in the mouse bindings is triggered and pops up a notification panel.
- The `Load...' panel should be a lot fancier. Perhaps there should be a database of document titles, as distinct from filenames, and the `Load...' panel should display the longer titles.
- When you `Save As...', hypertext links are lost in the saved file, even if you're saving in a format that supports the concept.
- The underlining that indicates links hides the underscore character; this is a particular problem with programming documentation.

## Future Directions

##

##

There should be preferences for fonts.
- The user should be able to customise how links are shown, perhaps using a different colour or a raised border instead of underlining them.
- I want to standardise bindings for noneditable text widgets and put them in the bindings libraries in some fashion.
- The Find panel should work differently; it should highlight all the found strings, and then let you jump back and forth among them.
- I'd like to support a mechanism for making documents available in multiple languages and selecting the right one, if available, based on a usersettable or sitewide preference.

`
`