Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
dtinfo(user cmd)					      dtinfo(user cmd)

NAME
       dtinfo -- browse	on-line	information

SYNOPSIS
       dtinfo [-help]  [-l infolib]  [-sect section
	[  {-section  |	,section }  ...] ]  [-secondary]  [-verbose]  [-print]
       [-hierarchy]  [-printer x_print_server]	[-copies number]   [-paperSize
       size]  [-s]

DESCRIPTION
       The dtinfo command starts the desktop on-line information browser, also
       known as	the CDE	Information Manager.  On-line information is typically
       packaged	into an	information library (infolib), which is	a hierarchy of
       bookcases containing SGML books (see the	 dtinfogen(1)  command).   The
       browser	offers	an ability to view, search, and	print on-line informa-
       tion with a high	degree of control. Bookmarks and  annotations  may  be
       attached	at desired points for later recall.

   Generalized Locator Format
       The  generalized	locator	format is used as an identifier	for target in-
       formation. The following	format shows the  fully	 specified  case,  al-
       though it is usually not	required to uniquely identify sections:

       mmdb:INFOLIB=ilib_path&BOOKCASE=bc_name&LOCATOR=locator

       where  ilib_path	 is the	infolib's path on disk;	bc_name	is the name of
       the bookcase (an	MMDB); and locator is the MMDB locator value.  The lo-
       cator  itself must be a unique reference	across document	collections by
       the time	an infolib's build process is complete.

       If just INFOLIB is present, the collection corresponding	to the infolib
       is  returned.  To display at the	beginning of a known bookcase, use the
       form:

       mmdb:INFOLIB=ilib_path&BOOKCASE=bc_name

       Note, however, that bookcase names are less protected from change  than
       locators, and should not	be relied upon for other than dynamically ver-
       ifiable bookcase	targets.

       If a locator is not expected to be  in  the  desktop  default  infolib,
       identify	 its  infolib by including the full file path name for the in-
       formation library (ilib_path). The most common  form  of	 reference  is
       then either:

       mmdb:INFOLIB=ilib_path&LOCATOR=locator

       or:

       mmdb:LOCATOR=locator

       If  INFOLIB  and	 BOOKCASE  are	omitted, a locator is looked up	in all
       loaded information libraries. If	no information libraries are currently
       loaded,	the locator is looked up in the	default	information library(s)
       specified by DTINFOLIBDEFAULT.  For the -sect  argument,	 the  value(s)
       "locator"  alone	 is sufficient to reach	the desired section, if	it oc-
       curs in the default infolib, or those indicated by -l arguments.

   Persistent User Settings
       A few characteristics are saved	across	browser	 sessions.  These  are
       bookmarks,  annotations,	 named search scopes, and certain user prefer-
       ences. All of these are saved on	a locale-specific basis. Query history
       and  browse  history  lists are provided, but are not persistent	across
       sessions.

OPTIONS
       The following options are available:

       -help	 Prints	a summary of the command's syntax.

       -l infolib
		 Specifies an absolute file path or the	filename of an	infor-
		 mation	 library.   If an infolib's filename is	specified, the
		 search	path specified by DTINFOLIBSEARCHPATH is used to  help
		 locate	 the  file.  If	 the -l	option is omitted, the browser
		 displays the default information library(s) specified by  DT-
		 INFOLIBDEFAULT.  This option can be specified more than once.

       -secondary
		 Starts	a secondary instance of	dtinfo.	Secondary instances do
		 not respond to	 Dtinfo_ShowInfoAtLoc  and  Dtinfo_LoadInfoLib
		 ToolTalk messages.

       -verbose	 Prints	 information  on  the terminal as the command runs, if
		 dtinfo	is started from	the command line.

       -sect section[{-section|,section}...]
		 Specifies the infolib section or sections to  either  display
		 or  print.  Sections  can be specified	in generalized locator
		 format.

		 To specify a range of sections, use the form:

		 -sect section-section

		 where the start and end sections are separated	by the	hyphen
		 character.

		 To specify a discontiguous list of sections, use the form:

		 -sect section,section

		 where	the  sections  in  the list are	separated by the comma
		 character.

		 If the	-print option is specified, the	sections are  printed.
		 Otherwise, dtinfo loads the specified infolib(s) and displays
		 all the sections in separate browser windows.

       -print	 Instructs dtinfo to print the locations  specified  with  the
		 -sect	option.	Printing of an entire infolib from the command
		 line is disallowed. If	a specified location is	not at the top
		 of a section, the section containing the location is printed.

   Print Control Options
       These options are valid only if the -print option is also specified.

       -hierarchy
		 Prints	 an  entire  specified	section	and all	of its subsec-
		 tions.	By default, only the specified section is printed.

       -printer	x_print_server
		 Specifies which X Print server	to use.	If this	is not	speci-
		 fied as a command-line	option or resource, the	value is taken
		 from the environment.

       -copies number
		 Specifies how many copies to print. The default value	is  1.
		 This option is	ignored	when generating	an output file.

       -paperSize size
		 Specifies  a size of paper to which the output	should be for-
		 matted. Valid sizes are iso-a4, iso-b4, na-letter, and	na-le-
		 gal.

       -outputFile filename
		 Specifies  a file to hold the print-ready output. If this op-
		 tion is specified, no output is sent to the printer. If  this
		 option	is specified, the -copies option is ignored.

       -s	 Specifies  silent  printing.  dtinfo does not write to	either
		 standard out or standard error, nor does it attempt  to  open
		 any windows.

PRINT FEATURES
       This section describes the features that	affect printing	with dtinfo.

   Page	Numbers
       Pages are numbered relative to the print	job. For example, if a section
       spans over four printed pages, the pages	are numbered 1-4. To get  page
       numbers	starting relative to the front of the book, it is necessary to
       print the entire	contents of the	book. When printing more than one book
       (a  bookcase, for example) the page numbering is	reset to page 1	at the
       start of	each book. A section is	determined to be a book	if it is a Ta-
       ble of Contents.

       When  specifying	 "what	to  print" all references are given in logical
       terms. You cannot specify a page	range since this number	 has  no  real
       meaning	until  the document is rendered	to a given page	size. "What to
       print" is specified as a	section	or list	of sections in generalized lo-
       cator format. It	is also	possible to specify a range of sections.

   Table of Contents
       The table of contents can be printed as part of a book or as a separate
       section.	When printed as	part of	a book,	it is always printed  last  to
       allow the page number references	to be calculated while the document is
       printing. When printed separately, the page numbers are not calculated.

   Image Scaling
       Dtinfo supports a number	of graphic file	formats: Tiff, XPM, XWD,  GIF,
       JPEG,  and  CGM.	Of all these formats, only CGM is a natural "scalable"
       format made of vectors and independent  coordinates,  much  like	 Post-
       Script.	All  the  other	graphic	formats	are specified in Dots Per Inch
       (DPI) and designed for a	given resolution. Since	most displays  have  a
       resolution of between 90/100 DPI	and printers commonly have resolutions
       of 300/600 DPI, printed documents can end up with graphics 3 or 6 times
       smaller than their screen counterparts, especially when the surrounding
       fonts are scaled	to match the screen size.

       To address this problem,	dtinfo automatically scales a graphic  accord-
       ing to the following formula:

       printed_image_size= image_size *	(resolution / 100 DPI)

       During  scaling	it is important	that the image not be scaled in	excess
       of the hard page	boundary. See "Hard Page Boundaries" for more detail.

   Hard	Page Boundaries
       On-line documentation is	often developed	with little or	no  considera-
       tion for	printability. As a result, on-line documents often have	graph-
       ics or tables that exceed the hard-page boundaries of the  printed  me-
       dia.  The  dtinfo command attempts to correct these problems during the
       layout-for-print	process	by a combination of page break insertions, ro-
       tation (landscape/portrait), and	scalable objects.

       Graphic	objects	 that are too wide for the page	are scaled down	to the
       page width.

       Graphic objects that are	too tall for the  remaining  page  height  are
       started	on the next page. If a graphic object is too tall for a	single
       page it is scaled down to the page height.

       Table objects that are too wide for the page are	started	 on  the  next
       page and	rotated	for landscape printing.	If a table is still too	large,
       it is scaled to the page	height.	Once the table has  been  printed,  an
       additional  page	 break	is performed and the remainder of the printing
       resumes in the default page orientation.	Space left in the current page
       layout is filled	by flow-up of subsequent text.

   Hard	Copy Page Style	Rendering
       dtinfo  hard  copy  page-style  rendering, with addition	of headers and
       footers,	page breaks, and numbering. For	these characteristics,	it  is
       necessary to use	print-specific style sheet features.

   Background Printing
       dtinfo  allows  simultaneous browsing and multiple print	requests to be
       active in parallel.

RESOURCES
   XRM Resources
       The XRM resources understood by dtinfo are as follows:

       BrowseGeometry
		 Specifies the default size of reading windows in pixel	dimen-
		 sions,	x by y.	The default is 500x630.

       BrowseLock
		 Specifies whether the current reading window is automatically
		 "pinned" when a new document display request is made (on)  or
		 not  (off).  If on, the new document appears in a new reading
		 window. System	resources utilized are often  much  higher  in
		 the on	mode. The default is off.

       DisplayFirstHit
		 Specifies whether the first document listed in	the search re-
		 sults list is displayed automatically (true) or not  (false).
		 The default is	false.

       FontScale Specifies  the	 relative  size	to use for text	in all reading
		 windows, compared to the publisher-specified font size, where
		 0  means "per style sheet". Possible values are -2, -1, 0, 1,
		 2, 3, 4, and 5. Invalid values	default	to 0. A	non-zero value
		 is  used  by  the  browser  to	associate incrementally	larger
		 sizes of the same font, when possible.	The default is 0.

       MapAutoUpdate
		 Specifies whether the graphical map (when visible)  is	 auto-
		 matically  updated  as	the user moves to new documents	(true)
		 or not	(false). The default is	true.

       MapGeometry
		 Specifies the default size of the  graphical  map  window  in
		 pixel dimensions, x by	y. The default is 520x350.

       MaxSearchHits
		 Specifies  the	 maximum  number of document titles to be dis-
		 played	in the Search Results List window in fulfillment of  a
		 query.	 The  entries  in  the search results list are ordered
		 roughly by importance to the query, so	a value	here  includes
		 the most relevant results. The	default	is 50.

       NodeHistSize
		 Specifies  the	 maximum number	of document visits to be main-
		 tained	in the browse history list. Duplicates	are  not  dis-
		 played	 in  the  list,	but re-visits change the list order by
		 moving	a previously viewed document to	the  top.  The	browse
		 history  is  not saved	across dtinfo sessions.	The default is
		 100.

       SearchHistorySize
		 Specifies the maximum number of previously performed  queries
		 to  be	 maintained  for  the  search  history list. Using the
		 search	history	list is	a quick	way to re-access  the  results
		 of  a prior query. The	search history is not saved across dt-
		 info sessions.	The default is 50.

   Display Color Resources
       The following resources set colors for various dtinfo display features:

       Dtinfo*display_area.background
		 Specifies the background color	for on-line document presenta-
		 tion.	The  user  is cautioned	to avoid choices of background
		 color which match the color used for either  hypertext	 links
		 or search hits. The keyboard traversal	highlight color	should
		 also be considered when setting this resource.	 There	is  no
		 default.

       Dtinfo*display_area.foreground
		 Specifies the foreground color	for on-line document presenta-
		 tion (used for	text not otherwise highlighted). The  user  is
		 cautioned  to	avoid  choices of foreground color which match
		 the color used	for either hypertext  links  or	 search	 hits.
		 There is no default.

       Dtinfo*doc_list.background
		 Specifies  the	 background  color  for	the infolib book list.
		 There is no default.

       Dtinfo*doc_list.foreground
		 Specifies the foreground color	for  the  infolib  book	 list.
		 There is no default.

       Dtinfo.results*list.background
		 Specifies  the	 background color for the search results list.
		 There is no default.

       Dtinfo.results*list.foreground
		 Specifies the foreground color	for the	search	results	 list.
		 There is no default.

   Print-Related Resources
       For  print-related  resources, see "Descendants"	and "Resources"	in Dt-
       PrintSetupBox(3).

STDIN
       Not used.

ENVIRONMENT VARIABLES
       The following environment variables affect the execution	of dtinfo:

       DTINFOLIBSEARCHPATH
		 Specifies the search path for locating	information  libraries
		 on local and remote mounted systems.

       DTINFOLIBDEFAULT
		 Specifies  the	 name of the default information library(s) to
		 load if the -l	or -sect option	is not specified. Multiple in-
		 formation  libraries  can  be	specified by a comma separated
		 list. By default, DTINFOLIBDEFAULT is initialized to the  CDE
		 infolib  cde.	Note that dtinfo will not start	if there is no
		 infolib specified explicitly or by default.  DTINFOLIBDEFAULT
		 requires the definition of an applicable DTINFOLIBSEARCHPATH.

       PDPRINTER,
		 LPDEST, PRINTER" 10 Specify the name of the printer to	use if
		 the -printer option, XPRINTER environment variable,  and  Xp-
		 Printer  resource  are	not specified. dtinfo checks PDPRINTER
		 first,	LPDEST next, and PRINTER last to obtain	a printer name
		 that  can  be	used to	generate an X Printer Specifier	to use
		 for the default X Printer shown  in  the  Printer  Name  text
		 field.	 The host:display portion of the specifier is obtained
		 by checking if	the X Server to	which the  client  application
		 is  connected	is an X	Print Server managing printer name. If
		 not,  the  list  of  X	 Print	Servers	  specified   in   the
		 XpServerList  resource	 is queried, until the first X Printer
		 with a	matching printer name is found.

       XPRINTER	 Specifies the default destination X Printer Specifier for the
		 DtPrintSetupBox.  If the specifier is just a printerName, the
		 host:display portion of the specifier is obtained by checking
		 if  the X Server to which the client application is connected
		 is an X Print Server  managing	 printerName.  Otherwise,  the
		 first server in the XpServerList resource or the XPSERVERLIST
		 environment variable that manages the printer will  be	 used.
		 If the	:display number	is omitted, :0 is assumed.

       DTPRINTSILENT
		 Specifies whether to display a	Print dialog box if the	-s op-
		 tion is not specified.	When the variable is set to True,  the
		 Print	dialog	is  not	displayed. If the variable is not set,
		 the dialog is displayed.

       XPDMDISPLAY
		 Specifies whether an alternate	X Print	Server will be used to
		 find  the  PDM_MANAGER	selection. If the variable is not set,
		 an alternate X	Print Server will not be used.

ACTIONS/MESSAGES
       dtinfo registers	with ToolTalk to handle	 the  following	 ToolTalk  re-
       quests:

       DtInfo_LoadInfoLib
		 Causes	 dtinfo	 to  load the specified	infolib	or the default
		 infolib, if none is specified.

       DtInfo_ShowInfoAtLoc
		 Causes	dtinfo to display a  particular	 section  of  data  or
		 topic.

       DtInfo_PrintInfoAtLoc
		 Routes	 print	requests back to the requesting	dtinfo process
		 after the end-user drags one or more sections from  the  book
		 list and drops	them on	the printer icon in the	front panel.

       Desktop actions invoking	the browser are:

       DtShowInfoAtLoc
		 Sends a DtInfo_ShowInfoAtLoc message.

       DtLoadInfoLib
		 Sends a DtInfo_LoadInfoLib message.

       DtPrintInfoAtLoc
		 Sends a DtInfo_PrintInfoAtLoc message.

       Use  of	any  default  desktop representations to start dtinfo from its
       icon or the icon	of an infolib causes dtinfo  to	 be  invoked  via  the
       desktop action mechanism.

STDOUT
       Not used.

STDERR
       Not used.

INPUT FILES
       For  input, dtinfo accepts the file path, relative or absolute, for one
       or more information libraries.

OUTPUT FILES
       For output, dtinfo produces a file to hold print-ready output,  if  the
       -outputFile and the -print options are specified.

EXTENDED DESCRIPTION
       None.

RETURN VALUE
       A non-zero return value for dtinfo implies an error condition on	start-
       up.

ERRORS/WARNINGS
   Warning Messages
       Warning:	Illegal	or missing paper size.
		 This warning indicates	an invalid value of the	paperSize  re-
		 source	 or -paperSize option. Correctly specify the option on
		 the utility line or set a default resource value.

       Warning:	Illegal	number of copies.
		 This warning is  displayed  when  both	 the  -outputFile  and
		 -copies  options  are	specified, and the number of copies is
		 greater than 1.

   Error Messages
       Error: Unable to	open x print server <x_print_server>
		 This error  indicates	that  the  display  specified  by  the
		 printer resource or -printer option could not be opened.

       Error: section not found.
		 This error indicates that the specified section locator could
		 not be	found.

       Error: invalid section specification <section>.
		 This error indicates that specified section locator  was  in-
		 correctly formatted.

       Error: printing of the entire infolib is	not supported.
		 Use  the  -sect  option  to identify the specific sections to
		 print.

       Error: unable to	allocate memory	for temporary file.
		 This error indicates that the memory  needed  to  create  the
		 temporary file	name could not be allocated.

       Error: unable to	open temporary file.
		 This  error  indicates	 that  the temporary file could	not be
		 opened	for writing.

EXAMPLES
       Start the browser and display the default information library:

       % dtinfo

       Start the browser with a	library	located	at /cdrom/encyclopedia.dti:

       % dtinfo	-l /cdrom/encyclopedia.dti

       Start the browser with a	library	from the search	path:

       % dtinfo	-l encyclopedia

       Start the browser with a	specific section to display:

       % dtinfo	-sect mmdb:INFOLIB=encyclopedia&LOCATOR=home_topic

       or:

       % dtinfo	-sect INFOUG.SEARCH.DIV.5,INFOUG.SEARCH.DIV.22

       An alternate form of the	previous command:

       % dtinfo	-l /cdrom/encyclopedia.dti -sect mmdb:LOCATOR=home_topic

       Print a specific	section	without	starting dtinfo:

       % dtinfo	-print -sect INFOUG.NAVIGATE.DIV.3

       Printing	of an entire infolib is	not supported from the command line:

       % dtinfo	-print -l /cdrom/encyclopedia.dti
       *** Error ***

       Examples	for the	use of dtinfo directly:

       % dtaction DtLoadInfoLib	/usr/local/dt/infolib/C/cde.dti

       % dtaction DtShowInfoAtLoc /usr/local/dt/infolib/C/cde.dti GI.RGFBE.1698OL

       If the infolib path environment variable	is defined:

       % dtaction DtShowInfoAtLoc cde INFOUG.GSTART.DIV.3

FILES
       Command line start-up recognizes	an infolib directory path (see	DtMmd-
       bInfoLibInfo(5)).  The name of the directory and	its contained files is
       used to ascertain whether it is a valid infolib.

       User-specific files for bookmarks and annotations are  internally  man-
       aged under the locale-specific directory	$HOME/.dt/dtinfo/%L/marks/.

       User  preferences, set via the Preferences dialog in an instance	of dt-
       info, and user-defined search scopes are	saved in  the  generated  file
       $HOME/.dt/dtinfo/%L/preferences.

       Application  specific  resources	 are  defined in /usr/local/dt/app-de-
       faults/%L/Dtinfo.

       Utility files and supporting data for dtinfo are	found  in  the	system
       location	/usr/local/dt/infolib.

SEE ALSO
       Generalized  Locator  Format(4),	 dtinfogen(1), DtPrintSetupBox(3), Dt-
       Info_LoadInfoLib(4), DtInfo_ShowInfoAtLoc(4), DtInfo_PrintInfoAtLoc(4),
       dtinfoaction(5),	DtMmdbInfoLibInfo(5)

							      dtinfo(user cmd)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | PRINT FEATURES | RESOURCES | STDIN | ENVIRONMENT VARIABLES | ACTIONS/MESSAGES | STDOUT | STDERR | INPUT FILES | OUTPUT FILES | EXTENDED DESCRIPTION | RETURN VALUE | ERRORS/WARNINGS | EXAMPLES | FILES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dtinfo&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help