 |
Index for
Section 1 |
|
 |
Alphabetical
listing for D |
|
 |
Bottom of
page |
|
dthelpprint(1)
CDE
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 Ttype of Help data. type = 0
(help volume), 1 (string),
2 (man page), 3 (help file)
volume full path of Help volume file.
-helpVolume
location name of Help topic in the
-locationId
volume.
-allTopics print all topics, TOC, and index.
-subTopics print topic locationId and all
subtopics.
-oneTopic print topic locationId.
-toc print Help volume table of
contents.
-index print Help volume index.
print Help volume front matter.
-frontMatter
-manPage manpagename name of reference page.
string Help text to print.
-stringData
-helpFile filename file containing Help text.
title title string for Help text.
-topicTitle
Options controlling how to print:
-printer printername printer to use.
copies number number of copies to print.
filename write output to this file.
-outputFile
-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 additional resources.
resourcestring
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 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 dthelpview1 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 reference 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 is not 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(1X).
-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.
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. 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 reference 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.
RESOURCE OVERVIEW
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 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 resources 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
Nam Class Type Default
locationId LocationId string _HOMETOPIC
helpVolume HelpVolume string NULL
manPage ManPage string NULL
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
string > %s
redirectCmdAndArgs
RedirectCmdAndArgs
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.
$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 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 theprCommand. 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 reference 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 lp1 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"
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
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.
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 volume
files within the desktop environment:
DTHELPSEARCHPATH
System search path environment variable for locating Help volumes on
local and remote NFS mounted systems.
DTHELPUSERSEARCHPATH
User search path environment variable for locating user specific Help
volumes on local and remote NFS mounted systems.
Refer to DtHelpDialog(3) or DtHelpQuickDialog(3) for information of setting
the DTHELP environment variables.
EXAMPLES
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
INPUT FILES
The following 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 by means of NFS.
$PWD/db.dthelpprint
This file is generated in the current directory when the debugHelpPrint
resource is defined. The file contains the complete set of resources
used by dthelpprint to configure its operation.
Warning Messages
Warning: Illegal or missing paper size.
help_papersize_letter used.
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 width.
help_papersize_letter used.
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 is not correctly specified by a full or relative path or does
not 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>
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.
Error: helpType is dynamic string,
but no stringData specified.
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 could not be
allocated.
Error: unable to open temporary file
The temporary file could not be opened for writing.
SEE ALSO
DtHelpDialog(3), DtHelpQuickDialog(3), dthelpview(1), man(1)
CDE Help
|
Index for
Section 1 |
|
|
Alphabetical
listing for D |
|
 |
Top of
page |
|