The jdoc Document Viewer
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.09.30.
Copyright and contact information is available in
the
jstools documentation.
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.
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 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.)
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.)
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.
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.
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.
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.)
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.
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.)
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.
-
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.