/usr/man/cat.1/dthelpgen.1

dthelpgen(1)		 USER COMMANDS		     dthelpgen(1)

NAME
     dthelpgen - generates a top-level help browser volume

SYNOPSIS
     dthelpgen -dir directory [options]

DESCRIPTION
     The dthelpgen utility searches for	all TED	help family files
     installed and registered, and generates a help volume named
     browser, which contains hypertext links to	all help families
     and volumes found.	 By default, the scope of this search
     includes only the local system; however, it can be	extended
     to	remote systems using the environment variables described
     below.

     The dthelpgen utility only	updates	the browser help volume
     if	new family files or volumes are	detected within	the
     search path directories.  In the case where no new	family
     files are present,	dthelpgen exits.  If new files are
     present, dthelpgen	posts an information dialog telling the
     user that it's updating the browser volume.

     By	viewing	the browser help volume	and traversing its hyper-
     text links, the user can navigate through all of the
     registered	online help information.

     To	view the browser volume, select	the Help Viewer	control
     from the desktop's	Front Panel.  The top level of the
     browser volume lists product families.  The second	level,
     under each	family,	lists the volumes that are members of the
     product family.

     TED users or system administrators	typically do not need to
     interact directly with the	dthelpgen utility.  A browser
     volume is generated (when one does	not already exist, or is
     out of date) when the user	selects	the Help Viewer	control
     from the TED front	panel.	A browser volume is also gen-
     erated when the user executes the ReloadApps Action, or runs
     dthelpgen directly	from a terminal	window.	 In the	first two
     cases, the	resulting browser volume is placed in the user's
     $HOME/.dt/help/$DTUSERSESSION directory.  When running
     dthelpgen from a terminal window, the -dir	option must be
     used to specify the location to create the	resulting browser
     file.

OPTIONS
     The following options are available:

	-generate      Specifies that dthelpgen	unconditionally
		       regenerate the browser volume without
		       first checking if new families or help
		       volumes are present.

Unix System LaboratoLast change: 1 August 1995			1

dthelpgen(1)		 USER COMMANDS		     dthelpgen(1)

	-dir directory Specifies the directory to deposit the
		       generated files.	 The specification can
		       use substitution	values.	 The ENVIRONMENT
		       VARIABLES heading describes the substitu-
		       tion values allowed and their effect.  If
		       the environment variable	LANG is	not set
		       or is NULL, it is forced	to C.

	-file basename Specifies the base name for the files gen-
		       erated by dthelpgen.  The default name is
		       browser.	 Extensions are	appended to
		       basename	to create the file names for the
		       help volume.

	-lang language Specifies which language	directories to
		       search for help Family files and	help
		       volumes.	 If this option	is not set, the
		       default LANG value is used.  If the -lang
		       value is	set, it	takes precedence over the
		       current environment's LANG setting.

ENVIRONMENT VARIABLES
     The TED help system uses two environment variables	for
     locating help volumes and Family files within the desktop
     environment:

		       DTHELPSEARCHPATH
				      System search path environ-
				      ment variable for	locating
				      help volumes on local
				      and/or remote nfs	mounted
				      systems.

		       DTHELPUSERSEARCHPATH
				      Users search path	environ-
				      ment variable for	locating
				      user specific help volumes
				      on local and/or remote nfs
				      mounted systems.

		    The	environment variables contain colon-
		    separated lists of directory paths.	 Each
		    directory path can contain both environment
		    variable names as well as special field
		    descriptors	that are expanded at runtime.

		    Field descriptors consist of a percentage (%)
		    symbol followed by a single	character.  Field
		    descriptors	and their substitution values
		    are:

Unix System LaboratoLast change: 1 August 1995			2

dthelpgen(1)		 USER COMMANDS		     dthelpgen(1)

		       %H	      This value is replaced with
				      the current volume or fam-
				      ily name being searched
				      for.

		       %L	      Replaced with the	current
				      value of the LANG	environ-
				      ment variable.

		       %%	      Replaced with a single %.

		    For	example, given:
		    ""
		    DTHELPSEARCHPATH="/etc/dt/appconfig/help/%L/%H.sdl"

		    The	dthelpgen utility looks	for files ending
		    with .hf in	the directory
		    /etc/dt/appconfig/$LANG.  To find the volumes
		    listed in each .hf file, dthelpgen looks in
		    /etc/dt/help/appconfig/$LANG/%H.sdl	with %H
		    replaced with the name of the volume listed
		    in the Family file.

		    The	dthelpgen utility uses both DTHELPUSER-
		    SEARCHPATH and DTHELPSEARCHPATH.  The default
		    value for DTHELPUSERSEARCHPATH is:

		    $HOME/.dt/help/$DTUSERSESSION/%H:
		    $HOME/.dt/help/$DTUSERSESSION/%H.sdl:
		    $HOME/.dt/help/$DTUSERSESSION/%H.hv:
		    $HOME/.dt/help/%H:
		    $HOME/.dt/help/%H.sdl:
		    $HOME/.dt/help/%H.hv

		    The	DTHELPUSERSEARCH is first searched for
		    the	requested volume.  If the volume is not
		    found, the DTHELPSEARCHPATH	value is
		    searched.

		    The	default	value for DTHELPSEARCHPATH path
		    is:

		    /etc/dt/appconfig/help/%L/%H:
		    /etc/dt/appconfig/help/%L/%H.sdl:
		    /etc/dt/appconfig/help/%L/%H.hv:
		    /etc/dt/appconfig/help/C/%H:
		    /etc/dt/appconfig/help/C/%H.sdl:
		    /etc/dt/appconfig/help/C/%H.hv:
		    /usr/dt/appconfig/help/%L/%H:
		    /usr/dt/appconfig/help/%L/%H.sdl:
		    /usr/dt/appconfig/help/%L/%H.hv:

Unix System LaboratoLast change: 1 August 1995			3

dthelpgen(1)		 USER COMMANDS		     dthelpgen(1)

		    /usr/dt/appconfig/help/C/%H:
		    /usr/dt/appconfig/help/C/%H.sdl:
		    /usr/dt/appconfig/help/C/%H.hv

INPUT FILES
     The following are input files used	by dthelpgen.

		       <file>.hf      runtime Help Family file,
				      accessed directly	by
				      dthelpgen.

		       <file>.sdl     runtime Help volume
				      file(s), accessed
				      indirectly through explicit
				      references within	the Help
				      Family file.

OUTPUT FILES
     The following are descriptions of the output files	generated
     by	dthelpgen.

		       browser.hv     The master runtime browser
				      Help volume file generated
				      by dthelpgen.

		       browser00.ht & browser01.ht
				      Runtime browser Help topic
				      files generated by dthelp-
				      gen.

  Warning Messages
		       Zero Volume files found
				      Indicates	that none of the
				      volumes specified	in the
				      Family files are registered
				      in the system.

		       Zero Family files found
				      Indicates	that no	Family
				      files are	registered in the
				      system.

  Error	Messages
		       Element of path is not a	directory
				      Indicates	that some part of
				      the path is not a	direc-
				      tory.

		       Access denied for directory path.
				      Try running as super user?"

Unix System LaboratoLast change: 1 August 1995			4

dthelpgen(1)		 USER COMMANDS		     dthelpgen(1)

				      Indicates	that some part of
				      path does	not allow the
				      caller read, access or
				      write permission.

		       Element of path does not	exist
				      Indicates	that some element
				      of path does not exist or
				      is misspelled.

		       File system containing path is full
				      Indicates	that the disc
				      containing the path does
				      not contain any space or
				      inodes.

				    value
		       Unable to access	path -
				       error status number
				      Indicates	that there is an
				      access problem of	type
				      value occurred with path.

		       File system containing path is read only
				      Indicates	that the disc
				      containing the path is
				      mounted read-only.

		       Requires	root permission	to write to path
				      Indicates	that some part of
				      the path does not	allow the
				      user write permission.

		       Write to	volume invalid
				      Indicates	that volume does
				      not have the correct write
				      permissions for the caller.

		       Search Path empty
				      Indicates	that the environ-
				      ment variables.  DTHEL-
				      PUSERSEARCHPATH and/or
				      DTHELPSEARCHPATH were
				      declared but no paths were
				      specified	in the variables.

		       `title' resource	missing
				      Indicates	that the title
				      resource in a Family file
				      is missing.

		       `abstract' resource missing

Unix System LaboratoLast change: 1 August 1995			5

dthelpgen(1)		 USER COMMANDS		     dthelpgen(1)

				      Indicates	that the abstract
				      resource in a Family file
				      is missing.

		       `volumes' resource missing
				      Indicates	that the volumes
				      resource in a Family file
				      is missing.

		       `character' set resource	missing
				      Indicates	that the CharSet
				      resource in a Family file
				      is missing.

				    error status number	value
		       Unable to access	current	working	directory -
				      Indicates	that the -dir
				      option was specified with	a
				      relative path and	that
				      dthelpgen	is unable to get
				      the current working direc-
				      tory.

		       Unable to allocate memory
				      System resources are used
				      up, no available memory,
				      dthelpgen	aborts execution.

		       Destination directory missing
				      Missing directory	value for
				      -dir option.

		       Invalid system language specified
				      Non-supported value used
				      with the -lang option.

EXAMPLES
		       dthelpgen -dir $HOME/.dt/help
				      Creates, if required, a new
				      browser help volume in the
				      users home directory under
				      .dt/help/.

		       dthelpview -dir	$HOME/.dt/help -generate
				      Forces the creation of a
				      new browser help volume and
				      places it	in the users home
				      directory	under .dt/help/.

SEE ALSO
     dthelpview(1), dtsearchpath(1), dthffile(4), TED Help System
     Author's and Programmer's Guide.

Unix System LaboratoLast change: 1 August 1995			6

See also dthelpgen(1)