Index of /archives/text/CTAN/macros/latex/contrib/vpe
Name Last modified Size Description
![[PARENTDIR]](/icons/back.gif)
Parent Directory -
![[TXT]](/icons/text.gif)
vpe.sty 2012-04-18 09:30 19K
vpe.pl 2012-04-18 09:30 9.5K
README 2012-04-18 09:41 16K
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.