1TEXDOCTK(1)                 General Commands Manual                TEXDOCTK(1)
2
3
4

NAME

6       texdoctk  - GUI for easier access of TeX package and program documenta‐
7       tions
8

SYNOPSIS

10       texdoctk -[aq]
11

DESCRIPTION

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 derivates (mainly LaTeX). It is optimized and included in the
16       teTeX and fpTeX distributions and also available with TeXLive.
17
18       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
22       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
27       a2ps myfile.txt >myfile.ps
28

OPTIONS

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
34       -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

CONFIGURATION

39       The configuration is controlled by the  system  default  concfiguration
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
44   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 programm call or  as  new  defaults.  The
47       latter  case  is  the  purpose  of  the Save button, which generates or
48       rewrites the user's own ~/.texdocrc file. The system defaults cannot be
49       edited with the Settings menu.
50
51       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
55       General viewer behaviour
56
57              Suppress  error  messages  toggle  verbose mode (see option -v);
58              default is off.
59
60              Autostart viewer for one-item listboxes if  a  listbox  contains
61              only one item (see option -a)
62
63              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
70              Change viewer colours using either RGB triplets  in  the  format
71              #rrggbb or the standardized names.
72
73       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
78              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
82                 dvi->ps:   dvips  (is  part  of  teTeX)  (http://www.radical
83              eye.com/dvips.html)
84
85                pdf->ps:  pdf2ps  (http://www.cs.wisc.edu/~ghost)  or  Acrobat
86              Reader (http://www.adobe.com)
87
88               html->ps: html2ps (http://user.it.uu.se/~jan/html2ps.html)
89
90               plain text->ps: a2ps (http://www-inf.enst.fr/~demaille/a2ps/)
91
92              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
97       The  system-wide  configuration  file   is   ($TEXMFMAIN)/texdoctk/tex‐
98       docrc.defaults and should only be writeable 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
104   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
110       @section_name
111
112       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
116       package-label;Short description for listbox (opt. package-name);path in
117       doc directory;optional keywords
118
119       (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
128       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
136       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
144       @Graphics
145       foo;Create bells and whistles (foo);latex/foo/foo.dvi;decoration
146
147       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
155       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
162       0      no specific place, scattered between the code
163
164       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
168       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
172       3      as 2, but with a blank line as termination
173
174       See the system database for plenty of examples.
175
176

FILES

178        $TEXMFMAIN/texdoctk/texdocrc.defaults system-wide configuration file
179
180         ~/.texdocrc  (optional) personal configuration file; can also be cre‐
181       ated with the Settings menu
182
183        $TEXMFMAIN/texdoctk/texdoctk.dat default database file for  documenta‐
184       tion files of the distribution
185
186        $TEXMFLOCAL/texdoctk/texdoctk-local.dat (optional) local database file
187       for documentation files
188
189         $TEXMFHOME/texdoctk/texdoctk-pers.dat  (optional)  personal  database
190       file of individual users for documentation files
191

BUGS

193       Widget  placement  in topic toplevels becomes ugly when the toplevel is
194       stretched or shrunk.
195
196       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
200       Netscape and Mozilla error output will be written to stderr even if the
201       quiet mode was set.
202

AUTHOR

204       texdoctk was written by Thomas Ruedas <tr@dlc.ku.dk>.
205
206       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
210
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
217
218
219                                                                   TEXDOCTK(1)
Impressum