Man Linux: Main Page and Category List

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