summaryrefslogtreecommitdiff
path: root/support/TVS/TVS/docs/tvs.texi
diff options
context:
space:
mode:
Diffstat (limited to 'support/TVS/TVS/docs/tvs.texi')
-rw-r--r--support/TVS/TVS/docs/tvs.texi913
1 files changed, 913 insertions, 0 deletions
diff --git a/support/TVS/TVS/docs/tvs.texi b/support/TVS/TVS/docs/tvs.texi
new file mode 100644
index 0000000000..06084a36c9
--- /dev/null
+++ b/support/TVS/TVS/docs/tvs.texi
@@ -0,0 +1,913 @@
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename tvs.info
+@settitle @TeX{} Versioning System
+@afourpaper
+@c %**end of header
+
+@c This is TeX Versioning System documentation
+@c $Id: tvs.texi,v 1.23 2000/08/16 17:00:24 antos Exp $
+
+@titlepage
+@title @TeX{} Versioning System
+@subtitle Software for storing complete source codes of @TeX{} documents
+@author by David Anto@v{s}
+
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 2000 David Anto@v{s}
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+@end ignore
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation approved
+by the Free Software Foundation.
+
+@end titlepage
+
+@dircategory TeX
+@direntry
+* TVS: (tvs) TeX Versioning System
+@end direntry
+
+@c ---------------------------------------------------------------------
+@node Top, Copying, (dir), (dir)
+@ifnottex
+@chapter @TeX{} Versioning System
+This is documentation of @TeX{} Versioning System, software for storing
+complete source codes of @TeX{} documents.
+
+@menu
+* Copying::
+* Introduction::
+* Installation::
+* Using @code{TVS} step by step::
+* Reference guide to @code{TVS} commands::
+* Config file and pattern files::
+* Credits::
+* Dealing with bugs in @code{TVS}::
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Introduction
+
+* Why do you need @code{TVS}?::
+* What @code{TVS} can do?::
+* What do you need to run @code{TVS}?::
+
+Using @code{TVS} step by step
+
+* Useful commands::
+* Basic running @code{TVS}::
+* Ignoring files::
+* Format file sources::
+* Configuration file::
+* Limitations of @code{TVS}::
+* Fonts::
+* What to do with collected output::
+
+Reference guide to @code{TVS} commands
+
+* Invoking @code{TVS}::
+* Global switches::
+* Ignoring files and cutting filenames::
+* Output directory setting::
+* Storing format source files and fonts::
+
+Config file and pattern files
+
+* Config file::
+* Pattern file structure::
+
+Pattern file structure
+
+* Pathcuts pattern file::
+* Ignore pattern file::
+
+@end detailmenu
+@end menu
+
+@c --------------------------------------------------------------------
+@node Copying, Introduction, Top, Top
+@chapter Copying
+
+The program @code{TVS} and its documentation is written and
+maintained by David Anto@v{s}, @email{xantos
+(at) fi.muni.cz}. (Of course substitute (at) with @@.)
+Contact him when in trouble, but please read the documentation first.
+
+Copyright @copyright{} 2000 David Anto@v{s}
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+@end ignore
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation approved
+by the Free Software Foundation.
+
+@end ifnottex
+
+@c -------------------------------------------------------------------
+@node Introduction, Installation, Copying, Top
+@chapter Introduction
+
+This is documentation of @TeX{} Versioning System, software for storing
+complete source codes of @TeX{} documents.
+
+Version 1.0
+
+(Documentation CVS ver. $Id: tvs.texi,v 1.23 2000/08/16 17:00:24 antos Exp $)
+
+@menu
+* Why do you need @code{TVS}?::
+* What @code{TVS} can do?::
+* What do you need to run @code{TVS}?::
+@end menu
+
+@node Why do you need @code{TVS}?, What @code{TVS} can do?, Introduction, Introduction
+@section Why do you need @code{TVS}?
+
+It must have happened to you. You use @TeX{} at work. You run another
+distribution at home. You wrote a beautiful document at home, you came to
+work and got error message @code{I can't find file `foo.tex'}. There is a
+package missing in your work installation.
+
+Or: You wrote a beautifully typeset book several years ago.
+You used em-@TeX{} on M$-DOS machine. The book should be typeset again. You
+have only my_book.tex and no macros you used. What to do?
+
+To be serious, there is nothing to be done now. But if you stored the
+@emph{complete} source of the documents, it didn't have to happen to you.
+And how to store the complete source? It's simple---use @code{TVS}.
+
+@cartouche
+Please! Please! Packing complete @TeX{} document sources is a delicate
+and sensitive operation. Read the entire manual before you use
+@code{TVS} to do something important. This kind of software can be
+useful for you if and only if you use it correctly. I'm sorry for this
+but it's the fact.
+@end cartouche
+
+@node What @code{TVS} can do?, What do you need to run @code{TVS}?, Why do you need @code{TVS}?, Introduction
+@section What @code{TVS} can do?
+
+@code{TVS} can store complete source codes of @TeX{} documents. It parses
+logs of @TeX{} and finds files which were used to typeset the document.
+@code{TVS} can work in three levels:
+
+@itemize @bullet
+@item Only document log is examined. It stores all macros, styles,
+included documents etc. you need.
+@item Document log and format log is examined. It also stores all
+source files needed to build up format file.
+@item (experimental) Moreover dvips log is parsed and used fonts are
+stored. This is not so useful as only @code{.pk}
+files may be obtained this way.
+@end itemize
+
+Files collected by @code{TVS} can be used on any @TeX{} installation to
+build up exactly the same document.
+Next, let us call the product of @code{TVS} a @emph{complete source}.
+
+There are several important features of @code{TVS}:
+
+@itemize @bullet
+@item @code{TVS} is a Perl script, it runs wherever Perl is available (it
+means nearly everywhere).
+@item There is no difference in using of @code{TVS} when running La@TeX{},
+plain, or whatever you want.
+@item On the destination (the place you typeset the complete source), there is
+no need to run @code{TVS}. You only need to say @TeX{} to find files
+in working directory first.
+@item @code{TVS} is @emph{not} a version control system. It cannot handle
+versions of your documents. There are other systems, e.g., @code{RCS} or
+@code{CVS}, designed to do this.
+@end itemize
+
+@node What do you need to run @code{TVS}?, , What @code{TVS} can do?, Introduction
+@section What do you need to run @code{TVS}?
+
+Hardware and OS requirements are simple. @code{TVS} is a Perl script so it
+runs wherever Perl 5.x is available.
+It uses packages Getopt::Long, File::Basename, File::Copy, and
+File::Path. These packages should be nevertheless in standard Perl
+distribution.
+
+For information on Perl for your OS check
+@url{http://www.perl.com}. There should be no problem on most Unices, in
+Linux, Perl is usually a part of standard distribution.
+
+Maybe you find useful having also @code{make} and @code{Texinfo}
+utilities installed on your system, but @code{Texinfo} is only needed to
+produce documentation in DVI, PostScript, Info, or HTML formats which
+are pregenerated in @code{TVS} distribution. And @code{make} is only to
+generate them comfortably.
+
+There are some requirements for your @TeX{} source codes to be able to
+handle them successfully. There is a problem with including files into your
+source. The usual and best way to do it is to have the main source at the
+top of the source tree and use relative paths in all variants of
+@code{\input} command.
+Avoid pathological inputs like
+@code{\includegraphics ../../pictures/pict1.ps}.
+This should not bother you as nearly everybody does it.
+
+Usually @code{TVS} is able to pack files referenced by ``up-going''
+relative path (if it makes a conflict, @code{TVS}
+recognizes it), but you run into difficulties when re-typesetting the
+complete source and you have to correct all the things by hand.
+
+@c ------------------------------------------------------------------------
+@node Installation, Using @code{TVS} step by step, Introduction, Top
+@chapter Installation
+
+The program @code{TVS} and its documentation is written and
+maintained by David Anto@v{s}, @email{xantos
+(at) fi.muni.cz}. (Of course substitute (at) with @@.)
+Contact him when in trouble, but please read the documentation first.
+
+The following instructions assume that Perl version >=5 is installed on
+your system. For information on Perl consult @url{http://www.perl.org}.
+
+The homepage of @code{TVS} is @url{http://www.fi.muni.cz/~xantos/tvs}.
+Here you can get @code{TVS} either file-by-file or as @code{tvs.tar.gz}
+file. @code{TVS} can also be obtained on CTAN in @code{support/TVS}.
+
+Because of platform independence we decided not to prepare any
+``instant'' packages.
+
+If you downloaded @code{tvs.tar.gz}, gunzip and un-tar it somewhere. If
+you downloaded separate files, reconstruct the original file structure
+anywhere you want.
+
+On UNIX, make a link to @code{tvs.pl} from a directory which is in your
+@code{PATH}, e.g. @code{/usr/local/bin}, if your system decodes first
+lines of scripts to run them. In this case, it may be needed to correct
+the very first line of @code{tvs.pl} and put the right path to your Perl
+interpreter there. Otherwise you may still run @code{TVS}
+running @code{perl tvs.pl}. Install the documentation in your favorite
+format, where your docs-reader can find it. At least,
+@code{/usr/doc/tvs} wouldn't be a bad choice to store Post Script or
+HTML documentation.
+
+Generally speaking, there is no need to install @code{TVS} to global
+directories if you are the only-one who runs it or you are not root.
+
+Try @code{tvs --help}. If a TVS header and help message written,
+everything is OK.
+
+If your standard Perl distribution does not contain packages
+Getopt::Long, File::Basename, File::Copy, and File::Path, get them from
+@url{http://www.perl.org}.
+
+On M$ DOS/Window$ platforms the @code{.pl} suffix should be enough for
+Perl script to run, of course if Perl is correctly installed. Please do
+not expect me to make better support for M$ platforms as I do not run
+them.
+
+On other platforms, if there are difficulties in installing or running
+@code{TVS}, please drop me a line.
+
+@c ------------------------------------------------------------------------
+@node Using @code{TVS} step by step, Reference guide to @code{TVS} commands, Installation, Top
+@chapter Using @code{TVS} step by step
+
+This chapter shows the usage of @code{TVS} and various examples. It also
+points out the limitations of this system, in other words what it
+@emph{can} do for you (and it's quite a lot) and what it cannot. Yes, there
+are some unpleasant things you must do manually.
+
+@menu
+* Useful commands::
+* Basic running @code{TVS}::
+* Ignoring files::
+* Format file sources::
+* Configuration file::
+* Limitations of @code{TVS}::
+* Fonts::
+* What to do with collected output::
+@end menu
+
+@node Useful commands, Basic running @code{TVS}, Using @code{TVS} step by step, Using @code{TVS} step by step
+@section Useful commands
+
+To make sure that @code{TVS} is correctly installed on your system, run
+@code{tvs -h}.
+You should obtain a short help on using @code{TVS}.
+
+There are two useful switches you should know before starting experiments
+with @code{TVS}. You may increase verbosity level using @code{-v} or even
+@code{-vv} switch. @xref{Global switches}, for detailed information
+on verbosity levels.
+
+In following examples you may also specify @code{--dummy} command. It means
+that no files are really copied and no real output is produced. But
+everything else looks like real operations were performed.
+
+@node Basic running @code{TVS}, Ignoring files, Useful commands, Using @code{TVS} step by step
+@section Basic running @code{TVS}
+
+Now it's time to look to the @code{examples} directory in your
+distribution. It contains source file @code{sample.tex} we will use to
+demonstrate the usage of @code{TVS}.
+
+The first step you must not forget is to @TeX{} your source correctly.
+Document @code{sample.tex} uses @code{\tableofcontents}, so you must run
+@example
+latex sample.tex
+@end example
+@noindent
+twice. Make sure your document is @TeX{}ed correctly. It is @emph{very
+very} important.
+
+Let's try what @code{TVS} can do now. First try to run
+@example
+tvs sample.log
+@end example
+@noindent
+The most important for @code{TVS} is log file @code{sample.log}. You do not
+have to specify name with @code{.log} extension as it is tried to add
+automatically.
+What @code{TVS} now does? It goes through the file @code{sample.log}
+and finds
+all the files which are needed to build up the final document.
+
+@code{TVS} created an output directory named @code{TVS-OUT}. Check its
+contents. In fact, on M$-DOS or M$-Windows machines this didn't work.
+@footnote{Do not install Linux immediately, we will correct it in the
+next paragraph. @code{;-)}}
+On UN*X machines, there is stupidly deep directory structure containing
+only one directory in another.
+
+There is a way to avoid this.
+Please copy file @code{pathcuts.tvs} into the @code{examples} directory.
+Edit @code{pathcuts.tvs}, replace path @code{/usr/TeX/texmf} with the path
+to your @TeX{} main directory.
+
+Delete the @code{TVS-OUT} directory and run
+@example
+tvs -v -p pathcuts.tvs sample
+@end example
+@noindent
+See what @code{TVS} does now.
+You may also check what is in the @code{TVS-OUT} directory.
+By @code{-p file} we say that @code{file} contains paths we want to shorten.
+On M$ file system, there is in fact needed to use this to
+cut things like @code{c:\} to be able to construct file names used in the
+output directory.
+
+@node Ignoring files, Format file sources, Basic running @code{TVS}, Using @code{TVS} step by step
+@section Ignoring files
+
+As you can see, there is @code{sample.toc} in the output directory. We do
+not really need it as it can be always generated. Now let us show the way
+how to ignore files. Please copy file @code{ignpats.tvs} to the working
+directory. This file contains patterns which are compared to ends of
+files. Matching files are not copied to the output directory.
+
+If you want to try it, delete the output directory and run
+@example
+tvs -v -p pathcuts.tvs -i ignpats.tvs sample
+@end example
+@noindent
+Now files ending with @code{toc} are missing.
+
+@emph{Warning:} use this feature with care and only if you know what you
+are doing. Always make sure that files you want to ignore may be rebuilt up
+from the rest of the source.
+
+@node Format file sources, Configuration file, Ignoring files, Using @code{TVS} step by step
+@section Format file sources
+
+In fact, storing the complete document source may not be enough to be able
+to produce the same output. We must also store format source files. Storing
+only the format file itself doesn't help as this file is not
+binary compatible in general.
+
+The main thing you need is to know where log files of generated formats
+are stored. To obtain this information consult your local documentation, or
+you may try to find files @code{latex.log, tex.log, pdftex.log}, or ask
+your @TeX{} administrator. It is also possible that your administrator
+deleted log files after generating formats. In this case ask him to
+regenerate format files and leave the logs untouched.
+This is not a good manner to delete log files of this importance.
+Your administrator may have even delete format file sources. In this case,
+ask him to reinstall them and better find a new @TeX{} administrator.
+
+You should make sure that formats were really generated on your local
+installation. They may have been generated on a binary compatible
+machine with other organization of @TeX{} directories. If so, you must
+re-generate them. If you run a distribution which allows you to set
+local @TeX{} installation root directory, this is quite possible. For
+example, on my texlive-4 I had to correct this.
+
+In emergency, if you do not have root privilegies and you cannot
+globally make format logs correct, you still can generate formats in
+your own directory and use them overriding your system defaults.
+In this case, give your root my regards.
+
+To store format sources, you need to tell @code{TVS} where logs are.
+It is done by @code{-f path} switch. Let's try to call
+@example
+tvs -v -p pathcuts.tvs -f where_your_logs_are sample
+@end example
+@noindent
+You should obtain output directory similar to previous one but containing
+subdirectory named @code{FORMAT}, where complete source for format
+generating is stored.
+
+If @code{TVS} is not able to determine format name correctly, you may
+force format name by adding @code{--fmtname name} into command line
+similar to previous example. You may try
+@example
+tvs -v -p pathcuts.tvs -f where_your_logs_are --fmtname latex sample
+@end example
+
+@node Configuration file, Limitations of @code{TVS}, Format file sources, Using @code{TVS} step by step
+@section Configuration file
+
+The command lines we use are getting too long. If file @code{tvsrc} is
+located in the working directory, it is used as config file. You may
+also specify the config file explicitly by @code{-c filename} or
+@code{--config filename} switch.
+
+Please copy file @code{tvsrc} to the @code{examples} directory. Config file
+has simple structure
+@example
+<variable> <value>
+@end example
+Values set here may be always overridden by the command line. Setting
+values for ignore, pathcuts and format doesn't mean that files are
+ignored, paths cut and format sources stored by default. You must use
+switches @code{-i, -p} and @code{-f}, but there is no need to follow
+them by values.
+It may seem a bit strange but it is done this way in order to prevent
+you from doing something you do not want to. It doesn't save your
+keystrokes but---we hope---your nerves.
+
+If you edit the @code{format} entry in @code{tvsrc} to the path to your
+format logs, you may for example use
+@example
+tvs -i -p -f -v sample
+@end example
+@noindent
+to store the source with format with ignoring files and cutting paths
+instead of the long form without config file which goes
+@example
+tvs -i ignpats.tvs -p pathcuts.tvs -f /usr/TeX/texmf/web2c -v sample
+@end example
+
+But if you use only
+@example
+tvs -p sample
+@end example
+@noindent
+then no format file is examined and no files are ignored, no matter that
+the config file exists.
+
+In the config file you may also specify the default output
+directory name with
+@code{output} entry and the default verbosity level using
+@code{verbose} with value 0, 1, or 2. These values are used always
+and may be overridden with
+@code{-o} and @code{-v}.
+
+@node Limitations of @code{TVS}, Fonts, Configuration file, Using @code{TVS} step by step
+@section Limitations of @code{TVS}
+
+Work of @code{TVS} is limited by the files which are noticed in log files.
+If you use anything which is done by external program, you must take
+special care on files you want to store. If you include graphics in
+Post Script, it may be included only by @code{\special} command and may not
+be noticed in log.
+
+You must always ask yourself the main important question: @emph{Which
+files---not used in @TeX{} last run---I want to store?}
+
+For example if you use a bibliography, your source is a @code{.bib}
+file. But
+in the last @TeX{} run only sorted part of it, @code{.bbl} file is included.
+If the @code{.bbl} file is enough for you, it's good.
+But if you want to store
+sources for bibliography completely, you need also @code{.bib} file and
+@code{.bst} file, which contains bibliography style. And there is no way
+for @code{TVS} to know it as Bib@TeX{} is an external utility.
+That's why you must copy them to @code{TVS-OUT} by hand.
+
+If you don't do so, you are still able to obtain exactly the same document,
+but you run into difficulties trying to do any modifications.
+
+It is always better store more than you need. If you are a @TeX{} beginner
+and you are absolutely not
+sure, it may be reasonable for you to preserve all the files from your
+working directory. Includes from @TeX{} directory (e.g.,
+@code{c:\tex\texmf}) are handled correctly.
+
+@node Fonts, What to do with collected output, Limitations of @code{TVS}, Using @code{TVS} step by step
+@section Fonts
+
+This is experimental!
+
+Usually there is no reason to store also font source files. The exception
+is if your national modification of fonts changed its encoding or you use
+unusual fonts.
+
+If you want to,
+you may run @code{dvips} with @code{-d} switch to produce a log file with
+list of opened files.
+Consult your @code{dvips} documentation how to do it.
+This switch is followed by number indicating what should be logged.
+
+If you use @code{tvs -d dvips.log}, a subdirectory FONTS is created
+in the output
+directory and all files used by dvips are stored there.
+Only font bitmaps may
+be obtained this way, so this feature is not very useful. If you want to
+store Metafont sources, you must do it by hand.
+
+There is no guarantee of correct work of @code{-d} switch as @code{dvips}
+log changed.
+
+@node What to do with collected output, , Fonts, Using @code{TVS} step by step
+@section What to do with collected output
+
+Currently @code{TVS} implements no way of packing nor extracting collected
+complete source. Use any way of packing this directory you like depending
+of the platform you run @code{TVS} and the platform you will want to
+re-typeset your work in the future.
+
+There is no way to run TVS on the destination. You must only tell @TeX{}
+@itemize @bullet
+@item to generate the format file if format sources were stored,
+@item to generate fonts if fonts were stored,
+@item to find files in working directory and its subdirectories at first.
+@end itemize
+To do this, consult the local documentation.
+
+@c -----------------------------------------------------------------------
+@node Reference guide to @code{TVS} commands, Config file and pattern files, Using @code{TVS} step by step, Top
+@chapter Reference guide to @code{TVS} commands
+
+This chapter describes overall structure of @code{TVS} commands and
+describes the function of the commands in detail.
+
+@menu
+* Invoking @code{TVS}::
+* Global switches::
+* Ignoring files and cutting filenames::
+* Output directory setting::
+* Storing format source files and fonts::
+@end menu
+
+@node Invoking @code{TVS}, Global switches, Reference guide to @code{TVS} commands, Reference guide to @code{TVS} commands
+@section Invoking @code{TVS}
+
+General structure of calling @code{TVS} is
+@example
+tvs [switches] filename
+@end example
+@noindent
+where @code{filename} is a name of the main @TeX{} log file.
+@code{TVS} must be run in the directory where main @TeX{} log file is
+located.
+
+Always make sure
+that your document is @TeX{}-ed correctly (index is sorted, bibliography is
+present, pictures are included etc.)! Usually you have to run @TeX{}
+several times to typeset the document (but we hope this doesn't
+surprise you).
+
+@node Global switches, Ignoring files and cutting filenames, Invoking @code{TVS}, Reference guide to @code{TVS} commands
+@section Global switches
+
+These switches may be used to change globally behavior of @code{TVS}.
+
+@table @code
+
+@item -h, --help
+Prints short usage and version information and exits successfully.
+This switch doesn't need a filename as a parameter.
+
+@item -v, --verbose
+Sets verbosity level. May used several times. There are three verbosity
+levels:
+@itemize @bullet
+@item Level 0---only examined files and errors are written.
+This is the default.
+@item Level 1---found files, copying info and errors are written.
+@item Level 2---extra talkative, writes all it does.
+@end itemize
+For level 1, use @code{-v} or @code{--verbose} once, for level 2, use it
+twice. You may also specify @code{-vv}, which is the most comfortable way
+to do it.
+
+@item -c file, --config file
+Specifies the configuration file name. @xref{Config file}, for
+details about configuration file.
+
+If @code{--config} switch is not specified, file @code{tvsrc} in working
+directory is used as a config file if it exists. There is no need of having
+config file as all options may be set from command line.
+
+@item --dummy
+Sets @code{TVS} to dummy mode. No files are changed, no files are really
+copied to output directory, it is only shown what has to be done. Useful if
+used with @code{--verbose}. (Inspired by similar switch in cdrecord.)
+@end table
+
+@node Ignoring files and cutting filenames, Output directory setting, Global switches, Reference guide to @code{TVS} commands
+@section Ignoring files and cutting filenames
+
+Using following settings we may set files which shouldn't be copied to
+output and set usual paths we don't want to store completely.
+
+@table @code
+
+@item -i [file], --ignore [file]
+Sets file with patterns of filenames which we don't want to be copied to
+output. @xref{Ignore pattern file}, for details about ignore pattern file.
+
+If @code{file} name is omitted, value from config file is used. If
+@code{ignore} parameter is not set in config file, @code{TVS} terminates
+with an error.
+
+@item -p [file], --pathcuts [file]
+Sets file with path patterns to cut. @xref{Pathcuts pattern file},
+for information about file
+path names handling.
+
+If @code{file} name is not specified, value from config file is used. If
+@code{pathcuts} parameter in config file is not specified,
+@code{--pathcuts} parameter is silently ignored. It makes no harm to
+function of @code{TVS} and if it causes filename conflict, @code{TVS} stops
+with an error.
+@end table
+
+@node Output directory setting, Storing format source files and fonts, Ignoring files and cutting filenames, Reference guide to @code{TVS} commands
+@section Output directory setting
+
+@table @code
+
+@item -o dirname, --output dirname
+Sets the name of output directory to @code{dirname}. This may be only
+useful to override setting in config file. If config file doesn't set
+output directory name, default name @code{TVS-OUT} is used and this is
+created in working directory.
+@end table
+
+@node Storing format source files and fonts, , Output directory setting, Reference guide to @code{TVS} commands
+@section Storing format source files and fonts
+
+@table @code
+
+@item -f [dirname], --format [dirname]
+Specifies directory where format log files are and packs format file
+sources. If @code{dirname} is
+omitted, value from config file is taken. If @code{format} parameter is not
+specified in config file, @code{TVS} dies with an error. @xref{Format
+file sources}, for
+details about format source files extracting.
+Format file name is taken from the main document log from the first line
+which contains @code{format=name}.
+
+@item --fmtname [name]
+Specifies format name, e.g. @code{plain}, @code{latex}, etc. Useful, if
+format name cannot be found in log of document in form
+@code{format=name}.
+Specifying @code{--fmtname [name]} doesn't imply packing format sources.
+You must specify @code{--format}, too.
+This option cannot be specified in @code{TVS}'s
+config file.
+
+@item -d file, --dvips file
+Sets name of @code{dvips} log file. This cannot be specified in config
+file. This is only experimental. @xref{Fonts}, for information on dvips
+log file
+examining and font storing. You would better not to use this feature unless
+you know what you are doing.
+@end table
+
+@c --------------------------------------------------------------------
+@node Config file and pattern files, Credits, Reference guide to @code{TVS} commands, Top
+@chapter Config file and pattern files
+
+In this chapter we discuss config file setting and structure and usage of
+files with patterns. These are used to shorten (cut) filenames to use
+reasonable short paths in output directory and to set files which we do not
+want to store at all.
+
+@menu
+* Config file::
+* Pattern file structure::
+@end menu
+
+@node Config file, Pattern file structure, Config file and pattern files, Config file and pattern files
+@section Config file
+
+We may set values for @code{verbose, format, ignore, pathcuts,} and
+@code{output} variables in config file.
+
+If @code{TVS} is run with @code{--config} switch, it sets used config file
+name. If this is not used, default config file named @code{tvsrc} in
+working directory is tried.
+If it doesn't exist, no config file is used at all.
+There is no default config file location (e.g.
+@code{/etc/tvsrc} or something similar) because of the platform independence
+of @code{TVS}.
+
+The structure of config file is quite simple. Everything after @code{#} and
+@code{%} characters is ignored. Lines with structure
+@example
+<variable> <value>
+@end example
+@noindent
+set values of variables. There must be just one white character between
+the @code{<variable>} and the @code{<value>}. There may be any count of
+white spaces before and after this structure on the line. Lines with
+other structure or specifying variables not listed below are silently
+ignored.
+
+For example of config file, see file @code{tvsrc} enclosed with the
+distribution.
+
+Variables have meanings as follows:
+
+@table @code
+
+@item verbose
+Sets the default verbosity level. Reasonable values are
+@table @code
+@item 0
+This is the default.
+@item 1, 2
+Set verbosity level to 1 or 2. @xref{Global switches}, for description
+of verbosity levels.
+@end table
+
+@item format
+Sets the name of the directory where format log files are stored. This is
+used only of @code{--format} or @code{-f} switch is set and may be
+overridden by this. You should specify @code{format} parameter in config
+file if you want to store format sources. And you should store format
+sources. Simply---use it.
+
+@item ignore
+Sets the name of file with patterns used to ignore files. @xref{Ignore
+pattern file}, for
+information about ignoring files.
+This is used only if @code{--ignore} or @code{-i} switch is set and may be
+overridden by this.
+
+@item pathcuts
+Sets the name of file with patterns used to shorten the stored filenames.
+Used only if @code{--pathcuts} or @code{-p} switch is set and may be
+overridden by these.
+
+@item output
+Sets the default output directory name. May be overridden by @code{--output}
+or @code{-o} switch. If not set, default value @code{TVS-OUT} is used.
+@end table
+
+@node Pattern file structure, , Config file, Config file and pattern files
+@section Pattern file structure
+The structure of files which contain patterns is quite simple. Everything
+after @code{#} or @code{%} characters is ignored. A line of the file may
+start and end with white characters. These white characters are ignored.
+The remaining part of the line (if it is nonempty) is considered to be a
+pattern.
+
+A pattern is treated as a Perl regular expression.
+It doesn't matter if you don't know what it is, all you need to know is
+seen from the examples. Nevertheless you may try @code{man perlre} or
+equivalent for reading documentation on you system.
+
+Next, we'll discuss the usage of pattern files.
+
+@menu
+* Pathcuts pattern file::
+* Ignore pattern file::
+@end menu
+
+@node Pathcuts pattern file, Ignore pattern file, Pattern file structure, Pattern file structure
+@subsection Pathcuts pattern file
+
+This file is used if @code{--pathcuts} or @code{-p} switch is specified.
+An example is enclosed with the distribution and named @code{pathcuts.tvs}.
+
+The file specifies list of patterns which are compared to the
+@emph{beginnings} of
+filenames. On @emph{first match} the matching part is cut
+and the rest of pattern
+list is not used. So it has no sense to have a pattern list
+@example
+/usr/TeX
+/usr/TeX/texmf
+@end example
+@noindent
+as the second entry will be never used.
+But sequence
+@example
+/usr/TeX/texmf
+/usr/TeX
+@end example
+@noindent
+may be reasonable. (It's an exercise why and when @code{:-)}.)
+
+An example: Let us have pattern list containing @code{/usr/TeX/texmf}. If
+filename is
+@example /usr/TeX/texmf/tex/latex/algorith/algorithm.sty
+@end example
+@noindent
+it matches and is cut to
+@example
+tex/latex/algorith/algorithm.sty
+@end example
+@noindent
+File @code{inputs/my_macro.tex} doesn't match the pattern and is
+left untouched.
+
+@node Ignore pattern file, , Pathcuts pattern file, Pattern file structure
+@subsection Ignore pattern file
+
+This file is used when @code{--ignore} or @code{-i} switch is specified. An
+example named @code{ignpats.tvs} is enclosed.
+
+This file specifies list of patterns which are compared to @emph{ends}
+of filenames. If @emph{any} of them matches, file is ignored and is not
+copied to output. Usually, suffices of files (e.g. @code{toc, bbl}) are
+used here. If you want make sure that there is a dot before @code{toc}
+or @code{bbl}, use @code{\.toc} and @code{\.bbl} entries in pattern file
+as entries are PERL regular expressions. For detailed information see
+@code{perlre(1)}.
+
+Use this feature with care, it is usually better to have a superset of
+needed complete source then have @emph{incomplete} source. There may be
+files which loaded (and you don't know about them) with suffices you
+don't expect. Use it only if you know what you are doing. You've been
+warned.
+
+@node Credits, Dealing with bugs in @code{TVS}, Config file and pattern files, Top
+@appendix Credits
+
+I would like to thank to:
+@itemize @bullet
+@item
+Petr Sojka, who made me to write @code{TVS} and helped me very much with
+all the troubles and decisions we have had to make,
+@item
+Richard Bot@'{@dotless{i}}k, who lent me the
+``Perl Camel Book'' for a fortnight,
+@item
+many others,
+@item
+Bubo, my home computer, as it surprisingly didn't get overheated too much
+during the terribly hot spring of year 2000 in middle Europe.
+@end itemize
+
+@node Dealing with bugs in @code{TVS}, , Credits, Top
+@appendix Dealing with bugs in @code{TVS}
+
+Please send bug-reports to @email{xantos (at) fi.muni.cz} with subject
+@code{TVS bug}. Add information on platform, @TeX{} installation and
+include log files which were parsed. Also please note version of TVS,
+both version number and CVS version code (it's the line containing
+@code{$Id: tvs.pl,v...}). You can get this information by running
+@code{tvs --help}.
+
+If you tried to compare @code{.dvi} files obtained running @TeX{} on
+various platforms using @code{TVS} complete source, please keep in mind
+they may differ if something depending on ``the state of the computer''
+(especially date) was included.
+
+@contents
+@bye