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>