Provided by: yorick-doc_2.2.01+dfsg-2_all bug

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>

                                            2008-05-18                        UPDATE-YORICKDOC(1)