TEXDOCTK(1)                 General Commands Manual                TEXDOCTK(1)



NAME
       texdoctk  - GUI for easier access of TeX package and program documenta-
       tions

SYNOPSIS
       texdoctk -[aq]

DESCRIPTION
       texdoctk is a GUI for easier access to a large part of the vast  amount
       of  package  and  program  documentations and tutorials for TeX and its
       different derivatives (mainly LaTeX). It is optimized and  included  in
       the teTeX and fpTeX distributions and also available with TeXLive.

       The documentation is grouped into 17 categories; the 18th button of the
       main panel is inactive by default and intended for use with local addi-
       tions (see section CONFIGURATION below).

       In  the settings window you see a checkbox in the html->ps and text->ps
       converter menus for switching on/off output redirect. This  is  due  to
       the fact that some converters do not write their output into a file but
       to stdout by default, so a redirect is needed, e.g.

       a2ps myfile.txt >myfile.ps

OPTIONS
       -v     verbose: enable some viewer messages which are otherwise sent to
              stderr,  as well as some warning popup windows. This can also be
              set in a configuration file.

       -a     autoview: autostart viewer if a listbox contains only  one  item
              (this  will  frequently happen in search results). This can also
              be set in a configuration file.

CONFIGURATION
       The configuration is controlled by  the  system  default  configuration
       file ($TEXMFMAIN)/texdoctk/texdocrc.defaults, most of whose entries can
       though be overridden by  the  users'  own  optional  ~/.texdocrc  files
       and/or command line options.

   The Settings menu and configuration files
       The Settings menu is used to change the user-definable settings of tex-
       doctk for the duration of the program call or as new defaults. The lat-
       ter case is the purpose of the Save button, which generates or rewrites
       the user's own ~/.texdocrc file. The system defaults cannot  be  edited
       with the Settings menu.

       Paths  The  TEXMF-type  paths  on the system are reported, and the user
              can specify the name of the subdirectory  of  $HOMETEXMF,  where
              the personal documentation is stored.

       General viewer behaviour

              Suppress  error  messages  toggle  verbose mode (see option -v);
              default is off.

              Autostart viewer for one-item listboxes if  a  listbox  contains
              only one item (see option -a)

              Use  text  viewer for unknown file format i.e. treat the file as
              plain text. texdoctk should recognize the usual file formats and
              also  relate  names like README to plain text, but some docs may
              have freely invented names. Default is on; if switched off, try-
              ing  to view such files will raise an error. The switch does not
              influence printing: unrecognized formats cannot be printed.

              Change viewer colours using either RGB triplets  in  the  format
              #rrggbb or the standardized names.

       DVI/PostScript/PDF/HTML/Plain text
              For  text files, texdoctk provides an own viewer. If this viewer
              is disabled, but no alternative viewer  is  specified,  texdoctk
              tries to read the content of the environment variable $PAGER.

              If  you want to print the documentations, you will need convert-
              ers to turn non-PS files into PostScript. Here are some  sugges-
              tions:

                 dvi->ps:   dvips  (is  part  of  teTeX)  (http://www.radical-
              eye.com/dvips.html)

                pdf->ps:  pdf2ps  (http://www.cs.wisc.edu/~ghost)  or  Acrobat
              Reader (http://www.adobe.com)

               html->ps: html2ps (http://user.it.uu.se/~jan/html2ps.html)

               plain text->ps: a2ps (http://www-inf.enst.fr/~demaille/a2ps/)

              The  html->ps  and text->ps converter menus for switching on/off
              output redirect.  This is due to the fact that  some  converters
              do  not write their output into a file but to stdout by default,
              so a redirect is needed, e.g.  a2ps myfile.txt >myfile.ps

       The  system-wide  configuration  file   is   ($TEXMFMAIN)/texdoctk/tex-
       docrc.defaults  and should only be writable by the administrator of the
       installation using any text editor.  The  optional  user  configuration
       file  is  ~/.texdocrc  and  can  override all but those system settings
       which affect the installation as a whole. The preferred way of changing
       it is through the Settings menu.

   The databases
       texdoctk  comes with a default database file ($TEXMFMAIN)/texdoctk/tex-
       doctk.dat with a special format. It is divided into 17 sections  corre-
       sponding  to  the  17  buttons that are active by default. Each section
       begins with a line

       @section_name

       where section_name is the text as it appears in the button. This  title
       is  followed  by  the descriptive entries for each documentation, which
       have this format:

       package-label;Short description for listbox (opt. package-name);path in
       doc directory;optional keywords

       (without  breaking  the line!). Comments (initiated with a #) and empty
       lines are ignored by the program. The second field  is  the  text  dis-
       played  in  the  selection  listboxes of texdoctk, and you will usually
       want to mention the name of the package in parens along  with  it;  the
       first  field  is a unique label for the package for internal use of the
       program which will usually be chosen identical to the package name, but
       can  be  different  if there is more than one documentation file coming
       with a package.

       The administrator will probably  install  additional  packages  in  the
       local  texmf tree. The corresponding documentation can be made accessi-
       ble by an additional database  $TEXMFLOCAL/texdoctk/texdoctk-local.dat.
       Furthermore,  individual  users possibly install additional packages in
       an texmf subdirectory of their $HOME, for which they can make an  indi-
       vidual  database  themselves  as $TEXMFHOME/texdoctk/texdoctk-pers.dat.
       After creating such files, texhash must be executed.

       Both types of databases must have the  same  structure  as  the  system
       database,  although they need (and should) not include all its sections
       if there are no additional entries. For example, if the the package foo
       is  added to the local tree such that its documentation file is ($TEXM-
       FLOCAL)/doc/latex/foo/foo.dvi and it is decided that it fits best  into
       the  existing  category  Graphics,  texdoctk-local.dat  would look like
       this:

       @Graphics
       foo;Create bells and whistles (foo);latex/foo/foo.dvi;decoration

       The entry for foo will then be appended to the list of entries  in  the
       Graphics  category.  The  18th button can be activated in the same way,
       but using a new category name; possible entries at the beginning of the
       database which have not been assigned to a category will be assigned to
       the default Miscellaneous, making the  18th  button  active  with  that
       label.  Note that you cannot have more than 18 categories; if there are
       more, only the one defined last will appear and be used.

       If the documentation is included in the .sty file instead of  a  proper
       documentation  file,  the  optional  keywords  should  start  with  -?-
       directly after the semicolon, where ? is 0, 1, 2 or 3; these are  flags
       which  indicate  in  which part of the .sty the instructions are placed
       and should help texdoctk to extract the documentation  from  the  style
       and present it without the code, which would normally be of little use.

       0      no specific place, scattered between the code

       1      at  end,  behind  \endinput; some .sty files have well-organized
              documentation behind the end  of  the  actual  code,  where  TeX
              doesn't see it upon compilation

       2      at  beginning,  terminated  by %%%%%%; in some other cases, some
              usage information is at the beginning of the .sty as  a  comment
              terminated by a line full of %

       3      as 2, but with a blank line as termination

       See the system database for plenty of examples.


FILES
        $TEXMFMAIN/texdoctk/texdocrc.defaults system-wide configuration file

         ~/.texdocrc  (optional) personal configuration file; can also be cre-
       ated with the Settings menu

        $TEXMFMAIN/texdoctk/texdoctk.dat default database file for  documenta-
       tion files of the distribution

        $TEXMFLOCAL/texdoctk/texdoctk-local.dat (optional) local database file
       for documentation files

         $TEXMFHOME/texdoctk/texdoctk-pers.dat  (optional)  personal  database
       file of individual users for documentation files

BUGS
       Widget  placement  in topic toplevels becomes ugly when the toplevel is
       stretched or shrunk.

       The font in the frame labels of the Settings menu are not forced to the
       default  font;  this  will become visible e.g. at hi-res screens, where
       the label font is not scaled up.

       Netscape and Mozilla error output will be written to stderr even if the
       quiet mode was set.

AUTHOR
       texdoctk was written by Thomas Ruedas <tr@geol.ku.dk>.

       This manual page was originally written by Adrian Bunk <bunk@fs.tum.de>
       for the Debian GNU/Linux system (but may be used by others). It is  now
       maintained by Thomas Ruedas.


COPYRIGHT
       Copyright (C) 2000-2004 Thomas Ruedas
       This  is free software; see the source for copying conditions. There is
       NO warranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR
       PURPOSE.



                                                                   TEXDOCTK(1)
