Provided by: texlive-base_2024.20241115-1_all 
NAME
texdoctk - GUI for easier access of TeX package and program documentations
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 additions (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 texdoctk 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 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,
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
(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/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.
The databases
texdoctk 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
@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 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 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 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 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 ($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:
@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 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 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)