NAME

dthelpprint − print utility for DtHelpDialog and DtHelpQuickDialog widgets

SYNOPSIS

dthelpprint [options]
Options controlling what to print:
   -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
       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

dthelpprint 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 command processes help topics and can send the output to a printer or to a specified output file.  dthelpprint is an integral part of the CDE Help System.  Access to dthelpprint is provided by the dthelpview client’s Print dialog, an application’s help window, or through a command line shell. 

dthelpprint 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 Man pages and CDE Help volumes; help volumes and files may be specified with an absolute pathname. 

OPTIONS

dthelpprint has two sets of command 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 command 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” below 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 discussed below in the “ENVIRONMENT VARIABLES” section.  The volume may also be specified relative to the current directory by beginning the volume name with "./" or "../".  This option is only useful in conjunction with a −helpType of 0. 

−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 only useful 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 only useful in conjunction with −helpVolume. 

−subTopics
Instructs dthelpprint to print the topic specified by −locationId and all the subtopics of that topic.  This option is only useful in conjunction with −helpVolume. 

−oneTopic
Instructs dthelpprint to print the topic specified by -locationId.  This option is only useful in conjunction with −helpVolume. 

−toc Instructs dthelpprint to print the Table of Contents of the specified helpVolume.  This option is only useful in conjunction with −helpVolume. 

−index
Instructs dthelpprint to print the Index of the specified helpVolume.  This option is only useful 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 only useful in conjunction with −helpVolume. 

−stringData string
Specifies a string to print. This option is only useful in conjunction with a −helpType of 1. 

−manPage manpagename
Specifies the name of the Unix man page to print. This option is only useful in conjunction with a −helpType of 2. 

−helpFile filename
Specifies a file to print. This option is only useful 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 command-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 way 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

dthelpprint uses resources in addition to command-line options to configure its operation.  There are many more resources available for this purpose than command-line options.  To set a resource on the command 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 resources or the -name option.  In the following discussion 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 will take precedence over the class resource.  In addition, when a value can be specified using either a resource or command-line option, the command-line option value takes precedence. 

dthelpprint has three types of resources. 

Help Content
These resoures specify what to print.  Typically, these values are specified using command-line options instead of resources.

Content Processing
These resources specify in more detail the configuration of how to print.  They include some values that can be specified with command-line options, but also many others.

Printer Configuration:
dthelpprint 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	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 command-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 command-line options of the same name.  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
$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......................................................$SECTNUM0

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

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 command 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 fold command is 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 command 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 command 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 out is to be redirected to a file, this command and arguments is used.  The string must use printf()() formatting and may reference these arguments:  STRING filename

lpCommand
The command is used to print a file.  The command must accept the standard lp(1) command-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 command 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:

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

rowsHeight
Height of the paper in rows of text in the default printer font. The value may not be 0.

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>

command−line resources

 

OUTPUT FILES

dthelpprint 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 program.  Note that 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

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 command line or set a default resource value. 

Warning: Missing paper size and height and/or width.  help_papersize_letter used.
Indicates that the printer.colsWidth or printer.rowsHeight resources were used to override the paperSize resource and at least one is set to 0 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 or unspecified and defaulted to 0 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>
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 (man 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

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

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

  —  08 August 1994