readme.txt (2005/11/28) 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 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 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 `-*', 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' (place: a, default: ) 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@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 2005/11/28 (X)emacs section from Uwe Brauer