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