summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pdfcomment/pdfcomment.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2009-04-04 23:50:10 +0000
committerKarl Berry <karl@freefriends.org>2009-04-04 23:50:10 +0000
commit5c5c5ed81aa69504f93545be63af54bb9a82e200 (patch)
treedf30ddf59a57bc370607352abf7fae1368163414 /Master/texmf-dist/doc/latex/pdfcomment/pdfcomment.tex
parentbc915313252483d95234b4706a597f56b2ca8a05 (diff)
pdfcomment 1.4 (2apr09)
git-svn-id: svn://tug.org/texlive/trunk@12625 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/pdfcomment/pdfcomment.tex')
-rw-r--r--Master/texmf-dist/doc/latex/pdfcomment/pdfcomment.tex174
1 files changed, 152 insertions, 22 deletions
diff --git a/Master/texmf-dist/doc/latex/pdfcomment/pdfcomment.tex b/Master/texmf-dist/doc/latex/pdfcomment/pdfcomment.tex
index 1f4011f8db7..8c206614e28 100644
--- a/Master/texmf-dist/doc/latex/pdfcomment/pdfcomment.tex
+++ b/Master/texmf-dist/doc/latex/pdfcomment/pdfcomment.tex
@@ -13,15 +13,19 @@
\usepackage{ltxdocext}%
\usepackage{hyperref}
\usepackage{pdfcomment}
-\def\fileversion{v1.3}
+\def\fileversion{v1.4}
\def\filename{pdfcomment.sty}
\def\XeLaTeX{Xe\LaTeX}
-%\usepackage{acrofont}%
\CodelineIndex
-%\EnableCrossrefs
-%\makeatletter
-%\def\tableofcontents{\@starttoc{toc}}
-%\makeatother
+\makeatletter
+\renewcommand\tableofcontents%
+{%
+ %\section*{\contentsname
+ \@mkboth{%
+ \MakeUppercase\contentsname}{\MakeUppercase\contentsname}%
+ \@starttoc{toc}%
+}%
+\makeatother
\renewcommand{\arg}[1]{%
{\ttfamily\string{}\meta{#1}{\ttfamily\string}}%
\index{#1=\string\ttt{#1}, Argument}\index{Argument>#1=\string\ttt{#1}}%
@@ -51,7 +55,8 @@
\setlength\parindent{0pt}
\makeatletter
\renewcommand\@biblabel[1]{\makebox[1.5cm][l]{[#1]}}
-\renewcommand*\l@subsubsection{\@dottedtocline{3}{3.8em}{4.0em}}
+\renewcommand*\l@subsection{\@dottedtocline{2}{1.2em}{2.3em}}
+\renewcommand*\l@subsubsection{\@dottedtocline{3}{2.4em}{3.7em}}
\makeatother
\hypersetup{pdfauthor={Josef Kleber},pdftitle={A user-friendly interface to PDF annotations},pdfsubject={Documentation for LaTeX style \filename}}
\begin{document}
@@ -78,13 +83,12 @@ If you can't see this annotation \pdfcomment[author={Josef Kleber},subject={Test
\end{center}
\vfill
\clearpage
-%\begin{multicols}{2}
-%[\section*{Inhaltsverzeichnis}
-%\setlength{\columnseprule}{.4pt}
-%\setlength{\columnsep}{18pt}]
-%\tableofcontents
-%\end{multicols}
+\begin{multicols}{2}
+[\section*{\contentsname}
+\setlength{\columnseprule}{.5pt}
+\setlength{\columnsep}{30pt}\small]
\tableofcontents
+\end{multicols}
\clearpage
\section*{Acknowledgment}
I want to thank the following persons for contributions to the development of this package:
@@ -93,7 +97,7 @@ I want to thank the following persons for contributions to the development of th
\item \textbf{Alexander Grahn} for contributing a patch for other drivers
\medskip
-\noindent\hfill\texttt{\LaTeX{} $\rightarrow$ \texttt{dvips} $\rightarrow$ \texttt{ps2pdf}, \LaTeX{} $\rightarrow$ \texttt{dvipdfmx} und \XeLaTeX}.\hfill
+\noindent\hfill\texttt{\LaTeX{} $\rightarrow$ \texttt{dvips} $\rightarrow$ \texttt{ps2pdf}, \LaTeX{} $\rightarrow$ \texttt{dvipdfmx} and \XeLaTeX}.\hfill
\medskip
\item \textbf{Gabriel Cardona} for pointing out problems with older versions of \texttt{hyperref} (v6.76a [2007/04/09])
@@ -114,7 +118,7 @@ The option \styleoption{draft} (default) will set the package to draft mode. The
\subsubsection[\texttt{dvipdfmx}]{\styleoption{dvipdfmx}}\label{sec:dvipdfmx}
If you want to use the driver \texttt{dvipdfmx} for creating your documents, you have to use the option \styleoption{dvipdfmx}. The other drivers are recognized automatically.
\subsection{Local options}
-The following options are useable as options for the commands presented in section \ref{sec:befehle}, as well as style options. As style options they have global effect, whereas they have only local effect when used in commands. Furthermore global options are not overwritten.
+The following options are useable as options for the commands presented in sections \ref{sec:kommentarumgebungen} and \ref{sec:kommentarbefehle}, as well as style options. As style options they have global effect, whereas they have only local effect when used in commands. Furthermore global options are not overwritten.
\subsubsection[\texttt{subject}]{\styleoption{subject}}\label{sec:subject}
You can use the option \styleoption{subject} for defining the subject of the PDF popup annotations.
@@ -141,6 +145,9 @@ By definition the PDF specification allows four different color spaces with diff
\end{tabular}
\end{center}
+\subsubsection[\texttt{icolor}]{\styleoption{icolor}}\label{sec:icolor}
+You can use the option \styleoption{icolor} for defining the so called 'inner color', which is used by some PDF annotations, like arrowheads or the inner area of PDF circle annotation. For the rest, the provisions of the option \styleoption{color} shall apply.
+
\subsubsection[\texttt{icon}]{\styleoption{icon}}\label{sec:icon}
You can use the option \styleoption{icon} for defining the graphic used for the PDF text annotations. The following icons are defined as mandatory by the PDF reference:
@@ -173,6 +180,86 @@ You can use the option \styleoption{open} for defining the opening status of the
If you want to print the PDF popup annotations (with transparency) you will have to use the option \styleoption{open} = \texttt{true}.
+\subsubsection[\texttt{hspace}]{\styleoption{hspace}}\label{sec:hspace}
+You can use the option \styleoption{hspace} for defining the horizontal space after the PDF text annotations, otherwise the PDF text annoations will overlay the text.
+
+\subsubsection[\texttt{type}]{\styleoption{type}}\label{sec:type}
+You can use the option \styleoption{type} for defining the type of PDF annotation, if a comment command supports more than one PDF annotations:
+
+{\renewcommand{\arraystretch}{1.2}
+\begin{center}
+\begin{tabular}{ll}
+\multicolumn{1}{c}{comment command} & \multicolumn{1}{c}{possible types}\\
+\hline
+\cs{pdffreetextcomment} & freetext, callout, typewriter \\
+\cs{pdflinecomment} & line, polyline, polygon \\
+\end{tabular}
+\end{center}}
+
+
+\subsubsection[\texttt{font}]{\styleoption{font}}\label{sec:font}
+You can use the option \styleoption{font} for defining the font of PDF freetext annotations, like all fonts installed in the system, which don't contain a space in their name. Although \texttt{Adobe Reader} shows these fonts as embedded, they are not embedded in reality, but the PDF file just contains a reference to the font (default: Helvetica)! Therefore you should use this option quite carefully. In the case of document exchange between several authors you should just use fonts, which are available on all computer systems, like the so called 'standard 14 fonts'. \pdfcomment[icon=Help,color=blue,open=true,subject={standard 14 fonts}]{Times-Roman, Times-Bold, Times-Italic, Times-BoldItalic, Helvetica, Helvetica-Bold, Helvetica-Oblique, Helvetica-BoldOblique, Courier, Courier-Bold, Courier-Oblique, Courier-BoldOblique, Symbol, ZapfDingbats}
+
+\subsubsection[\texttt{fontsize}]{\styleoption{fontsize}}\label{sec:fontsize}
+You can use the option \styleoption{fontsize} for defining the fontsize of PDF freetext annotations.
+
+\subsubsection[\texttt{fontcolor}]{\styleoption{fontcolor}}\label{sec:fontcolor}
+You can use the option \styleoption{fontcolor} for defining the font color in PDF freetext annotations,which must be a RGB color.
+
+\subsubsection[\texttt{line}]{\styleoption{line}}\label{sec:line}
+You can use the option \styleoption{line} for defining the coordinates of lines in certain PDF annotations, e.\,g. in the form \{$x_1$\space$y_1$\space$x_2$\space$y_2$\}. The origin is in the bottom left page corner. The given numbers will be interpreted as Postscript points (\LaTeX{} unit: bp (big points)), as usual in PDF documents.
+
+{\renewcommand{\arraystretch}{1.2}
+\begin{center}
+\begin{tabular}{ll}
+\multicolumn{1}{c}{type of line} & \multicolumn{1}{c}{\# points}\\
+\hline
+line & $n = 2$ \\
+polyline, polygon & $n > 2$ \\
+callout line & $n = 3$ \\
+\end{tabular}
+\end{center}}
+
+In general, the points must be given from line begin to line end. For callout lines the points must be given from line end to line begin. Please note the example file \texttt{example.tex}!
+
+To avoid the method 'trail and error' you can load the PDF file with the Ghostscript viewer, which is capable of showing the cursor position in it's status line.
+
+\subsubsection[\texttt{linewidth}]{\styleoption{linewidth}}\label{sec:linewidth}
+You can use the option \styleoption{linewidth} for defining the line width of PDF annoations.
+
+\subsubsection[\texttt{linebegin}]{\styleoption{linebegin}}\label{sec:linebegin}
+You can use the option \styleoption{linebegin} for defining the arrow type at the line begin. The example file \texttt{example.pdf} shows all possible types of arrows. \pdfcomment[icon=Help,color=blue,open=true,subject={arrow types}]{/None, /Square, /Circle, /Diamond, /OpenArrow, /ClosedArrow, /Butt (PDF1.5), /ROpenArrow (PDF1.5), /RClosedArrow (PDF1.5), /Slash (PDF1.6)}
+
+
+\subsubsection[\texttt{lineend}]{\styleoption{lineend}}\label{sec:lineend}
+You can use the option \styleoption{lineend} for defining the arrow type at the line end.
+
+\subsubsection[\texttt{linesep}]{\styleoption{linesep}}\label{sec:linesep}
+You can use the option \styleoption{linesep} for defining the horizontal space between text and line in the command \cs{pdfsidelinecomment}.
+
+\subsubsection[\texttt{borderstyle}]{\styleoption{borderstyle}}\label{sec:borderstyle}
+You can use the option \styleoption{borderstyle} for defining the line style.Possible values are: \styleoption{solid} (default) and \styleoption{dashed}
+
+\subsubsection[\texttt{dashstyle}]{\styleoption{dashstyle}}\label{sec:dashstyle}
+You can use the option \styleoption{dashstyle} for defining the dash style, e.\,g. \{5 3\} (5 points line, 3 points space).
+
+\subsubsection[\texttt{bse}]{\styleoption{bse}}\label{sec:bse}
+You can use the option \styleoption{bse} for defining the 'border style effect'. Possible values are: \styleoption{none} (default) and \styleoption{cloudy}
+
+\subsubsection[\texttt{bsei}]{\styleoption{bsei}}\label{sec:bsei}
+You can use the option \styleoption{bsei} for defining the 'border style effect intensity' (size of cloud elements). The PDF reference suggests values between 1 and 2.
+
+\subsubsection[\texttt{caption}]{\styleoption{caption}}\label{sec:caption}
+You can use the option \styleoption{caption} for defining the caption type of lines. Possible values are: none, inline (default), top
+
+The options \styleoption{inline} and \styleoption{top} shows the comment 'inline' and on top of the line. While using \styleoption{none} the comment will be shown in a PDF popup annotation.
+
+\subsubsection[\texttt{captionhoffset}]{\styleoption{captionhoffset}}\label{sec:captionhoffset}
+You can use the option \styleoption{captionhoffset} for defining a horizontal offset, that is a horizontal shift of the line caption.
+
+\subsubsection[\texttt{captionvoffset}]{\styleoption{captionvoffset}}\label{sec:captionvoffset}
+You can use the option \styleoption{captionvoffset} for definig a vertical offset of the line caption.
+
\subsubsection[\texttt{voffset}]{\styleoption{voffset}}\label{sec:voffset}
You can use the option \styleoption{voffset} for defining a vertical offset of the PDF annotations, that is a vertical shift for the given length.
@@ -185,9 +272,6 @@ You can use the option \styleoption{width} for defining the width of PDF annotat
\subsubsection[\texttt{height}]{\styleoption{height}}\label{sec:height}
You can use the option \styleoption{height} for definig the height of PDF annotations. PDF text annatations have a height of \cmd\baselineskip{} by definition.
-\subsubsection[\texttt{hspace}]{\styleoption{hspace}}\label{sec:hspace}
-You can use the option \styleoption{hspace} for defining the horizontal space after the PDF text annotations, otherwise the PDF text annoations will overlay the text.
-
\subsubsection[\texttt{markup}]{\styleoption{markup}}\label{sec:markup}
You can use the option \styleoption{markup} for defining the type of the PDF text markup annotation. Possible values are: Highlight, Underline, Squiggly und StrikeOut.
@@ -197,9 +281,32 @@ With the option \styleoption{avatar} you can load the option lists, that were pr
\subsubsection[\texttt{style}]{\styleoption{style}}\label{sec:style}
With the option \styleoption{style} you can also load predefined option lists for spliting personal and stylistic options, e.\,g. \texttt{avatar=Josef, style=MyComment}.
+\section{Environments}\label{sec:umgebungen}
+
+\subsection{Comment environments}\label{sec:kommentarumgebungen}
+
+\subsubsection{\texorpdfstring{\cs{pdfsidelinecomment}}{\textbackslash pdfsidelinecomment}}
+\label{sec:sidelinecomment}
+Possible \marginnote{\raggedleft\scriptsize\envb{pdfsidelinecomment}\\\oarg{options}\marg{comment}\\\dots\\\enve{pdfsidelinecomment}}options: \styleoption{avatar}, \styleoption{style}, \styleoption{subject}, \styleoption{author}, \styleoption{color}, \styleoption{icolor}, \styleoption{opacity}, \styleoption{linewidth}, \styleoption{linebegin}, \styleoption{lineend}, \styleoption{linesep}, \styleoption{borderstyle}, \styleoption{dashstyle}, \styleoption{caption}, \styleoption{captionhoffset}, \styleoption{captionvoffset}
+
+\bigskip
+With the environment \env{pdfsidelinecomment} you can comment complete parts of a page in the form of two lines in the margins.
+
+\hspace*{0pt}\newline
+\begin{pdfsidelinecomment}[color=red,icolor=yellow,linebegin=/Circle,lineend=/Circle,linewidth=3bp,linesep=1cm]{ Please note }
+Limitations:
+
+\begin{itemize}
+\item The PDF sideline annotation must not be longer than one page, otherwise the recognition of the page break will fail.
+\item While using dvi files in the meantime you have to use a \LaTeX{} distribution, which is using \texttt{pdf(e)latex} as engine in a version $\geq$ v1.40.0\footnote{older versions are not capable of providing x/y coordinates of the current position in dvi mode.}!
+\item While using \XeLaTeX{} you have to make sure that page dimensions are written to the xdvi file, e.\,g. with the option \styleoption{pagesize} of the KoMa-Script classes, or as option of the package \package{typearea.sty} respectively.
+\end{itemize}
+\end{pdfsidelinecomment}
+
+
\section{Commands}\label{sec:befehle}
-\subsection{Comment commands}
+\subsection{Comment commands}\label{sec:kommentarbefehle}
You can use the following commands for commenting your documents.
@@ -222,7 +329,7 @@ Possible \margcs{\cmd\pdfmargincomment\\\oarg{options}\marg{comment}}options: \s
Possible \margcs{\cmd\pdfmarkupcomment\oarg{options}\\\marg{markup text}\marg{comment}}options: \styleoption{avatar}, \styleoption{style}, \styleoption{subject}, \styleoption{author}, \styleoption{color}, \styleoption{opacity}, \styleoption{markup}
\bigskip
-\cmd\pdfmarkupcomment{} will typeset so called PDF text markup annotations over the text specified in the argument \marg{markup text}. Possible types for the option \styleoption{markup} are: \pdfmarkupcomment[color=yellow,markup=Highlight]{Highlight}{This is a Highlight markup annotation!}, \pdfmarkupcomment[color=red,markup=Underline]{Underline}{This is a Underline markup annotation!}, \pdfmarkupcomment[color=Teal,markup=Squiggly]{Squiggly}{This is a Squiggly markup annotation!} and \pdfmarkupcomment[color=red,markup=StrikeOut]{StrikeOut}{This is a StrikeOut markup annotation!}
+\cmd\pdfmarkupcomment{} will typeset so called PDF text markup annotations over the text specified in the argument \marg{markup text}. Possible types for the option \styleoption{markup} are: \pdfcommentsetup{subject={\textbackslash pdfmarkupcomment test}}\pdfmarkupcomment[color=yellow,markup=Highlight]{Highlight}{This is a Highlight markup annotation!}, \pdfmarkupcomment[color=red,markup=Underline]{Underline}{This is a Underline markup annotation!}, \pdfmarkupcomment[color=Teal,markup=Squiggly]{Squiggly}{This is a Squiggly markup annotation!} and \pdfmarkupcomment[color=red,markup=StrikeOut]{StrikeOut}{This is a StrikeOut markup annotation!}
\hspace*{0pt}\newline
Limitations:
@@ -231,15 +338,38 @@ Limitations:
\item As the name PDF text markup annotation might lead to suggest, this form of comment is suitable for text only.
\item The specified text with the argument \marg{markup text} must not be longer than one paragraph.
\item The PDF text markup annotation must not be longer than one page, otherwise the recognition of the page break will fail.
+\item While using dvi files in the meantime you have to use a \LaTeX{} distribution, which is using \texttt{pdf(e)latex} as engine in a version $\geq$ v1.40.0\footnote{older versions are not capable of providing x/y coordinates of the current position in dvi mode.}!
\item While using \XeLaTeX{} you have to make sure that page dimensions are written to the xdvi file, e.\,g. with the option \styleoption{pagesize} of the KoMa-Script classes, or as option of the package \package{typearea.sty} respectively.
\end{itemize}
\subsubsection{\texorpdfstring{\cs{pdffreetextcomment}}{\textbackslash pdffreetextcomment}}
\label{sec:pdffreetextcomment}
-Mögliche \margcs{\cmd\pdffreetextcomment\\\oarg{options}\marg{comment}}Optionen: \styleoption{avatar}, \styleoption{style}, \styleoption{subject}, \styleoption{author}, \styleoption{color}, \styleoption{opacity}, \styleoption{height}, \styleoption{width}, \styleoption{voffset}, \styleoption{hoffset}
+Possible \margcs{\cmd\pdffreetextcomment\\\oarg{options}\marg{comment}} options: \styleoption{avatar}, \styleoption{style}, \styleoption{subject}, \styleoption{author}, \styleoption{color}, \styleoption{font}, \styleoption{fontsize}, \styleoption{fontcolor}, \styleoption{opacity}, \styleoption{line}, \styleoption{linewidth}, \styleoption{lineend}, \styleoption{borderstyle}, \styleoption{dashstyle}, \styleoption{bse}, \styleoption{bsei}, \styleoption{type}, \styleoption{height}, \styleoption{width}, \styleoption{voffset}, \styleoption{hoffset}
+
+\bigskip
+\cmd\pdffreetextcomment{} (type=freetext) will typeset a comment in form of a freely positioned box on the wished spot of the page.\pdffreetextcomment[subject={\textbackslash pdffreetextcomment Test},height=1.2cm,width=4cm,voffset=-3.7cm,hoffset=-1.2cm,opacity=0.5,color=yellow]{This is a FreeText annotation} By using the option \styleoption{type} = \texttt{callout} the box will have an additional so called callout line, to bind the box to a certain element of the page. With the option \styleoption{type} = \texttt{typewriter} you can write a comment everywhere on the page with a virtual 'typewriter'. These PDF freetext annotation do have no frame and a transparent background for 'overwriting' arbitrary parts of the page. Please note the example file \texttt{example.pdf}!
+
+\subsubsection{\texorpdfstring{\cs{pdfsquarecomment}}{\textbackslash pdfsquarecomment}}
+\label{sec:pdfsquarecomment}
+Possible \margcs{\cmd\pdfsquarecomment\\\oarg{options}\marg{comment}} options: \styleoption{avatar}, \styleoption{style}, \styleoption{subject}, \styleoption{author}, \styleoption{color}, \styleoption{icolor}, \styleoption{opacity}, \styleoption{linewidth}, \styleoption{borderstyle}, \styleoption{dashstyle}, \styleoption{bse}, \styleoption{bsei}, \styleoption{height}, \styleoption{width}, \styleoption{voffset}, \styleoption{hoffset}
+
+\bigskip
+\cmd\pdfsquarecomment{} will typeset a rectangular box at the wished spot of a page (see: \texttt{example.pdf}).
+
+
+\subsubsection{\texorpdfstring{\cs{pdfcirclecomment}}{\textbackslash pdfcirclecomment}}
+\label{sec:pdfcirclecomment}
+Possible \margcs{\cmd\pdfcirclecomment\\\oarg{options}\marg{comment}} options: \styleoption{avatar}, \styleoption{style}, \styleoption{subject}, \styleoption{author}, \styleoption{color}, \styleoption{icolor}, \styleoption{opacity}, \styleoption{linewidth}, \styleoption{borderstyle}, \styleoption{dashstyle}, \styleoption{bse}, \styleoption{bsei}, \styleoption{height}, \styleoption{width}, \styleoption{voffset}, \styleoption{hoffset}
+
+\bigskip
+\cmd\pdfsquarecomment{} will typeset a comment in form of a circle or ellipse at the wished spot of the page (see: \texttt{example.pdf}).
+
+\subsubsection{\texorpdfstring{\cs{pdflinecomment}}{\textbackslash pdflinecomment}}
+\label{sec:pdflinecomment}
+Possible \margcs{\cmd\pdfsidelinecomment\\\oarg{options}\marg{comment}}options: \styleoption{avatar}, \styleoption{style}, \styleoption{subject}, \styleoption{author}, \styleoption{type}, \styleoption{color}, \styleoption{icolor}, \styleoption{opacity}, \styleoption{caption}, \styleoption{captionhoffset}, \styleoption{captionvoffset}, \styleoption{linewidth}, \styleoption{linebegin}, \styleoption{lineend}, \styleoption{line}, \styleoption{borderstyle}, \styleoption{dashstyle}
\bigskip
-\cmd\pdffreetextcomment{} will typset a comment in form of a freely positioned box on the wished spot of the page.\pdffreetextcomment[subject={\textbackslash pdffreetextcomment Test},height=1.2cm,width=4cm,voffset=-1.3cm,hoffset=1.2cm,opacity=0.5,color=yellow]{This is a FreeText annotation}
+\cmd\pdflinecomment{} will typeset a comment in form of a line, polyline or polygon at the wished spot of the page (see: \texttt{example.pdf}).
\subsection{Misc. commands}