path: root/Build/source/utils/texdoctk/README

				texdoctk v.0.5.3

texdoctk is a Perl/Tk-based frontend for easy access of package documentation
for the TeX typesetting system on Unix platforms. It includes the following
files:

	texdoctk 	  - the program source
	texdoctk.dat 	  - the database containing the information about the
			    accessible documentation files for teTeX-texmf
	texdocrc.defaults - the system-wide default specification for viewer
			    and printer settings
	texdoctk.1	  - manpage
	README.texdoctk	  - this file
The current version is 0.6.0.

REQUIREMENTS
The program is written in Perl/Tk; it requires Perl 5 and Perl/Tk 8.x. It is
known to run with Perl 5.004_04 or higher and PerlTk 800.015.
The database file texdoctk.dat is made for the teTeX distribution.
Note that the program is *not* a viewer, but an interface to access a document
with the appropriate viewer. Thus, you need to have appropriate viewers for
the different formats to actually read the files. Documentations are available
as .dvi, .ps, .pdf, .html or plain text; some packages are only documented in
the .sty files. For plain text files (.txt, .sty etc.), texdoctk's own text
viewer can be used (default). If a document format is not known, texdoctk
will by default assume that it is plain text and use the text file viewer;
this behaviour can be switched off in the Settings menu.
If you want to print the documentations, you will need converters to turn
non-PS files into PostScript. Here are some suggestions:
dvi->ps:	dvips (is part of teTeX)
		http://www.radicaleye.com/dvips.html
pdf->ps:	pdf2ps
		http://www.cs.wisc.edu/~ghost
		Acrobat Reader
		http://www.adobe.com
html->ps:	html2ps
		http://user.it.uu.se/~jan/html2ps.html
plain text->ps:	a2ps
		http://www-inf.enst.fr/~demaille/a2ps/
To increase the font size automatically for high-resolution screen, the program
xwininfo is used; texdoctk will work without as well, though.

INSTALLATION
The program texdoctk can be copied into any directory where programs are stored
on your system, e.g. into /usr/local/bin or, probably more adequate, into
/usr/local/teTeX/bin. It assumes that you have the env command in /usr/bin/
available to determine the location of the Perl executable; therefore, you may
need to change the first line of the code if this is not the case for your
system or if for some reason your Perl executable is not called "perl"; you
will also have to change the perl call in the sub viewslc as well.
The database file texdoctk.dat and the configuration file texdocrc.defaults 
must then be put into a subdirectory of the main texmf directory called
texdoctk. If you want to include information for your local system,
generate a file texdoctk-local.dat. Make sure to run texhash after
installation. See the manpage for more info.
Set the defaults in texdocrc.defaults according to your system; you can
replace the settings which are specified in the shipped file, but do not
uncomment variables for items which are not available or applicable for you,
but just leave the value empty by specifying nothing.
The individual users can define their own preferences by copying the system
texdocrc.defaults to ~/.texdocrc and assign new values to the items to be
changed. They can also establish an additional personal database for packages
they might have installed in their respective $HOME; this database must be
called texdoctk-pers.dat and reside in $HOMETEXMF/texdoctk/.
If you meet the requirements concerning the teTeX distribution, I assume that
the texdoctk.dat file should work without failures; if you have another
distribution or if your texmf/doc tree is somehow modified, it may happen that
a file is not found in spite of the program trying to find it elsewhere. You
will have to edit the file then, but make sure to keep the right format for
the entries:
<package-label>;Short description for listbox (opt. <package-name>);path in doc directory;optional keywords
(without breaking the line!). If the documentation is included in the .sty file
instead of a proper documentation file, the optional keywords should start with
-?- directly after the semicolon, where ? is 0, 1, 2 or 3; these are flags
which indicate in which part of the .sty the instructions are placed. See the
database file and/or the manpage for more details if necessary.
The documentation is grouped into 17 categories; the 18th button of the main
panel is inactive by default. If you have special documents which do not fit
into any of the categories, you can create a block with a new name in
texdoctk-local.dat or texdoctk-pers.dat with the respective entries.
In the settings window you see a checkbox in the html->ps and text->ps
converter menus for switching on/off output redirect. This is due to the fact
that some converters do not write their output into a file but to stdout by
default, so a redirect is needed, e.g.
a2ps myfile.txt >myfile.ps

DISCLAIMER
texdoctk v.0.6.0 (Sep 23, 2004) - GUI for TeX documentation access
Copyright (C) 2000-2004  Thomas Ruedas
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

ACKNOWLEDGEMENTS
Thomas Esser included the program in the teTeX distribution of TeX and Friends.
He provided me with informations about changes in the texmf tree and made a
number of very useful suggestions. He also has coordinated and kept track of
several additions from other contributors, who fixed bugs and added extensions
e.g. for use under Win32 systems.
Reinhard Kotucha and Andreas Werner made very valuable comments and suggestions
to enhance v.0.3.0, especially about the special treatment of Netscape.
Reinhard Kotucha also made many useful suggestions and provided patches for
v.0.4.0; unfortunately, I could not implement all these ideas yet.
Hans Fredrik Nordhaug made some suggestions, e.g. concerning local and
personal texmf trees, and reported several bugs in different releases; he also
contributed fixes/patches.
Adrian Bunk also has reported a bug and contributed a small manpage for the
program. He made a Debian GNU/Linux package of texdoctk.
Michael Sanders reminded me to set the permissions right in the tarball.
As this is my first application written in PerlTk, it happened that I could
not solve every problem with my book and the other documentation, but had to
ask for help on comp.lang.perl.tk. Paul R. Andersen and Stephen O. Lidie have
given helpful replies and examples for me to try out.
Fabrice Popineau, and possibly others who I don't know, have provided
portability to Win32 platforms for use with fpTeX. Staszek Wawrykiewicz helped
making it ready for use with new TeXLive editions.
Paul Szabo pointed out a potential security risk related to the way names of
temporary files are generated.

TO DO LIST
Unfortunately, I didn't have time to implement all suggestions made by the
aforementioned people; I hope that I can do that at some later time:
- widget placement in topic toplevels becomes ugly when the toplevel is
  stretched or shrunk; should be made more elegant
- raise existing texdoctk window instead of possibly running texdoctk twice;
  (this seems to be difficult, because it requires interprocess communication
  which is kind of unsafe and requires the use of perl -T)
Possible further long-term enhancements:
- maybe use Williams Catalogue for automatically building database during
  installation
- refined printing facility

BUGS
Netscape error output will be written to stderr even if the quiet mode was set,
because I didn't manage to start it with the "inline" perl script.
Widget placement in topic toplevels becomes ugly when the toplevel is stretched
or shrunk.
The font in the frame labels of the Settings menu are not forced to the default
font; this will become visible e.g. at hi-res screens, where the label font is
not scaled up.
Please let me know if you find bugs or have suggestions for improvements.

HISTORY/CHANGES
v.0.6.0   Sep 23, 2004
	- Unknown document formats will be opened as plain text with the text
	  file viewer by default; the Settings menu was given a new button to
	  toggle this behaviour.
	- Allow for texmf-dist and texmf-doc trees for compliance with teTeX 3
	  and TeXLive.
	- Made an attempt to allow for additional personal user's databases to
	  be located in $HOMETEXMF, following a long-standing suggestion of
	  H.F.Nordhaug. Additional local and personal databases do not need
	  to be copies of the system database; instead their contents will be
	  appended to the entries of the default list.
	- Fixed a bug with the handling of the local texmf tree reported by
	  Sebastian Luque.
	- Updated this README and the manpage.
v.0.5.2	  May 20, 2004
	- Changed the name generation of temporary files to something random
	  in order to address a potential security risk pointed out by Paul
	  Szabo.
	- Replaced -q option for enabling "quiet" behaviour by -v option for
	  enabling "verbose" behaviour; quiet behaviour is now the default and
	  was extended to suppress the popup of Warning windows (popmsg level
	  1).
        - Added a possibility to have the Settings menu write the user's
          ~/.texdocrc (older suggestion by R.Kotucha). NB: It is not intended
          to write the system-wide texdocrc.defaults, because it does not set
          $TEXDOCPATH and $LOCALDOCPATH.
        - Button colours are made configurable through the texdocrc files or
          the Settings menu. This is intended to fix a problem H.F.Nordhaug
          reported with users of newer versions of the KDE, where some button
          colours suddenly where messed up. - Validity of entered colours
          is checked if X11's showrgb program is available.
        - DVIPS_OPTS, PDFPS_OPTS and PRINT_OPTS in texdocrc.defaults are now
          obsolete, but still supported. It seemed more reasonable to treat
          the contents of DVIPS_CONV, PDFPS_CONV and PRINT_CMD as command lines
          (which actually would have already been possible all the time). The
          same is true for the viewer variables.
        - Command line options can now be grouped (i.e. -av instead of -a -v).
        - Cursor changes from arrow to watch in some tasks, to indicate a
          process which takes a bit of time.
        - fixed some glitches in databases: semicolons at the end of the
          pdfTeX-related entries; corrected description of ltxtable (hint by
          Rolf Niepraschk) and changed its position; corrected description of
          AMSguide (AMS TeX instead of AMS LaTeX) (hint by H.F.Nordhaug)
	- several additions by other contributors, for instance support for
	  Win32 systems
v.0.5.1	  April 21, 2001
	- Enhanced right-button search function so that compressed doc files
	  are also found.
	- Fixed a bug in the documentation finding subroutine reported by H.F.
	  Nordhaug: the compression determination block in sub finddoc was
	  broken.
	- Improved treatment of entering an empty string in the search:
	  this is now explicitly treated as demand for display of the whole
	  database, instead of search for a null string.
	- Automatic selection of list item in listbox if it contains only one
	  element; this will frequently happen in search results. In this
	  context, the autoview flag (option -a) has been introduced in the
	  texdocrc.defaults and the Settings menu: if it is chosen, the
	  appropriate viewer will be started automatically in the case of
	  one-item listboxes.
	- Made <Ctrl-q>, <Ctrl-s>, <Ctrl-t> and <Ctrl-h> definitions active in
	  all widgets; thus, you don't need to type <Ctrl-q> in the main window
	  to quit, for example. Introduced new global key binding for raising
	  the main window (<Ctrl-m>).
	- Fixed a braindead typo in the texdoc-*.dat files (too dumb to tell).
	- Some small changes/updates in the Help text; the button and window
	  are now named "Help/About".
	- Added an emacs perl-mode directive at the end, mostly for my
	  convenience.
v.0.5.0a  April 19, 2001
	- Fixed bug in texdoc-102.dat reported by H.F.Nordhaug: correct path
	  for multirow is latex/multirow/multirow.sty (instead of
	  latex/misc/multirow.sty, as in texdoc-100.dat)
v.0.5.0   April 18, 2001
	- For some packages, the only documentation is included in the .sty
	  file itself. This documentation is now made accessible by extracting
	  the comments/instructions, writing them into a temporary text file
	  and calling the text file viewer on it. Thus 38 additional
	  documentation files are made accessible now.
	- implementation of a suggestion by Hans Fredrik Nordhaug: contents of
	  the local texmf tree ($TEXMFLOCAL) can be included now. Arbitrary
	  inclusion of additional private texmf trees is not yet possible,
	  though.
	- Two fixes/improvements in the databases by R.Kotucha were made
	  (concerning epslatex and the MetaPost tutorial)
	- R.Kotucha suggested the use of the program xwininfo to determine
	  screen resolution and switch to a larger font size at hi-res screens.
	  He provided a patch for this, which I added after a slight
	  adaptation.
	- auto-determination of Perl's path (stolen from some script by Thomas
	  Esser, IIRC)
	- If a beta release of teTeX is used, the teTeX-1.0.2 database will be
	  used as a default instead of the 1.0.0 database
	- introduced new message type with transient windows
	- fatal error messages if essential config/database files are not found
	- some syntax cosmetics
v.0.4.0	  June 11, 2000
	- implementation of several suggestions by Reinhard Kotucha and
	  Andreas Werner:
	  * More than 1 document can now be viewed at one time, because the
	    viewers now run as background processes. They are not killed when
	    texdoctk itself is quit.
	    If Netscape is your browser, HTML documents are now loaded into
	    an existing Netscape window; no new Netscape will be started. This
	    is to be a bit economic with system resources.
	  * The Search button resp. <Ctrl-s> now switches on/off the search
	    entry widget; this is to avoid that multiple entry widgets come up,
	    because that doesn't make much sense.
	  * If no TXT_VIEWER is defined, the environment variable $PAGER will
	    be used, if defined (but see below).
	- bugs/fixes and suggestions reported by Hans Fredrik Nordhaug:
	  * $j for loop in sub srchstr was too short:
		$j<$maxind[$i] --> $j<$maxind[$i]+1
	  * misplaced last SRCH in keywords branch of sub srchstr: last SRCH
	    had to be put into inner if block
	  * added support of zip compression format
	- bug/fix reported by Adrian Bunk:
	  * ambiguous use of redirection flag/sign hor html and text->ps
	    conversion
	- own text viewer for plain text documentation files; this is now the
	  default in the original texdocrc.defaults
	- kpsewhich instead of find is used for rescue file search
	- temporary files generated when printing or possibly decompressing (as
	  in Debian) now get different names to prevent overwriting files which
	  are still in use
	- main, settings, and help windows made non-resizable
	- suppressed availability of listbox selection to X selection
	- document selection toplevel windows will be raised now instead of
	  being opened twice or more times if they are already open
	- uniform font for all text-containing widgets explicitly set; I had
	  some weird font configuration when running texdoctk under a CDE
	- environment
v.0.3.0	  March 11, 2000
	- first full public release
	- implementation of some suggestions by Thomas Esser:
	  use of kpsewhich, changes in directory and database configuration
	  implemented cd to file directory to ensure rendering of graphics
	  made viewer message output suppression really quiet
	  better layout of help window
v.0.2	  March 7, 2000
	- first public release (preliminary)
v.0.1	- private trial version, does not exist anymore

AUTHOR
Thomas Ruedas
tr@geol.ku.dk
http://www.geophysik.uni-frankfurt.de/~ruedas/progs.html