Ubuntu Manpage: update-yorickdoc - Build HTML documentation for Yorick

Provided by: yorick-doc_2.2.04+dfsg1-5ubuntu1_all

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.

AUTHORS