summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/pdfsync/pdfsync-doc.tex
blob: 946cf0e334f2207a5665b76ed9049c59308eab0f (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
\documentclass[pagesize=auto, fontsize=12, DIV=11]{scrartcl}

\usepackage{fixltx2e}
\usepackage{etex}
\usepackage{lmodern}
\usepackage[T1]{fontenc}
\usepackage{textcomp}
\usepackage{hologo}
\usepackage{microtype}
\usepackage{hyperref}

\newcommand*{\mail}[1]{\href{mailto:#1}{\texttt{#1}}}
\newcommand*{\pkg}[1]{\textsf{#1}}
\newcommand*{\cs}[1]{\texttt{\textbackslash#1}}
\makeatletter
\newcommand*{\cmd}[1]{\cs{\expandafter\@gobble\string#1}}
\makeatother
\newcommand*{\opt}[1]{\texttt{#1}}

\addtokomafont{title}{\rmfamily}
\addtokomafont{subtitle}{\mdseries}

\title{The \pkg{pdfsync} package\thanks{This manual corresponds to \pkg{pdfsync.sty}~v1.1, dated~2008/01/26.}}
\subtitle{A \LaTeX\ package for synchronizing between source and \textsc{pdf} output}
\author{J. Laurens\thanks{\mail{jlaurens@users.sourceforge.net}}}
\date{2008/01/26}


\begin{document}

\maketitle


\section{Presentation}

\pkg{pdfsync.sty} allows one to synchronize between \LaTeX\ source and \textsc{pdf} output.
When used with a text editor and a PDF viewer that both support \pkg{pdfsync},
you can navigate from the source to the output and vice versa.
This is some kind of \pkg{srcltx} ported from \textsc{dvi} to \textsc{pdf}.

When you typeset \texttt{foo.tex} with \pkg{pdfsync.sty} and either \texttt{pdfetex} or \texttt{xetex},
a \texttt{foo.pdfsync} auxiliary file is created. It only contains geometrical information
used by text editors or PDF viewers for synchronization.
You can delete this file when you are done.

Actually, i\TeX Mac, i\TeX Mac2, \TeX Shop, Auc\TeX\ are
text editors implementing \pkg{pdfsync} support at various level.
i\TeX Mac, i\TeX Mac2, \TeX Shop, \TeX niscope, PDFView are
PDF viewers implementing \pkg{pdfsync} support at various level.

This is most certainly the last update of this package,
this technology will most certainly be embedded in \hologo{pdfTeX} and \hologo{XeTeX} engines and won't rely any longer on \textsc{pdf} techniques.
As a matter of fact, synchronization will be available both for \textsc{dvi}, \textsc{xdv} and \textsc{pdf}.
Also it will work the same for Plain, \LaTeX\@, Con\TeX t and whatsoever.
Moreover, synchronization will not modify any package.


\section{News}

\begin{itemize}
\item 01/30/2007: version~1.1 is the second version officially available.
  Some internals were modified in order to provide a stronger \cmd{\pdfsyncstart}, \cmd{\pdfsyncstop} pair.
  Paul Taylor's \pkg{diagram} package now works with \pkg{pdfsync}. You may have to update.
  Anticipating over \hologo{pdfTeX} improvements, this package will load with option ``\opt{off}'' if the \cmd{\synchronize} macro is defined
\end{itemize}


\section{Installation}

If this package is not already included in your \TeX\ distribution,
just copy the \texttt{pdfsync.sty} file to the proper location.
On Mac~OS~X, it can be
%
\begin{verbatim}
     YOUR_HOME_DIRECTORY/Library/texmf/tex/latex/graphics/graphics.sty
\end{verbatim}
%
where you should replace \verb+YOUR_HOME_DIRECTORY+ by its actual value.


\section{Usage}

Put \verb+\usepackage{pdfsync}+ in your \LaTeX\ preamble.

In case of severe conflicts with another package, try instead
%
\begin{verbatim}
     \usepackage[novbox]{pdfsync}
\end{verbatim}

If \pkg{pdfsync} breaks only some part of your \LaTeX\ code, you can try to
enclose it in
%
\begin{verbatim}
     \pdfsyncstop \pdfsyncstart
\end{verbatim}
%
pair. If you want to add
more control point add \cmd{\pdfsync} at sensible locations in your code.
In that case,
%
\begin{verbatim}
     \usepackage[off]{pdfsync}
\end{verbatim}
%
will disable \textsc{pdf} synchronization
and \cmd{\relax} the above commands.


\section{Bugs}

\pkg{pdfsync} uses extremely sensible code.
You should not use \pkg{pdfsync} on final documents because
it can change the layout rather significantly
(different page/line breaks are the most obvious changes),
despite this is rather rare,
17th~Murphy's law states that it will happen to you when it absolutely must not\dots

The accuracy of \textsc{pdf} synchronization depends on the application used for that purpose.
i\TeX Mac2 is actually the most accurate implementation because it combines \pkg{pdfsync}
with \textsc{pdf} searching. The lack of accuracy, is not a bug in \pkg{pdfsync} a priori.

You should report bugs and package conflicts to \\
\null\quad\quad\href{mailto:jlaurens@users.sourceforge.net}{\texttt{jlaurens AT users DOT sourceforge DOT net.}}


\section{Credits:}

The original idea of \pkg{pdfsync} was proposed by Piero~D'Ancona in the summer of 2003.
He and Jerome~Laurens both created the first working package.
Hans~Hagen and David~Kastrup made very significant enhancements to the original code.


\section{License}

This program is free software; you can redistribute it and/or modify
it under the terms of the The \LaTeX\ Project Public License version~1.3c at least \\
\url{http://www.latex-project.org/lppl.txt}


\section{Home page}

The official site where you will find both the latest version and the \texttt{.pdfsync} file specifications is \\
\null\quad\quad\url{http://itexmac.sourceforge.net/pdfsync.html}

\bigskip

copyright 2007, \href{mailto:jlaurens@users.sourceforge.net}{\texttt{jlaurens AT users DOT sourceforge DOT net}}

\end{document}