summaryrefslogtreecommitdiff
path: root/Build/source/utils/texdoctk/README.texdoctk
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/utils/texdoctk/README.texdoctk')
-rw-r--r--Build/source/utils/texdoctk/README.texdoctk298
1 files changed, 298 insertions, 0 deletions
diff --git a/Build/source/utils/texdoctk/README.texdoctk b/Build/source/utils/texdoctk/README.texdoctk
new file mode 100644
index 00000000000..54217cb61ce
--- /dev/null
+++ b/Build/source/utils/texdoctk/README.texdoctk
@@ -0,0 +1,298 @@
+ 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