diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/oberdiek')
| -rw-r--r-- | Master/texmf-dist/doc/latex/oberdiek/alphalph.pdf | bin | 0 -> 365369 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/latex/oberdiek/holtxdoc.zip | bin | 0 -> 12850 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/latex/oberdiek/hypbmsec.pdf | bin | 0 -> 331597 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/latex/oberdiek/hypcap.pdf | bin | 0 -> 207393 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/latex/oberdiek/pagesel.pdf | bin | 0 -> 344174 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/latex/oberdiek/readme.txt | 287 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/oberdiek/twoopt.pdf | bin | 0 -> 288035 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/latex/oberdiek/vpe.pl | 421 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/oberdiek/vpe.txt | 421 |
9 files changed, 1129 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/oberdiek/alphalph.pdf b/Master/texmf-dist/doc/latex/oberdiek/alphalph.pdf Binary files differnew file mode 100644 index 00000000000..01e8f918f41 --- /dev/null +++ b/Master/texmf-dist/doc/latex/oberdiek/alphalph.pdf diff --git a/Master/texmf-dist/doc/latex/oberdiek/holtxdoc.zip b/Master/texmf-dist/doc/latex/oberdiek/holtxdoc.zip Binary files differnew file mode 100644 index 00000000000..475af92d738 --- /dev/null +++ b/Master/texmf-dist/doc/latex/oberdiek/holtxdoc.zip diff --git a/Master/texmf-dist/doc/latex/oberdiek/hypbmsec.pdf b/Master/texmf-dist/doc/latex/oberdiek/hypbmsec.pdf Binary files differnew file mode 100644 index 00000000000..7eb38d0b61a --- /dev/null +++ b/Master/texmf-dist/doc/latex/oberdiek/hypbmsec.pdf diff --git a/Master/texmf-dist/doc/latex/oberdiek/hypcap.pdf b/Master/texmf-dist/doc/latex/oberdiek/hypcap.pdf Binary files differnew file mode 100644 index 00000000000..e6beaf023da --- /dev/null +++ b/Master/texmf-dist/doc/latex/oberdiek/hypcap.pdf diff --git a/Master/texmf-dist/doc/latex/oberdiek/pagesel.pdf b/Master/texmf-dist/doc/latex/oberdiek/pagesel.pdf Binary files differnew file mode 100644 index 00000000000..bdb3b3f112b --- /dev/null +++ b/Master/texmf-dist/doc/latex/oberdiek/pagesel.pdf diff --git a/Master/texmf-dist/doc/latex/oberdiek/readme.txt b/Master/texmf-dist/doc/latex/oberdiek/readme.txt new file mode 100644 index 00000000000..784ac519469 --- /dev/null +++ b/Master/texmf-dist/doc/latex/oberdiek/readme.txt @@ -0,0 +1,287 @@ +readme.txt 2001/08/27 + +This file describes the files in directory + CTAN:macros/latex/contrib/supported/oberdiek/ +It contains five packages in dtx format: + +* hypbmsec 1999/04/12 v2.0 Bookmarks in sectioning commands. +* pagesel 1999/04/13 v1.1 Selecting shipout pages. +* alphalph 1999/04/13 v1.1 Converting numbers to letters. +* twoopt 1999/04/12 v1.3 Definitions with two optional arguments. +* hypcap 2001/08/27 v1.3 Adjusting anchors of captions. + +and ten packages as single files: +* pdfcolmk.sty 2000/09/06 v0.5 PDFtex COLor MarK. +* dvipscol.sty 2000/08/31 v1.0 Fix for dvips.def. +* engord.sty 2000/05/23 v1.0 English ordinal numbers. +* refcount.sty 2000/09/07 v2.0 Converting references to numbers. +* settobox.sty 2000/09/07 v1.1 Getting box sizes. +* epstopdf.sty 2001/02/04 v1.1 Conversion with epstopdf on the fly. +* pdflscape.sty 2001/02/04 v0.2 Landscape pages in PDF. +* ifpdf.sty 2001/07/14 v1.1 Providing \ifpdf. +* chemarr.sty 2001/06/22 v1.1 Chemical reaction arrows. +* pdfcrypt.sty 2001/08/09 v0.6 Setting pdf encryption. + +COPYRIGHT, DISCLAIMER, LICENSE +============================== + +Copyright (C) 1999-2001 Heiko Oberdiek. + +The files listed below 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. + +FILES +===== +readme.txt: this file. + +hypbmsec.dtx: docstrip archive and documentation source. +hypbmsec.ins: docstrip installation script. +hypbmsec.pdf: documentation. + +pagesel.dtx: docstrip archive and documentation source. +pagesel.ins: docstrip installation script. +pagesel.pdf: documentation. + +alphalph.dtx: docstrip archive and documentation source. +alphalph.ins: docstrip installation script. +alphalph.sty: package file (for TeX users without docstrip). +alphalph.pdf: documentation. + +twoopt.dtx: docstrip archive and documentation source. +twoopt.ins: docstrip installation script. +twoopt.pdf: documentation. + +hypcap.dtx: docstrip archive and documentation source. +hypcap.ins: docstrip installation script. +hypcap.pdf: documentation. + +holtxdoc.zip: archive with files for generating the documentation: + * holtxdoc.sty: * common macros for all dtx files + * hyperref support + * patches, bug fixes + * hothread.sty * writes thread informations into the log file. + * hothread.pl * perl script that reads the thread informations + and updates the pdf file, it is a workaround + for bugs in pdfTeX (tested with 0.13b). +!!! Caution !!! + * These files are very out of date and I intend + to update these files in future. + * For hypcap.dtx a newer version of holtxdoc.sty is + needed, but it is not yes released by me. +!!! Caution !!! + +And the LaTeX packages, documentation is directly available +in the files: + * pdfcolmk.sty + * dvipscol.sty + * engord.sty + * refcount.sty + * settobox.sty + * epstopdf.sty + * pdflscape.sty + * ifpdf.sty + * chemarr.sty + * pdfcrypt.sty + +REQUIREMENTS +============ +All packages are LaTeX2e packages. +alphalph can be used by plain-TeX, too. + +SHORT USER INTERFACE +==================== +For a longer description see the pdf files or +the package files themselves. + +* With package `hypbmsec' bookmark entries can be given in another + argument of the sectioning commands, e.g.: + out = outline string, toc = string in table of contents + \section{toc, out, txt} + \section[toc, out]{txt} + \section[toc][out]{txt} + \section[toc](out){txt} + \section(out)[toc]{txt} + \section(out){toc, txt} + hyperref is required to get the bookmarks, but the syntax work + without hyperref, too. + +* Package `pagesel' selects single pages, page areas, odd, or + even pages for output. + +* Package `alphalph' provides the new expandable commands \alphalph + \AlphAlph. They are like \number, but the expansion consists of + lowercase and uppercase letters respectively: + 1..26 = a..z + 27..52 = aa..az + 53..78 = ba..bz + 702,703 = zz, aaa + So the commands can be used as an replacement for LaTeX's \@alph + and \@Alph macros. + +* Package `twoopt' provides commands to define macros with two + optional arguments: + \newcommandtwoopt{\Cmd}[3][DefaultA][DefaultB]{Args: #1, #2, #3} + \renewcommandtwoopt, \providecommandtwoopt + +* Package `hypcap' tries a solution for a problem of package + `hyperref' with figures: The anchor for the figure caption + is made in the caption itself. Therefore a link will point to + the caption, but not to the start of the figure environment. + Now `hypcap' provides a command \capstart that sets the + anchor for the next \caption and redefines \caption, so that + \caption uses the previous anchor. If all figure environments + contain one \caption, then this can be automated by redefining + the figure environment to execute \capstart every time at the + beginning of the environment. Also table environments and + the star forms are supported. + See hypcap.pdf for further documentation and use. + +* Package `pdfcolmk' tries to fix color problems of pdfTeX + at page breaks because of a missing color stack. + Use: \usepackage{pdfcolmk} after \usepackage[pdftex]{color} + See package file for further documentation. + +* Package `dvipscol' tries to fix color stack overflows by + `dvips' (e-TeX recommended). + Use with e-TeX: \usepackage{dvipscol} + Use without e-TeX: \usepackage{dvipscol} and all toplevel + \color commands should be replaced by \nogroupcolor. + See package file for further documentation. + +* Package `engord' converts numbers to English ordinal + numbers. + Use: \engord{<LaTeX counter>} + \engordnumber{<any TeX number>} + See package file for further documentation and use. + +* Package `refcount' extracts the numbers from references. + The implementation is more safe than the direct use + of references as numbers, because they works with packages + such as `hyperref' that adds additional stuff to the + references. + Use: Commands similar to \setcounter and \addtocounter: + \setcounterref, \addtocounterref, + \setcounterpageref, \addtocounterpageref + Arguments: {<LaTeX counter>}{<reference>} + For expandable contexts: + \getrefnumber, \getpagerefnumber + Argument: {<reference>} + See package file for further documentation and use. + +* Package `settobox' defines commands similar to + LaTeX's \settowidth commands: + \settoboxwidth, \settoboxheight, + \settoboxdepth, \settoboxtotalheight + Arguments: {<LaTeX length>}{<LaTeX box name>} + See package file for further documentation and use. + +* Package `epstopdf' adds support of handling eps images + to package graphic{s,x} with option `pdftex'. + If an eps image is detected, `epstopdf' is automatically + called to convert it to pdf format. + To get the call of `epstopdf' work, the feature `\write18' + has to be enabled, for example by command line option: + pdflatex -shell-escape test.tex + See package file for further documentation and use. + +* Package `pdflscape' adds PDF support to the + environment `landscape' of package `lscape' + by setting the page attribute `/Rotate'. + Both the pdfTeX route and the dvips method + are supported. + Use: Load this package instead of `lscape': + \usepackage{pdflscape} + \begin{landscape}...\end{landscape} + See package file for further documentation and use. + +* Package `ifpdf' looks for pdfTeX in pdf mode and implements + and sets the switch \ifpdf. The detection is based on + \pdfoutput and the package will not change this value. + It works with plain or LaTeX formats. + Use: LaTeX: \usepackage{ifpdf} + plain: \input ifpdf.sty + The package provides the switch \ifpdf: + \ifpdf + ... do things, if pdfTeX is running in pdf mode ... + \else + ... other TeX or pdfTeX in dvi mode ... + \fi + See package file for further documentation and use. + +* Package `chemarr': Very often chemists need a longer + version of reaction arrows (\rightleftharpoons) with + the possibility to put text above and below. Analogous + to amsmath's \xrightarrow and \xleftarrow this package + provides the macro \xrightleftharpoons. + Requirements: amsmath + Use: \usepackage{chemarr} + \xrightleftharpoons[below]{above} + See package file for further documentation and use. + +* Package `pdfcrypt' allows the setting of pdf encryption + options for + * pdfTeX, patched by Ricardo Sanchez Carmenes, or + * VTeX, version 7.35. + Use: The options can be set as package options or + in the command \pdfcryptsetup: + owner=OwnerPassword + user=UserPassword + print, copy, edit, annotate=true, false + all, none + The encryption is set at \begin{document} by default, + but this can be forced for an earlier time by option `set'. + Example: + \usepackage[owner=Donald,user=Knuth,print=false]{pdfcrypt} + See package file for further documentation and use. + +INSTALLATION +============ +For the packages in docstrip format run: + tex oberdiek.ins +or for a single docstrip package run: + tex <package>.ins + +Generating the documentation: + + 1. latex <package>.dtx + 2. makeindex -rs <package> + 3. latex <package>.dtx + 4. makeindex -rs <package> + 5. latex <package>.dtx +Remarks: +* alphalph needs another cycle of latex/makeindex. +* holtxdoc.sty of holtxdoc.zip is needed (see above). +* For hyperlink support hyperref is required. For other than the + default drivers use an appropriate hyperref.cfg file. +* pdfTeX users: + * Thumbnail support is added by package thumbpdf: + CTAN:macros/pdftex/thumbpdf/ + 6. thumbpdf <package> + 7. latex <package> + * For correct article threads hothread.sty and hothread.pl + (holtxdoc.zip) are needed to correct bugs in pdfTeX: + 8. hothread <package> + +CAUTION: I am sorry, that I did not yet found the time + for updating the files that are necessary + to produce the documentation. + +AUTHOR +====== +Heiko Oberdiek +Email: oberdiek@ruf.uni-freiburg.de + +QUESTIONS, SUGGESTED IMPROVEMENTS +================================= + +If you have questions, problems, error reports, +improvements, or want to have additional features, +please send them to the author. + +Happy TeXing diff --git a/Master/texmf-dist/doc/latex/oberdiek/twoopt.pdf b/Master/texmf-dist/doc/latex/oberdiek/twoopt.pdf Binary files differnew file mode 100644 index 00000000000..10495938cd7 --- /dev/null +++ b/Master/texmf-dist/doc/latex/oberdiek/twoopt.pdf diff --git a/Master/texmf-dist/doc/latex/oberdiek/vpe.pl b/Master/texmf-dist/doc/latex/oberdiek/vpe.pl new file mode 100644 index 00000000000..9eb52b69e3c --- /dev/null +++ b/Master/texmf-dist/doc/latex/oberdiek/vpe.pl @@ -0,0 +1,421 @@ +eval '(exit $?0)' && eval 'exec perl -S $0 ${1+"$@"}' && eval 'exec perl -S $0 $argv:q' + if 0; +use strict; +# +# vpe.pl +# +# Copyright (C) 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. +# +# See file "vpe.txt" for a list of files that belong to this project. +# +# This file "vpe.pl" may be renamed to "vpe" +# for installation purposes. +# +my $file = "vpe.pl"; +my $program = uc($&) if $file =~ /^\w+/; +my $version = "0.1"; +my $date = "2000/09/15"; +my $author = "Heiko Oberdiek"; +my $copyright = "Copyright (c) 2000 by $author."; +# +# History: +# 2000/09/15 v0.1: First release. +# + +### program identification +my $title = "$program $version, $date - $copyright\n"; + +### editor call +# %F: file name +# %L: line number +my $EditorCall = "xterm -e joe +%d %s"; +$EditorCall = $ENV{TEXEDIT} if $ENV{TEXEDIT}; +$EditorCall = $ENV{VPE} if $ENV{VPE}; + +### error strings +my $Error = "!!! Error:"; # error prefix + +my $usage = <<"END_OF_USAGE"; +${title} +Depending on the name of the script `vpe' works in four modes: + +* [vpe] Syntax: vpe <pdf file>[.pdf] + The pdf file is scanned for actions created by VTeX, + that start an editor with the source file at the + specified line under Windows. + A symbol link is made from the source file name + extended by the extension `.vpe' to this script. + The line number is encoded in the path and the + action is changed to start this script. + +* [sty] Internal for vpe.sty: + Syntax: vpe --sty [--progname=...] <latex file> <vpe file> + +* [system] Internal for vpe.sty: + Syntax: vpe --system <vpe file> + +* [launch] Syntax: <source file name>.vpe + The script decodes the line number in the path of + the source file name and starts an editor with + this file at that line number. + +Options: + --help: print usage. + --verbose: print additional informations during running. + --force: force symbol links + --delete: delete symbol links + --sty: internal for `vpe.sty' (get absolute file name and lines) + --system: internal for `vpe.sty' (get system info linux or win) + --progname: latex, pdflatex, elatex, pdfelatex +END_OF_USAGE + +### options +$::opt_verbose = 0; +$::opt_help = 0; +$::opt_force = 0; +$::opt_delete = 0; +$::opt_sty = 0; +$::opt_system = 0; +$::opt_progname = "latex"; +use Getopt::Long; +GetOptions( + "help!", + "verbose!", + "force!", + "delete!", + "sty!", + "system!", + "progname=s", +) or die $usage; +if ($::opt_help) { + die $usage; +} + +if ($::opt_sty and $::opt_system) { + die "$usage" . + "$Error Options --sty and --system cannot used together!\n"; +} + +################### +### launch mode ### +################### +if ($0 =~ /\.vpe/) { + + @ARGV == 0 or + die "$usage$Error Too many arguments [launch mode]!\n"; + + my $file = ""; + $0 =~ m|(^[\./]+\./)(.+)\.vpe$| or + die "$Error Cannot extract line number ($0)!\n"; + my $str = $1; + $file = "/$2"; + + my $line = ""; + while ($str ne "") { + $str =~ m|^(/*)(\.?)\./(.*)$| or + die "$Error Parse error!\n"; + $line .= length($1) + (($2 eq ".") ? 5 : 0); + $str = $3; + } + + my $callstr = $EditorCall; + $EditorCall =~ s/%s/$file/; + $EditorCall =~ s/%d/$line/; + print "File: $file, line: $line\n" if $::opt_verbose; + exec($EditorCall); + exit 1; +} + +### +### used by both sty and system mode: +### +my $system = "linux"; +$system = "" if $^O =~ /os2/i; +$system = "" if $^O =~ /mac/i; +$system = "win" if $^O =~ /dos/i; +$system = "win" if $^O =~ /win/i; + +################ +### sty mode ### +################ +if ($::opt_sty) { + + @ARGV == 2 or + die "$usage$Error Wrong arguments [sty mode]!\n"; + + my $vpefile = $ARGV[1]; + print "VPE file: $vpefile\n" if $::opt_verbose; + + my $file = `kpsewhich -progname=$::opt_progname $ARGV[0]`; + chomp $file; + if (!($file =~ m|^/| or $file =~ m|^\w:|)) { + use Cwd; + $file = cwd() . "/" . $file; + $file =~ s|/[^/]+/\.\./|/|g; + $file =~ s|/\./|/|g; + } + -f $file or + die "$Error Cannot find file `$file' [sty mode]!\n"; + print "File: $file\n" if $::opt_verbose; + + my $last = 0; + if (open(IN, $file)) { + while (<IN>) { + $last++; + } + } + if ($last == 0) { + $last = 10000; + } + print "Last line: $last\n" if $::opt_verbose; + + open(OUT, ">>$vpefile") or + die "$Error Cannot open file `$vpefile`!\n"; + print OUT "\\vpeentry{$file}{$last}\n"; + + exit 1; +} + +################### +### system mode ### +################### +if ($::opt_system) { + + @ARGV == 1 or + die "$usage$Error Wrong arguments [system mode]!\n"; + + my $vpefile = $ARGV[0]; + print "VPE file: $vpefile\n" if $::opt_verbose; + + open(OUT, ">>$vpefile") or + die "$Error Cannot open file `$vpefile`!\n"; + print OUT "\\vpesystem{$system}\n"; + + exit 1; +} + +################ +### vpe mode ### +################ +if (@ARGV < 1) { + die "$usage$Error Missing pdf file [vpe mode]!\n"; +} +if (@ARGV > 2) { + die "$usage$Error Too many arguments [vpe mode]!\n"; +} + +my $pdffile = $ARGV[0]; +if (!-f $pdffile) { + my $name = $pdffile; + $pdffile .= ".pdf"; + -f $pdffile or + die "$Error File `$name' not found [vpe mode]!\n"; +} + +open(IN, "+<$pdffile") or + die "$Error Cannot open `$pdffile' [vpe mode]!\n"; +binmode(IN); +my %symlinks = (); +while (<IN>) { + + if (m|/F\([\./]*(/.*)\.vpe\)|) { + $symlinks{$1} = 1; + next; + } + + my $do = 0; + my ($action, $file, $line, $type); + # my $color; # only for debugging + + if (m|^ + /A \s* << \s* + /Type \s* /Action \s* + /S \s* /Launch \s* + /Win \s* << \s* + /F \s* \(aftcomp.exe\) \s* + /P \s* \("(.*)\" \s+ \d+\-(\d+)\) \s* + >> \s* + >> \s* + $ + |x + ) { + $action = $_; + $file = $1; + $line = $2; + # $color = "/C[0 0 1]"; # only for debugging + $type = "aftcomp"; + $do = 1; + } + + if (m|^ + /A \s* << \s* + /Type \s* /Action \s* + /S \s* /Launch \s* + /Win \s* << \s* + /F \s* \(repos.exe\) \s* + /P \s* \( + "(.*)" \s* + "(\d+)" \s* + "(.*)" \s* + "(\d+)" + \) \s* + >> \s* + >> \s* + $ + |x + ) { + $action = $_; + if ($3 eq "") { + $file = $1; + $line = $2; + } + else { + # ??? + $file = $1; + $line = $2; + } + # $color = "/C[1 0 0]"; # only for debugging + $type = "repos"; + $do = 1; + } + + if ($do) { + my $length = length($action); + print "* File: $file, line: $line, type: $type\n" if $::opt_verbose; + + if (!($file =~ m|^/|)) { + print STDERR "$Error File `$file' lacks of absolute path!\n"; + next; + } + + if (!$::opt_delete) { + if ($line <= 0) { + $line = 1; + } + + my $newaction = ""; + { + my $digit = substr($line, 0, 1); + if ($digit <= 5) { + $newaction .= "/" x $digit; + } + else { + $newaction .= "/" x ($digit - 5) . "."; + } + $newaction .= "./"; + my $rest = $line; + while (($rest = substr($rest, 1)) ne "") { + $digit = substr($rest, 0, 1); + if ($digit < 5) { + $newaction .= "/" x $digit; + } + else { + $newaction .= "/" x ($digit - 5) . "."; + } + $newaction .= "./"; + } + } + $newaction .= substr($file, 1) . ".vpe"; + $newaction = # $color . # only for debugging + "/A<</Type/Action/S/Launch/F($newaction)>>"; + $newaction .= " " x ($length - length($newaction) - 1); + if (length($newaction) > $length) { + print STDERR "$Error Action too long!\n"; + next; + } + + seek(IN, -length($action), 1); + print IN $newaction; + } + + $symlinks{$file} = 1; + } +} + +if (keys(%symlinks)) { + + my $this = $0; + if (!$::opt_delete) { + if (!-f $0 or !-x $0) { + $this = `which $0`; + ($this ne "") or die "$Error Cannot find this script!\n"; + } + if (!($this =~ m|^/|)) { + use Cwd; + $this = cwd() . "/" . $this; + } + $this =~ s|/[^/]+/\.\./|/|g; + $this =~ s|/\./|/|g; + } + + if ($::opt_delete) { + print "Delete symlinks:\n"; + } + else { + if ($::opt_force) { + print "Forced symlinks to $this:\n"; + } + else { + print "Symlinks to $this:\n"; + } + } + + foreach (keys(%symlinks)) { + my $sym = $_ . ".vpe"; + print " $sym ["; + + if ($::opt_delete) { + if (!-l $sym) { + print "ok, not existing]\n"; + next; + } + unlink($sym); + if (!-l $sym) { + print "ok, deleted]\n"; + next; + } + print "failed]\n"; + next; + } + if ($::opt_force) { + if (-l $sym) { + unlink($sym); + if (-l $sym) { + print "deletion failed]\n"; + next; + } + if (symlink($this, $sym)) { + print "ok, deleted and created]\n"; + next; + } + print "deleted, creation failed]\n"; + next; + } + if (symlink($this, $sym)) { + print "ok, created]\n"; + next; + } + print "creation failed]\n"; + next; + } + if (-f $sym) { + print "exists]\n"; + next; + } + if (symlink($this, $sym)) { + print "ok, created]\n"; + next; + } + print "failed]\n"; + next; + } +} +__END__ diff --git a/Master/texmf-dist/doc/latex/oberdiek/vpe.txt b/Master/texmf-dist/doc/latex/oberdiek/vpe.txt new file mode 100644 index 00000000000..5182b326561 --- /dev/null +++ b/Master/texmf-dist/doc/latex/oberdiek/vpe.txt @@ -0,0 +1,421 @@ +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 |