The jdoc document viewer is distributed as part of the jstools package.
This document describes jdoc version 4.1/4.4.
Copyright and contact information is available in the jstools documentation.
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.
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.
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.
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.)
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.
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.)
* 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.
* 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.