/usr/dt/share/man/cat1/dthelpprint.1

dthelpprint(1) USER COMMANDS dthelpprint(1)

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 con-
tents.
-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.
___________________________________________________________________________

Unix System LaboratoLast change: 1 August 1995 1

dthelpprint(1) USER COMMANDS dthelpprint(1)

DESCRIPTION
The dthelpprint utility is a private utility used by DtHelp-
Dialog(3) and DtHelpQuickDialog(3) for printing Help infor-
mation. It is not a public utility, and no effort to main-
tain 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 TED Help Sys-
tem. 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 TED Help volumes. TED 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
TED 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).

Unix System LaboratoLast change: 1 August 1995 2

dthelpprint(1) USER COMMANDS dthelpprint(1)

-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 TED 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 con-
junction with -helpVolume.

-toc Instructs dthelpprint to print the Table of Con-
tents 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 informa-
tion. 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

Unix System LaboratoLast change: 1 August 1995 3

dthelpprint(1) USER COMMANDS dthelpprint(1)

only in conjunction with a -helpType of 3.

Options controlling how to print:

-printer printername
Specifies which printer to use. If this isn't speci-
fied 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 generat-
ing 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 dthelp-
print. 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

Unix System LaboratoLast change: 1 August 1995 4

dthelpprint(1) USER COMMANDS dthelpprint(1)

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 other-
wise 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 dthelp-
print) 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 pre-
cedence 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
____________________________________________________________

Unix System LaboratoLast change: 1 August 1995 5

dthelpprint(1) USER COMMANDS dthelpprint(1)

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 speci-
fying 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

Unix System LaboratoLast change: 1 August 1995 6

dthelpprint(1) USER COMMANDS dthelpprint(1)

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

Unix System LaboratoLast change: 1 August 1995 7

dthelpprint(1) USER COMMANDS dthelpprint(1)

$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\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

Unix System LaboratoLast change: 1 August 1995 8

dthelpprint(1) USER COMMANDS dthelpprint(1)

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 for-
matting 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,

Unix System LaboratoLast change: 1 August 1995 9

dthelpprint(1) USER COMMANDS dthelpprint(1)

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 configura-
tion, specifically with respect to the paper used for print-
ing. Paper size can be specified either by using the paper-
Size 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 dimen-
sions are given in columns and rows of
text in the default printer font.

colsWidth Width of the paper in columns of charac-
ters 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

Unix System LaboratoLast change: 1 August 1995 10

dthelpprint(1) USER COMMANDS dthelpprint(1)

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 TED 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 infor-
mation 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,

Unix System LaboratoLast change: 1 August 1995 11

dthelpprint(1) USER COMMANDS dthelpprint(1)

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 com-
plete 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 con-
figure dthelpprint.

Error Messages
Error: helpType is topic, but no helpVolume specified.
Indicates that the helpType resource or
-helpType option was 0 (zero) or unspeci-
fied 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

Unix System LaboratoLast change: 1 August 1995 12

dthelpprint(1) USER COMMANDS dthelpprint(1)

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 neces-
sary memory.

tionId <loc>
Error: unable to get topic information:volume <vol>, loca-
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.

fied.
Error: helpType is dynamic string, but no stringData speci-
The helpType resource or -helpType option
is 1 (dynamic string) but no stringData
resource or -stringData option was speci-
fied.

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 speci-
fied.

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.

Unix System LaboratoLast change: 1 August 1995 13

dthelpprint(1) USER COMMANDS dthelpprint(1)

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), TED Help System Author's and Programmer's Guide.

Unix System LaboratoLast change: 1 August 1995 14