dtinfo(user cmd)

NAME
dtinfo — browse on-line information

SYNOPSIS

dtinfo [-help] [-l infolib] [-sect section
 [ {-section | ,section } ...] ] [-secondary] [-verbose] [-print] [-hierarchy] [-printer x_print_server] [-copies number] [-paperSize size] [-s]

DESCRIPTION

The dtinfo command starts the desktop on-line information browser, also known as the CDE Information Manager. On-line information is typically packaged into an information library (infolib), which is a hierarchy of bookcases containing SGML books (see the dtdocbook2infolib(1) command). The browser offers an ability to view, search, and print on-line information with a high degree of control. Bookmarks and annotations may be attached at desired points for later recall.

  Generalized Locator Format

The generalized locator format is used as an identifier for target information. The following format shows the fully specified case, although it is usually not required to uniquely identify sections:

mmdb:INFOLIB=ilib_path&&BOOKCASE=bc_name&&LOCATOR=locator

where ilib_path is the infolib's path on disk; bc_name is the name of the bookcase (an MMDB); and locator is the MMDB locator value. The locator itself must be a unique reference across document collections by the time an infolib's build process is complete.

If just INFOLIB is present, the collection corresponding to the infolib is returned. To display at the beginning of a known bookcase, use the form:

mmdb:INFOLIB=ilib_path&&BOOKCASE=bc_name

Note, however, that bookcase names are less protected from change than locators, and should not be relied upon for other than dynamically verifiable bookcase targets.

If a locator is not expected to be in the desktop default infolib, identify its infolib by including the full file path name for the information library (ilib_path). The most common form of reference is then either:

mmdb:INFOLIB=ilib_path&&LOCATOR=locator

or:

mmdb:LOCATOR=locator

If INFOLIB and BOOKCASE are omitted, a locator is looked up in all loaded information libraries. If no information libraries are currently loaded, the locator is looked up in the default information library(s) specified by DTINFOLIBDEFAULT. For the -sect argument, the value(s) "locator" alone is sufficient to reach the desired section, if it occurs in the default infolib, or those indicated by -l arguments.

  Persistent User Settings

A few characteristics are saved across browser sessions. These are bookmarks, annotations, named search scopes, and certain user preferences. All of these are saved on a locale-specific basis. Query history and browse history lists are provided, but are not persistent across sessions.

OPTIONS

The following options are available:

-help
    Prints a summary of the command's syntax.

-l infolib
    Specifies an absolute file path or the filename of an information library. If an infolib's filename is specified, the search path specified by DTINFOLIBSEARCHPATH is used to help locate the file. If the -l option is omitted, the browser displays the default information library(s) specified by DTINFOLIBDEFAULT. This option can be specified more than once.

-secondary
    Starts a secondary instance of dtinfo. Secondary instances do not respond to Dtinfo_ShowInfoAtLoc and Dtinfo_LoadInfoLib ToolTalk messages.

-verbose
    Prints information on the terminal as the command runs, if dtinfo is started from the command line.

-sect section[{-section|,section}…]
    Specifies the infolib section or sections to either display or print. Sections can be specified in generalized locator format.

    To specify a range of sections, use the form:

    -sect section-section

    where the start and end sections are separated by the hyphen character.

    To specify a discontiguous list of sections, use the form:

    -sect section,section

    where the sections in the list are separated by the comma character.

    If the -print option is specified, the sections are printed. Otherwise, dtinfo loads the specified infolib(s) and displays all the sections in separate browser windows.

-print
    Instructs dtinfo to print the locations specified with the -sect option. Printing of an entire infolib from the command line is disallowed. If a specified location is not at the top of a section, the section containing the location is printed.

  Print Control Options

These options are valid only if the -print option is also specified.

-hierarchy
    Prints an entire specified section and all of its subsections. By default, only the specified section is printed.

-printer x_print_server
    Specifies which X Print server to use. If this is not specified as a command-line option or resource, the value is taken from the environment.

-copies number
    Specifies how many copies to print. The default value is 1. This option is ignored when generating an output file.

-paperSize size
    Specifies a size of paper to which the output should be formatted. Valid sizes are iso-a4, iso-b4, na-letter, and na-legal.

-outputFile filename
    Specifies a file to hold the print-ready output. If this option is specified, no output is sent to the printer. If this option is specified, the -copies option is ignored.

-s  Specifies silent printing. dtinfo does not write to either standard out or standard error, nor does it attempt to open any windows.

PRINT FEATURES

This section describes the features that affect printing with dtinfo.

  Page Numbers

Pages are numbered relative to the print job. For example, if a section spans over four printed pages, the pages are numbered 1-4. To get page numbers starting relative to the front of the book, it is necessary to print the entire contents of the book. When printing more than one book (a bookcase, for example) the page numbering is reset to page 1 at the start of each book. A section is determined to be a book if it is a Table of Contents.

When specifying "what to print" all references are given in logical terms. You cannot specify a page range since this number has no real meaning until the document is rendered to a given page size. "What to print" is specified as a section or list of sections in generalized locator format. It is also possible to specify a range of sections.

  Table of Contents

The table of contents can be printed as part of a book or as a separate section. When printed as part of a book, it is always printed last to allow the page number references to be calculated while the document is printing. When printed separately, the page numbers are not calculated.

  Image Scaling

Dtinfo supports a number of graphic file formats: Tiff, XPM, XWD, GIF, JPEG, and CGM. Of all these formats, only CGM is a natural "scalable" format made of vectors and independent coordinates, much like PostScript. All the other graphic formats are specified in Dots Per Inch (DPI) and designed for a given resolution. Since most displays have a resolution of between 90/100 DPI and printers commonly have resolutions of 300/600 DPI, printed documents can end up with graphics 3 or 6 times smaller than their screen counterparts, especially when the surrounding fonts are scaled to match the screen size.

To address this problem, dtinfo automatically scales a graphic according to the following formula:

printed_image_size= image_size * (resolution / 100 DPI)

During scaling it is important that the image not be scaled in excess of the hard page boundary. See "Hard Page Boundaries" for more detail.

  Hard Page Boundaries

On-line documentation is often developed with little or no consideration for printability. As a result, on-line documents often have graphics or tables that exceed the hard-page boundaries of the printed media. The dtinfo command attempts to correct these problems during the layout-for-print process by a combination of page break insertions, rotation (landscape/portrait), and scalable objects.

Graphic objects that are too wide for the page are scaled down to the page width.

Graphic objects that are too tall for the remaining page height are started on the next page. If a graphic object is too tall for a single page it is scaled down to the page height.

Table objects that are too wide for the page are started on the next page and rotated for landscape printing. If a table is still too large, it is scaled to the page height. Once the table has been printed, an additional page break is performed and the remainder of the printing resumes in the default page orientation. Space left in the current page layout is filled by flow-up of subsequent text.

  Hard Copy Page Style Rendering

dtinfo hard copy page-style rendering, with addition of headers and footers, page breaks, and numbering. For these characteristics, it is necessary to use print-specific style sheet features.

  Background Printing

dtinfo allows simultaneous browsing and multiple print requests to be active in parallel.

RESOURCES

  XRM Resources

The XRM resources understood by dtinfo are as follows:

BrowseGeometry
    Specifies the default size of reading windows in pixel dimensions, x by y. The default is 500x630.

BrowseLock
    Specifies whether the current reading window is automatically "pinned" when a new document display request is made (on) or not (off). If on, the new document appears in a new reading window. System resources utilized are often much higher in the on mode. The default is off.

DisplayFirstHit
    Specifies whether the first document listed in the search results list is displayed automatically (true) or not (false). The default is false.

FontScale
    Specifies the relative size to use for text in all reading windows, compared to the publisher-specified font size, where 0 means "per style sheet". Possible values are -2, -1, 0, 1, 2, 3, 4, and 5. Invalid values default to 0. A non-zero value is used by the browser to associate incrementally larger sizes of the same font, when possible. The default is 0.

MapAutoUpdate
    Specifies whether the graphical map (when visible) is automatically updated as the user moves to new documents (true) or not (false). The default is true.

MapGeometry
    Specifies the default size of the graphical map window in pixel dimensions, x by y. The default is 520x350.

MaxSearchHits
    Specifies the maximum number of document titles to be displayed in the Search Results List window in fulfillment of a query. The entries in the search results list are ordered roughly by importance to the query, so a value here includes the most relevant results. The default is 50.

NodeHistSize
    Specifies the maximum number of document visits to be maintained in the browse history list. Duplicates are not displayed in the list, but re-visits change the list order by moving a previously viewed document to the top. The browse history is not saved across dtinfo sessions. The default is 100.

SearchHistorySize
    Specifies the maximum number of previously performed queries to be maintained for the search history list. Using the search history list is a quick way to re-access the results of a prior query. The search history is not saved across dtinfo sessions. The default is 50.

  Display Color Resources

The following resources set colors for various dtinfo display features:

Dtinfo*display_area.background
    Specifies the background color for on-line document presentation. The user is cautioned to avoid choices of background color which match the color used for either hypertext links or search hits. The keyboard traversal highlight color should also be considered when setting this resource. There is no default.

Dtinfo*display_area.foreground
    Specifies the foreground color for on-line document presentation (used for text not otherwise highlighted). The user is cautioned to avoid choices of foreground color which match the color used for either hypertext links or search hits. There is no default.

Dtinfo*doc_list.background
    Specifies the background color for the infolib book list. There is no default.

Dtinfo*doc_list.foreground
    Specifies the foreground color for the infolib book list. There is no default.

Dtinfo.results*list.background
    Specifies the background color for the search results list. There is no default.

Dtinfo.results*list.foreground
    Specifies the foreground color for the search results list. There is no default.

  Print-Related Resources

For print-related resources, see "Descendants" and "Resources" in DtPrintSetupBox(3).

STDIN

Not used.

ENVIRONMENT VARIABLES

The following environment variables affect the execution of dtinfo:

DTINFOLIBSEARCHPATH
    Specifies the search path for locating information libraries on local and remote mounted systems.

DTINFOLIBDEFAULT
    Specifies the name of the default information library(s) to load if the -l or -sect option is not specified. Multiple information libraries can be specified by a comma separated list. By default, DTINFOLIBDEFAULT is initialized to the CDE infolib cde. Note that dtinfo will not start if there is no infolib specified explicitly or by default. DTINFOLIBDEFAULT requires the definition of an applicable DTINFOLIBSEARCHPATH.

PDPRINTER,
    LPDEST, PRINTER" 10 Specify the name of the printer to use if the -printer option, XPRINTER environment variable, and XpPrinter resource are not specified. dtinfo checks PDPRINTER first, LPDEST next, and PRINTER last to obtain a printer name that can be used to generate an X Printer Specifier to use for the default X Printer shown in the Printer Name text field. The host:display portion of the specifier is obtained by checking if the X Server to which the client application is connected is an X Print Server managing printer name. If not, the list of X Print Servers specified in the XpServerList resource is queried, until the first X Printer with a matching printer name is found.

XPRINTER
    Specifies the default destination X Printer Specifier for the DtPrintSetupBox. If the specifier is just a printerName, the host:display portion of the specifier is obtained by checking if the X Server to which the client application is connected is an X Print Server managing printerName. Otherwise, the first server in the XpServerList resource or the XPSERVERLIST environment variable that manages the printer will be used. If the :display number is omitted, :0 is assumed.

DTPRINTSILENT
    Specifies whether to display a Print dialog box if the -s option is not specified. When the variable is set to True, the Print dialog is not displayed. If the variable is not set, the dialog is displayed.

XPDMDISPLAY
    Specifies whether an alternate X Print Server will be used to find the PDM_MANAGER selection. If the variable is not set, an alternate X Print Server will not be used.

ACTIONS/MESSAGES

dtinfo registers with ToolTalk to handle the following ToolTalk requests:

DtInfo_LoadInfoLib
    Causes dtinfo to load the specified infolib or the default infolib, if none is specified.

DtInfo_ShowInfoAtLoc
    Causes dtinfo to display a particular section of data or topic.

DtInfo_PrintInfoAtLoc
    Routes print requests back to the requesting dtinfo process after the end-user drags one or more sections from the book list and drops them on the printer icon in the front panel.

Desktop actions invoking the browser are:

DtShowInfoAtLoc
    Sends a DtInfo_ShowInfoAtLoc message.

DtLoadInfoLib
    Sends a DtInfo_LoadInfoLib message.

DtPrintInfoAtLoc
    Sends a DtInfo_PrintInfoAtLoc message.

Use of any default desktop representations to start dtinfo from its icon or the icon of an infolib causes dtinfo to be invoked via the desktop action mechanism.

STDOUT

Not used.

STDERR

Not used.

INPUT FILES

For input, dtinfo accepts the file path, relative or absolute, for one or more information libraries.

OUTPUT FILES

For output, dtinfo produces a file to hold print-ready output, if the -outputFile and the -print options are specified.

EXTENDED DESCRIPTION

None.

RETURN VALUE

A non-zero return value for dtinfo implies an error condition on start-up.

ERRORS/WARNINGS

  Warning Messages

Warning: Illegal or missing paper size.
    This warning indicates an invalid value of the paperSize resource or -paperSize option. Correctly specify the option on the utility line or set a default resource value.

Warning: Illegal number of copies.
    This warning is displayed when both the -outputFile and -copies options are specified, and the number of copies is greater than 1.

  Error Messages

Error: Unable to open x print server &<x_print_server>
    This error indicates that the display specified by the printer resource or -printer option could not be opened.

Error: section not found.
    This error indicates that the specified section locator could not be found.

Error: invalid section specification &<section>.
    This error indicates that specified section locator was incorrectly formatted.

Error: printing of the entire infolib is not supported.
    Use the -sect option to identify the specific sections to print.

Error: unable to allocate memory for temporary file.
    This error indicates that the memory needed to create the temporary file name could not be allocated.

Error: unable to open temporary file.
    This error indicates that the temporary file could not be opened for writing.

EXAMPLES

Start the browser and display the default information library:

% dtinfo

Start the browser with a library located at /cdrom/encyclopedia.dti:

% dtinfo -l /cdrom/encyclopedia.dti

Start the browser with a library from the search path:

% dtinfo -l encyclopedia

Start the browser with a specific section to display:

% dtinfo -sect mmdb:INFOLIB=encyclopedia&&LOCATOR=home_topic

or:

% dtinfo -sect INFOUG.SEARCH.DIV.5,INFOUG.SEARCH.DIV.22

An alternate form of the previous command:

% dtinfo -l /cdrom/encyclopedia.dti -sect mmdb:LOCATOR=home_topic

Print a specific section without starting dtinfo:

% dtinfo -print -sect INFOUG.NAVIGATE.DIV.3

Printing of an entire infolib is not supported from the command line:

% dtinfo -print -l /cdrom/encyclopedia.dti
*** Error ***

Examples for the use of dtinfo directly:

% dtaction DtLoadInfoLib /usr/pkg/dt/infolib/C/cde.dti

% dtaction DtShowInfoAtLoc /usr/pkg/dt/infolib/C/cde.dti GI.RGFBE.1698OL

If the infolib path environment variable is defined:

% dtaction DtShowInfoAtLoc cde INFOUG.GSTART.DIV.3

FILES

Command line start-up recognizes an infolib directory path (see DtMmdbInfoLibInfo(5)). The name of the directory and its contained files is used to ascertain whether it is a valid infolib.

User-specific files for bookmarks and annotations are internally managed under the locale-specific directory $HOME/.dt/dtinfo/%L/marks/.

User preferences, set via the Preferences dialog in an instance of dtinfo, and user-defined search scopes are saved in the generated file $HOME/.dt/dtinfo/%L/preferences.

Application specific resources are defined in /usr/pkg/dt/app-defaults/%L/Dtinfo.

Utility files and supporting data for dtinfo are found in the system location /usr/pkg/dt/infolib.

SEE ALSO

Generalized Locator Format(4), dtdocbook2infolib(1), DtPrintSetupBox(3), DtInfo_LoadInfoLib(4), DtInfo_ShowInfoAtLoc(4), DtInfo_PrintInfoAtLoc(4), dtinfoaction(5), DtMmdbInfoLibInfo(5)