Table of Contents
Name
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 dtinfogen(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:
- -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.
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.
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:
CWprinted_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:
- 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.
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.
For print-related resources, see "Descendants" and "Resources"
in DtPrintSetupBox(3)
.
Not used.
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.
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.
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.
- 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: 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.
Start the browser and display
the default information library:
CW% dtinfo
Start the browser with a library located at /cdrom/encyclopedia.dti:
CW% dtinfo -l /cdrom/encyclopedia.dti
Start the browser with a library from the search path:
CW% dtinfo -l encyclopedia
Start the browser with a specific section to display:
CW% dtinfo -sect mmdb:INFOLIB=encyclopedia&LOCATOR=home_topic
or:
CW% dtinfo -sect INFOUG.SEARCH.DIV.5,INFOUG.SEARCH.DIV.22
An alternate form of the previous command:
CW% dtinfo -l /cdrom/encyclopedia.dti -sect mmdb:LOCATOR=home_topic
Print a specific section without starting dtinfo:
CW% dtinfo -print -sect INFOUG.NAVIGATE.DIV.3
Printing of an entire infolib is not supported from the command line:
CW% dtinfo -print -l /cdrom/encyclopedia.dti
*** Error ***
Examples for the use of dtinfo directly:
CW% dtaction DtLoadInfoLib /usr/dt/infolib/C/cde.dti
CW% dtaction DtShowInfoAtLoc /usr/dt/infolib/C/cde.dti GI.RGFBE.1698OL
If the infolib path environment variable is defined:
CW% 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/dt/app-defaults/%L/Dtinfo.
Utility files and supporting data for dtinfo are found in the system location
/usr/dt/infolib.
Generalized Locator Format(4)
, dtinfogen(1)
, DtPrintSetupBox(3)
,
DtInfo_LoadInfoLib(4)
, DtInfo_ShowInfoAtLoc(4)
, DtInfo_PrintInfoAtLoc(4)
,
dtinfoaction(5)
, DtMmdbInfoLibInfo(5)
Table of Contents