GSP
Quick Navigator
Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
dtinfo(user cmd) dtinfo(user cmd)

dtinfo — browse on-line information

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

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.

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.

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.

The following options are available:

Prints a summary of the command's syntax.
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.
Starts a secondary instance of dtinfo. Secondary instances do not respond to Dtinfo_ShowInfoAtLoc and Dtinfo_LoadInfoLib ToolTalk messages.
Prints information on the terminal as the command runs, if dtinfo is started from the command line.
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.
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.

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

Prints an entire specified section and all of its subsections. By default, only the specified section is printed.
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.
Specifies how many copies to print. The default value is 1. This option is ignored when generating an output file.
Specifies a size of paper to which the output should be formatted. Valid sizes are iso-a4, iso-b4, na-letter, and na-legal.
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.
Specifies silent printing. dtinfo does not write to either standard out or standard error, nor does it attempt to open any windows.

This section describes the features that affect printing with dtinfo.

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.

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.

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.

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.

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.

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

The XRM resources understood by dtinfo are as follows:

Specifies the default size of reading windows in pixel dimensions, x by y. The default is 500x630.
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.
Specifies whether the first document listed in the search results list is displayed automatically (true) or not (false). The default is false.
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.
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.
Specifies the default size of the graphical map window in pixel dimensions, x by y. The default is 520x350.
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.
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.
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.

The following resources set colors for various dtinfo display features:

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.
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.
Specifies the background color for the infolib book list. There is no default.
Specifies the foreground color for the infolib book list. There is no default.
Specifies the background color for the search results list. There is no default.
Specifies the foreground color for the search results list. There is no default.

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

Not used.

The following environment variables affect the execution of dtinfo:

Specifies the search path for locating information libraries on local and remote mounted systems.
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.
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.
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.
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.
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.

dtinfo registers with ToolTalk to handle the following ToolTalk requests:

Causes dtinfo to load the specified infolib or the default infolib, if none is specified.
Causes dtinfo to display a particular section of data or topic.
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:

Sends a DtInfo_ShowInfoAtLoc message.
Sends a DtInfo_LoadInfoLib message.
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.

Not used.

Not used.

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

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

None.

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

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.
This warning is displayed when both the -outputFile and -copies options are specified, and the number of copies is greater than 1.

This error indicates that the display specified by the printer resource or -printer option could not be opened.
This error indicates that the specified section locator could not be found.
This error indicates that specified section locator was incorrectly formatted.
Use the -sect option to identify the specific sections to print.
This error indicates that the memory needed to create the temporary file name could not be allocated.
This error indicates that the temporary file could not be opened for writing.

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/local/dt/infolib/C/cde.dti


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

If the infolib path environment variable is defined:

% dtaction DtShowInfoAtLoc cde INFOUG.GSTART.DIV.3

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/local/dt/app-defaults/%L/Dtinfo.

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

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

Search for    or go to Top of page |  Section u |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.