Directory macros/latex/contrib/vpe

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.