summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/vpe/README
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/vpe/README')
-rw-r--r--macros/latex/contrib/vpe/README478
1 files changed, 478 insertions, 0 deletions
diff --git a/macros/latex/contrib/vpe/README b/macros/latex/contrib/vpe/README
new file mode 100644
index 0000000000..9ac6edf8fd
--- /dev/null
+++ b/macros/latex/contrib/vpe/README
@@ -0,0 +1,478 @@
+README for project vpe 2012/04/18 v0.2
+
+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
+F.3 (X)emacs
+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, 2012 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.
+README: 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 vpe.pl in a PERLLIB directory and copy the
+ exe program to `vpe.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
+
+F.3 (X)emacs
+------------
+This section is provided by Uwe Brauer.
+
+In order to use vpe with (X)emacs, you will need to set a
+client as the editor variable since otherwise for each
+call a separate (X)macs session would be started. There
+are two server/clients: gnuclient which is shipped with
+xemacs and emacsclient which is shipped with GNU emacs.
+The configuration for emacsclient is a little more
+delicate, that's why in the following only the
+configuration of gnuclient is discussed. Either install
+gnuclient for GNU emacs or, if you want to use emacsclient,
+read the following instuctions
+http://xdvi.sourceforge.net/inverse-search.html.
+
+* insert in your .emacs the line
+ (gnuserv-start)
+
+* set the variable VPE, either
+ setenv VPE 'gnuclient -q +%d %s'
+ in your .tcshrc file or
+ export VPE='gnuclient -q +%d %s'
+ in your .bashrc file
+
+* now if you want to avoid that a new window(frame) is
+ opened every time you call the gnuclient, insert
+ something like this in your .emacs file
+
+ (custom-set-variables
+ ;;; ... other stuff ...
+ '(gnuserv-frame t)
+ '(gnuserv-visit-hook (lambda () (raise-frame) (recenter))))
+
+* If you use AuCTeX, the following definitions come in handy:
+ Copy in your .emacs file
+
+ (custom-set-variables
+ '(TeX-command-list (quote (
+ ;; ..other stuff..
+ ("srcpdflatex" "pdflatex --shell-escape %t" TeX-run-command t "nil")
+ ("vpe" "vpe %g" TeX-run-command t nil))))
+ '(TeX-expand-list (quote (
+ ;; ..other stuff..
+ ("%g" file "pdf" t)))))
+
+ If you don't want to use %g for pdf files, use another letter
+ but make sure that it is not already in use.
+ Now you can call srcpdflatex for generating an appropriate pdf
+ file and the perl script vpe to insert the source specials.
+
+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: heiko.oberdiek at googlemail.com
+
+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 (2000):
+* 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
+2005/11/28 (X)emacs section from Uwe Brauer
+2012/04/18 v0.2:
+ * Option --version added.
+ * `vpe.txt' renamed to `README'.
+ * Email address updated.