Lectern1

Usage

Overview

Lectern is a document viewer. It is intended to make it easy and comfortable for you to read text documents, such as technical papers, on-line.

Lectern lets you view documents that are in a proprietary format, created by the program BuildLectern(1). These documents contain images of each page, at original resolution and at reduced resolutions, as well as data derived from the document by applying an OCR algorithm. The page images can be acquired by scanning, or by rasterizing some machine readable form (e.g., by using a program such as GhostScript - gs(1) - to render PostScript files into images). See the BuildLectern(1) man page for details on how to construct and modify Lectern documents.

When Lectern starts up it creates a single image window displaying the first page of the Lectern document whose path is file (or an error message, or the Digital logo if file is omitted).

SRC has a substantial shared repository of Lectern documents. The repository can be browsed hierarchically, or through a full text index. See the Virtual Paper home page to get started.

You can use the programs LecternToHTML(1) and BuildLecternIndex(1) to build such repositories.

User interface generalities

You can choose whether to drive Lectern's user interface primarily with a mouse or from your keyboard. You can discover all of Lectern's commands using your mouse and the pull-down menu: click the down-arrow at the top left corner of the image window to see the menu, or just type m. The menu goes away whenever you execute a command, or when you click the up-arrow at its top left, or when you type m once more.

If you are using the mouse as your primary tool, you will want to make the toolbar visible. Type t or click Show or Hide Toolbar on the menu. The commands on the toolbar are shortcuts for things you could have done from the pull-down menu. The + and “pencil” buttons in the link browsers (described below) are also designed to assist those whose are using a mouse. In the toolbar sub-window, the +/- 1/5/20 buttons (for moving 1, 5, or 20 pages at a time), activate on a down-click, and auto-repeat if you keep the mouse button held down.

If you are using your keyboard as your primary tool, you might still want to look at the menu as documentation: it describes all the keyboard shortcuts. Just type m to see the menu, then type the keyboard shortcut for the command you want (or m again) and the menu will go away.

The command descriptions below are given in terms of the keyboard shortcuts, with the equivalent menu commands in parentheses.

Some Lectern commands produce pop-up dialogs. In general, you can cancel or close any dialog by typing [escape] or by clicking the up-arrow in the corner of the dialog; some also have a Cancel button. In general, one button in the dialog has a black outline; typing [return] is equivalent to clicking that button.

Issuing any command implicitly closes the error dialog, the About Lectern dialog, and the menu. Any command other than one of the Find commands closes the Find dialog.

Some of the pop-up dialogs have type-in boxes. You can edit text in these using keyboard commands as specified for the FormsVBT library: see the FormsVBT Reference Manual. By default these commands are similar to simple Emacs commands. You can also copy text into (or out of) them using these commands.

Lectern refers to the images in the document by page number, as far as possible. The document's creator should have specified which page should be treated as page 1, in a way that corresponds to the page numbers printed on the pages and used in tables of contents or indexes. Lectern refers to images prior to page 1 by image numbers, counting the first image in the document as image 1. The menu anchor shows the current page number, or the current image number when you are positioned before page 1. The menu itself always shows the current image number, and the page number when it is defined.

Files and printing

This section describes explicit commands for controlling Lectern's access to files. The link mechanism provides other ways to open files. As mentioned earlier, you can also use LecternClient(1), and you can access Lectern documents through Mosaic and the WWW.

You can type o (Open Document) to open further Lectern documents, either in separate windows (click New in the Open dialog) or replacing the document in the current window (click Here in the Open dialog, or type [return]).

You can close an image window at any time using the facilities of your window manager or by typing w (Close Viewer). If you used the links mechanism to modify the document and you haven't saved it, you will be asked to confirm that you really want to discard your modifications.

When you close the last image window, Lectern quits. Typing q (Quit) is equivalent to closing each image window in turn.

Type p (Print) to send the images (or original PostScript) to the printer, or to save images as EPSF or PostScript job files. Note that printing rasterized 300 DPI images is quite slow - multiple minutes per page on typical printers. It would be even slower for grayscale or color images, except that printing them isn't implemented yet. Printing the original PostScript (if it's available) proceeds at the original rate.

Selections

You can select text in the image window by clicking (once) with the left mouse button. You can extend the selection by dragging, or by right-clicking, or by shift-clicking. A selection can extend over multiple pages. When you have selected text, it is available in character form as the X-11 “source selection”. For example, you can paste it into an xterm by middle-clicking there. The characters you get, and the order of the words in an extended selection, are those provided by the OCR algorithm that was applied to the images by BuildLectern(1).

If you double-click with the left mouse button on a word, Lectern will select that word then try to find the next occurrence of the word in the document, as if you had typed f (Find), followed by the word, followed by [return] (Find Next).

If you double-click with the middle mouse button on a word that is an integer, Lectern will select that word and move to that page of the document, as if you had typed the number followed by [return] (To Page).

Navigating

This section describes Lectern's basic navigation commands. The link and thumbnail mechanisms (described later) provide further navigation tools.

Type [space] (Go Forward) to move forward in the document and [backspace] (Go Backward) to move backward. See the section on View-Area and Viewing Controls for a more precise description. You can equivalently use the cursor or arrow keys on your keyboard: up or left means Go Backward, down or right means Go Forward.

Use + (Next Page) to move to the next page. Use - (Previous Page) to move to the previous page. b (Beginning Page) moves to the beginning of the document. c (Contents Page) moves to the first contents page, if the document has a known contents page. i (Index Page) moves to the first index page, similarly. The function key next or page down is equivalent to +, as is =; the function key prior or page up is equivalent to -. The function key end moves to the end of the document.

Type h (Home), or use the home function key, to move to the page containing the selection (or the beginning of the document if there is no selection).

Typing any digit 0 through 9 brings up the go dialog, with its type-in initialized to the digit. Finish typing a number, then type [return] (To Page) to go to that page. Or type + (Fwd) to go forward that number of pages, or - (Back) to go back that number of pages. For example, if you're on page 34, type 7[return] to go to page 7, or 7+ to go to page 41, or 7- to go to page 27. The meaning of page 1 was defined by the document's creator, so as to correspond to the page numbers in the document: it's likely not to be the first image in the document. Images before page 1 have no page numbers; you can get to them only by relative positioning, or commands such as b (Beginning Page) and c (Contents Page).

As described above, middle-double-click on a number is a shortcut for typing number [return], i.e., it goes to the numbered page, provided the document's creator correctly specified the location of page 1.

Type f (Find) to pop-up the Find dialog. Also, if the selection is not on the current page, this command sets an empty selection at the start of the current page. (If you don't want that, type h (Home) first.) In the Find dialog you can type a search target (currently only a single word), then click First, Next or Prev to find the first, next, or previous occurrence of that word in this document, starting at the beginning of the selection. You can type [return] as a shortcut for Next. After the search, keystrokes are interpreted as commands (any of which will implicitly close the Find dialog). But while the Find dialog remains visible, you can continue typing [return] to find the next occurrence of the search target. Type [escape] to close the Find dialog explicitly.

As described above, left-double-click on a word is a shortcut for typing f word [return], i.e., it finds the next occurrence in this document.

Type u (Undo Page Change) to undo the most recent operation that moved to a different page or to a different resolution (< or >, described below). You can repeatedly type u to move backwards in history, until you reach the point where you opened this window. This includes moving back across places where you opened a new document into an existing window. Type r (Redo Page Change) to redo, i.e., to undo an undo command (if you haven't moved to another page or resolution in between).

If you hold down the middle mouse button (or control-left) in the image window, you can drag the image around. The effect of this dragging is transient - it is ignored the next time you issue a command that moves around the page or moves to another page. See also the description of the View-Area and Viewing Controls, which provide a more persistent way of altering the part of the image that is visible.

Links and thumbnails

Links and thumbnails provide a mechanism that lets you jump to a particular page of a particular document with a single click. If the link specifies a different document, jumping implicitly opens the document. Jumping can also select some text starting on the specified page.

Lectern supports three types of links:

Thumbnails are stored with a document, and are generated automatically by BuildLectern(1)}. They provide a visual way to find a page within that document.

Bookmarks, diaries and outlines are all essentially the same mechanism. They differ in how or when they are created, accessed and deleted, and how and where they are stored. But each of them is just a way of remembering a particular place in a particular document (not necessarily the current document).

Bookmarks, diary links and outline links are identified by text strings. Thumbnails are identified by 1/16 scale images of their pages.

To create a link of any type, first go to the place that you want the link to jump to. Then either type n (New Bookmark) to create a bookmark, or click the + button in one of the link browsers to create a link of the corrseponding type. Lectern chooses a name for the link and creates it.

Whenever you stop viewing a document (by closing a viewer, by terminating Lectern, or by opening a new document in an existing viewer), Lectern creates a bookmark link describing the place that you just left.

Creating an eleventh bookmark link implicitly deletes the first bookmark link.

A newly created link is placed at the bottom of its class. You can use e (Edit Links) to promote it or to rename it, or to convert it to another type of link, as described below.

The simplest way to jump to a link or thumbnail is to type L (Show or Hide Link Browsers), so that the link browsers are visible in your image window, then click once on one of the links or thumbnails. If you left-click, the link's destination is loaded into the current window; right-click or shift-left-click to load it into a new window.

If you prefer to use the keyboard to jump to a link, type j (Jump to Link). In the popup-up dialog, select the type of link you're interested in (by default you see the bookmarks). You can do this by clicking one of the radio buttons, or by using the right-arrow and left-arrow cursor keys on your keyboard. Then select the link: type the initial part of the its name (until the appropriate link is selected); or select it manually in the dialog using the mouse; or select it using the down-arrow and up-arrow cursor keys on your keyboard. Or use a combination of all of these methods. Then type [return] (Jump) to jump to it.

You can use e (Edit Links) to modify the existing sets of links. (You can't modify the thumbnails.) In the Edit Links dialog you can select a link in the usual ways. You can use the (Up) and (Down) buttons to change the order of the links. You can convert a link from one type to another. Or you can rename a link. You can do these operations for several links in a single use of the dialog.

You can also edit links by clicking the “pencil” button at the top of one of the links browsers, when they are visible.

Changes you make to your diary or to the set of bookmarks are saved when you close the New Link or Edit Links dialog.

You can save changes that you make to a document's outline with the s (Save Document) command.

Your bookmarks and diary are shared across simultaneously executing Lecterns, provided they access the same "$HOME". When one Lectern saves changes to your diary or bookmarks, any other copy of Lectern notices the changes in about 10 seconds, and updates its viewers appropriately.

You can access someone else's bookmarks or diary from within Lectern by opening their $HOME/.bookmarks.lect or $HOME/.diary.lect as an ordinary Lectern document: their bookmarks or diary will appear as the outline of that document.

Windows and settings

Type m (Menu Buttons) to pull down or release the menu. Type k (Menu Anchor) to show or hide the menu anchor button. Type v (Viewing Controls) to show or hide the viewing controls window (described below). Type t (Thumbnail Window) to show or hide the thumbnail window (described earlier). Type [return] to confirm an operation in a modal dialog, or to close the About Lectern window. Type [escape] to cancel or close a dialog.

You can zoom an image window by typing z (Zoom) (and again to unzoom it). When you do this, Lectern tries to make the image window occupy the entire screen. This is especially effective if you use Lectern for presentations. And you can use the k (Menu Anchor) command to hide the menu anchor button, leaving your entire screen filled with just the images.

By default Lectern shows the images scaled to 100 dots per inch (DPI) (if the originals were 300 DPI). This makes the image look life size or somewhat larger on your screen, depending on the actual resolution of your monitor. Type > (Larger Images) to move to a finer resolution (magnifying the image), or < (Smaller Images) to move to a coarser resolution (shrinking the image). Typing , or . is equivalent to < or >. The available resolutions are 75, 100, 150 DPI (or more accurately, scale factors of 4, 3, and 2 from the original images). Most current monitors are 75 to 100 DPI.

View-area and viewing controls

The view-area is a rectangle specifying what part of the current page image you would like to be able to view. By default, Lectern calculates this for you automatically whenever you move to a new page, and by default the [space] (Go Forward) command traverses through the view-area of the current page in vertical strips, starting at its top-left corner. When you reach the bottom right, [space] (Go Forward) moves you to the next page. The [backspace] (Go Backward) command works similarly in the opposite direction.

This process works well if the automatic calculation corresponds to the part of the page you actually want to view, and if the page is set in either one or two columns, and if each column is no wider than the window. In other situations, you might need to intervene. On occasion, the best fix is to change the width of the Lectern viewer window. The rest of the time you'll need to use the viewing controls sub-window. Type v (Viewing Controls) to show or hide the viewing controls sub-window.

If Lectern's automatic calculation of the view-area is wrong, use your mouse to adjust the view area rectangle's corners in the viewing controls sub-window. Doing so flips the radio button below the thumbnail from automatic to manual. Your choice of rectangle persists from page to page, until you choose a different rectangle, or click the automatic radio button or type a (Automatic View Area), which switches back to having Lectern calculate the view-area for you on each page.

If traversing the view-area by vertical strips isn't appropriate, click one of the other radio buttons in the viewing controls sub-window. Using horizontal strips is good for some pages laid out as tables. Using a single strip down the center of the page is good if you want to ignore marginal labels or notes. Using "to the next page" is good for concentrating on the center of the view area, ignoring intrusive marginal notes, headers and footers. I've never used a single strip across the page, but it completes the set. Note that if the entire view-area fits into the window, all the choices here are equivalent. Your choice of traversal method persists from page to page, until you change it.

LecternClient

You can also create a viewer on a Lectern document with the LecternClient program. LecternClient will communicate with an existing instance of the Lectern program, or if necessary will start Lectern for you. See the LecternClient(1) man page for details.

Using LecternClient causes Lectern to load a document into the image window labelled as server. The first image window is the initial server. You can type d to detach an image window, so that it is no longer the server. In this situation, or if you close the server window, the next LecternClient request will create a new image window as the server window.

LecternClient can have one or two integer arguments following the document's file title. If the first integer argument is present, it is interpreted by Lectern as a word number; the second is a word count. If they are present, these arguments cause Lectern to select a range of words in the document (counting from 0), and to position the opened document to the page containing the start of that selection.