summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pax/README
blob: 03e070a98539e468873bf14ad2d875d767fa16f3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
README for project pax (PDFAnnotExtractor), 2007/07/19 v0.1h


TABLE OF CONTENTS
=================

A. Project pax
B. Copyright, License
C. Files
D. Author
E. Requirements
F. Download
G. Installation
H. Use
I. History


A. PROJECT PAX
==============

If PDF files are included using pdfTeX, PDF annotations
are stripped. This project tries a solution without
altering pdfTeX. A Java program (pax.jar) parses the PDF file that
will later be included. It writes the data of the annotations
in a file that can be read by TeX. Then a LaTeX package (pax.sty)
extends the graphics package. If a PDF file is included, the package
looks for the file with the annotation data, reads them and puts
the annotations in the right place.

Project status: experimental


B. COPYRIGHT, LICENSE
=====================

Copyright (C) 2006, 2007 Heiko Oberdiek.

The project consists of two parts:
* The Java program pax.jar with sources.
  License is GPL, see license/gpl.txt.
* The LaTeX package pax.sty.
  License is LPPL 1.3.
The file README belongs to both parts.

The Java program uses the PDF library PDFBox,
see http://www.pdfbox.org/.


C. FILES
========

The project is available in CTAN (ftp.ctan.org):
  CTAN:macros/latex/contrib/pax/

There are the following files:
* README
    This file.
* pax-tds.zip
    The whole project, ready to unpack in a TDS (texmf) tree.

The files inside pax-tds.zip:
* doc/latex/pax/README
    This file.
* scripts/pax/pax.jar
    The Java program.
* source/latex/pax/license/LaTeX/lppl.txt
    License (LPPL) for the LaTeX package.
* source/latex/pax/license/PDFAnnotExtractor/gpl.txt
    License (GPL) for the Java program.
* source/latex/pax/src/Constants.java
  source/latex/pax/src/Entry.java
  source/latex/pax/src/EntryWriteException.java
  source/latex/pax/src/PDFAnnotExtractor.java
  source/latex/pax/src/StringVisitor.java
    Java source files.
* source/latex/pax/src/MANIFEST.MF
    Manifest file for the JAR file.
* source/latex/pax/src/build.xml
    Ant build file for generating the JAR file.
* tex/latex/pax/pax.sty
    The LaTeX package.


D. AUTHOR
=========

Heiko Oberdiek <oberdiek@uni-freiburg.de>

E. REQUIREMENTS
===============

* Java 1.4+.
* PDFBox 0.7.2+.

F. DOWNLOAD
===========

1. Download pax-tds.zip from CTAN:
     ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/pax/pax-tds.zip

2. Download PDFBox-0.7.2.jar from http://www.pdfbox.org/:
     http://prdownloads.sourceforge.net/pdfbox/PDFBox-0.7.2.zip?download

G. INSTALLATION
===============

Examples are given for linux.

3. Install PDFBox. In the following it is assumed, that the JAR file
   is available as:
     /usr/local/share/PDFBox-0.7.2/lib/PDFBox-0.7.2.jar

4. Unzip pax-tds.zip inside the TDS tree, where you want to put this
   project, e.g.:
     unzip pax-tds -d /usr/local/share/texmf
   Don't forget to update the database (texhash, mktexlsr, ...).

5. Put the PDFBox library in the right place:
     mkdir /usr/local/share/texmf/scripts/pax/lib
     ln /usr/local/share/PDFBox-0.7.2/lib/PDFBox-0.7.2.jar \
        /usr/local/share/texmf/scripts/pax/lib/
     (A symbol link does not seam to work, a hard link or copy is needed.)
   Alternatively, include PDFBox-0.7.2.jar in your CLASSPATH and/or
   adjust the Class-Path entry in MANIFEST.MF of pax.jar for the
   right location of the PDFBox library.

6. Write a wrapper script or whatever to ease the call of the
   Java program, e.g.:
     #!/bin/sh
     java -jar /usr/local/share/texmf/scripts/pax/pax.jar "$@"

Version of PDFBox
-----------------
Developing the pax project I have used and tested version 0.7.2.
However, you may try a more uptodate version of PDFBox.
Then fix the entry in the file MANIFEST.MF inside pax.jar or
create a symbol link that TDS:scripts/pax/lib/PDFBox-0.7.2.jar
points to the new JAR file.


H. USE
======

As example I am using usrguide.pdf (with links from project latex-tds)
that will be included in test.tex:

%%% cut %%% test.tex %%% cut %%%
\documentclass[a4paper,12pt,landscape]{article}
\usepackage[
  hmargin=1in,
  vmargin=1in,
]{geometry}

\usepackage{pdfpages}
% pdfpages loads graphicx

\usepackage{pax}

\iffalse
  \usepackage{hyperref}
  \hypersetup{
    filebordercolor={1 1 0},
  }
\fi

\begin{document}
  \includepdf[pages=-,nup=2x1]{usrguide}
\end{document}
%%% cut %%% test.tex %%% cut %%%

First run the Java program on usrguide.pdf:

  $ java -jar pax.jar usrguide.pdf

It generates usrguide.pax.
Next run pdflatex on test.tex twice at least:

  $ pdflatex test
  $ pdflatex test

Then the links should work.

Additionally package hyperref can be used (replace \iffase by \iftrue).
Then the links can be configured using hyperref settings.
(But keep in mind, the colored links by option colorlinks can't
be changed in included documents.


I. History
==========

2006/08/24 v0.1a
  * First release.
2006/09/04 v0.1b
  * Bug fix in PDFAnnotExtractor.add_dest()/named destinations.
2007/06/29 v0.1c
  * \l@addto@macro renamed to \PAX@l@addto@macro to avoid
    collision with classes of KOMA-Script.
2007/06/30 v0.1d
  * Use of package `etexmcds'.
2007/07/12 v0.1e
  * The Java program can be called with several files.
2007/07/16 v0.1f
  * PDF files are explicitely closed to avoid warnings.
2007/07/18 v0.1g
  * Compiled for Java 1.4.
2007/07/19 v0.1h
  * JAR file without TDS tree.