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>