unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



catman(8)							    catman(8)



NAME

  catman - Creates or rebuilds formatted reference pages and the whatis	data-
  base

SYNOPSIS

  /usr/sbin/catman [-M search_path] [-cnpvw] [section...]

OPTIONS

  -M search_path
      Creates formatted	versions of reference pages only in the	set of direc-
      tories specified by search_path.	The search_path	argument has the form
      of a colon-separated list	of directory names. The	default	search path
      (assuming	MANPATH	has not	been set) is the following:


	   /usr/share/man:/usr/dt/share/man:/usr/local/man

      The -M option, unlike the	MANPATH	setting, overrides the default place-
      ment of the whatis database (in /usr/share/man).	When the -M option is
      included in a command that builds	the whatis database, catman creates
      the database in the first	directory included in search_path.

      Refer to the man(1) reference page for more information on the MANPATH
      variable.	See DESCRIPTION	for a list of locale directives	that can be
      included in search_path.

  -c  Uses the gzip command to compress	preformatted output files. The -c
      option has no effect when	used with the -w option.

  -n  Prevents creation	of the whatis database.

  -p  Displays what would be done instead of doing it.

  -v  Displays the name	of each	reference page file as it is being processed.

  -w  Causes only the whatis database to be created.  No reformatting is
      done.

OPERANDS

  section...
      Specifies	one or more reference page sections whose corresponding
      directories are to be searched for files.	If you do not specify this
      parameter, the command searches for reference page source	files in all
      section directories encountered in its search path.

      The section operand affects creation of preformatted files, not the
      whatis database.	The catman command always searches all section direc-
      tories in	its search path	when creating the whatis database.


DESCRIPTION

  The catman command creates formatted versions	of the online reference	pages
  from the nroff source	files. The command also	creates	from the NAME entries
  in source files the whatis database that is used by the whatis and apropos
  commands.

  When catman is invoked, each reference page is examined and those whose
  preformatted versions	are missing or out of date are created by nroff	using
  the -man macro package.  See man(5).

  An argument not starting with	a - (single minus sign)	is assumed to be a
  list of the reference	sections to look in. If	you do not specify a list,
  catman formats all reference pages in	the search path.  In general, sec-
  tions	are referenced by a single digit in the	range 1	through	8.  But, you
  can use any section allowed by the man command.  The list of sections	is
  applied to all reference page	areas in the search path.

  If a .../man/cat? directory does not exist for a section, catman creates
  the directory.

  The command recognizes and appropriately processes either compressed or
  uncompressed source files.  By default, the command creates formatted	files
  in uncompressed form;	however, you can specify the -c	option to direct cat-
  man to compress its output files. When catman	processes an uncompressed
  source file, any corresponding pointers are generated	as symbolic links.
  When catman processes	a compressed source file, any corresponding pointers
  are generated	as hard	links. Refer to	man(1) for more	information, includ-
  ing restrictions, that apply to pointers and compressed files.

  A reference page source file can include a multicharacter 7-bit ASCII	sub-
  section suffix appended to its name, following the section character.	The
  subsection suffix, if	it exists, must	start with a letter.  The formatted
  reference page file also includes the	subsection suffix in its name.

  The catman command assumes that reference page source	files can contain
  unprocessed tables and equations.  Therefore,	it automatically processes
  source files through tbl and neqn before invoking nroff.  When catman
  processes a compressed file, the command automatically executes the gunzip
  -c command to	uncompress the file before piping output to the	other com-
  mands.

  Processing reference pages always invokes nroff with the -Tlp	option to
  format output	for the	term(4)	lp device. See RESTRICTIONS for	information
  appropriate for printers and some display devices.

  When you view	preformatted reference page files directly with	the more com-
  mand,	you should invoke more with the	-svf options. The vf options ensure
  that the pages display properly in cases where the nroff lp device driver
  generates special device control codes.

  The following	locale directives can be included in the pathnames in
  search_path:

  %L  The current locale name, for example, ja_JP.eucJP, that is defined for
      the LC_MESSAGES environment variable.

  %P  The same as %L except that any "@" modifier on the locale	name is
      removed.

  %l  The language element of the current locale name, for example, ja.

  %t  The territory element of the current locale name,	for example, JP.

  %c  The codeset element from the current locale name,	for example, eucJP.

  %%  A	single % (percent sign)	character.

      These directives allow catman to use the current locale setting to find
      translated source	files and create translated output files in an
      appropriate and predictable location.  Refer to the i18n_intro(5)
      reference	page for more information about	locales	and associated
      environment variables.

RESTRICTIONS

  The following	subsections discuss restrictions associated with both catman
  and its input	and output files.

  Reference Page Pointers


  Refer	to man(1) for introductory information on reference page pointers and
  general pointer restrictions.

  When processing reference page files,	the catman command changes its direc-
  tory to each reference page area in the search path.	Some reference pages
  assume this change of	directory.  Therefore, an attempt to format
  uncompressed reference pages can fail	if any .so directives specifying par-
  tial pathnames do not	start with man?/.

  Optional Section Directories


  The /usr/share/man/man? directories for sections C, L, F, n, l, p, o,	and 0
  are optional.	 Only your system administrator	can create them.  Once they
  are created, however,	catman will create the corresponding .../man/cat?
  directories whenever it receives a request to	format reference pages in one
  of those sections.

  The whatis Database


  The whatis (man -f) and apropos (man -k) commands fail unless	the whatis
  database exists in the /usr/share/man	directory or, if the command includes
  the -M option, in the	search path specified with that	option.

  The operating	system can optionally install a	/usr/share/man/whatis file
  that is useful during	system configuration tasks. However, you must
  recreate this	file manually if you install reference pages that are not
  included in subsets for the operating	system product;	otherwise, entries
  for the additional reference pages are not included in the whatis database.

  You create or	recreate the whatis file when you invoke catman	without
  specifying the -n option. You	can also specify the -w	option to create the
  whatis file without creating or updating preformatted	reference pages	in
  the cat? directories.

  An update installation procedure or a	setld command that processes refer-
  ence page subsets for	the operating system itself may	selectively remove or
  add specific whatis database entries to help keep the	database up to date.
  However, this	feature	is of limited use in making sure that the whatis
  database remains current with	respect	to the reference pages that are	actu-
  ally available on the	system.	 As already mentioned, selective update	is
  not supported	by most	of the optional	software products that can load
  reference pages to the system.  Furthermore, selective update	has database
  location dependencies. For selective update to work, the whatis entries for
  all operating	system product reference pages (including those	for CDE) must
  reside in /usr/share/man/whatis.  In other words, automatic and selective
  revision of the whatis database does not work	correctly if the whatis	data-
  base is rebuilt in a directory other than /usr/share/man or if the system
  administrator	creates	a CDE-specific whatis database in the
  /usr/dt/share/man directory.

  Therefore, do	not rely on automatic update of	the whatis database to ensure
  that its entries reflect the current set of reference	pages installed	on
  the system. It is strongly recommended that you always use the catman
  command to manually rebuild the database as the last task following a	com-
  pleted series	of software product installations.

  Default Formatting Is	Not Appropriate	for All	Devices


  The catman command formats reference pages for the nroff lp device. The lp
  device driver, as supplied by	the operating system, is set to	generate out-
  put for Compaq Computer Corporation video terminals, but not for all
  printers or third-party terminals. If	your system administrator changes the
  supplied setting for the lp device, all preformatted reference page files
  created by man or catman should be deleted and then reformatted for the new
  lp device.

  Preformatted reference pages may not be in a format suitable for printing
  on your hardcopy printers.  To format	a reference page for a specific
  printer, move	to the reference page area and issue a command such as the
  following:

       % cd /usr/share/man
       % gunzip	-c man1/ls.1.gz	|tbl |neqn |nroff -Tdevice -man	-h | lpr \
       -Pmyprinter

  Replace the device argument with /usr/share/lib/term/tabdevice, where	dev-
  ice is the name of a device listed in	term(4). The lpr device	setting,
  because it supports primitive	line printers, is least	likely to cause	prob-
  lems that are	related	to escape sequences that the device cannot handle.
  On the other hand, if	the reference page has tables and the device is	not
  capable of reverse line movements, column entries intended to	be in the
  same row may not align correctly.

  Preformatted reference pages also might not be in a format suitable for
  display on video terminals from other	vendors.  To format a reference	page
  for a	specific display device, move to the reference page directory and
  issue	a command such as the following:

       % cd /usr/share/man
       % gunzip	-c man1/ls.1 |tbl |neqn	|nroff -Tdevice	-man -h	| more -svf

  Replace the device argument with /usr/share/lib/term/tabdevice, where	dev-
  ice is the name of a device listed in	term(4).

EXIT STATUS

  0 (Zero)
      Success.

  >>0  An error occurred.

EXAMPLES

   1.  To create or update compressed preformatted files for reference pages
       and also	create or rebuild the whatis database, enter:
	    catman -c

   2.  To create uncompressed preformatted files only for sections 1, 2, and
       3, enter:
	    catman 123

       This command also creates or rebuilds the whatis	database. The new
       database	contains entries for reference pages in	all sections (not
       just 1, 2, and 3) that are found	in the search path.

   3.  To create or rebuild the	whatis database	without	creating or updating
       formatted files,	enter:
	    catman -w

   4.  To create compressed preformatted files for all reference pages in the
       search path but not rebuild the whatis database,	enter:
	    catman -c -n



FILES

  /usr/share/man
      Main reference page area

  /usr/share/man/man?
      Directories containing source files for most reference pages

  /usr/share/man/cat?/*
      Directories containing preformatted files	for most reference pages

  /usr/dt/share/man
      Reference	page area for the Common Desktop Environment (CDE)

  /usr/dt/share/man/man?
      Directories containing source files for CDE reference pages

  /usr/dt/share/man/cat?/*
      Directories containing preformatted files	for CDE	reference pages

  /usr/local/man
      Local (site-specific) reference page area

  /usr/local/man/man?
      Directories containing source files for local reference pages

  /usr/local/man/cat?/*
      Directories containing preformatted files	for local reference pages

  /usr/share/man/whatis
      The whatis database created or modified by catman	unless the -M option
      is specified

  /usr/lbin/mkwhatis
      Command script to	make the whatis	database

  /usr/lbin/getNAME
      Program used by the mkwhatis command to extract data from	reference
      pages

SEE ALSO

  Commands: man(1), neqn(1), nroff(1), tbl(1)

  Files: term(4), man(5), rsml(5)