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.