.\" $Id: update-yorickdoc.1,v 1.5 2009/12/02 16:01:03 paumard Exp $ .\" .IX Title "UPDATE\-YORICKDOC 1" .TH UPDATE\-YORICKDOC 1 "2008\-05\-18" "" "Yorick" .SH "NAME" update\-yorickdoc \- Build HTML documentation for Yorick .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fBupdate\-yorickdoc\fR [\fB\-\-conf=\fRfile] [\fB\-\-auto\fR] [\fB\-\-auto\-now\fR] [\fB\-\-from=\fRdirectory] [\fB\-\-to=\fRdirectory] [\fB\-\-xref\-dir=\fRdirectory] [\fB\-\-src\-dir=\fRdirectory] [\fB\-\-template=\fRfile] .SH "DESCRIPTION" .IX Header "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). .PP 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. .PP 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. .PP 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 \fBFILES\fR below as well as /usr/share/doc/yorick-dev/yorick-policy.gz. .SH "OPTIONS" .IX Header "OPTIONS" .IP "\fB\-\-auto\fR | \fB\-a" 4 .IX Item "\-\-auto" 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. .IP "\fB\-\-auto\-now\fR | \fB\-A" 4 .IX Item "\-\-auto\-now" 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. .IP "\fB\-\-conf=\fRfile" 4 .IX Item "\-\-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. .IP "\fB\-\-from=\fRdirectory1:directory2..." 4 .IX Item "\-\-from=directory1:directory2..." Colon\-separated list of directories to scan for Yorick files. Default: /usr/share/yorick/i:/usr/share/yorick/i0. .IP "\fB\-\-purge\fR | \fB\-p" 4 .IX Item "\-\-purge" 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. .IP "\fB\-\-quiet\fR | \fB\-q" 4 .IX Item "\-\-quiet" Be quiet, only telling shortly what update\-yorickdoc does. This is the built-in default but may have been overridden in a configuration file. .IP "\fB\-\-src\-dir=\fRdirectory" 4 .IX Item "\-\-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. .IP "\fB\-\-template=\fRfile" 4 .IX Item "\-\-template=file" Template file for htmldoc.i. The correct format is detailed htmldoc.i. Default: /usr/share/yorick\-doc/template.html. .IP "\fB\-\-to=\fRdirectory" 4 .IX Item "\-\-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. .IP "\fB\-\-verbose\fR | \fB\-v" 4 .IX Item "\-\-verbose" Be verbose, outputting lots of debugging information. The built-in default is to be quiet, just telling shortly what update\-yorickdoc does. .IP "\fB\-\-xref\-dir=\fRword" 4 .IX Item "\-\-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. .SH "FILES" .IX Header "FILES" .IP "\fB/etc/yorick\-doc\fR" 4 .IX Item "/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. .IP "\fB$HOME/.yorick\-doc\fR" 4 .IX Item "$HOME/.yorick\-doc" User\-level equivalent to the above. It is ignored for the root user. .IP "\fB/usr/share/yorick\-doc/*.packinfo\fR" .IX Item "/usr/share/yorick\-doc/*.packinfo" Source for the package index in the documentation. .IP "\fB/usr/share/yorick\-doc/*.keywords\fR" .IX Item "/usr/share/yorick\-doc/*.keywords" Lists of keywords for the index page of the documentation. .IP "\fB/usr/share/yorick\-doc/*.aliases\fR" .IX Item "/usr/share/yorick\-doc/*.aliases" See htmldoc.i. .IP "\fB/usr/share/yorick\-doc/template.html\fR" .IX Item "/usr/share/yorick\-doc/template.html" Template file for htmldoc.i. .IP "\fB/usr/share/yorick/i/htmldoc.i\fR" .IX Item "/usr/share/yorick/i/htmldoc.i" the Yorick script which does most of the actual work. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fI/usr/share/yorick/i/htmldoc.i\fR, \&\fI/usr/share/doc/yorick-dev/yorick-policy.gz\fR, \&\fIdh_installyorick\fR\|(1) .SH "AUTHORS" .IX Header "AUTHORS" Thibaut Paumard