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 packages).
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
documentation 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