Debian Codegraph @

texmf-dist/doc/man/man1/texdoctk.1

raw
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.