DTHELPPRINT(1)

📦
version 2.5.3 · 2 versions
, in nixos 26.05

👑 dthelpprint — the manual, but make it make sense

okay so real talk: the header of this page is dthelpprint(user cmd) — that's the title plus the manual section, and yes it's a user command, and yes we're gonna get into it.

🌸 NAME

dthelpprint — the print utility for DtHelpDialog and DtHelpQuickDialog widgets. that's the whole vibe. it prints help stuff. iconic behavior honestly.

✨ SYNOPSIS

dthelpprint [options]

🎀 Options

the "what am i even printing" squad:

  • -helpType type — the type of Help data. like, what flavor of help are we dealing with.
  • -helpType type — okay so the page lists this one twice (go off king 💅) but here's the actual tea: type is a number, and type = 0 (help volume), 1 (string), 2 (man page), 3 (help file).
  • -helpVolume volume — full path of the Help volume file.
  • -locationId location — name of the Help topic inside the volume.
  • -allTopics — print all topics, toc, & index.
  • -subTopics — print topic locationId and all its subtopics.
  • -oneTopic — print just the topic locationId.
  • -toc — print the Help volume table of contents.
  • -index — print the Help volume index.
  • -frontMatter — print the Help volume front matter.
  • -manPage manpagename — name of the man page.
  • -stringData string — the Help text you actually want printed.
  • -helpFile filename — file containing the Help text.
  • -topicTitle title — the title string for the Help text.
ngl there's a weird little tgroup dispwid="6.10in"Caret artifact sitting in the raw source right about here — that's table-formatting goo from the man page itself, not a flag you can pass. ignore her. she's just vibing. 🫶

the "ok but HOW do we print it" squad:

  • -printer printername — which printer to use.
  • -copies number — how many copies to print.
  • -outputFile filename — write the output to this file instead.
  • -paperSize size — format the content to this paper size.
  • -paperSize size — listed twice again (double trouble 😭) but the full 411: format content to this paper size, where size = {help_papersize_letter|help_papersize_legal|help_papersize_executive|help_papersize_a4|help_papersize_b5}.
  • -display displayname — display to grab resources from.
  • -name name — program name used when getting resources.
  • -class name — class name used when getting resources.
  • -xrm resourcestring — extra resources, sprinkle as needed.
and then, again, the source has a tgroup dispwid="6.14in" table artifact chilling at the bottom of the list. also not a flag. also ignore. 🧚

💖 DESCRIPTION

so the dthelpprint utility is a private utility used by DtHelpDialog(3) and DtHelpQuickDialog(3) to print Help information. bestie, read that again: private. it is not a public utility, and no effort to maintain backwards compatibility will be made across versions. like, zero effort. they said it themselves. 🫠 that said, it is sometimes useful to use dthelpprint directly and to configure how it operates, which is why we're all here.

the dthelpprint utility processes help topics and can send the output to a printer or to a specified output file. it's an integral part of the CDE Help System. access to dthelpprint is provided by the dthelpview(1) client's Print dialog, an application's Help window, or through a utility line shell. three doors, same room. ✨

the dthelpprint utility can print plain text strings, plain text files, Unix man pages, and CDE Help volumes. now the important part: CDE Help volumes are printed without any graphics, and there is no indication of missing graphics. so no "oops we lost the image" placeholder — it's just gone, silently. that's the whole rule. 🙈

the standard man(1) and dthelpview(1) search paths are used to find manual pages and CDE Help volumes; Help volumes and files may be specified with an absolute pathname. so yes, you can be absolute about it. main character energy. 💅

🌈 OPTIONS

the dthelpprint utility has two sets of utility line options. set one controls what should be printed. set two controls how it should be printed. all option names must be used exactly as given — no creative spelling, no vibes-based abbreviations. 🎀

an alternative to specifying options on the utility line is to specify them using resources in an app-defaults file. super useful for changing the default values from the ones given below. see the RESOURCE OVERVIEW heading in this manual page for more info. iykyk.

🔥 Options controlling what to print

  • -helpType type — the type of Help data to print. this is a numeric value, as follows: 0=help volume, 1=string, 2=man page, 3=help file. the default value is 0, a Help volume. so if you say nothing, you get a volume. periodt.
  • -helpVolume volume — the name of the volume holding the topics to be printed. if volume is unqualified, the standard dthelpview(1) search paths are used to locate the volume; these are also covered in the ENVIRONMENT VARIABLES heading in this manual page. the volume may also be specified relative to the current directory by beginning the volume name with ./ or ../. ⭐ this option is useful only in conjunction with a -helpType of 0 (zero).
  • -locationId location — the starting topic for processing topics of a Help volume. the location must be a text string used by the author to mark a location in the volume. the default value is _hometopic, which is the top topic of a CDE Help volume. 📍 this option is useful only in conjunction with -helpVolume.
  • -allTopics — instructs dthelpprint to print the entire help volume, including front matter, table of contents, all topics, and an index. the whole thing. the deluxe package. this option is useful only in conjunction with -helpVolume.
  • -subTopics — instructs dthelpprint to print the topic specified by -locationId and all the subtopics of that topic. it's giving family tree. 🌳 this option is useful only in conjunction with -helpVolume.
  • -oneTopic — instructs dthelpprint to print the topic specified by -locationId. just the one. no plus-ones. this option is useful only in conjunction with -helpVolume.
  • -toc — instructs dthelpprint to print the Table of Contents of the specified helpVolume. this option is useful only in conjunction with -helpVolume.
  • -index — instructs dthelpprint to print the Index of the specified helpVolume. this option is useful only in conjunction with -helpVolume.
  • -frontMatter — instructs dthelpprint to print the front matter of the specified helpVolume. front matter includes the volume title, abstract, and copyright information. 🎀 this option is useful only in conjunction with -helpVolume.
  • -stringData string — specifies a string to print. this option is useful only in conjunction with a -helpType of 1.
  • -manPage manpagename — specifies the name of the Unix man page to print. this option is useful only in conjunction with a -helpType of 2.
  • -helpFile filename — specifies a file to print. this option is useful only in conjunction with a -helpType of 3.

💜 Options controlling how to print

  • -printer printername — specifies which printer to use. if this isn't specified as a utility-line option or resource, the default value is taken from the environment variable LPDEST. 🖨️
  • -copies number — specifies how many copies to produce. the default value is 1. this option is only ignored when generating an output file.
  • -outputFile filename — specifies a file to hold the print-ready output. if this option is specified, no output is sent to the printer. like, at all. choose one. 🫶
  • -paperSize size — specifies a size of paper to which the output should be formatted. there are five valid values for size: help_papersize_letter, help_papersize_legal, help_papersize_executive, help_papersize_a4, help_papersize_b5. the default value is help_papersize_letter. the source lists this option twice, but there are only five sizes, so don't come for me. 💅
  • -display displayname — specifies the X display used to retrieve resource values. typical format for displayname is hostname:display_number.screen_number. if no screen number is specified, the first screen (0) is used. see also X(1). 🌈
  • -name name — specifies the application name under which resources are to be obtained. the default is dthelpprint. the resource application.name way also be used to specify the name. (yes, that's how it's written in the original — "way", not "may". i'm just the messenger 😭)
  • -class classname — specifies the application class name under which resources are to be obtained. the default is dthelpprint. the resource application.class may also be used to specify the class name.
  • -xrm resourcestring — specifies an addition to the resource database used by this invocation of the program. little extra sprinkle, just for this run. ✨

🦋 RESOURCE OVERVIEW

the dthelpprint utility uses resources in addition to utility-line options to configure its operation. and bestie, there are many more resources available for this purpose than utility-line options. like, a lot more. to set a resource on the utility line, use the -xrm option. 🎀

the application class is dthelpprint unless specified otherwise with the application.class or Application.Class resource or the -class option. the application instance name is the name used to run the program (usually dthelpprint) unless specified otherwise with the application.class or Application.Class resource or the -name option. in the following coverage of resource specifications, the application's class name and instance name can be used interchangably (that spelling is from the original, bestie, don't @ me); however, if the same resource is specified more than once, the instance-specific resource takes precedence over the class resource. and in addition, when a value can be specified using either a resource or a utility-line option, the utility-line option value takes precedence. 🏆 hierarchy is real.

the dthelpprint utility has three types of resources.

🌟 Help Content

these resoures (again — original spelling 😭) specify what to print. typically, these values are specified using utility-line options instead of resources. it's the "why would you" category. 🙈

🌟 Content Processing

these resources specify in more detail the configuration of how to print. these resources include some values that can be specified with utility-line options, but also many others. the overachiever of the three. 👑

🌟 Printer Configuration:

the dthelpprint utility allows printer-specific configurations to be specified. the configuration used is controlled by the value of the printer resource or -printer option. 🖨️✨

✨ ok that's chunk one — the resource lists themselves are coming up next, so stay tuned, don't touch that dial 💖

💖 HELP CONTENT RESOURCES 💖

These resources specify what to print. The syntax for specifying the resources is:

Dthelpprint* resource:resource value

For example, Dthelpprint*helpVolume: aVolume.sdl is used to specify the name of the Help volume. Slay, syntax handled.

🌸 Basic Resource Set 🌸

Here's the whole crew, with class/type/default exactly as listed:

  • locationId — Class: LocationId; Type: string; Default: _HOMETOPIC
  • helpVolume — Class: HelpVolume; Type: string; Default: NULL
  • manPage — Class: ManPage; Type: string; Default: NULL
  • stringData — Class: StringData; Type: string; Default: NULL
  • helpFile — Class: HelpFile; Type: string; Default: NULL
  • topicTitle — Class: TopicTitle; Type: string; Default: NULL
  • helpType — Class: HelpType; Type: string; Default: NULL
Source-table wiring check: tgroup dispwid="5.39in" — preserved, bestie. Nothing vanishes on my watch.

These Help-content resources are defined in DtHelpDialog(3). The following content options are specific to dthelpprint. Setting the resource to any value makes it True. Any value. Not a vibe check, just facts.

🦋 Additional Resource Set 🦋

  • allTopics — Class: AllTopics; Type: string; Default: NULL
  • subTopics — Class: SubTopics; Type: string; Default: NULL
  • oneTopic — Class: OneTopic; Type: string; Default: NULL
  • toc — Class: Toc; Type: string; Default: NULL
  • index — Class: Index; Type: string; Default: NULL
  • frontMatter — Class: FrontMatter; Type: string; Default: NULL

These Help-content resources have the same meaning as the dthelpprint utility-line options of the same name. Same name, same energy.

✨ HELP PROCESSING RESOURCES ✨

These resources specify how to print. The syntax for specifying the resources is:

Dthelpprint* resource:resource value

For example, Dthelpprint*printer: aPrinter is used to specify the name of the printer. Printer name goes brrr.

🎀 Basic Resource Set 🎀

  • printer — Class: Printer; Type: string; Default: NULL
  • copies — Class: Copies; Type: string; Default: NULL
  • outputFile — Class: OutputFile; Type: string; Default: NULL
  • paperSize — Class: PaperSize; Type: string; Default: NULL
  • display — Class: Display; Type: string; Default: NULL

These Help-processing resources have the same meaning as the dthelpprint utility-line options of the same name. It is used to specify the name of the printer. Yes, that's the sentence. I'm keeping it.

🌈 Additional Resource Set 🌈

  • evenTocHeader — Class: EvenTocHeader; Type: string; Default: see below
  • oddTocHeader — Class: OddTocHeader; Type: string; Default: see below
  • evenTocFooter — Class: EvenTocFooter; Type: string; Default: see below
  • oddTocFooter — Class: OddTocFooter; Type: string; Default: see below
  • evenBodyHeader — Class: EvenBodyHeader; Type: string; Default: see below
  • oddBodyHeader — Class: OddBodyHeader; Type: string; Default: see below
  • evenBodyFooter — Class: EvenBodyFooter; Type: string; Default: see below
  • oddBodyFooter — Class: OddBodyFooter; Type: string; Default: see below
  • evenIndexHeader — Class: EvenIndexHeader; Type: string; Default: see below
  • oddIndexHeader — Class: OddIndexHeader; Type: string; Default: see below
  • evenIndexFooter — Class: EvenIndexFooter; Type: string; Default: see below
  • oddIndexFooter — Class: OddIndexFooter; Type: string; Default: see below
  • echoCommand — Class: EchoCommand; Type: string; Default: echo
  • echoArgs — Class: EchoArgs; Type: string; Default: "%s"
  • foldCommand — Class: FoldCommand; Type: string; Default: fold
  • foldArgs — Class: FoldArgs; Type: string; Default: -w %d %s
  • prCommand — Class: PrCommand; Type: string; Default: pr
  • prArgs — Class: PrArgs; Type: string; Default: see below
  • prOffsetArg — Class: PrOffsetArg; Type: string; Default: -o%d
  • manCommand — Class: ManCommand; Type: string; Default: man
  • manArgs — Class: ManArgs; Type: string; Default: %s
  • redirectCmdAndArgs — Class: RedirectCmdAndArgs; Type: string; Default: > %s
  • lpCommand — Class: LpCommand; Type: string; Default: lp
  • shCommand — Class: ShCommand; Type: string; Default: see below
  • iconvCmdAndArgs — Class: IconvCmdAndArgs; Type: string; Default: see below
Source-table wiring check: the raw page also carries tgroup dispwid="6.46in" and tgroup dispwid="6.85in", and it repeats those header/footer names in four columns: evenTocHeader, oddTocHeader, evenTocFooter, oddTocFooter; evenBodyHeader, oddBodyHeader, evenBodyFooter, oddBodyFooter; evenIndexHeader, oddIndexHeader, evenIndexFooter, oddIndexFooter. Same twelve icons, different table crumbs. Preserved.

The values of these resources are used as the header and footer strings only when printing Help volumes. Header and footer strings are specified separately for odd and even pages to support double sided printing. The strings may contain symbolic names for dynamic values.

Dynamic values are updated each time the string is to be used. Valid dynamic values are as follows:

  • $LMARGIN — left margin blanks.
  • $TODAY — today's date.
  • $VOLDATE — date on the help volume file.
  • $VOLUME — volume name.
  • $VOLUMEFILL — filler for fixed sized 50 column volume name.
  • $TOPIC — section topic title.
  • $TOPICFILL — filler for fixed sized 50 column section topic title.
  • $PAGENUM — page number.
  • $PAGENUMFILL — filler for fixed sized 3 column page number.
  • $SECTNUM — section number or name.
  • $SECTNUMFILL — filler for fixed sized 8 column section number or name.

The default values for the resources are as follows. To improve understanding, the blank spaces have been replaced with .:

evenTocHeader and oddTocHeader:
          $LMARGIN....$VOLUME

evenTocFooter and oddTocFooter:
          0LMARGIN...$SECTNUM

evenBodyHeader and oddBodyHeader:
          $LMARGIN$VOLUME$VOLUMEFILL....$PAGENUMFILLPage.$PAGENUMn

evenBodyFooter and oddBodyFooter:
          0LMARGIN$TOPIC$TOPICFILL.....$SECTNUMFILLSection.$SECTNUM

evenIndexHeader and oddIndexHeader:
          $LMARGIN$VOLUME$VOLUMEFILL.....$PAGENUMFILLPage.$PAGENUM

evenIndexFooter and oddIndexFooter:
          0LMARGIN.......$SECTNUM

And yes, that is 0LMARGIN with a zero in the footer defaults — I am not "fixing" it, bestie. Character-for-character.

  • echoCommand — The utility used to echo the stringData from stdin to stdout.
  • echoArgs — The argument string to the echoCommand. The string must use printf formatting and may reference this argument: STRING string.
  • foldCommand — The utility used to fold a long string into a formatted string with a maximum column width.
  • foldArgs — The argument string to the foldCommand. The string must use printf formatting and may reference these arguments: INT column width, STRING filename.
  • prCommand — The utility used to format a file in preparation for printing.
  • prArgs — The argument string to the prCommand. The string must use printf formatting and may reference these arguments: STRING job title, INT page height, STRING filename. The default value is -h %s -f -l%d %s".
  • prOffsetArg — Sometimes the prArgs is augmented with the option to offset the contents by n columns. The value contains the offset argument. The string must use printf formatting and may reference this argument: INT column-offset.
  • manCommand — The utility used to recover a formatted Unix man page.
  • manArgs — The argument string to the manCommand. The string must use printf formatting and may reference these arguments: STRING man-page-name.
  • redirectCmdAndArgs — When stdout is to be redirected to a file, this utility and arguments are used. The string must use printf formatting and may reference these arguments: STRING filename.
  • lpCommand — The utility is used to print a file. The utility must accept the standard lp(1) utility-line arguments.
  • shCommand — The shell script used by dthelpprint to actually invoke the lpCommand on the target file. The default value is /nix/store/6waxpwr8lzfzc9ka48gl7yh60rqvlkdb-cde-2.5.3/bin/dthelpprint.sh.
  • iconvCmdAndArgs — The utility is used to translate a file from one character set to another. The argument string must use printf formatting and may reference these arguments: STRING from-charset, STRING to-charset, STRING source-file, STRING dest-file. The default value is iconv -f %s -t %s %s > %s.

💖 PRINTER CONFIGURATION RESOURCES 💖

These resources are literally all about printer configuration, bestie — both the default setup and the per-printer setups. The syntax for specifying them is:

Dthelpprint*printer. resource:resource value
Dthelpprint*printer.printerName.resource :resource value

For example, these two:

Dthelpprint*printer.paperSize: help_papersize_legal
Dthelpprint*printer.laser-c4.paperSize: help_papersize_executive

set the default paper size to legal and the paper size on the printer named "laser-c4" to executive. Slay 💅

🎀 Basic Resource Set 🎀

  • paperSize — class PaperSize, type String, default help_papersize_letter
  • colsWidth — class ColsWidth, type int, default 0
  • rowsHeight — class RowsHeight, type int, default 0
  • colsLeftMargin — class ColsLeftMargin, type int, default 10
  • colsRightMargin — class ColsRightMargin, type int, default 10
  • rowsTopMargin — class RowsTopMargin, type int, default 6
  • rowsBottomMargin — class RowsBottomMargin, type int, default 6

These resources configure the printer, especially the paper situation. You can set paper size with the paperSize resource, or go explicit with colsWidth and rowsHeight. The margin values are the amount of white space kept around the page. Very demure, very mindful 🎀

  • paperSize — sets the paper size to predefined dimensions. Valid values are:
    • help_papersize_letter — 8.5 x 11 in; 69 rows x 91 cols
    • help_papersize_legal — 8.5 x 14 in; 88 rows x 91 cols
    • help_papersize_executive — 7.25 x 10.5 in, 66 rows x 77 cols
    • help_papersize_a4 — 210 x 297 mm, 73 rows x 88 cols
    • help_papersize_b5 — 182 x 257 mm, 63 rows x 76 cols

If those dimensions aren't enough, use colsWidth and rowsHeight to provide explicit dimensions. All dimensions are in columns and rows of text in the default printer font. No cap ✨

  • colsWidth — width of the paper in columns of characters in the default printer font. The value may not be 0 (zero).
  • rowsHeight — height of the paper in rows of text in the default printer font. The value may not be 0 (zero).
  • colsLeftMargin — width of the left margin in columns of characters in the default printer font.
  • colsRightMargin — width of the right margin in columns of characters in the default printer font.
  • rowsTopMargin — height of the top margin in rows of text in the default printer font.
  • rowsBottomMargin — height of the bottom margin in rows of text in the default printer font.

🌸 ENVIRONMENT VARIABLES 🌸

The CDE Help system uses two environment variables for locating Help volume files within the desktop environment:

  • DTHELPSEARCHPATH — system search path environment variable for locating Help volumes on local and/or remote nfs mounted systems.
  • DTHELPUSERSEARCHPATH — user's search path environment variable for locating user-specific Help volumes on local and/or remote nfs mounted systems.

Refer to DtHelpDialog(3) or DtHelpQuickDialog(3) for info on setting the DTHELP environment variables. iykyk 🦋

🦋 INPUT FILES 🦋

These input files and resource databases are merged by dthelpprint to construct the complete resource database used by the program. Resource collisions are resolved by having the last value take precedence. Last one wins, periodt 💅

  • /nix/store/6waxpwr8lzfzc9ka48gl7yh60rqvlkdb-cde-2.5.3/app-defaults/C/Dthelpprint
  • /usr/lib/X11/app-defaults/Dthelpprint
  • $HOME/Dthelpprint
  • display resources or $HOME/.Xdefaults
  • screen resources
  • $XENVIRONMENT or $HOME/.Xdefaults-&<hostname>
  • utility-line resources

💜 OUTPUT FILES 💜

The dthelpprint utility always generates an output file — either for sending to the printer or for placing in a user-specified file. It's giving "there will be output, bestie" ✨

  • $HOME/.dt/tmp/phlp&<process id>_&<cnt>.txt — these are the temporary files generated by the dthelpprint utility. They're placed under the user's directory so remote systems can reach the file via NFS.
  • $PWD/db.dthelpprint — this file is generated in the current directory when the debugHelpPrint resource is defined. It contains the complete set of resources used by dthelpprint to configure its operation.

💀 Warning Messages 💀

Ngl, the source text drops a literal 10 after some quoted messages, so I'm leaving it in. No details lost, okay? 🫶

  • Warning: Illegal or missing paper size. help_papersize_letter used." 10 — indicates an invalid or missing value of the paperSize resource or -paperSize option. Specify the option on the utility line or set a default resource value.
  • Warning: Missing paper size and height and/or width. help_papersize_letter used." 10 — indicates that the printer.colsWidth or printer.rowsHeight resource was used to override the paperSize resource and at least one is set to 0 (zero) or has an invalid value.
  • Warning: Unable to open display &<display> — indicates that the display specified by the display resource or -display option could not be opened. This means the display's resources cannot be used to configure dthelpprint.

😭 Error Messages 😭

Same 10 situation in some of these too — kept it visible, bestie 💀

  • Error: helpType is topic, but no helpVolume specified. — indicates that the helpType resource or -helpType option was 0 (zero) or unspecified and defaulted to 0 (zero) and no helpVolume was specified.
  • Error: unable to locate help volume &<volume> — indicates that the Help volume could not be found. This occurs when the volume isn't correctly specified by a full or relative path, or doesn't exist in any directory listed by the DtHelp environment variables.
  • Error: problem processing help volume &<volume> — a problem occurred while processing some part of the Help volume.
  • Error: memory allocation failed — the program was unable to allocate necessary memory.
  • Error: unable to get topic information:volume &<vol>, locationId &<loc>" 10 — information about the specified location in the specified volume was unavailable or an error occurred while retrieving it from the volume.
  • Error: helpType is string, but no stringData specified." 10 — the helpType resource or -helpType option is 1 (string) but no stringData resource or -stringData option was specified.
  • Error: helpType is dynamic string, but no stringData specified." 10 — the helpType resource or -helpType option is 1 (dynamic string) but no stringData resource or -stringData option was specified.
  • Error: helpType is man page, but no manPage specified. — the helpType resource or -helpType option is 2 (manual page) but no manPage resource or -manPage option was specified.
  • Error: helpType is file, but no helpFile specified. — the helpType resource or -helpType option is 3 (plain text file) but no helpFile resource or -helpFile option was specified.
  • Error: Illegal helpType &<number>. — the helpType resource or -helpType option is not in the range 0 to 3.
  • Error: unable to allocate memory for temporary file" 10 — the memory needed to create the temporary file name couldn't be allocated.
  • Error: unable to open temporary file — the temporary file couldn't be opened for writing.

🔥 EXAMPLES 🔥

Run 'em exactly like this, bestie:

dthelpprint -helpVolume Help4Help -allTopics -outputFile Help4Help.asc
dthelpprint -helpVolume Help4Help -toc -index -printer hplj3
dthelpprint -helpType 1 -stringData 'test string' -printer hplj3
dthelpprint -helpType 2 -manPage grep -outputFile grep.man
dthelpprint -helpType 3 -helpFile aFile -printer hplj3

🌈 SEE ALSO 🌈

xoxo, the dthelpprint(user cmd) page 💅🫶 — official footer stamp included; the source/version + date live in that footer, and I'm not out here inventing extra ones, bestie ✨

📦 where this page comes from