update-yorickdoc - Build HTML documentation for Yorick
update-yorickdoc [--conf=file] [--auto]
[--auto-now] [--from=directory] [--to=directory]
[--xref-dir=directory] [--src-dir=directory]
[--template=file]
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.
- --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.
- /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.
Thibaut Paumard <paumard@users.sourceforge.net>