TEXDOCTK(1)

📦 version 62186, in alpine 3.24, arch rolling, debian bookworm, debian trixie, fedora 43, fedora 44, opensuse-leap 16.0, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

🎀 NAME 🎀

Okay so the manual name is TEXDOCTK(1) and it lives in the General Commands Manual 📚

texdoctk is a GUI for finding TeX package and program documentation ✨

💅 SYNOPSIS 💅

texdoctk -[aq]

🦋 DESCRIPTION 🦋

Okay so texdoctk is a GUI that makes it way easier to get into the huge pile of package and program docs and tutorials for TeX and its different derivatives (mostly LaTeX) 💖 It's optimized and included in the teTeX and fpTeX distributions, and you can also get it with TeXLive 🌈

The docs are sorted into 17 categories. The 18th button on the main panel is inactive by default, and it's meant for your own local additions (see CONFIGURATION below) 🧚

In the settings window there's a checkbox in the html->ps and text->ps converter menus for switching output redirect on or off 🙈 This matters because some converters don't write to a file and instead send their output to stdout by default, so you need a redirect, like this:

a2ps myfile.txt >myfile.ps

✨ OPTIONS ✨

  • -v — verbose mode 📢 This turns on some viewer messages that would otherwise go to stderr, plus some warning popup windows. You can also set this in a configuration file.
  • -a — autoview 👀 This autostarts the viewer when a listbox has only one item (which happens a lot with search results). You can also set this in a configuration file.

🎀 CONFIGURATION 🎀

The configuration is controlled by the system default file ($TEXMFMAIN)/texdoctk/texdocrc.defaults. Most of its entries can be overridden by your own optional ~/.texdocrc files and/or command line options 💅

⚙️ The Settings menu and configuration files ⚙️

The Settings menu lets you change the user-definable settings for the length of one program call, or save them as new defaults 💖 Saving as defaults is what the Save button is for, and it creates or rewrites your own ~/.texdocrc file. The system defaults can't be edited from the Settings menu, sorry bestie 🙅

Paths — The TEXMF-type paths on your system are shown here, and you can pick the name of the subdirectory of $HOMETEXMF where your personal docs live 🗂️

General viewer behaviour 🪄

  • Suppress error messages — this toggles verbose mode (see option -v). Default is off.
  • Autostart viewer for one-item listboxes — if a listbox has only one item, the viewer starts automatically (see option -a).
  • Use text viewer for unknown file format — this treats the file as plain text 📝 texdoctk should recognize the usual file formats and also map names like README to plain text, but some docs have totally made-up names. Default is on. If you switch it off, trying to view those files raises an error. This switch doesn't affect printing, since unrecognized formats can't be printed.
  • Change viewer colours — use either RGB triplets in the format #rrggbb or the standardized color names 🌈

DVI/PostScript/PDF/HTML/Plain text 🖨️

For text files, texdoctk has its own viewer 💜 If that viewer is disabled and no alternative viewer is set, texdoctk tries to read the content of the environment variable $PAGER.

If you want to print the docs, you'll need converters to turn non-PS files into PostScript 😭 Here are some suggestions:

The html->ps and text->ps converter menus have the on/off switch for output redirect. This is needed because some converters don't write their output into a file and send it to stdout by default, so a redirect is required, e.g.:

a2ps myfile.txt >myfile.ps

The system-wide config file is ($TEXMFMAIN)/texdoctk/texdocrc.defaults, and it should only be writable by whoever administers the installation, using any text editor 🔒 The optional user config file is ~/.texdocrc, and it can override everything except the system settings that affect the installation as a whole. The preferred way to change it is the Settings menu 🫶

📚 The databases 📚

texdoctk comes with a default database file, ($TEXMFMAIN)/texdoctk/texdoctk.dat, in a special format 🧁 It's split into 17 sections, one for each of the 17 buttons that are active by default. Each section starts with a line like this:

@section_name

where section_name is the text exactly as it appears on the button. The title is followed by the entries for each doc, and each entry has this format (keep it on one line!!):

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

Comments (starting with a #) and empty lines get ignored by the program 🙈 The second field is the text shown in the selection listboxes, and you'll usually want the package name in parens after it. The first field is a unique label that the program uses internally. It's usually the same as the package name, but it can be different if a package ships with more than one doc file 💅

The admin will probably install extra packages in the local texmf tree 🏡 Their docs can be made accessible with an additional database, $TEXMFLOCAL/texdoctk/texdoctk-local.dat. Individual users might also install packages in a texmf subdirectory of their $HOME, and they can make their own database as $TEXMFHOME/texdoctk/texdoctk-pers.dat. After creating these files, you must run texhash ⚠️

Both kinds of databases need the same structure as the system database. They don't need (and really shouldn't include) every section if there's nothing new for them to add ✨ For example, say the package foo is added to the local tree, its doc file is ($TEXMFLOCAL)/doc/latex/foo/foo.dvi, and you decide it fits best in the existing Graphics category. Then texdoctk-local.dat would look like this:

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

The foo entry gets added to the end of the Graphics list 💖 The 18th button can be activated the same way, just with a new category name. Any entries at the start of the database that haven't been assigned to a category get put into the default Miscellaneous category, which makes the 18th button active with that label 🌸

⚠️ You can't have more than 18 categories. If there are more, only the one defined last will show up and get used.

If the documentation lives inside the .sty file instead of a proper doc file, the optional keywords should start with -?- right after the semicolon, where ? is 0, 1, 2 or 3 🧚 These flags say where in the .sty the instructions are, and they help texdoctk pull out the docs and show them without the code (which would normally be pretty useless to read).

  • 0 — no specific place, scattered between the code
  • 1 — at the end, behind \endinput. Some .sty files have well-organized docs after the actual code, where TeX doesn't look during compilation
  • 2 — at the beginning, terminated by %%%%%%. In other cases, some usage info sits at the top of the .sty as a comment that ends with a line full of %
  • 3 — same as 2, but terminated by a blank line

See the system database for plenty of examples 💜

📁 FILES 📁

  • $TEXMFMAIN/texdoctk/texdocrc.defaults — system-wide configuration file
  • ~/.texdocrc (optional) — personal configuration file, which can also be created with the Settings menu
  • $TEXMFMAIN/texdoctk/texdoctk.dat — default database file for the 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 gets ugly when the toplevel is stretched or shrunk 😬
  • The font in the frame labels of the Settings menu isn't forced to the default font. You'll see this on hi-res screens, where the label font doesn't get scaled up.
  • Netscape and Mozilla error output is written to stderr even if 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 others are allowed to use it). It's 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 PURPOSE 🦋

That's the whole page, bestie 🧚💖 Signing off as TEXDOCTK(1) from the General Commands Manual, stay cute and keep TeX-ing ✨💅

📦 where this page comes from