dthelpprint(1)

dthelpprint - print utility for DtHelpDialog and DtHelpQuickDialog widgets

As shipped in IRIX 6.5.19. Added in IRIX 6.5.19.

NAME
dthelpprint - print utility for DtHelpDialog and
DtHelpQuickDialog widgets

SYNOPSIS
dthelpprint [options]

Options controlling what to print:
-helpType type type of Help data.
-helpType type type of Help data. type = 0
(help volume), 1 (string), 2
(man page), 3 (help file)
-helpVolume volume full path of Help volume file.
-locationId location name of Help topic in the
volume.
-allTopics print all topics, toc, & index.
-subTopics print topic locationId and all
subtopics.
-oneTopic print topic locationId.
-toc print Help volume table of
contents.
-index print Help volume index.
-frontMatter print Help volume front matter.
-manPage manpagename name of man page.
-stringData string Help text to print.
-helpFile filename file containing Help text.
-topicTitle title title string for Help text.

Options controlling how to print:

-printer printername printer to use.
copies number number of copies to print.
-outputFile filename write output to this file.
-paperSize size format content to this paper
size.
-paperSize size format content to this paper
size. size =
{help_papersize_letter|help_papersize_legal|
help_papersize_executive|help_papersize_a4|
help_papersize_b5}
-display displayname display from which to get
resources.
-name name program name used when getting
resources.
-class name class name used when getting
resources.
-xrm resourcestring additional resources.

DESCRIPTION
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.

OPTIONS
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.

RESOURCE OVERVIEW
The dthelpprint utiity 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
resources or the -class option. The application instance
name is the name used to run the program (usually
dthelpprint) unless specified otherwise with the
application.name or Application.Name 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.

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.

Basic Resource Set
Name Class Type Default
_________________________________________________________________
locationId LocationId string _HOMETOPIC
helpVolume HelpVolume string NULL
manPage ManPage
stringData StringData string NULL
helpFile HelpFile string NULL
topicTitle TopicTitle string NULL
helpType HelpType string NULL

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.

Additional Resource Set
Name Class Type Default
_________________________________________________________________
allTopics AllTopics string NULL
subTopics SubTopics string NULL
oneTopic OneTopic string NULL
toc Toc string NULL
index Index string NULL
frontMatter FrontMatter string NULL

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

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.

Basic Resource Set
Name Class Type Default
_________________________________________________________________
printer Printer string NULL
copies Copies string NULL
outputFile OutputFile string NULL
paperSize PaperSize string NULL
display Display string 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.

Additional Resource Set
Name Class Type Default
_________________________________________________________________

evenTocHeader EvenTocHeader string see below
oddTocHeader OddTocHeader string see below
evenTocFooter EvenTocFooter string see below
oddTocFooter OddTocFooter string see below
evenBodyHeader EvenBodyHeader string see below
oddBodyHeader OddBodyHeader string see below
evenBodyFooter EvenBodyFooter string see below
oddBodyFooter OddBodyFooter string see below
evenIndexHeader EvenIndexHeader string see below
oddIndexHeader OddIndexHeader string see below
evenIndexFooter EvenIndexFooter string see below
oddIndexFooter OddIndexFooter string see below
echoCommand EchoCommand string echo
echoArgs EchoArgs string "%s"
foldCommand FoldCommand string fold
foldArgs FoldArgs string -w %d %s
prCommand PrCommand string pr
prArgs PrArgs string see below
prOffsetArg PrOffsetArg string -o%d
manCommand ManCommand string man
manArgs ManArgs string %s
redirectCmdAndArgs RedirectCmdAndArgs string > %s
lpCommand LpCommand string lp
shCommand ShCommand string see below
iconvCmdAndArgs IconvCmdAndArgs string see below

evenTocHeader, oddTocHeader, evenTocFooter, oddTocFooter,
evenBodyHeader, oddBodyHeader, evenBodyFooter, oddBodyFooter,
evenIndexHeader, oddIndexHeader, evenIndexFooter, oddIndexFooter

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 Value
___________________________________________________________________
$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.
$PAGENUMFILLfiller for fixed sized 3 column page number.

$SECTNUM section number or name.
$SECTNUMFILLfiller 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\n\n

evenTocFooter and oddTocFooter:
\n$LMARGIN......................................................$SECTNUM

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

evenBodyFooter and oddBodyFooter:
\n$LMARGIN$TOPIC$TOPICFILL.....$SECTNUMFILLSection.$SECTNUM\n

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

evenIndexFooter and oddIndexFooter:
\n$LMARGIN..................................................................$SECTNUM\n

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 referece 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

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
actally 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

PRINTER CONFIGURATION RESOURCES
These resources specify printer configuration. This
includes a default configuration as well as printer-specific
configurations. The syntax for specifying the resources is

Dthelpprint*printer.resource:resource value

Dthelpprint*printer.printerName.resource:resource value

For example,

Dthelpprint*printer.paperSize: help_papersize_legal

help_papersize_executive
Dthelpprint*printer.laser-c4.paperSize:

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

Basic Resource Set
Name Class Type Default
_________________________________________________________________
paperSize PaperSize String help_papersize_letter
colsWidth ColsWidth Int 0
rowsHeight RowsHeight Int 0
colsLeftMargin ColsLeftMargin Int 10
colsRightMargin ColsRightMargin Int 10
rowsTopMargin RowsTopMargin Int 6
rowsBottomMargin RowsBottomMargin Int 6

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.

ENVIRONMENT VARIABLES
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.

INPUT FILES
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

OUTPUT FILES
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 Messages
used.
Warning: Illegal or missing paper size. help_papersize_letter
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.

help_papersize_letter used.
Warning: Missing paper size and height and/or width.
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 Messages
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.

locationId <loc>
Error: unable to get topic information:volume <vol>,
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.
The helpType resource or -helpType option
is 1 (string) but no stringData resource
or -stringData option was specified.

specified.
Error: helpType is dynamic string, but no stringData
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
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
Help4Help.asc
dthelpprint -helpVolume Help4Help -allTopics -outputFile
dthelpprint -helpVolume Help4Help -toc -index -printer hplj3

hplj3
dthelpprint -helpType 1 -stringData 'test string' -printer

dthelpprint -helpType 2 -manPage grep -outputFile grep.man

dthelpprint -helpType 3 -helpFile aFile -printer hplj3

SEE ALSO
DtHelpDialog(3), DtHelpQuickDialog(1), dthelpview(1),
man(1), CDE Help System Author's and Programmer's Guide.