summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/oberdiek/vpe.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/oberdiek/vpe.txt')
-rw-r--r--Master/texmf-dist/doc/latex/oberdiek/vpe.txt421
1 files changed, 0 insertions, 421 deletions
diff --git a/Master/texmf-dist/doc/latex/oberdiek/vpe.txt b/Master/texmf-dist/doc/latex/oberdiek/vpe.txt
deleted file mode 100644
index 5182b326561..00000000000
--- a/Master/texmf-dist/doc/latex/oberdiek/vpe.txt
+++ /dev/null
@@ -1,421 +0,0 @@
-readme.txt for project vpe 2000/09/15 v0.1
-
-TABLE OF CONTENTS
-=================
-A. Project vpe
-B. Copyright, Disclaimer, Lizenz
-C. Files
-D. Requirements
-E. Installation
-F. Howto
-F.1 VTeX/Linux
-F.2 PdfTeX and dvips
-G. User interface
-G.1 Perl script
-G.2 Package
-H. Linux launch details
-I. Author
-J. Questions, bug reports
-K. History
-
-A. PROJECT VPE
-==============
-VPE deals with source specials for pdf files: clicking
-on special annotations will launch an editor with the
-source file at the source line.
-
-The project supports three routes to pdf files:
-
-* VTeX/Linux route:
- MicroPress' VTeX is able to insert specials by itself.
- It smoothly works under Windows. But the AcrobatReader
- versions under Linux/Unix require additional work, see
- section H "Linux launch details", that is done by the
- perl script `vpe.pl'.
-
-* pdfTeX route:
- For Han The Thanh's pdfTeX under Linux/Unix or Windows
- the package `vpe.sty' inserts the specials with the
- help of the perl script `vpe.pl'.
- The catalog entry `/AcroForm' is added, so that
- the `revert' menu entry of AR4.05 is enabled for
- easier reloading, if the pdf file has changed.
- Users of AR4.05 can also try option `form' of
- the package to get nicer source special markers,
- but the memory consumption is higher.
-
-* dvips route:
- As in the pdfTeX route package `vpe.sty' inserts the
- specials with the help of the perl script `vpe.pl'.
- Also the `/AcroForm' entry is added, but the
- `form' option is not implemented.
-
-B. COPYRIGHT, DISCLAIMER, LIZENZ
-================================
-Copyright (C) 1999, 2000 Heiko Oberdiek.
-
-This program may be distributed and/or modified under the
-conditions of the LaTeX Project Public License, either version 1.2
-of this license or (at your option) any later version.
-The latest version of this license is in
- http://www.latex-project.org/lppl.txt
-and version 1.2 or later is part of all distributions of LaTeX
-version 1999/12/01 or later.
-
-C. FILES
-========
-The project `vpe' consists of three files:
-
-vpe(.pl): Perl script, used by all routes. The extension `.pl'
- may be omitted for installation purposes.
-vpe.sty: LaTeX2e package for pdftex and dvips routes.
-vpe.txt: Documentation, the file you are reading.
-
-Help and temporary files, generated by use:
-myfile.tex.vpe: Symbol link from source file `myfile.tex'
- to the perl script, required for the source
- specials launch actions in the pdf file.
- Each source file need a link.
-myfile.vpe: Temporary file for data exchange between
- TeX and the perl script called by \write18{}.
-vpe.cfg: Configuration file of package `vpe.sty'.
-
-D. REQUIREMENTS
-===============
-All routes:
-* Perl5 (version 5 of the perl interpreter).
-
-pdfTeX, dvips routes:
-* \write18 feature (--shell-escape)
-* LaTeX2e
-
-pdfTeX route:
-* pdfTeX >= v0.14
-
-E. INSTALLATION
-===============
-1. TeX directory structure (TDS):
- The files
- `vpe.txt' (documentation)
- `vpe.sty' (pdf(e)tex, pdf(e)latex, (e)tex, (e)latex)
- go to
- texmf/doc/latex/oberdiek/vpe.txt
- texmf/tex/latex/oberdiek/vpe.sty
-
-2. Perl script `vpe.pl':
-
- Unix
- * Your are allowed to rename `vpe.pl' to `vpe':
- mv vpe.pl vpe
- * Ensure that the execute permission is set:
- chmod +x vpe
- * Move the file to a directory where the shell can find it
- (environment variable PATH, e.g. /usr/local/bin/).
- * The environment variables TEXEDIT and VPE are
- looked for the editor call, eg:
- export VPE='xterm -e joe +%d %s' (bash)
- %d will be replaced by the line number and
- %s by the file name.
-
- Windows (Dos)
- * Methods for calling by typing the script name without extension
- and perl interpreter:
- a) If your perl distribution provides a pl2exe program,
- use it to generate `vpe.exe'.
- Advantage: I/O redirection works.
- b) A good method is a dos program of John Dallman:
- #!perl.exe (versions below 4)
- hbperl.exe (version 4)
- http://www.perl.com/CPAN/authors/id/JDALLMAN/hbp_403.zip
- Move thumbpdf.pl in a PERLLIB directory and copy the
- exe program to `thumbpdf.exe'. Then the program looks
- for the perl interpreter, the script and calls them.
- Advantage: I/O redirection works.
- c) Windows NT 4.0 users can use associated file types:
- SET PATHEXT=.pl;%PATHEXT%
- See perl win32 faq "How do I associate Perl scripts with perl?":
- http://www.activestate.com/support/faqs/win32/perlwin32faq4.html
- Disadvantage: I/O redirection does not work.
- d) 4DOS: SET .PL=c:/bin/perl.exe
- See perl win32 faq "How can I get Perl to run a Perl script at
- the 4DOS command line by typing the name of the script without
- the extension or "perl", just like a regular exe file?":
- http://www.activestate.com/support/faqs/win32/perlwin32faq1.html
- e) Convert the perl script to a batch file `vpe.bat', if your
- distribution provides `pl2bat.bat'.
- Disadvantage: I/O redirection does not work.
- Many of this methods are listed in the perl win32 faq
- "What's the equivalent of the shebang ("#!") syntax for Win32?":
- http://www.activestate.com/support/faqs/win32/perlwin32faq4.html
- * Running the perl interpreter directly with the perl script:
- perl vpe.pl ...
- Use this method only, if the other methods fail.
- Then you have to configure the command name in the
- configuration file `vpe.cfg':
- \vpesetup{command={perl vpe.pl}}
- * The editor application and the syntax of the paramters
- for the editor can be configured by \vpesetup in
- the configuration file `vpe.cfg':
- \vpesetup{application={pfe.exe},parameters={-g $d $s}}
- $d will be replaced by the line number,
- $s by the file name.
-
-F. HOWTO
-========
-
-F.1 VTeX/Linux
---------------
-Do not use the package `vpe.sty', the VTeX/Linux route
-is only based on the perl script.
-
-a) Enable VTeX's source special generation with option `-*<num>',
- eg: -*20
-b) Run the perl script on the generated pdf file. It
- fixes the launch actions and creates the necessary symbol
- links (See section H "Linux launch details"):
- vpe myfile.pdf
-
-F.2 PdfTeX and dvips
---------------------
-a) Load the package `vpe.sty', eg:
- \usepackage{vpe}
-b) Produce the pdf file, but with enabled \write18{} feature
- for system commands. This can be achieved by setting the
- command line option `--shell-escape' for pdfTeX or TeX.
- An alternative is the boolean variable `shell_escape'
- in the configuration file `texmf.cnf'. For security
- reasons I recommend the command line option.
-c) Only Linux: After the first call it is possible that
- the symbol links are not created yet (depends on write
- puffer effects). Then it can be done by envoking the
- perl script manually:
- vpe myfile.pdf
-
-G. USER INTERFACE
-=================
-
-G.1 Perl script
----------------
-General options:
---help: print help and usage screen.
---verbose: print additional informations.
-
-Options that influence the symbol links:
---force: force symbol links (`ln -f' is called).
---delete: remove the symbol links for the source files,
- mentioned in the pdf file:
- vpe --delete myfile.pdf
-
-Internal options, called by the package `vpe.sty':
---system: detects the system (linux or win) and writes
- the information in the data exchange file:
- vpe --system myfile.vpe
---sty: generates the absolute file name of the
- source file `file.tex', get the maximum
- line number and writes the informations
- in the data exchange file `myfile.vpe':
- vpe --sty file.tex myfile.vpe
---progname: this option sets the program name option
- of `kpsewhich', called by the --sty option:
- vpe --sty --progname=pdfelatex file.tex myfile.vpe
-
-G.2 Package
------------
-There are three places, where the options can be specified
-in evaluation order:
-a) Configuration file `vpe.cfg` with \vpesetup.
-b) LaTeX package options: local in \usepackage or
- global in \documentclass.
-c) Some options can be set by \vpesetup after the
- package is loaded.
-
-`active', `inactive' (place: abc, default: active)
- Enables/disables insertion of source specials
-
-`debug' (place: a, default: off)
- Verbose messages for debugging purposes.
-
-`dupes', `nodupes' (place: abc, default: dupes)
- Option `nodupes' suppresses source specials that point
- to the same file and line.
-
-`linux', `unix', `win', `dos' (place: ab, default: automatic)
-`system=linux|win' (place b)
- The format of the launch action differs in the win and unix
- case. Therefore the packages has to know, which kind it
- should generate. If none of the options is given, then
- the packages calls the perl script with option `--system'
- to get the information.
- (Recommendation: set in `vpe.cfg' to save time.)
-
-`form', `noform' (place: ab, default: noform)
- Users of AR4.05 can try this option to get nicer
- source special marks. Only the pdfTeX route is
- supported currently.
-
-`acroform', `noacroform' (place: ab, default: acroform)
- With forms AR4.05 enables the `revert' menu entry,
- so that changed files can more easily be reloaded.
- If option `form' is used, the /AcroForm dictionary
- can be suppressed with `noacroform', when another
- /AcroForm is already provided.
-
-`command=...' (place: bc, default: vpe)
- Call of the perl script for the \write18{} feature.
-
-`progname=...' (place: bc, default: automatic)
- TeX cannot provide absolute path names of files,
- therefore the package calls the perl script to ask
- `kpsewhich'. This program needs the program/format
- name in order to select the correct search path
- variables. Automatically the package is able to
- distinguish between `latex', `elatex', `pdflatex'
- and `pdfelatex'. For other names this option has
- to be set.
-
-`application=...' (place: bc, default: pfe.exe)
-`parameters=...' (place: bc, default: `-g $d $s')
- These options configure the editor call for windows:
- `application' contains the call of the editor,
- `parameters' the parameters for the editor.
- $d will be replaced by the line number and
- $s by the file name.
-
-`width', `height', `depth', `color', `border',
-`flag', `attr' (place: bc, default: see vpe.sty)
- With these options the launch annotation
- can be configured (`noform' version).
- Because of the beta status of the options,
- they can change in future, for details see
- the package source.
-
-`everyhbox', `noeveryhbox' (place: ab, default: noeveryhbox)
- By this option a lot of source specials are inserted,
- but there is a high risk to get a lot of "Underfull
- \hbox" warnings.
-
-`no<feature>' (place: a, default: <feature>)
- For the introduction of source specials many
- internal commands are redefined. This can cause
- problems with incompatible packages and macros.
- The redefinitions that cause problems can be
- disabled. Current list of features:
- input, @input, include,
- newpage, clearpage,
- everypar, document, @item, @doendpe,
- @arrayparboxrestore, @xsect, @afterheading,
- @setminipage, @startsection,
- everymath, everyhbox,
- newline, mbox, TILDE,
- ref, cite,
- item, trivlist, endtrivlist,
- @bsphack, @esphack, @Esphack, @xaddvskip,
- @tabularcr, @arraycr,
- hrule, vrule
-
-H. LINUX LAUNCH DETAILS
-=======================
-It is quite easy to launch a program with parameters
-with a link annotation under Windows, because
-AcrobatReader knows a /Win dictionary, eg:
- << /Type Annot
- /Subtype /Link
- /Rect [100 700 120 720]
- /A << /Type /Action
- /S /Launch
- /Win << /F (pfe.exe)
- /P (-g 21 c:/myhome/myfile.tex)
- >>
- >>
- >>
-A corresponding /Unix dictionary is not yet defined
-in the pdf specification and not implemented in AR.
-Therefore only the file name can be used to store
-the parameter informations, eg:
- /A << /Type /Action
- /S /Launch
- /F (//.////../myhome/myfile.tex.vpe)
- >>
-
-The file that will be launched is a symbol link
-to the script `vpe(.pl)', eg:
- ln -s /usr/local/bin/vpe /myhome/myfile.tex.vpe
-
-The script scans its calling name, the name of the
-symbol link, to extract the parameters for the
-editor call:
-* The initial part encodes the line number,
-* the rest without the extension `.vpe' is the
- file name.
-* Condition: The path names are absolute path names.
-
-The coding algorithm for the line number:
-* The decimal digits of the number are separated
- and ended by the sequence "./".
-* Each decimal digit of the number is converted
- to a sequence of slashes, optionally followed
- by a period. The count of slashes is the
- number. With the period, the count have to be
- incremented by 5.
-* The conversion of the first digit always starts
- with a slash to ensure a absolute path names,
- eg: "5" is converted to "/////", but not as
- first digit it can be shrunk to ".".
-Examples (spaces only for clarifying):
- 2: // ./
- 6: /. ./
- 9: ////. ./
- 11: / ./ / ./
- 28: // ./ ///. ./ (see example above)
- 505: ///// ./ ./ . ./
-
-I. AUTHOR
-=========
-Heiko Oberdiek
-Email: oberdiek@ruf.uni-freiburg.de
-
-J. QUESTIONS, BUG REPORTS
-=========================
-If you have questions, problems with `vpe', error reports,
-if you have improvements or want to have additional features,
-please send them to the author.
-
-Because I do not have to much time, I cannot garantee
-that I will fix all problems and add all suggested features.
-
-Regarding bug reports I have some wishes:
-* Please only send a minimal test file.
- I do not have the time to check hundreds of lines
- and pages.
- Strip the minimal file off all unnecessary packages,
- macros, and stuff.
- But the minimal file should be complete, so that I can
- immediately call latex on it.
-* Please no .log, .dvi, .ps, .pdf files.
- I have a lot of TeX and related programs installed
- and can generate them in the most cases.
-* Please get all versions numbers of packages and
- programs (examples see below). Only the
- distribution version does not help, so I do not
- have MikTeX installed and I am using a very old
- teTeX and even emTeX, but almost always the latest
- pdfTeX binaries. Therefore the pdfTeX version is
- much more important.
- Hints:
- * With "\listfiles" LaTeX prints the versions of the
- used files at the end of the .log file.
- * Many programs know options like:
- --version, -v, -help, -h, -?
-
-My environment for developing and testing:
-* linux, debian 2.0
-* perl 5.004_04
-* VTeX/Linux: 7.06
-* pdfTeX: 0.14g-pretest-20000912
-* TeX: 3.14159, Web2C 7.2
-* dvips 5.78
-* Ghostscript 6.01
-
-K. HISTORY
-==========
-2000/09/15 v0.1 first release