texlive[50100] Master/texmf-dist: pdfreview (22feb19)

commits+karl at tug.org commits+karl at tug.org
Sat Feb 23 23:17:01 CET 2019


Revision: 50100
          http://tug.org/svn/texlive?view=revision&revision=50100
Author:   karl
Date:     2019-02-23 23:17:01 +0100 (Sat, 23 Feb 2019)
Log Message:
-----------
pdfreview (22feb19)

Modified Paths:
--------------
    trunk/Master/texmf-dist/doc/latex/pdfreview/README.md
    trunk/Master/texmf-dist/doc/latex/pdfreview/pdfreview.pdf
    trunk/Master/texmf-dist/doc/latex/pdfreview/pdfreview.sh
    trunk/Master/texmf-dist/doc/latex/pdfreview/pdfreview.tex
    trunk/Master/texmf-dist/doc/latex/pdfreview/pdfshrink.sh
    trunk/Master/texmf-dist/tex/latex/pdfreview/pdfreview.sty

Added Paths:
-----------
    trunk/Master/texmf-dist/doc/latex/pdfreview/lorem-ipsum.pdf
    trunk/Master/texmf-dist/doc/latex/pdfreview/sample.pdf
    trunk/Master/texmf-dist/doc/latex/pdfreview/sample.tex

Removed Paths:
-------------
    trunk/Master/texmf-dist/doc/latex/pdfreview/sample-for-docs.pdf

Modified: trunk/Master/texmf-dist/doc/latex/pdfreview/README.md
===================================================================
--- trunk/Master/texmf-dist/doc/latex/pdfreview/README.md	2019-02-23 15:52:13 UTC (rev 50099)
+++ trunk/Master/texmf-dist/doc/latex/pdfreview/README.md	2019-02-23 22:17:01 UTC (rev 50100)
@@ -18,7 +18,7 @@
 `pdfreview.pdf`
 : the docs compiled from `pdfreview.tex`
 
-`sample-for-docs.pdf`
+`sample.pdf`
 :  a graphics file that is included when latexing the docs.
 
 `pdfshrink.sh`
@@ -35,6 +35,7 @@
 
 September 22nd, 2017: version 1.1
 
+February 22nd, 2019: version 1.2
 
 Licence
 -------

Added: trunk/Master/texmf-dist/doc/latex/pdfreview/lorem-ipsum.pdf
===================================================================
(Binary files differ)

Index: trunk/Master/texmf-dist/doc/latex/pdfreview/lorem-ipsum.pdf
===================================================================
--- trunk/Master/texmf-dist/doc/latex/pdfreview/lorem-ipsum.pdf	2019-02-23 15:52:13 UTC (rev 50099)
+++ trunk/Master/texmf-dist/doc/latex/pdfreview/lorem-ipsum.pdf	2019-02-23 22:17:01 UTC (rev 50100)

Property changes on: trunk/Master/texmf-dist/doc/latex/pdfreview/lorem-ipsum.pdf
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+application/pdf
\ No newline at end of property
Modified: trunk/Master/texmf-dist/doc/latex/pdfreview/pdfreview.pdf
===================================================================
(Binary files differ)

Modified: trunk/Master/texmf-dist/doc/latex/pdfreview/pdfreview.sh
===================================================================
--- trunk/Master/texmf-dist/doc/latex/pdfreview/pdfreview.sh	2019-02-23 15:52:13 UTC (rev 50099)
+++ trunk/Master/texmf-dist/doc/latex/pdfreview/pdfreview.sh	2019-02-23 22:17:01 UTC (rev 50100)
@@ -1,32 +1,35 @@
 #!/bin/bash
 
-# this script is part of the pdf-annotation LaTeX package by M. Palmer
-# like all files in the package, it is covered by the LPPL.
-
 # this assumes ghostscript is installed as 'gs - change as needed
 ghostscript="gs"
 
 script_name=`basename "$0"`
 
-if [ -z $1 ]; then
+if [ -z "$1" ]; then
    echo "Usage: $script_name inputfile.pdf > outputfile.tex"
    exit 1
 fi
 
-source_doc=$1
+if [ ! -f "$1" ]; then
+    echo "File $1 not found"
+    exit 1
+fi
 
-# doc_header will become the preamble of your wrapper document
-# edit it according it your preferences.
+source_doc="$1"
 
+# doc_header will become the preamble of your generated wrapper document
+# edit it according it your own preferences.
+
 doc_header="\documentclass[letterpaper,10pt]{article}
 
+\usepackage{mathptmx}
+
 \usepackage[
-  sourcedoc=$source_doc,
+  sourcedoc={$source_doc},
   inline=true,
-  withnotesonly=false,
   grid=true,
   gridcolor=black!30,
-  trim={1cm 1cm 1cm 1cm},
+  trim={2cm 1cm 2cm 1cm},
   bodywidth=0.75,
   pageoffset=0,
   fontsize=footnotesize,
@@ -33,7 +36,9 @@
   twocolumn=false,
   notesbg=yellow,
   notesframe=black,
-  insertpagemargin=2.5cm
+  insertpagemargin=2.5cm,
+  withnotesonly=false,
+  staggered=true
 ]{pdfreview}
 
 \begin{document}
@@ -53,4 +58,3 @@
 done
 
 echo "\end{document}"
-

Modified: trunk/Master/texmf-dist/doc/latex/pdfreview/pdfreview.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/pdfreview/pdfreview.tex	2019-02-23 15:52:13 UTC (rev 50099)
+++ trunk/Master/texmf-dist/doc/latex/pdfreview/pdfreview.tex	2019-02-23 22:17:01 UTC (rev 50100)
@@ -1,6 +1,15 @@
 \documentclass{codedoc}
 
-\usepackage{lmodern,tikz,graphicx,shortvrb,url,xspace}
+\usepackage{
+    lmodern,
+    tikz,
+    graphicx,
+    shortvrb,
+    url,
+    xspace
+}
+
+\usepackage[defaultlines=2,all]{nowidow}
 \usepackage[small]{titlesec}
 \usepackage[margin=1in]{geometry}
 
@@ -8,33 +17,43 @@
 \newcommand{\option}[3]{\item [\texttt{#1}] (\meta{#2}; default: \texttt{#3}).}
 \newcommand*{\pkgname}{\texttt{pdfreview}\xspace}
 
-\author{Michael Palmer}
+\author{Michael Palmer (\texttt{mpalmer at uwaterloo.ca})}
 \title{The \pkgname package}
-\date{v1.1 (\today)}
+\date{v1.2 (\today)}
 
 \usepackage{bookmark}
+\hypersetup{colorlinks,linkcolor=blue}
 
+% figure placement: Set more liberal parameters for combining
+% text and figures on the same page.
+\renewcommand{\topfraction}{0.9}
+\renewcommand{\bottomfraction}{0.9}
+\renewcommand{\floatpagefraction}{0.8}
+\renewcommand{\textfraction}{0.1}
+
+\usepackage{adjustmargins}
+
 \begin{document}
 
 \maketitle
 
 \begin{abstract}
-\noindent The \pkgname package lets you add comments in the page margins of PDF files, e.g.\ when reviewing manuscripts or grading reports. The PDF file to be annotated is included, one page at a time, as graphics, in a manner similar to the \texttt{pdfpages} package. Notes are placed in the margin next to the included graphics using a grid of help lines. Alternatively, only numbers are placed in the page margins, and the notes are collected into a numbered list at the end of the document. \par
-Note that this package is \emph{not} intended for adding notes directly to the \LaTeX{} source of the document that is being reviewed; instead, the document undergoing review is already in PDF format and remains unchanged. Also note that this package does not produce the usual PDF `sticky notes' that must be opened by clicking on them; instead, the notes are simply shown as text. 
+\noindent The \pkgname package lets you add comments in the page margins of PDF files, e.g.\ when reviewing manuscripts or grading reports. The PDF file to be annotated is included, one page at a time, as graphics, in a manner similar to the \texttt{pdfpages} package. Notes are placed in the margin next to the included graphics using a grid of guides. Alternatively, only numbers are placed in the page margins, and all the notes are collected into a numbered list at the end of the document. \par
+Note that this package is \emph{not} intended for adding notes into the \LaTeX{} source of the document that is being reviewed; instead, the document undergoing review is already in PDF format and remains unchanged. Also note that this package does not produce the usual PDF `sticky notes' that must be opened in the viewer by clicking on them; instead, the notes are simply shown as text in the page margin.
 \end{abstract}
 
 \section{An example}
 
-Let's assume a student submitted his essay as \texttt{lorem-ipsum.pdf}. In order to review and annotate it, I create this wrapper \LaTeX{} document:
+Let's assume a student submitted his essay as \mbox{\texttt{lorem ipsum.pdf}}. In order to review and annotate it, I create this wrapper \LaTeX{} document:
 
 \begin{verbatim}
 \documentclass[letterpaper,10pt]{article}
-
 \usepackage[
-  sourcedoc=lorem-ipsum.pdf,      % declare the PDF document being reviewed
-  grid=true,                      % draw help lines for margin notes (set false when done)
+  sourcedoc={lorem ipsum.pdf},    % declare the PDF document being reviewed
+  grid=true,                      % draw guides for margin notes (set false when done)
+  staggered=true,                 % avoid vertical overlap of adjacent notes
   bodywidth=0.66,                 % set width of source doc page as fraction of \textwidth
-  twocolumn=true,                 % place margin notes on both sides
+  twocolumn=true,                 % enable margin notes on both sides
   trim=2cm,                       % trim all page margins of source doc by this amount
 ]{pdfreview}
 
@@ -43,9 +62,9 @@
 \begin{page}{1}                   % mount the first page
 
 \begin{leftnotes}                 % write notes into the left margin
-\cnote{84}{It looks like Latin.}  % place note centered on help line 84
-\bnote{68}{Is this really Latin?} % align bottom of note to help line 68
-\tnote{16}{No, not Latin}         % align top of note to help line 16
+\cnote{84}{It looks like Latin.}  % place note vertically centered on guide 84
+\bnote{68}{Is this really Latin?} % align bottom of note to guide 68
+\tnote{16}{No, not Latin}         % align top of note to guide 16
 \end{leftnotes}                   % notes after this point go into the right margin
 
 \tnote{48}{You really should be writing proper Latin}
@@ -59,74 +78,103 @@
 \end{verbatim}
 \clearpage 
 
-\noindent This gives us the following output (only the first page is shown):
+\noindent The first page of the output is shown in Figure 1. When you have added all your comments, you can set the package option \texttt{grid=false} in order to hide the guides in the page margins. That is already the gist of it; some more options and a few tips and tricks will be given below.
 
-\begin{center}
-\includegraphics[width=\textwidth]{sample-for-docs}
-\end{center}
+\begin{figure}
+\centering
+\includegraphics[clip,trim=0 1.7in 0 1.7in,width=\textwidth,page=1]{sample}
+\caption{Frst page of the output produced by the sample listing above.}
+\end{figure}
 
-When you have added all your comments, you can set the package option \texttt{grid=false} in order to hide the help lines. That is essentially it, already; some more options and a few tips and tricks will be given below. 
-
 \section{Package options}
 
+\subsection{Options for controlling the selection and formatting of the source document}
+
 \begin{description}
 
-\option{sourcedoc}{file name}{noname} Name of the PDF file to be reviewed. The file extension (\texttt{.pdf}) can be omitted. 
+\option{sourcedoc}{file name}{noname} Name of the PDF file to be reviewed. The file extension (\texttt{.pdf}) can be omitted. If the file name of your source document contains spaces, be sure to include it in braces.
 
-\option{withnotesonly}{boolean}{false} By default, \texttt{pdfreview} will output every page that was mounted with \texttt{\textbackslash{}begin\textbraceleft page\textbraceright\ \ldots\ \textbackslash{}end\textbraceleft page\textbraceright}, even if no notes were placed on the page. If set to true, pages on which no notes were made will be omitted from the output. This can be useful to reduce file size. 
+\option{bodywidth}{number}{0.75} Width of the included source doc page, as fraction of \texttt{\textbackslash textwidth} of the wrapper document. The remainder of \texttt{\textbackslash textwidth} will be used for the margin notes. 
 
-Pages inserted with \texttt{\textbackslash{}begin\textbraceleft insertpage\textbraceright\ \ldots\ \textbackslash{}end\textbraceleft insertpage\textbraceright} will always be included in the output, regardless of whether or not they are empty.
+The default of 0.75 should be suitable in combination with \texttt{inline=true,twocolumn=false}, that is, with full note text in the right margin only (which is my own most common use case). Use smaller values with \texttt{inline=true,twocolumn=true} or larger ones with \texttt{inline=false}. 
 
+\option{trim}{length(s)}{1cm} How much to trim off the margins of each page of the source document. This option is passed to the \texttt{\textbackslash adjustbox} macro from the eponymous package. Accordingly, you can use two lengths to specify separate trimmings for horizontal and vertical margins, and four lengths to specify separate values for the left, lower, right, and top margins (in this order).%
+%
+\footnote{No, this order doesn't resemble a clock, fuel gauge, or anything else that mere mortals might have encountered.} 
+
+Note that multiple lengths values must be surrounded with braces, e.g.\ \texttt{trim=\textbraceleft 1cm 2cm\textbraceright} or \texttt{trim=\textbraceleft 1cm 2cm 0cm 1cm\textbraceright}. If you omit the braces, only the first length value will be used, and the others will be silently ignored. 
+
+\end{description}
+
+\subsection{Options for controlling the placement of notes}
+
+\begin{description}
+
 \option{twocolumn}{boolean}{false} If true, place included page in the middle and arrange for margin notes on both sides. If false, place included page on the left and have margin notes on the right hand side only. 
 
-\option{inline}{boolean}{true} If true, print the note text into the page margin. If false, print only the number of each note into the page margin. In the latter case, the note text will be collected and printed out as an \texttt{enumerate}'d list at the end of the document. Numbers in the margin and list items will be reciprocally hyperlinked.
+\option{inline}{boolean}{true} If true, print the note text into the page margin. If false, print only the number of each note into the page margin. In the latter case, the note text will be collected and printed out as an \texttt{enumerate}'d list at the end of the document. The items in this list and the corresponding numbers in the margin will be reciprocally hyperlinked.
 
 \option{notenumbers}{boolean}{false} If true, start each note with its number. If option \texttt{inline} is false, the number is printed regardless of this option. 
 
-\option{grid}{boolean}{true} Draw help lines for margin notes. 
+\option{alignnotes}{t,b, or c}{c} Vertical alignment of a margin note declared with |\note|. Can be overridden by passing \texttt{t} or \texttt{b} as an optional argument (e.g.~|\note[b]{Go boil your bottoms}| or |\note[t]{I shall taunt you a second time}|). 
 
-\option{gridcolor}{color name}{black!30} Color to use for help lines and line numbers. 
+\option{notesep}{length}{3pt} Empty space between included page and margin notes.
 
-\option{maxscale}{number}{100} Number of vertical length units/help lines for placing margin notes. If not divisible by 4, you will get a few ugly surplus lines at the top. 
+\option{staggered}{boolean}{true} If true, vertical overlap of one margin note by a second is avoided by pushing the second note downward below the first one. See section \ref{sec-overlap} for additional discussion.
 
-\option{stretch}{number}{1} By default, the vertical scale for placing margin notes is exactly as high as the first source document page. If that doesn't work well for some reason---for example, because you manually trim some pages more than others (see below)---then you can use this fudge factor to adjust the height of the scale manually. The scale will always be the same for all pages though.   
+\option{maxscale}{number}{100} Number of vertical length units/guides for placing margin notes---the height of the source doc page will be divided into \texttt{maxscale} units. If not divisible by 4, you will get a few ugly surplus lines at the top. 
 
-\option{bodywidth}{number}{0.75} Width of the included source doc page, as fraction of \texttt{\textbackslash textwidth} of the wrapper document. The remainder of \texttt{\textbackslash textwidth} will be used for the margin notes. 
+\end{description}
 
-The default of 0.75 should be suitable in combination with \texttt{inline=true,twocolumn=false}, that is, with full note text in the right margin only (which is my own most common use case). Use smaller values with \texttt{inline=true,twocolumn=true} or larger ones with \texttt{inline=false}. 
+\subsection{Options for controlling the appearance and formatting of notes and helplines}
 
-\option{trim}{length(s)}{1cm} How much to trim off the margins of each page of the source document. This option is passed to the \texttt{\textbackslash adjustbox} macro from the package by the same name. Accordingly, you can use two lengths to specify separate trimmings for horizontal and vertical margins, and four lengths to specify separate values for the left, lower, right, and top margins (in this order. No, it doesn't resemble a clock, fuel gauge, or anything else that mere mortals might have encountered). 
+\begin{description}
 
-Note that multiple lengths values must be surrounded with braces, e.g.\ \texttt{trim=\textbraceleft 1cm 2cm\textbraceright} or \texttt{trim=\textbraceleft 1cm 2cm 0cm 1cm\textbraceright}. If you omit the braces, only the first length value will be used, and the others will be silently ignored. 
-
-\option{alignnotes}{t,b, or c}{c} Vertical alignment of a margin note declared with |\note|. Can be overridden by passing \texttt{t} or \texttt{b} as an optional argument (e.g.~|\note[b]{Go boil your bottoms}| or |\note[t]{I shall taunt you a second time}|). 
-
 \option{notesbg}{color name or `none'}{yellow} Background color to use for the margin notes. If `none', the background will be transparent. 
 
 \option{notesframe}{color name or `none'}{black} Color to use for the box frame of the margin notes. If `none', no box is drawn. 
 
-\option{notesep}{length}{3pt} Empty space between included page and margin notes.
+\option{important}{frame color name}{red} Color to use for frame around notes declared with style `important' (e.g.\ |\tnote[important]{Important note!}|). Note that \texttt{important} is just a TikZ style declared inside the package; you can override this style with |\tikzset| take control of font, background color etc. 
 
-\option{fontsize}{string}{footnotesize} Font size to use for the margin notes. Use any of the usual font size commands, but without the backslash.
+\option{grid}{boolean}{true} Draw numbered guides for margin notes. 
 
-\option{pageoffset}{number}{0} This option only affects the PDF bookmarks for each page of the current document; it is intended to synchronize the bookmarks with the page numbers of the source document. 
+\option{gridcolor}{color name}{black!30} Color to use for help guides and their numbers. 
 
-By default, \pkgname simply numbers all included pages consecutively, starting with 1. If the source document has, say, 5 unnumbered (or Roman-numbered) pages preceding the proper page 1, you can declare this with \texttt{pageoffset=-5}; in this case, the first 5 pages will be given Roman numerals, and Arabic numbers will start (at 1) on the sixth physical page. Similarly, if the source document is missing some logical pages at the beginning, you can correct for this using a positive value for \texttt{pageoffset}.
+\option{fontsize}{string}{footnotesize} Font size to use for the margin notes (and also the numbers on the guides, if present). Use any of the usual font size commands, but without the backslash.
+\end{description}
 
-(As usual, the least useful options require the most explanation.)
 
+\subsection{Other options}
+\label{sec-options-other}
+
+\begin{description}
+
+\option{withnotesonly}{boolean}{false} By default, \texttt{pdfreview} will output every page that was mounted with \texttt{\textbackslash{}begin\textbraceleft page\textbraceright\ \ldots\ \textbackslash{}end\textbraceleft page\textbraceright}, even if no notes were placed on the page. When you set \texttt{withnotesonly=true}, pages on which no notes were made will be omitted from the output. This can be useful to reduce file size.
+
+Extra pages inserted with \texttt{\textbackslash{}begin\textbraceleft insertpage\textbraceright\ \ldots\ \textbackslash{}end\textbraceleft insertpage\textbraceright} will always be included in the output, regardless of whether or not they were left empty.
+
+
+\option{scaletopage}{number}{1} Page number of source document to use for scaling all pages. It sometimes happens that the first page of a PDF document has different proportions from the subsequent ones; in this case, you can use this option to scale to the second page (\texttt{scaletopage=2}) or another one. 
+
 \option{insertpagemargin}{length}{2.5cm} If you have comments of a general nature, or ones that don't fit comfortably into the page margin, you can put them on separate pages insert one or more empty pages using the \texttt{insertpage} environment (see below).
 
 By default, \pkgname leaves only very narrow empty page margins beyond the margin notes. For inserted text pages, it is more appropriate to use a wider margin; you can adjust it with this option. 
 
+\option{pageoffset}{number}{0} This option only affects the PDF bookmarks for each page of the current document; it is intended for synchronizing the bookmarks with the page numbers of the source document. 
+
+By default, \pkgname simply numbers all included pages consecutively, starting with 1. If the source document has, say, 5 unnumbered (or Roman-numbered) pages preceding the proper page 1, you can declare this with \texttt{pageoffset=-5}; in this case, the first 5 pages will be given Roman numerals, and Arabic numbers will start (at 1) on the sixth physical page. Similarly, if the source document is missing some logical pages at the beginning, you can correct for this using a positive value for \texttt{pageoffset}.%
+%
+\footnote{Attentive students of Korean appliance makers' owner's manuals will recognize this pattern---the least useful features require the most long-winded explanations.}
+
 \end{description}
 
 \section{Macros}
+\label{sec-macros}
 
 \begin{description}
 
 \item [{\texttt{\textbackslash note[\meta{alignment}]\marg{height}\marg{text}}}] 
-      The optional \texttt{alignment} argument is one of \texttt{b}, \texttt{c}, or \texttt{t}. The \meta{height} argument names the help line to align to; \meta{text} is the content of the note. (The \meta{height} argument doesn't have to be an integral number. Also, it can fall outside of the displayed help line scale, within reason.
+      The optional \texttt{alignment} argument is one of \texttt{b}, \texttt{c}, or \texttt{t}. The \meta{height} argument names the guide to align to; \meta{text} is the content of the note. (The \meta{height} argument doesn't have to be an integral number. Also, it can fall outside of the displayed guide scale, within reason.
       
       Note that the entire text of each note will go inside a \texttt{TikZ} node. This means you cannot use empty lines within a note to insert paragraphs. If you do need paragraphs, use the |\par| macro instead.
       
@@ -135,27 +183,44 @@
 
 \item [\texttt{\textbackslash sourcedoc}\marg{file name}] Set the file name of the PDF file whose pages are to be included. More commonly, this is done using the \texttt{sourcedoc} package option (see above). However, this macro can be used to switch to another source document halfway through. 
 
+\item [{\texttt{\textbackslash pagegrid[\meta{tikz settings}][\meta{steps}]}}] 
+
+Occasionally, you may want to place a note right on top of the source page instead of in the margin. To this end, the \texttt{page} environment can be used like a \texttt{tikzpicture} environment (see section \ref{sec-environments}). This macro assists by drawing a grid of horizontal and vertical guides over the source doc pages. If you leave the \meta{tikz settings} empty, the lines will be drawn in the same style as the guides for the margin notes, but you can use e.g.\ \texttt{\textbackslash pagegrid[red,\,thick]} to make them stand out more. The \meta{steps} parameter controls the density of the grid. The number of guides in each dimension is given by 100/\meta{steps}; the default is 10. 
+
 \end{description}
 
+\begin{figure}
+\centering
+\includegraphics[clip,trim=0 1.7in 0 1.7in,width=\textwidth,page=2]{sample}
+\caption{How to draw things on top of the included page, and how to muck up vertical spacing of the margin notes by misplacing a \texttt{leftnotes} environment.}
+\label{fig-drawing}
+\end{figure}
+
 \section{Environments}
+\label{sec-environments}
 
 \begin{description}
 
 \item [\texttt{\textbackslash begin\textbraceleft page\textbraceright [\meta{graphics options}]\marg{page number} \ldots\ \textbackslash end\textbraceleft page\textbraceright}] 
 
-This environment loads the physical page \meta{page number} from the source document and sets up the container for the margin notes. The formatting and scaling of the included page and of the margin notes is subject to the package options described earlier. 
+This environment loads the physical page \meta{page number} from the source document and sets up the containers for the margin notes. The formatting and scaling of the included page and of the margin notes is subject to the package options described earlier. 
 
 The optional \meta{graphics options} are passed to the \texttt{\textbackslash adjustbox} macro from the  package of the same name. You could use this for example to override the global \texttt{trim} package option for this one page, like so: \texttt{trim=\textbraceleft0cm 1cm\textbraceright}. 
 
+Another point to note is that the \texttt{page} environment can be used like a \texttt{tikzpicture} environment for drawing or placing nodes on top of the included source doc page. The dimension-less $x$ and $y$ units have been adjusted such that the point (0,\,0) is at the bottom left, and (100,\,100) is at the top right of the source doc page. That means you can say |\node[sticky] at (50,50) \{Sheesh!\}| to place some text smack-dab in the middle of the included page. (The \texttt{sticky} TikZ style will format the node text like the notes in the margin.) 
+You can use the |\pagegrid| macro to draw a grid of guides over the included page for this purpose (see section \ref{sec-macros} and Figure \ref{fig-drawing}).
+
 \item [\texttt{\textbackslash begin\textbraceleft leftnotes\textbraceright \ldots\ \textbackslash end\textbraceleft leftnotes\textbraceright}] 
 
-This environment goes inside a \texttt{page} environment. In \texttt{twocolumn} mode, it will move the enclosed |\note| macros to the left page margin; with \texttt{twocolumn=false} it does nothing, that is, notes enclosed in \texttt{leftnotes} will show up in the right margin. 
+This environment goes inside a \texttt{page} environment. In \texttt{twocolumn} mode, it will move the enclosed |\note| macros to the left page margin; with \texttt{twocolumn=false} it does nothing, that is, notes enclosed in \texttt{leftnotes} will also show up in the right margin. In this case, note that the \texttt{staggered=true} option will fail to prevent overlap between notes within and outside the \texttt{leftnotes} environment, respectively. 
 
-\item [\texttt{\textbackslash begin\textbraceleft rightnotes\textbraceright \ldots\ \textbackslash end\textbraceleft rightnotes\textbraceright}] Never does anything, ever; it only exists to avoid tripping up users who surmise its existence from that of the \texttt{leftnotes} environment. 
+There should be only one \texttt{leftnotes} environment within each \texttt{page} environment, and it should come either before or after all notes intended for the right margin. Otherwise, the mechanism for avoiding vertical overlap of margin notes that is activated by the package option \texttt{staggered=true} will not work properly.
 
+\item [\texttt{\textbackslash begin\textbraceleft rightnotes\textbraceright \ldots\ \textbackslash end\textbraceleft rightnotes\textbraceright}] A no-op; it only exists to avoid tripping up users who might surmise its existence from that of the \texttt{leftnotes} environment.
+
 \item [\texttt{\textbackslash begin\textbraceleft insertpage\textbraceright [\meta{heading}] \ldots\ \textbackslash end\textbraceleft insertpage\textbraceright}] 
 
-Inserts one or more extra pages for longer comments. These are not subject to any special formatting, except for the page margin, which can be set using a package option (see above). Alternatively, you can set the margins manually using |\newgeometry| and |\restoregeometry| from the \texttt{geometry} package, which is loaded by \pkgname. (The optional argument \meta{heading} defaults to ``General comments''.)
+Inserts one or more extra pages for longer comments. These are not subject to any special formatting, except for the page margin, which can be set using the \texttt{insertpagemargin} package option (see section \ref{sec-options-other}). Alternatively, you can set the margins manually using |\newgeometry| and |\restoregeometry| from the \texttt{geometry} package, which is loaded by \pkgname. (The optional argument \meta{heading} defaults to ``General comments''.)
 
 \end{description}
 
@@ -168,9 +233,12 @@
 The \texttt{geometry} package will be loaded to divide up the page. By default, \pkgname leaves 0.25 cm empty margins on both sides. If you load the \texttt{geometry} package yourself, \pkgname will respect your settings and not impose its own margin width. In that case, note that the entire content---included PDF page and margin notes---will go inside |\textwidth|. Any margins you declare using the \texttt{geometry} package will remain entirely empty. Also note that any \texttt{geometry} settings can be declared in the preamble only; if you try to change the margins within the document using |\newgeometry|, things will unravel. 
 
 \subsection{Vertical overlap of margin notes}
+\label{sec-overlap}
 
-There is no automatic mechanism that would prevent mutual overlap of margin notes; this has to be prevented manually. Where space is tight, it may help to use e.g.\ a |\bnote{60}{some note}| followed by a |\tnote{60}{another note}|; no space is wasted between both notes, yet at the same time they will not overlap. 
+Beginning with version 1.2, vertical overlap of margin notes can be prevented by using the package option \texttt{staggered=true}; this will cause any note that would overlap the preceding one to be pushed downwards (see Figure \ref{fig-drawing}). I myself use it all the time, and I have therefore made this the default.
 
+If for some reason you don't want to use this convenience, then you will have to prevent vertical overlap manually. Where space is tight, it may help to use e.g.\ a |\bnote{60}{some note}| followed by a |\tnote{60}{another note}|; no space is wasted between both notes, yet at the same time they will not overlap.
+
 The \texttt{bodywidth} package option also decides the horizontal and vertical space available for the margin notes. Should you decide half-way through to reduce the \texttt{bodywidth} parameter, this will create more horizontal space for the notes, but at the same time reduce the vertical space. This may occasionally create some new vertical overlap that would have to be fixed manually.
 
 Another consideration is what font to use for your notes, and at what size. Times is a nice, space-saving font (in pdfLaTeX, you can load it with |\usepackage{mathptmx}|). You can adjust the font size using the corresponding package option (e.g.~\texttt{fontsize=scriptsize}).
@@ -189,7 +257,7 @@
 
 Particularly when working with large source files, \pkgname can produce some startlingly large PDF output files. This problem is apparently related to the way |\includegraphics| works and has been described before (see \url{https://tex.stackexchange.com/questions/207527/}).
 %
-It can be amended by post-processing the output PDF file with ghostscript, for example: 
+It can often be amended by post-processing the output PDF file with ghostscript, for example: 
 
 \begin{verbatim}
 gs -sDEVICE=pdfwrite -dCompatibilityLevel=1.4 -dPDFSETTINGS=/printer -dNOPAUSE -dQUIET \
@@ -202,17 +270,17 @@
 mpalmer at holzkopf:/data$ pdfshrink.sh large.pdf
 \end{verbatim}
 
-\noindent An optional second argument controls the resolution of included bitmap graphics, with possible values (in order of decreasing resolution) \texttt{prepress}, \texttt{printer}, \texttt{default} (the default value), \texttt{ebook}, and \texttt{screen}. A  optional third argument can be used to indicate the output file name.  
+\noindent An optional second argument controls the resolution of included bitmap graphics, with possible values (in order of decreasing resolution) \texttt{prepress}, \texttt{printer}, \texttt{default} (the default value), \texttt{ebook}, and \texttt{screen}. A  optional third argument can be used to set the output file name.
 
 Again, you need to save the script in a directory listed in your shell's search path for this work. 
 
 \subsection{Uncooperative input files}
 
-Occasionally, I've run into source documents that failed to cooperate with the page-wise inclusion attempted by \pkgname. I got around that by first printing the recalcitrant PDF input file to another PDF file---or, alternatively, running through \texttt{pdfshrink}---and then using the resulting file as the source document instead. (This might also be useful on occasion when using the \texttt{pdfpages} package.)
+Occasionally, I've run into source documents that failed to cooperate with the page-wise inclusion attempted by \pkgname, and/or with the \texttt{pdfreview.sh} code generation script, which internally uses ghostscript. I got around that by first printing the recalcitrant PDF input file to another PDF file---or, as long as ghostscript wasn't the problem, running through the  \texttt{pdfshrink.sh} script---and then using the resulting file as the source document instead. (This might also be useful on occasion when using the \texttt{pdfpages} package.)
 
 \section{Implementation}
 
-This package depends on several others that are all in TeXLive. Among these is the \texttt{ulem} package, which makes the |\sout{strike me out}| command available for a strike-through effect. The \texttt{geometry} package is used for dividing up the page; if you load it yourself, your settings will be respected, as long you declare them in the preamble (but don't use |\newgeometry| halfway through the document). The \texttt{adjustbox} package is used to scale and trim the included pages, and also to scale the containers for the margin notes. The \texttt{environ} package is used to implement the \texttt{page} environment. The \texttt{tikz} package is used for placing help lines and margin notes. 
+This package depends on several others that are all in TeXLive. Among these is the \texttt{ulem} package, which makes the |\sout{strike me out}| command available for a strike-through effect. The \texttt{geometry} package is used for dividing up the page; if you load it yourself, your settings will be respected, as long you declare them in the preamble (but don't use |\newgeometry| halfway through the document). The \texttt{adjustbox} package is used to scale and trim the included pages, and also to scale the containers for the margin notes. The \texttt{environ} package is used to implement the \texttt{page} environment. The \texttt{tikz} package is used for placing guides and margin notes. 
       
 For further details, see the package file itself.
 
@@ -223,6 +291,18 @@
 
 \item [September 2017] corrections to documentation; added \texttt{withnotesonly} option (1.1)
 
+\clearpage 
+
+\item [February 2019] (version 1.2)
+
+    \begin{itemize}
+    \item added package options \texttt{staggered}, \texttt{important}, and \texttt{scaletopage}
+    \item removed \texttt{stretch} option
+    \item added |\pagegrid| macro
+    \item updated documentation 
+    \item updated auxiliary shell scripts to work with file names containing spaces, and to prevent loss of internal hyperlinks caused by ghostscript reprocessing
+    \end{itemize}
+
 \end{description}
 
 \section{License}

Modified: trunk/Master/texmf-dist/doc/latex/pdfreview/pdfshrink.sh
===================================================================
--- trunk/Master/texmf-dist/doc/latex/pdfreview/pdfshrink.sh	2019-02-23 15:52:13 UTC (rev 50099)
+++ trunk/Master/texmf-dist/doc/latex/pdfreview/pdfshrink.sh	2019-02-23 22:17:01 UTC (rev 50100)
@@ -1,34 +1,24 @@
 #!/bin/bash
+INPUTPDF="$1"
 
-# this script is part of the pdf-annotation LaTeX package by M. Palmer
-# like all files in the package, it is covered by the LPPL.
-
-# this assumes ghostscript is installed as 'gs - change as needed
-ghostscript="gs"
-
-script_name=`basename "$0"`
-
 if [ -z $1 ]; then
-   echo "Usage: $script_name inputfile.pdf [quality [outputfile]]"
+   echo "Usage: pdfshrink inputfile.pdf [quality [outputfile]]"
    exit 1
 fi
 
-input_pdf=$1
-
 # values for 'quality' argument:
-#
-# 'prepress' is highest quality
-# 'printer' or 'default' are 300dpi, both quite good
-# 'ebook' is 150 dpi; still reasonable on screen
-# 'screen' is 72dpi - looks poor
+# 
+# 'prepress' is highest quality,
+# 'ebook' is only 150 dpi
+# 'screen' is 72dpi - looks very poor
+# 'printer' and 'default' are good compromises
 
 
-if [ ! -f $input_pdf ]; then
-   echo "file $input_pdf not found"
+if [ ! -f "$INPUTPDF" ]; then
+   echo "file $INPUTPDF not found"
    exit 1
 fi
 
-# let quality default to 'default'
 quality=${2-default}
 
 if [ $quality = 'default' ]; then
@@ -37,16 +27,16 @@
     suffix=$quality
 fi
 
-output_pdf=${3-${1%.pdf}-${suffix}}
-output_pdf=${output_pdf%.pdf}.pdf
+OUTPUTPDF="${3-${1%.pdf}-${suffix}}"
+OUTPUTPDF="${OUTPUTPDF%.pdf}.pdf"
 
-echo "converting $input_pdf to $output_pdf using quality '$quality'"
+echo "converting $INPUTPDF to $OUTPUTPDF using quality '$quality'"
 
-$ghostscript \
-   -sDEVICE=pdfwrite \
+gs -sDEVICE=pdfwrite \
    -dCompatibilityLevel=1.4 \
    -dHaveTransparency=true \
    -dFastWebView=true \
+   -dPrinted=false \
    -dPDFSETTINGS=/$quality \
    -dEmbedAllFonts=true \
    -dSubsetFonts=true \
@@ -53,8 +43,8 @@
    -dNOPAUSE \
    -dQUIET \
    -dBATCH \
-   -sOutputFile="$output_pdf" \
-   "$input_pdf"
+   -sOutputFile="$OUTPUTPDF" \
+   "$INPUTPDF" 2> /dev/null
 
-chmod 644 "$output_pdf"
+chmod 644 "$OUTPUTPDF"
 echo "done"

Deleted: trunk/Master/texmf-dist/doc/latex/pdfreview/sample-for-docs.pdf
===================================================================
(Binary files differ)

Added: trunk/Master/texmf-dist/doc/latex/pdfreview/sample.pdf
===================================================================
(Binary files differ)

Index: trunk/Master/texmf-dist/doc/latex/pdfreview/sample.pdf
===================================================================
--- trunk/Master/texmf-dist/doc/latex/pdfreview/sample.pdf	2019-02-23 15:52:13 UTC (rev 50099)
+++ trunk/Master/texmf-dist/doc/latex/pdfreview/sample.pdf	2019-02-23 22:17:01 UTC (rev 50100)

Property changes on: trunk/Master/texmf-dist/doc/latex/pdfreview/sample.pdf
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+application/pdf
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/pdfreview/sample.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/pdfreview/sample.tex	                        (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/pdfreview/sample.tex	2019-02-23 22:17:01 UTC (rev 50100)
@@ -0,0 +1,66 @@
+\documentclass[letterpaper,10pt]{article}
+\usepackage{lipsum,mathptmx}
+
+\pagestyle{empty}
+
+\usepackage[
+  sourcedoc={lorem-ipsum.pdf},    % use braces if the file name contains spaces
+  grid=true,                      % set to false to remove help lines when done
+  staggered=true,                 % avoid overlap between notes 
+  trim={2cm},                     % trim source doc pages by 2cm all around
+  bodywidth=0.66,                 % use 2/3 of the page width for the source doc
+  twocolumn=true,                 % have two columns of notes, left and right
+]{pdfreview}
+
+
+\begin{document}
+
+\begin{page}{1}                   % mount the first page
+
+\begin{leftnotes}                 % write notes into the left margin
+\cnote{84}{It looks like Latin.}  % place note centered on help line 84
+\bnote{68}{Is this really Latin?} % align bottom of note to help line 68
+\tnote{16}{No, not Latin}         % align top of note to help line 16
+\end{leftnotes}                   % notes after this point go into the right margin
+
+\tnote[important]{48}{Important note: You really should be writing proper Latin}
+\cnote{12}{Cite your references}
+\end{page}
+
+\begin{page}{2}
+\pagegrid[red][20] % draw a grid of guides on top of source doc page - comment out when done
+
+% place node on top of source doc page. Default x and y units in are scaled
+% to 1/100 of width and height of source doc
+\node[sticky,anchor=center, text width=1.5in] at (50,65) {You can draw on top of the page, too, using dimension-less units ranging from 0 to 100 for both $x$ and $y$.};
+
+% draw an ellipse in the center of the page
+\draw[blue, thick](50,50) circle (20 and 10);
+
+\begin{leftnotes}
+\cnote{69}{With \texttt{staggered=true}, there can be only one \texttt{leftnotes} environment, and it must come either before or after all of the notes on the right}
+\end{leftnotes}
+
+\tnote{80}{This note should top-align to 80 and then prattle on for a little bit}
+\tnote{76}{This note is declared to top-align to 76, but it gets pushed downward to not overlap the previous one, because we use option \texttt{\textbackslash staggered=true}}
+\tnote{90}{And this note, even though declared to top-align to 90, will be pushed down below the previously declared one}
+
+\tnote{52}{With \texttt{staggered=true}, there can be only one \texttt{leftnotes} environment, and it must come either before or after all of the notes on the right. This is because \texttt{leftnotes} resets the staggering mechanism.}
+
+\begin{leftnotes}
+\cnote{50}{With \texttt{staggered=true}, there can be only one \texttt{leftnotes} environment, and it must come either before or after all of the notes on the right. This is because \texttt{leftnotes} resets the staggering mechanism. This note is declared in a separate \texttt{leftnotes} environment and therefore overlaps the preceding one.}
+\end{leftnotes}
+
+\tnote{36}{This note is separated from the preceding one by a \texttt{leftnotes} environment, and therefore overlaps it.}
+
+\end{page}
+
+\begin{insertpage}
+This is an example of the \texttt{insertpage} environment.
+
+\lipsum[1-3]
+\end{insertpage}
+
+\end{document}
+
+


Property changes on: trunk/Master/texmf-dist/doc/latex/pdfreview/sample.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Modified: trunk/Master/texmf-dist/tex/latex/pdfreview/pdfreview.sty
===================================================================
--- trunk/Master/texmf-dist/tex/latex/pdfreview/pdfreview.sty	2019-02-23 15:52:13 UTC (rev 50099)
+++ trunk/Master/texmf-dist/tex/latex/pdfreview/pdfreview.sty	2019-02-23 22:17:01 UTC (rev 50100)
@@ -2,8 +2,26 @@
 % (see \url{http://www.latex-project.org/lppl.txt}). 
 % Please report bugs to the author (Michael Palmer, mpalmer at uwaterloo.ca) 
 
+% modifications since 1.1:
+% - added second optional argument to \note (tikz code)
+% - expunged package ifthen, since we require etoolbox anyway
+% - added package name to default pdfcreator string
+% - added 'important' option for applying different note formatting
+% - added 'staggered' option to prevent overlapping placement of notes
+% - added 'scaletopage' option to pick a page other than the first one
+%   in case that one has an atypical size, as sometimes happens. 
+% - added \pagegrid user macro to draw a grid of helplines over top
+%   the included source page.
+
+% In the docs, we should tell the users that the page environment is, in fact,
+% a tikzpicture - so they can use nodes etc inside it. Maybe we should 
+% specify a relative unit for the x axis also? yes, we do now. we also shift
+% the scope, so that the origin is always at the bottom left of the source page. 
+% we also need to add to the docs that the leftnotes env can stay - you don't 
+% need to remove it when you set twocolumn to false. 
+
 \NeedsTeXFormat{LaTeX2e}[1999/12/01]
-\ProvidesPackage{pdfreview}[2017/09/22 v1.10]
+\ProvidesPackage{pdfreview}[2019/02/22 v1.20]
 
 \RequirePackage{
     adjustbox,
@@ -10,14 +28,15 @@
     calc,
     environ,
     etoolbox,
+    fp,
     graphicx,
-    ifthen,
     kvoptions,
     tikz,
+    twoopt,
     xstring
 }
 
-\usetikzlibrary{calc}
+\usetikzlibrary{calc,arrows,positioning}
 
 % improve file name handling
 \RequirePackage[extendedchars,space]{grffile}
@@ -35,20 +54,23 @@
 \DeclareBoolOption[false]{notenumbers}
 \DeclareBoolOption[true]{inline}
 \DeclareBoolOption[false]{withnotesonly}
+\DeclareBoolOption[false]{staggered}
 %
+\DeclareStringOption[1]{scaletopage}
 \DeclareStringOption[black!30]{gridcolor}
 \DeclareStringOption[0.75]{bodywidth}
-\DeclareStringOption[1cm]{trim}
+\DeclareStringOption[{1cm 1cm 1cm 1cm}]{trim}
+\DeclareStringOption[0cm]{trimshift}
 \DeclareStringOption[0.5pt]{bodyframe}
 \DeclareStringOption[noname]{sourcedoc}
 \DeclareStringOption[0]{pageoffset}
 \DeclareStringOption[c]{alignnotes}
 \DeclareStringOption[yellow]{notesbg}
+\DeclareStringOption[red]{important}
 \DeclareStringOption[black]{notesframe}
 \DeclareStringOption[3pt]{notesep}
 \DeclareStringOption[footnotesize]{fontsize}
 \DeclareStringOption[100]{maxscale}
-\DeclareStringOption[1]{stretch}
 \DeclareStringOption[2.5cm]{insertpagemargin}
 
 \ProcessKeyvalOptions*
@@ -57,13 +79,17 @@
 % count spaces
 \StrCount{\prv at trim}{ }[\prv at trimspaces]
 
-\ifthenelse{\equal{\prv at trimspaces}{0}}%
+\typeout{trim option: \prv at trim}
+\typeout{trim spaces: \prv at trimspaces}
+
+% \ifstrequal from etoolbox doesn't work here
+\IfEq{\prv at trimspaces}{0}%
   % no spaces - trim all four sides the same 
   {\edef\prv at trimleft{\prv at trim}%
    \edef\prv at trimright{\prv at trim}%
    \edef\prv at trimtop{\prv at trim}%
    \edef\prv at trimbottom{\prv at trim}%
-  }{\ifthenelse{\equal{\prv at trimspaces}{1}}%
+  }{\IfEq{\prv at trimspaces}{1}%
   % one space - apply separate trimming to h and v
   {\StrCut{\prv at trim}{ }{\prv at trimh}{\prv at trimv}%
    \edef\prv at trimleft{\prv at trimh}%
@@ -75,6 +101,13 @@
    \StrCut{\prv at trimtwo}{ }{\prv at trimbottom}{\prv at trimthree}%
    \StrCut{\prv at trimthree}{ }{\prv at trimright}{\prv at trimtop}}}
 
+\newcommand{\resettrim}[1][0pt]{% may be needed for figure pages
+   \edef\prv at trimleft{#1}%
+   \edef\prv at trimright{#1}%
+   \edef\prv at trimtop{#1}%
+   \edef\prv at trimbottom{#1}%
+}
+
 \newcommand{\sourcedoc}{\prv at sourcedoc}
 
 % control the split between the included page and the notes pane
@@ -81,9 +114,17 @@
 \newlength{\prv at noteswidth}
 \newlength{\prv at sourcebodywidth}
 \newlength{\prv at bodyoffset}
-\newlength{\prv at rightnotesoffset}
+\newlength{\prv at notesxoffset}
 \newlength{\prv at bodypadding}
 
+% a length for keeping track of bottom of the last note, 
+% to guard against vertical overlap 
+\newlength{\prv at currentnotebottom}
+\newlength{\prv at requestedbottom}
+\newlength{\prv at workingbottom}
+\newlength{\prv at notesboxheight}
+\newcommand{\prv at anchor}{west}
+
 % empty space between body and notes 
 \setlength{\prv at bodypadding}{\prv at notesep}
 
@@ -102,11 +143,14 @@
 \setlength{\prv at helpnumwidth}{\widthof{\prv at notesfont$\prv at maxscale$}+2\prv at xsep}
 
 \RequirePackage[hidelinks]{hyperref}
+\hypersetup{pdfcreator={LaTeX with the pdfreview package}}
 \RequirePackage{bookmark}
 
 \newlength{\prv at notestextwidth}
 \newlength{\prv at pageheight}
 \newlength{\prv at unitheight}
+\newlength{\prv at unitwidth}
+
 \newlength{\prv at currentheight}
 
 \newsavebox{\prv at pagebox}
@@ -113,13 +157,21 @@
 \newsavebox{\prv at gridboxright}
 \newsavebox{\prv at gridboxleft}
 
+% global setlength - from https://tex.stackexchange.com/questions/406015/
+\gdef\gsetlength#1#2{%
+  \begingroup
+    \setlength\skip@{#2}
+    \global#1=\skip@
+  \endgroup
+}
+
 \tikzset{
-  notesfont/.style={
+  notesfont/.style={ % used for both notes and help line numbers
     font=\prv at notesfont
   },
   %
-  notes/.style={
-    notesfont,
+  sticky/.style={     % set font and graphics, but not size or anchor
+    notesfont,        % operation will shift the whole page up. 
     draw=\prv at notesframe,
     fill=\prv at notesbg,
     rounded corners=0.5pt,
@@ -127,10 +179,35 @@
     inner ysep=0.4\ht\prv at charbox,
     outer ysep=0.5pt,
     outer xsep=0pt,
+  },
+  %   
+  notes/.style={
+    sticky,
+    anchor=south west,% 't has to be this way, otherwise, the sbox 
     text width=\prv at notestextwidth,
-    text height=\ht\prv at charbox
+    text height=\ht\prv at charbox,
+    alias=NN,
+    append after command={
+      \pgfextra{ % calculate and globally save node height
+        % simplified for height only, from Alain Matthes answer
+        % to https://tex.stackexchange.com/questions/38473/ 
+        % the reason for this is that within tikzpicture the 
+        % \ht operator doesn't work on saveboxes for some reason.
+        % so we are forced to extract the height from the node. 
+        \coordinate (A) at (NN.south);
+        \coordinate (B) at (NN.north);
+        \pgfpointdiff{\pgfpointanchor{A}{center}}%
+                     {\pgfpointanchor{B}{center}}%
+        \pgfmathsetlength{\global\prv at notesboxheight}{\pgf at y}
+      }
+    }
   },
   %
+  important/.style={
+    notes,
+    draw=\prv at important
+  },
+  %
   helpnum/.style={
     notesfont,
     draw=none,
@@ -159,11 +236,13 @@
   },
   %
   hypertarget/.style={
-    notes,
+    draw=none,
+    inner sep=0pt,
+    outer sep=0pt,
     alias=targetnode,
     append after command={
-      let \p1=(targetnode.north west) in
-      node[draw=none,at=(\p1)] {\hypertarget{#1}{}}
+      node[draw=none,above of=targetnode,yshift=\prv at notesboxheight]
+      {\hypertarget{#1}{}}
     }
   },
   %
@@ -178,18 +257,18 @@
       node [inner sep=0pt, outer sep=0pt,anchor=north west,at=(\p1)] 
       {\hyperlink{#1}{\phantom{\rule{\n1}{\n2}}}}
     }
-  }
+  },
 }
 
 \newcommand{\prv at drawgridboxright}{%
-  \ifthenelse{\ht\prv at gridboxright<10}{%
+  \ifnumless{\ht\prv at gridboxright}{10}{%
     \global\sbox{\prv at gridboxright}{%
     \begin{tikzpicture}[y=\prv at unitheight,grid]%
     \foreach \y in {0, 4, ..., \prv at maxscale}{%
       \begin{scope}[yshift=\y\prv at unitheight]%
         \draw (0,0) -- ++(\prv at noteswidth-\prv at helpnumwidth,0) node[helpnum,anchor=west]{$\y$};
-        \ifthenelse{\equal{\y}{\prv at maxscale}}{}{%
-        \foreach \z/\w in {1/0.25,2/0.5,3/0.25}{%
+        \ifnumequal{\y}{\prv at maxscale}{}{%
+        \foreach \z/\w in {1/1,2/2.5,3/1}{%
            \draw (0,\z) -- ++(\w,0);
         }}%
       \end{scope}
@@ -199,15 +278,14 @@
 }
 
 \newcommand{\prv at drawgridboxleft}{%
-  \ifthenelse{\ht\prv at gridboxleft<10}{%
+  \ifnumless{\ht\prv at gridboxleft}{10}{%
     \global\sbox{\prv at gridboxleft}{%
     \begin{tikzpicture}[y=\prv at unitheight,grid,xscale=-1]%
-    %\draw[blue](0,0) rectangle (\prv at noteswidth,\prv at pageheight);
     \foreach \y in {0, 4, ..., \prv at maxscale}{%
       \begin{scope}[yshift=\y\prv at unitheight]%
         \draw (0,0) -- ++(\prv at noteswidth-\prv at helpnumwidth,0) node[helpnum,anchor=east]{$\y$};
-        \ifthenelse{\equal{\y}{\prv at maxscale}}{}{%
-        \foreach \z/\w in {1/0.25,2/0.5,3/0.25}{%
+        \ifnumequal{\y}{\prv at maxscale}{}{%
+        \foreach \z/\w in {1/1,2/2.5,3/1}{%
            \draw (0,\z) -- ++(\w,0);
         }}%
       \end{scope}
@@ -223,16 +301,67 @@
 \newbool{prv at isempty}
 \setbool{prv at isempty}{true}
 
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%5
+% boolean that is set if code executes inside page environment
+\newbool{prv at inpage}
+\setbool{prv at inpage}{false}
 
+% flag for noteslist
+\newbool{prv at noteslistempty}
+\setbool{prv at noteslistempty}{true}
+
 \newsavebox{\prv at wrapper}
 
+\newlength{\prv at leftshifted}
+\newlength{\prv at rightshifted}
+
+% flag for initial scaling - we scale dimensions to the first included page
+\newbool{prv at initialscaling}
+\setbool{prv at initialscaling}{false}
+
+\newcommand{\prv at scaledo}{%
+    \gsetlength{\prv at sourcebodywidth}{\prv at bodywidth\textwidth}%
+    \ifprv at twocolumn%
+        \gsetlength{\prv at noteswidth}{0.5\textwidth-0.5\prv at sourcebodywidth-\prv at bodypadding}%
+        \gsetlength{\prv at bodyoffset}{\prv at noteswidth+\prv at bodypadding-\prv at bodyframe}%
+    \else%
+        \gsetlength{\prv at noteswidth}{\textwidth-\prv at sourcebodywidth-\prv at bodypadding}%
+        \gsetlength{\prv at bodyoffset}{0pt}%
+    \fi%
+    % the x offset for the notes is a bit surprising, because the effective 
+    % offset gets altered by the savebox mechanism. This value applies to 
+    % the notes in the right margin; for the left margin, we override it locally
+    % in the leftnotes environment. 
+    \gsetlength{\prv at notesxoffset}{\textwidth-\prv at noteswidth}%
+    \gsetlength{\prv at notestextwidth}{\prv at noteswidth-\prv at helpnumwidth-2\prv at xsep}%
+    \sbox{\prv at pagebox}{%
+        {\setlength{\fboxsep}{0pt}%
+        \adjustbox{clip,trim=\prv at trimleft{} \prv at trimbottom{} \prv at trimright{} \prv at trimtop{},%
+                   width=\prv at sourcebodywidth,fbox=\prv at bodyframe}%
+                   {\includegraphics[page=\prv at scaletopage]%
+                   {\sourcedoc}}%
+    }}%
+    \gsetlength{\prv at pageheight}{\ht\prv at pagebox}%
+    \gsetlength{\prv at unitheight}{\prv at pageheight/\prv at maxscale}%
+    \gsetlength{\prv at unitwidth}{\prv at sourcebodywidth/\prv at maxscale}%
+    \global\setbool{prv at initialscaling}{true}
+}
+
 \NewEnviron{page}[2][]{%
-% now, start the actual page content. we use a minipage for vertical centering
-%
+\ifbool{prv at initialscaling}%
+  {}%
+  {\prv at scaledo}% use first page to scale internal length parameters
 \clearpage%
+% first, lets adjust the horizontal shifting
+\ifnumodd{#2}%
+    {\setlength{\prv at leftshifted}{\prv at trimleft+\prv at trimshift}%
+     \setlength{\prv at rightshifted}{\prv at trimright-\prv at trimshift}}
+    {\setlength{\prv at leftshifted}{\prv at trimleft-\prv at trimshift}%
+     \setlength{\prv at rightshifted}{\prv at trimright+\prv at trimshift}}
+
+%\setlength{\prv at currentnotebottom}{\prv at pageheight}%
+\pgfmathsetlength{\global\prv at currentnotebottom}{\prv at pageheight}%
 \setcounter{prv at offsetpage}{#2+\prv at pageoffset}%
-\ifthenelse{\value{prv at offsetpage}<1}%
+\ifnumless{\value{prv at offsetpage}}{1}%
   {\renewcommand*{\prv at pagelabel}{\roman{page}}}%
   {\renewcommand*{\prv at pagelabel}{\arabic{prv at offsetpage}}}%
 \ifbool{prv at withnotesonly}{}%
@@ -242,7 +371,7 @@
 \noindent\begin{minipage}[c][\textheight]{\textwidth}%
 \noindent\begin{center}%
 \begin{adjustbox}{width=\textwidth}%
-\begin{tikzpicture}[y=\prv at unitheight]%
+\begin{tikzpicture}[x=\prv at unitwidth,y=\prv at unitheight,node distance=3pt]%
 \ifprv at twocolumn
   \ifprv at grid
     \node[boxnode] at (0,0){\prv at drawgridboxleft};
@@ -258,21 +387,26 @@
 \begin{scope}
 \setlength{\fboxsep}{0pt}
 \node[boxnode] at (\prv at bodyoffset,0) 
-    {\adjustbox{clip, trim=\prv at trimleft{} \prv at trimbottom{} \prv at trimright{} \prv at trimtop{},%
+    {\adjustbox{clip, trim=\prv at leftshifted{} \prv at trimbottom{} \prv at rightshifted{} \prv at trimtop{},%
                #1,width=\prv at sourcebodywidth,fbox=\prv at bodyframe}%
-               {\includegraphics[page=#2]{\sourcedoc}}};%
+               {\includegraphics[page=#2]{\sourcedoc}%
+                }};%
 \end{scope}
-\begin{scope}[xshift=\prv at rightnotesoffset]%
-%}%
+% create a scope that overlays with the source page, in both
+% one- and two-column mode
+\begin{scope}[xshift=\prv at bodyoffset]
 %
+\global\setbool{prv at inpage}{true}
 \BODY
-%{
-\end{scope}\end{tikzpicture}%
+\global\setbool{prv at inpage}{false}
+%
+\end{scope}
+\end{tikzpicture}%
 \end{adjustbox}%
 \end{center}%
 \end{minipage}%
 \end{lrbox}
-%\ifbool{prv at isempty}%
+%
 \ifboolexpr{bool {prv at isempty} and bool {prv at withnotesonly}}%
   {\global\deadcycles=0}%
   {\noindent\usebox{\prv at wrapper}}%
@@ -279,61 +413,114 @@
 \global\setbool{prv at isempty}{true}\ignorespaces
 }
 
-\newenvironment{leftnotes}%
-{\ifprv at twocolumn
-   \begin{scope}[xshift=\prv at helpnumwidth-\prv at rightnotesoffset]%
- \else%
-   \begin{scope}
- \fi}
+\newenvironment{leftnotes}% locally override the xoffset for the notes. 
+{\ifprv at twocolumn%
+  \setlength{\prv at notesxoffset}{\prv at helpnumwidth}%
+\fi%
+% allow notes to start from the top again in staggered mode
+ % simple \setlength fails here, but \pgfmathsetlength works
+\pgfmathsetlength{\global\prv at currentnotebottom}{\prv at pageheight}}
 %
-{\end{scope}}
+{\pgfmathsetlength{\global\prv at currentnotebottom}{\prv at pageheight}}
 
-% a no-op environment for the bureaucratically inclined
+% a matching no-op environment for the bureaucratically inclined
 \newenvironment{rightnotes}{}{}
 
 % use an insertpage environment for putting out the list of notes if requested
-\newcommand{\prv at noteslist}{\begin{insertpage}[List of notes]\begin{enumerate}}
+\newcommand{\prv at noteslist}{\begin{listofnotes}\begin{enumerate}}
 
-\newcommand{\prv at notealignment}{north west}
 \newcounter{note}
+\newsavebox{\prv at notesbox}
 
-\newcommand{\note}[3][\prv at alignnotes]{%
-\ifbool{prv at isempty}%
-  {%
-    \ifbool{prv at withnotesonly}%
-      {\phantomsection%
-       \bookmark[level=1,page=\arabic{page}]{p. \prv at pagelabel}}{}%
-    \global\setbool{prv at isempty}{false}%
-  }%
-  {}%
-\stepcounter{note}%
-\ifthenelse{\equal{#1}{b}}{\renewcommand{\prv at notealignment}{south west}}{%
-  \ifthenelse{\equal{#1}{t}}{\renewcommand{\prv at notealignment}{north west}}{%
-  \renewcommand{\prv at notealignment}{west}}}
-%
-\ifprv at inline
-    \node[anchor=\prv at notealignment,hypertarget=note\arabic{note}] at (0,#2){%
-    \bookmark[level=2,dest=note\arabic{note}]{Note \arabic{note}}%
-    \raggedright\setlength{\parindent}{1em}\noindent%
-      \ifprv at notenumbers\arabic{note})\ \fi%
-      #3
-    };
-\else
-    \node[anchor=\prv at notealignment,hypertarget=note\arabic{note},%
-          hyperlink=noteitem\arabic{note}] at (0,#2){%
-    \bookmark[level=2,dest=note\arabic{note}]{Note \arabic{note}}%
-    \raggedright\setlength{\parindent}{1em}\noindent%
-    \g at addto@macro\prv at noteslist{\item \hypertarget{noteitem\arabic{enumi}}{}{#3}%
-                                  \hyperlink{note\arabic{enumi}}{~$\uparrow$}}%
-    \arabic{note}.
-    };
-\fi
-}%
+\newcommand{\prv at calcbottom}[2]{% 
+  % calculate bottom y to place next note on
+  % arguments: requested y pos, alignment. All other variables are global 
+  %
+  % scale requested bottom position to source page height
+  \FPdiv{\prv at bottomratio}{#1}{\prv at maxscale}%
+  \setlength{\prv at requestedbottom}{\prv at bottomratio\prv at pageheight}%
+  % correct requested bottom position for alignment
+  \ifstrequal{#2}{b}%
+    {}%
+    {\ifstrequal{#2}{c}%
+      {\addtolength{\prv at requestedbottom}{-0.5\prv at notesboxheight}}%
+      {\addtolength{\prv at requestedbottom}{-\prv at notesboxheight}}}%
+  % adjust actual position to avoid overlap where needed. It seems we need two 
+  % steps, since pgf is needed to make it stick globally, but it doesn't take 
+  % the \minof operator. Oooh the manifold joys of LaTeX. 
+  \ifprv at staggered%
+    \setlength{\prv at workingbottom}{\prv at currentnotebottom-\prv at notesboxheight}
+    \gsetlength{\prv at currentnotebottom}%
+        {\minof{\prv at requestedbottom}{\prv at workingbottom}}
+  \else%
+    \gsetlength{\prv at currentnotebottom}{\prv at requestedbottom}%
+  \fi%
+}
 
-\newcommand{\cnote}[2]{\note[c]{#1}{#2}}
-\newcommand{\bnote}[2]{\note[b]{#1}{#2}}
-\newcommand{\tnote}[2]{\note[t]{#1}{#2}}
+% draw a grid of help lines over the source page. We don't 
+% use this as a global option, and the optional argument 
+% to the page environment is already taken; therefore, it 
+% just goes into a user macro. 
+\newcommandtwoopt{\pagegrid}[2][][10]{%
+  \foreach \x in {0,#2,...,100}{
+    \draw[very thin,\prv at gridcolor,#1](0,\x) -- (100,\x);
+    \draw[very thin,\prv at gridcolor,#1](\x,0) -- (\x,100);
+}}
 
+\newcommand{\prv at importantitem}{\bfseries}% 
+
+\newcommandtwoopt{\note}[4][\prv at alignnotes][]{%
+\ifbool{prv at inpage}{%
+    \ifbool{prv at isempty}%
+      {%
+        \ifbool{prv at withnotesonly}%
+          {\phantomsection%
+           \bookmark[level=1,page=\arabic{page}]{p. \prv at pagelabel}}{}%
+        \global\setbool{prv at isempty}{false}%
+      }%
+      {}%
+    \stepcounter{note}%
+    %
+    \begin{scope}[xshift=-\prv at bodyoffset]
+    \ifprv at inline
+        \sbox\prv at notesbox{\node[notes,#2] {%
+        \vspace{-\baselineskip}\newline% hack to force enough height for tabulars
+        \raggedright\setlength{\parindent}{1em}\noindent%
+          \ifprv at notenumbers\arabic{note})\ \fi%
+          #4
+        };}
+        \prv at calcbottom{#3}{#1}
+        \node[hypertarget=note\arabic{note}] at (\prv at notesxoffset,\prv at currentnotebottom){%
+        \bookmark[level=2,dest=note\arabic{note}]{Note \arabic{note}}\usebox{\prv at notesbox}};
+    \else
+        \sbox\prv at notesbox{\node[notes,#2]{12345.};}
+        \prv at calcbottom{#3}{#1}
+        \node[hypertarget=note\arabic{note},hyperlink=noteitem\arabic{note}]
+               at (\prv at notesxoffset,\prv at currentnotebottom){%
+        \bookmark[level=2,dest=note\arabic{note}]{Note \arabic{note}}%
+        \raggedright\setlength{\parindent}{1em}\noindent%
+        \global\setbool{prv at noteslistempty}{false}
+        \IfSubStr{#2}{important}%
+            {\g at addto@macro\prv at noteslist{\item%
+                 \hypertarget{noteitem\arabic{enumi}}{}{\prv at importantitem{}#4}%
+                 \hyperlink{note\arabic{enumi}}{~$\uparrow$}}}%
+            {\g at addto@macro\prv at noteslist{\item%
+                 \hypertarget{noteitem\arabic{enumi}}{}{#4}%
+                 \hyperlink{note\arabic{enumi}}{~$\uparrow$}}}%
+        %
+        \arabic{note}.
+        };
+    \fi
+    \end{scope}}
+    {\PackageWarning{pdfreview}{Not typesetting note outside of page environment}}%
+}% end \note
+
+\newcommand{\cnote}[3][]{\note[c][#1]{#2}{#3}}
+\newcommand{\bnote}[3][]{\note[b][#1]{#2}{#3}}
+\newcommand{\tnote}[3][]{\note[t][#1]{#2}{#3}}
+
+\newcommandtwoopt{\remark}[3][100][c]{\note[#2]{#1}{#3}}
+
 % provide for extra pages with text
 \newenvironment{insertpage}[1][General comments]%{}{}%
 {\clearpage%
@@ -343,34 +530,32 @@
 %
 {\clearpage\aftergroup\restoregeometry}
 
+% noteslist is like insertpage, except that we don't restore the geometry
+% this will keep the modified margins in place for other appendices like 
+% bibliographies
+\newenvironment{listofnotes}%
+{\clearpage%
+\phantomsection\addcontentsline{toc}{section}{List of notes}%
+\newgeometry{margin=\prv at insertpagemargin}
+\section*{List of notes}}
+%
+{\clearpage}
 
+
 \AtBeginDocument{% divide up the page. Use package geometry if not yet loaded by user. 
     \@ifpackageloaded{geometry}{}% use of both package options and \newgeometry is intentional. 
         {\RequirePackage[hmargin=0.25cm,vmargin=2.5cm]{geometry}%
          \newgeometry{hmargin=0.25cm,vmargin=2.5cm}}%
-    \setlength{\prv at sourcebodywidth}{\prv at bodywidth\textwidth}%
-    \ifprv at twocolumn%
-        \setlength{\prv at noteswidth}{0.5\textwidth-0.5\prv at sourcebodywidth-\prv at bodypadding}%
-        \setlength{\prv at bodyoffset}{\prv at noteswidth+\prv at bodypadding-\prv at bodyframe}%
-    \else%
-        \setlength{\prv at noteswidth}{\textwidth-\prv at sourcebodywidth-\prv at bodypadding}%
-        \setlength{\prv at bodyoffset}{0pt}%
-    \fi%
-    \setlength{\prv at rightnotesoffset}{\textwidth-\prv at noteswidth}%
-    \setlength{\prv at notestextwidth}{\prv at noteswidth-\prv at helpnumwidth-2\prv at xsep}%
-    \sbox{\prv at pagebox}{%
-      {\setlength{\fboxsep}{0pt}%
-      \adjustbox{clip,trim=\prv at trimleft{} \prv at trimbottom{} \prv at trimright{} \prv at trimtop{},%
-                 width=\prv at sourcebodywidth,fbox=\prv at bodyframe}{\includegraphics[page=1]{\sourcedoc}}%
-    }}%
-    \setlength{\prv at pageheight}{\ht\prv at pagebox}%
-    \setlength{\prv at unitheight}{\prv at stretch\prv at pageheight/\prv at maxscale}%
 }%
 
 \AtEndDocument{%
 \ifprv at inline% do nothing
 \else% close the notes list and print it out
-  \g at addto@macro\prv at noteslist{\end{enumerate}\end{insertpage}}
-  \clearpage
-  \prv at noteslist
-\fi}
\ No newline at end of file
+    \ifbool{prv at noteslistempty}{}{%
+        \g at addto@macro\prv at noteslist{\end{enumerate}\end{listofnotes}}
+        \clearpage
+        \prv at noteslist
+    }
+\fi}
+
+\newcommand{\ssout}[1]{\,\textbf{#1}\,}
\ No newline at end of file



More information about the tex-live-commits mailing list