texdoctk - GUI for easier access of TeX package and program documentations
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 additions (see
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
- 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
- autoview: autostart viewer if a listbox contains only one item (this will
frequently happen in search results). This can also be set in a
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
The Settings menu and configuration files¶
The Settings menu is used to change the user-definable settings of
for the duration of the program call or as new defaults. The
latter 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
- 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
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, trying 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 converters to turn
non-PS files into PostScript. Here are some suggestions:
dvi->ps: dvips (is part of teTeX) (http://www.radicaleye.com/dvips.html)
pdf->ps: pdf2ps (http://www.cs.wisc.edu/~ghost) or Acrobat Reader
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/texdocrc.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.
comes with a default database file
($TEXMFMAIN)/texdoctk/texdoctk.dat with a special format. It is divided into
17 sections corresponding to the 17 buttons that are active by default. Each
section begins with a line
is the text as it appears in the button. This title is
followed by the descriptive entries for each documentation, which have this
;Short description for listbox (opt.
);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 displayed 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
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 accessible 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 individual database themselves as
$TEXMFHOME/texdoctk/texdoctk-pers.dat. After creating such files, texhash must
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
($TEXMFLOCAL)/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:
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
to extract the documentation from the style and present it
without the code, which would normally be of little use.
- no specific place, scattered between the code
- at end, behind \endinput; some .sty files have well-organized
documentation behind the end of the actual code, where TeX doesn't see it
- 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 %
- as 2, but with a blank line as termination
See the system database for plenty of examples.
$TEXMFMAIN/texdoctk/texdocrc.defaults system-wide configuration file
~/.texdocrc (optional) personal configuration file; can also be created with
the Settings menu
$TEXMFMAIN/texdoctk/texdoctk.dat default database file for documentation files
of the distribution
$TEXMFLOCAL/texdoctk/texdoctk-local.dat (optional) local database file for
$TEXMFHOME/texdoctk/texdoctk-pers.dat (optional) personal database file of
individual users for documentation files
Widget placement in topic toplevels becomes ugly when the toplevel is stretched
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.
was written by Thomas Ruedas <firstname.lastname@example.org>.
This manual page was originally written by Adrian Bunk <email@example.com>
for the Debian GNU/Linux system (but may be used by others). It is now
maintained by Thomas Ruedas.
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