DTINFO(1)

📦
version 2.5.3 · 2 versions
, in nixos 26.05

💖 dtinfo 💖 — browse on-line information

okay bestie, welcome to dtinfo(user cmd) — the manual page you're about to devour. this is the desktop on-line information browser situation and honestly it's giving main character energy ✨

🌸 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 💜

So the dtinfo command starts up the desktop on-line information browser — you might also know it as the CDE Information Manager 👑. On-line info is typically packaged into an information library (infolib), which is literally a hierarchy of bookcases containing SGML books (peep the dtdocbook2infolib(1) command for that part). The browser lets you view, search, and print on-line information with a high degree of control — like, so much control. And you can slap bookmarks and annotations onto whatever points you want for later recall 🎀.

✨ Generalized Locator Format ✨

The generalized locator format is the identifier used for target information. Here's the fully specified case, though ngl you usually don't need all of it 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. That locator has got to be a unique reference across document collections by the time an infolib's build process is complete — no cap.

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

mmdb:INFOLIB=ilib_path&&BOOKCASE=bc_name
⚠️ heads up though: bookcase names are less protected from change than locators, so don't go relying on them for anything other than dynamically verifiable bookcase targets. 💀

If a locator isn't expected to be in the desktop default infolib, you 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, the locator gets looked up in all loaded information libraries. And 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 enough to reach the desired section — that's if it occurs in the default infolib, or those indicated by -l arguments 🫶.

🦋 Persistent User Settings 🦋

A few characteristics get 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, periodt. Query history and browse history lists are provided, but they are not persistent across sessions 😭.

💅 OPTIONS 💅

The following options are available, bestie:

  • -help — Prints a summary of the command's syntax.
  • -l infolib — Specifies an absolute file path or the filename of an information library. If you specify an infolib's filename, 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. You can specify this option 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. iykyk.

  • -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. shhh 🤫

This section describes the features that affect printing with dtinfo. buckle up 🎀

🍓 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. iconic behavior honestly 💅

  • 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. multitasking queen 👑

🎀 RESOURCES 🎀

💅 XRM Resources

Okay so here's the whole menu of XRM resources that dtinfo understands — like, every single one, no skips:

  • BrowseGeometry — sets the default size of reading windows in pixel dimensions, x by y. The default is 500x630. 📐
  • BrowseLock — controls whether the current reading window gets automatically "pinned" when a new document display request comes in (on) or not (off). If it's on, the new document shows up in a brand new reading window. Heads up though: system resources utilized are often much higher in the on mode. The default is off. 😭
  • DisplayFirstHit — says whether the first document listed in the search results list pops up automatically (true) or not (false). The default is false.
  • FontScale — sets 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 — decides whether the graphical map (when visible) updates automatically as you move to new documents (true) or not (false). The default is true. 🗺️
  • MapGeometry — the default size of the graphical map window in pixel dimensions, x by y. The default is 520x350.
  • MaxSearchHits — the maximum number of document titles 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 — the maximum number of document visits kept 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 — the maximum number of previously performed queries kept 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

These ones set colors for all the various dtinfo display features:

  • Dtinfo*display_area.background — 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 — 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 — the background color for the infolib book list. There is no default.
  • Dtinfo*doc_list.foreground — the foreground color for the infolib book list. There is no default.
  • Dtinfo.results*list.background — the background color for the search results list. There is no default.
  • Dtinfo.results*list.foreground — the foreground color for the search results list. There is no default. 🎨

For the print-related resources, bestie, go see "Descendants" and "Resources" in DtPrintSetupBox(3). That's where the tea is.

🫶 STDIN

Not used. Nope. Nothing. Nada. 🙈

🌸 ENVIRONMENT VARIABLES

These env vars affect the execution of dtinfo, so pay attention:

  • DTINFOLIBSEARCHPATH — the search path for locating information libraries on local and remote mounted systems.
  • DTINFOLIBDEFAULT — 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 — 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 — 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 — 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 these ToolTalk requests, and honestly? iconic behavior:

  • 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. That's it. Nothing here. Moving on bestie 💅

🦋 RETURN VALUE

A non-zero return value for dtinfo implies an error condition on start-up. So like, if it's not zero, something went wrong. 😭

🔥 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 /nix/store/6waxpwr8lzfzc9ka48gl7yh60rqvlkdb-cde-2.5.3/infolib/C/cde.dti
% dtaction DtShowInfoAtLoc /nix/store/6waxpwr8lzfzc9ka48gl7yh60rqvlkdb-cde-2.5.3/infolib/C/cde.dti GI.RGFBE.1698OL

If the infolib path environment variable is defined:

% dtaction DtShowInfoAtLoc cde INFOUG.GSTART.DIV.3

📁 FILES 💖

So, like, when you start this from the command line, it recognizes an infolib directory path — that's the <pink>DtMmdbInfoLibInfo(5)</pink> situation, go look it up if you're curious bestie. The way it vibe-checks whether a directory is actually a valid infolib? It looks at the name of the directory and the files chillin' inside it. That's the whole test. Name + contents, no cap. ✨

Your personal bookmark and annotation files? Those are managed internally (i.e. not your problem, the app handles it) and they live under the locale-specific directory here:

$HOME/.dt/dtinfo/%L/marks/

Your preferences — the ones you set through the Preferences dialog in a running instance of dtinfo — plus any user-defined search scopes you made, they all get saved into this generated file:

$HOME/.dt/dtinfo/%L/preferences

The application-specific resources are defined over here, in this app-defaults file:

/nix/store/6waxpwr8lzfzc9ka48gl7yh60rqvlkdb-cde-2.5.3/app-defaults/%L/Dtinfo

And all the utility files plus the supporting data that dtinfo needs to actually function? Those live in the system location:

/nix/store/6waxpwr8lzfzc9ka48gl7yh60rqvlkdb-cde-2.5.3/infolib

That's the whole file tour, bestie. Very demure, very organized. 🎀

👀 SEE ALSO 🌈

Go read these next, they're all icon behavior:

That's a wrap on the whole page, bestie!! 🫶 You just read the entire dtinfo manual — every flag, every file, every vibe. Go forth and browse your infolibs like the main character you are. 💅✨

Cute little sign-off from the page itself: this one's filed under dtinfo(user cmd) — the user-command section of the man pages, and it comes from the CDE (Common Desktop Environment) documentation, version 2.5.3. The build path in there (/nix/store/...-cde-2.5.3/...) is a big giveaway that it was packaged up in Nix, iykyk. 🦋 No exact date is printed on the page, so we're not inventing one — mysterious and iconic of it, honestly. 🧚💜

📦 where this page comes from