Table of Contents
dthelpprint -- print utility for DtHelpDialog and DtHelpQuickDialog
widgets
dthelpprint [options!]
Options controlling what
to print:
| -helpType |
| -helpType |
| type of Help data. type = 0 (help volume), |
| 1 (string),
2 (man page), 3 (help file) |
| T} |
| -helpVolume |
| -locationId |
| -allTopics |
| print all topics,
toc, & index. |
| T} |
| -subTopics |
| print topic locationId and all subtopics. |
| T} |
| -oneTopic |
| -toc |
| print
Help volume table of contents. |
| T} |
| -index |
| -frontMatter |
| -manPage |
| -stringData |
| -helpFile |
| -topicTitle |
Options
controlling how to print:
| -printer |
| copies |
| -outputFile |
| -paperSize |
| -paperSize |
| format
content to this paper size. size = |
| {help_papersize_letter|help_papersize_legal|
help_papersize_executive|help_papersize_a4| |
| help_papersize_b5} |
| T} |
| -display |
| display
from which to get resources. |
| T} |
| -name |
| program name used when getting resources. |
| T} |
| -class |
| class
name used when getting resources. |
| T} |
| -xrm |
The dthelpprint utility
is a private utility used by DtHelpDialog(3)
and DtHelpQuickDialog(3)
for
printing Help information. It is not a public utility, and no effort to
maintain backwards compatibility will be made across versions. That said,
it is sometimes useful to use dthelpprint directly and to configure its
operation.
The dthelpprint utility processes help topics and can send the
output to a printer or to a specified output file. The dthelpprint utility
is 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.
The dthelpprint utility can print plain
text strings, plain text files, Unix man pages, and CDE Help volumes. CDE
Help volumes are printed without any graphics, and there is no indication
of missing graphics. 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.
The dthelpprint utility
has two sets of utility line options. The first set controls what should
be printed. The second set controls how it should be printed. All option
names must be used exactly as given. An alternative to specifying options
on the utility line is to specify them using resources in an app-defaults
file. This is useful for changing the default values from those given below.
See the RESOURCE OVERVIEW heading in this manual page for more information.
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.
- -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. 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. This option is useful
only in conjunction with -helpVolume.
- -oneTopic
- Instructs dthelpprint to print
the topic specified by -locationId. 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.
- -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.
- -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.
- -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.
The dthelpprint utility
uses resources in addition to utility-line options to configure its operation.
There are many more resources available for this purpose than utility-line
options. 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; however, if the
same resource is specified more than once, the instance-specific resource
takes precedence over the class resource. In addition, when a value can
be specified using either a resource or utility-line option, the utility-line
option value takes precedence.
The dthelpprint utility has three types of
resources.
- Help Content
- These resoures specify what to print. Typically, these
values are specified using utility-line options instead of resources.
- 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.
- 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.
These resources specify what to print. The syntax
for specifying the resources is
CWDthelpprint* resource:resource value
For example, Dthelpprint*helpVolume: aVolume.sdl is used to specify the
name of the Help volume.
| Name |
| locationId |
| helpVolume |
| manPage |
| stringData |
| helpFile |
| topicTitle |
| helpType |
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.
| Name |
| allTopics |
| subTopics |
| oneTopic |
| toc |
| index |
| frontMatter |
These
Help-content resources have the same meaning as the dthelpprint utility-line
options of the same name.
These resources specify
how to print. The syntax for specifying the resources is:
CWDthelpprint* resource:resource value
For example, Dthelpprint*printer: aPrinter is used to specify the name
of the printer.
| Name |
| printer |
| copies |
| outputFile |
| paperSize |
| display |
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.
| Name |
| evenTocHeader |
| oddTocHeader |
| evenTocFooter |
| oddTocFooter |
| evenBodyHeader |
| oddBodyHeader |
| evenBodyFooter |
| oddBodyFooter |
| evenIndexHeader |
| oddIndexHeader |
| evenIndexFooter |
| oddIndexFooter |
| echoCommand |
| echoArgs |
| foldCommand |
| foldArgs |
| prCommand |
| prArgs |
| prOffsetArg |
| manCommand |
| manArgs |
| redirectCmdAndArgs |
| lpCommand |
| shCommand |
| iconvCmdAndArgs |
| evenTocHeader |
| evenBodyHeader |
| evenIndexHeader |
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:
| Symbol |
| $LMARGIN |
| $TODAY |
| $VOLDATE |
| $VOLUME |
| $VOLUMEFILL |
| filler
for fixed sized 50 column volume name. |
| T} |
| $TOPIC |
| $TOPICFILL |
| filler for fixed
sized 50 column section |
| topic title. |
| T} |
| $PAGENUM |
| $PAGENUMFILL |
| filler for fixed
sized 3 column page number. |
| T} |
| $SECTNUM |
| $SECTNUMFILL |
| filler for fixed sized
8 column section number |
| or name. |
| T} |
The default values for the resources are
as follows (To improve understanding, the blank spaces have been replaced
with ’.’.):
- evenTocHeader and oddTocHeader:
- $LMARGIN....$VOLUME0n
- evenTocFooter
and oddTocFooter:
- 0LMARGIN...$SECTNUM
- evenBodyHeader and oddBodyHeader:
- $LMARGIN$VOLUME$VOLUMEFILL....$PAGENUMFILLPage.$PAGENUMn
- evenBodyFooter and oddBodyFooter:
- 0LMARGIN$TOPIC$TOPICFILL.....$SECTNUMFILLSection.$SECTNUM0ing,
- evenIndexHeader and oddIndexHeader:
- $LMARGIN$VOLUME$VOLUMEFILL.....$PAGENUMFILLPage.$PAGENUM0n
- evenIndexFooter and oddIndexFooter:
- 0LMARGIN.......$SECTNUM010
- 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 maxiumum 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 /usr/dt/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
These resources specify printer configuration. This includes a
default configuration as well as printer-specific configurations. The syntax
for specifying the resources is
CWDthelpprint*printer. resource:resource value
Dthelpprint*printer.printerName.resource :resource value
For example,
CWDthelpprint*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.
| Name |
| paperSize |
| colsWidth |
| rowsHeight |
| colsLeftMargin |
| colsRightMargin |
| rowsTopMargin |
| rowsBottomMargin |
These
resources are used to specify the printer configuration, specifically with
respect to the paper used for printing. Paper size can be specified either
by using the paperSize resource or by setting an explicit size with the
colsWidth and rowsHeight resources. The margin values specify the amount
of white space retained around the page.
- paperSize
- This resource can be used
to set 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) and help_papersize_b5
(182 x 257 mm, 63 rows x 76 cols). If these dimensions are insufficient,
the colsWidth and rowsHeight resources can be used to provide explicit
dimensions. All dimensions are given in columns and rows of text in the
default printer font.
- 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.
The CDE Help system uses two environment variables for locating
Help volumes files within the desktop environment:
- DTHELPSEARCHPATH
- System
search path environment variable for locating Help volumes on local and/or
remote nfs mounted systems.
- DTHELPUSERSEARCHPATH
- Users 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
information of setting the DTHELP environment variables.
The
following are 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.
-
- /usr/dt/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
The dthelpprint utility always generates
an output file, either for sending to the printer or to place in a user-specified
file.
- $HOME/.dt/tmp/phlp<process id>_<cnt>.txt
- These are the temporary files generated
by the dthelpprint utility. These files are placed under the user’s directory
so that 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. The file constains the complete set of resources used by dthelpprint
to configure its operation.
- 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 that the display’s resources cannot be used to configure dthelpprint.
- 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.
CWdthelpprint -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
DtHelpDialog(3)
, DtHelpQuickDialog(3)
, dthelpview(1)
, man(1)
, CDE
Help System Author’s and Programmer’s Guide.
Table of Contents