1TEXDOCTK(1) General Commands Manual TEXDOCTK(1)
2
6 texdoctk - GUI for easier access of TeX package and program documenta‐
7 tions
8
10 texdoctk -[aq]
11
13 texdoctk is a GUI for easier access to a large part of the vast amount
14 of package and program documentations and tutorials for TeX and its
15 different derivatives (mainly LaTeX). It is optimized and included in
16 the teTeX and fpTeX distributions and also available with TeXLive.
17 The documentation is grouped into 17 categories; the 18th button of the
19 main panel is inactive by default and intended for use with local addi‐
20 tions (see section CONFIGURATION below).
21 In the settings window you see a checkbox in the html->ps and text->ps
23 converter menus for switching on/off output redirect. This is due to
24 the fact that some converters do not write their output into a file but
25 to stdout by default, so a redirect is needed, e.g.
26 a2ps myfile.txt >myfile.ps
28
30 -v verbose: enable some viewer messages which are otherwise sent to
31 stderr, as well as some warning popup windows. This can also be
32 set in a configuration file.
33 -a autoview: autostart viewer if a listbox contains only one item
35 (this will frequently happen in search results). This can also
36 be set in a configuration file.
37
39 The configuration is controlled by the system default configuration
40 file ($TEXMFMAIN)/texdoctk/texdocrc.defaults, most of whose entries can
41 though be overridden by the users' own optional ~/.texdocrc files
42 and/or command line options.
43 The Settings menu and configuration files
45 The Settings menu is used to change the user-definable settings of tex‐
46 doctk for the duration of the program call or as new defaults. The lat‐
47 ter case is the purpose of the Save button, which generates or rewrites
48 the user's own ~/.texdocrc file. The system defaults cannot be edited
49 with the Settings menu.
50 Paths The TEXMF-type paths on the system are reported, and the user
52 can specify the name of the subdirectory of $HOMETEXMF, where
53 the personal documentation is stored.
54 General viewer behaviour
56 Suppress error messages toggle verbose mode (see option -v);
58 default is off.
59 Autostart viewer for one-item listboxes if a listbox contains
61 only one item (see option -a)
62 Use text viewer for unknown file format i.e. treat the file as
64 plain text. texdoctk should recognize the usual file formats and
65 also relate names like README to plain text, but some docs may
66 have freely invented names. Default is on; if switched off, try‐
67 ing to view such files will raise an error. The switch does not
68 influence printing: unrecognized formats cannot be printed.
69 Change viewer colours using either RGB triplets in the format
71 #rrggbb or the standardized names.
72 DVI/PostScript/PDF/HTML/Plain text
74 For text files, texdoctk provides an own viewer. If this viewer
75 is disabled, but no alternative viewer is specified, texdoctk
76 tries to read the content of the environment variable $PAGER.
77 If you want to print the documentations, you will need convert‐
79 ers to turn non-PS files into PostScript. Here are some sugges‐
80 tions:
81 dvi->ps: dvips (is part of teTeX) (http://www.radical‐
83 eye.com/dvips.html)
84 pdf->ps: pdf2ps (http://www.cs.wisc.edu/~ghost) or Acrobat
86 Reader (http://www.adobe.com)
87 html->ps: html2ps (http://user.it.uu.se/~jan/html2ps.html)
89 plain text->ps: a2ps (http://www-inf.enst.fr/~demaille/a2ps/)
91 The html->ps and text->ps converter menus for switching on/off
93 output redirect. This is due to the fact that some converters
94 do not write their output into a file but to stdout by default,
95 so a redirect is needed, e.g. a2ps myfile.txt >myfile.ps
96 The system-wide configuration file is ($TEXMFMAIN)/texdoctk/tex‐
98 docrc.defaults and should only be writable by the administrator of the
99 installation using any text editor. The optional user configuration
100 file is ~/.texdocrc and can override all but those system settings
101 which affect the installation as a whole. The preferred way of changing
102 it is through the Settings menu.
103 The databases
105 texdoctk comes with a default database file ($TEXMFMAIN)/texdoctk/tex‐
106 doctk.dat with a special format. It is divided into 17 sections corre‐
107 sponding to the 17 buttons that are active by default. Each section
108 begins with a line
109 @section_name
111 where section_name is the text as it appears in the button. This title
113 is followed by the descriptive entries for each documentation, which
114 have this format:
115 package-label;Short description for listbox (opt. package-name);path in
117 doc directory;optional keywords
118 (without breaking the line!). Comments (initiated with a #) and empty
120 lines are ignored by the program. The second field is the text dis‐
121 played in the selection listboxes of texdoctk, and you will usually
122 want to mention the name of the package in parens along with it; the
123 first field is a unique label for the package for internal use of the
124 program which will usually be chosen identical to the package name, but
125 can be different if there is more than one documentation file coming
126 with a package.
127 The administrator will probably install additional packages in the
129 local texmf tree. The corresponding documentation can be made accessi‐
130 ble by an additional database $TEXMFLOCAL/texdoctk/texdoctk-local.dat.
131 Furthermore, individual users possibly install additional packages in
132 an texmf subdirectory of their $HOME, for which they can make an indi‐
133 vidual database themselves as $TEXMFHOME/texdoctk/texdoctk-pers.dat.
134 After creating such files, texhash must be executed.
135 Both types of databases must have the same structure as the system
137 database, although they need (and should) not include all its sections
138 if there are no additional entries. For example, if the the package foo
139 is added to the local tree such that its documentation file is ($TEXM‐
140 FLOCAL)/doc/latex/foo/foo.dvi and it is decided that it fits best into
141 the existing category Graphics, texdoctk-local.dat would look like
142 this:
143 @Graphics
145 foo;Create bells and whistles (foo);latex/foo/foo.dvi;decoration
146 The entry for foo will then be appended to the list of entries in the
148 Graphics category. The 18th button can be activated in the same way,
149 but using a new category name; possible entries at the beginning of the
150 database which have not been assigned to a category will be assigned to
151 the default Miscellaneous, making the 18th button active with that
152 label. Note that you cannot have more than 18 categories; if there are
153 more, only the one defined last will appear and be used.
154 If the documentation is included in the .sty file instead of a proper
156 documentation file, the optional keywords should start with -?-
157 directly after the semicolon, where ? is 0, 1, 2 or 3; these are flags
158 which indicate in which part of the .sty the instructions are placed
159 and should help texdoctk to extract the documentation from the style
160 and present it without the code, which would normally be of little use.
161 0 no specific place, scattered between the code
163 1 at end, behind \endinput; some .sty files have well-organized
165 documentation behind the end of the actual code, where TeX
166 doesn't see it upon compilation
167 2 at beginning, terminated by %%%%%%; in some other cases, some
169 usage information is at the beginning of the .sty as a comment
170 terminated by a line full of %
171 3 as 2, but with a blank line as termination
173 See the system database for plenty of examples.
175
178 $TEXMFMAIN/texdoctk/texdocrc.defaults system-wide configuration file
179 ~/.texdocrc (optional) personal configuration file; can also be cre‐
181 ated with the Settings menu
182 $TEXMFMAIN/texdoctk/texdoctk.dat default database file for documenta‐
184 tion files of the distribution
185 $TEXMFLOCAL/texdoctk/texdoctk-local.dat (optional) local database file
187 for documentation files
188 $TEXMFHOME/texdoctk/texdoctk-pers.dat (optional) personal database
190 file of individual users for documentation files
191
193 Widget placement in topic toplevels becomes ugly when the toplevel is
194 stretched or shrunk.
195 The font in the frame labels of the Settings menu are not forced to the
197 default font; this will become visible e.g. at hi-res screens, where
198 the label font is not scaled up.
199 Netscape and Mozilla error output will be written to stderr even if the
201 quiet mode was set.
202
204 texdoctk was written by Thomas Ruedas <tr@geol.ku.dk>.
205 This manual page was originally written by Adrian Bunk <bunk@fs.tum.de>
207 for the Debian GNU/Linux system (but may be used by others). It is now
208 maintained by Thomas Ruedas.
209
212 Copyright (C) 2000-2004 Thomas Ruedas
213 This is free software; see the source for copying conditions. There is
214 NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
215 PURPOSE.
216 TEXDOCTK(1)