UPDATE-YORICKDOC(1)						      Yorick						       UPDATE-YORICKDOC(1)

NAME

       update-yorickdoc - Build HTML documentation for Yorick

SYNOPSIS

       update-yorickdoc  [--conf=file]	[--auto]  [--auto-now]	[--from=directory]  [--to=directory]  [--xref-dir=directory] [--src-dir=directory]
       [--template=file]

DESCRIPTION

       update-yorickdoc is a wrapper around htmldoc.i, a Yorick script that extracts DOCUMENT comments from Yorick source  files  and  turns  them
       into  a	set  of  HTML files. update-yorickdoc merges files from a "source directory" (default: /usr/share/yorick-doc, command-line option:
       --src-dir), deletes the target directory (default: /usr/share/doc/yorick-doc/html_xref), and, if Yorick is installed, calls "yorick  -batch
       htmldoc.i"  to  compile	HTML documentation for all currently installed functions (either from the main Yorick package or from add-on pack-
       ages).

       update-yorickdoc is meant to be called automatically whenever a Yorick package is installed or removed. It is possible to prevent automatic
       updates by setting "ENABLE_AUTO" to 0 in /etc/yorick-doc. It is also possible to use update-yorickdoc manually to create documentation from
       custom directories (e.g. a user's own ~/Yorick/ directory) or to a custom place, for instance.

       update-yorickdoc has a set of default parameters to function with. These parameters are overwritten in chronological order by  the  content
       /etc/yorick-doc, $HOME/.yorick-doc, and the command line.

       A  few  files  are  required  for  this script to function. Default files are provided in the default source directory, and add-on packages
       should provide additional information in the same place. See FILES below as well as /usr/share/doc/yorick-dev/yorick-policy.gz.

OPTIONS

       --auto | -a
	   This flag is being deprecated by the advent of triggers in dpkg. On systems where dpkg supports  triggers,  -a  turns  update-yorickdoc
	   into a no-op. On older systems, it behaves like -A below.

       --auto-now | -A
	   This  flag  is  meant  to be used only in the postinst script of the yorick-doc package, which is turn is supposed to be triggered each
	   time a yorick add-on package is installed, upgraded, or removed. It is possible to turn update-yorickdoc into a no-op when this flag is
	   set by setting ENABLE_AUTO to 0 in /etc/yorick-doc.

       --conf=file
	   Read  configuration	from  this  file.  This  file is parsed as the option is found on the command line, overwriting the options coming
	   before.

       --from=directory1:directory2...
	   Colon-separated list of directories to scan for Yorick files. Default: /usr/share/yorick/i:/usr/share/yorick/i0.

       --purge | -p
	   Only delete /usr/share/doc/yorick-doc/html_xref (or the directory set using	--to  and  --xref-dir,	or  the  equivalent  variables	in
	   /etc/yorick-doc), do not rebuild the documentation afterwards.

       --quiet | -q
	   Be quiet, only telling shortly what update-yorickdoc does. This is the built-in default but may have been overridden in a configuration
	   file.

       --src-dir=directory
	   Directory containing .packinfo, .keywords and .aliases files when building the documentation. Each of these three types of  files  will
	   be  concatenated in lexicographical order and fed to htmldoc.i using the --packinfo, --keywords, and --aliases options (see htmldoc.i).
	   Default: /usr/share/yorick-doc.

       --template=file
	   Template file for htmldoc.i. The correct format is detailed htmldoc.i. Default: /usr/share/yorick-doc/template.html.

       --to=directory
	   Top-level directory of the Yorick HTML hierarchy to update. This is	one  level  above  the	directory  that  will  be  deleted  and/or
	   (re)built. Defaults to /usr/share/doc/yorick-doc.

       --verbose | -v
	   Be  verbose,  outputting lots of debugging information. The built-in default is to be quiet, just telling shortly what update-yorickdoc
	   does.

       --xref-dir=word
	   The sub-directory of the "TO" directory in which to compile the documentation. Certain hyperlinks in the documentation  will  use  this
	   value. This should not be set to a directory whose content you value, since this directory will be first erased. Default: html_xref.

FILES

       /etc/yorick-doc
	   System-wide configuration for update-yorickdoc. This is the right place to set ENABLE_AUTO=0 in case you don't want Yorick's documenta-
	   tion each time a package of the Yorick suite is installed, upgraded, or removed. Another interesting option is FROM, in which  you  can
	   add for instance /usr/local/yorick/i if you maintain a secondary Yorick tree at your site. See the file itself for more details.

       $HOME/.yorick-doc
	   User-level equivalent to the above. It is ignored for the root user.

       /usr/share/yorick-doc/*.packinfo
	   Source for the package index in the documentation.

       /usr/share/yorick-doc/*.keywords
	   Lists of keywords for the index page of the documentation.

       /usr/share/yorick-doc/*.aliases
	   See htmldoc.i.

       /usr/share/yorick-doc/template.html
	   Template file for htmldoc.i.

       /usr/share/yorick/i/htmldoc.i
	   the Yorick script which does most of the actual work.

SEE ALSO

       /usr/share/yorick/i/htmldoc.i, /usr/share/doc/yorick-dev/yorick-policy.gz, dh_installyorick(1)

AUTHORS

       Thibaut Paumard <paumard@users.sourceforge.net>

								    2008-05-18						       UPDATE-YORICKDOC(1)