diff options
Diffstat (limited to 'support/TVS/TVS/docs/tvs.texi')
-rw-r--r-- | support/TVS/TVS/docs/tvs.texi | 913 |
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 |