summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/pdfoverlay
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2020-10-29 20:48:39 +0000
committerKarl Berry <karl@freefriends.org>2020-10-29 20:48:39 +0000
commit78e4a1e834b1f2654ee13090474f1225eee0ff34 (patch)
tree01c1d49b2a340b2e4f1561fa461c2e54eea27ffc /Master/texmf-dist/source/latex/pdfoverlay
parent8f6072a73faec9993fd2d2157200c95c954a0bc8 (diff)
pdfoverlay (29oct20)
git-svn-id: svn://tug.org/texlive/trunk@56803 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/pdfoverlay')
-rw-r--r--Master/texmf-dist/source/latex/pdfoverlay/pdfoverlay.dtx232
-rw-r--r--Master/texmf-dist/source/latex/pdfoverlay/pdfoverlay.ins4
2 files changed, 165 insertions, 71 deletions
diff --git a/Master/texmf-dist/source/latex/pdfoverlay/pdfoverlay.dtx b/Master/texmf-dist/source/latex/pdfoverlay/pdfoverlay.dtx
index 805ad91d63c..1f7064be067 100644
--- a/Master/texmf-dist/source/latex/pdfoverlay/pdfoverlay.dtx
+++ b/Master/texmf-dist/source/latex/pdfoverlay/pdfoverlay.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (c) 2018-2019 David Purton <dcpurton@marshwiggle.net>
+% Copyright (c) 2018-2020 David Purton <dcpurton@marshwiggle.net>
%
% This work may be distributed and/or modified under the conditions of
% the LaTeX Project Public License, either version 1.3c of this license
@@ -19,20 +19,22 @@
% \fi
%
% \changes{v1.0}{2018/05/08}{First public release}
-% \changes{v1.1}{2019/11/03}{Fix depracated macros}
+% \changes{v1.1}{2019/11/03}{Fix deprecated macros}
+% \changes{v1.2}{2020/10/29}{Update to use \pkg{l3hooks}}
%
% \title{The \pkg{pdfoverlay} package}
% \author{David Purton\thanks{Email: \url{dcpurton@marshwiggle.net}}}
-% \date{2019/11/03 v1.1}
+% \date{2020/10/29 v1.2}
%
% \maketitle
%
% \begin{abstract}
% This \pkg{pdfoverlay} package provides a simple interface to overlay text
-% on to an existing PDF. The text to be overlayed is typeset and positioned
-% normally as you would any other \LaTeX{} document. Some or all of the pages
-% of the PDF can be included and not all pages of the PDF need have overlayed
-% text. It's also possible to include text between pages of the PDF.
+% on to an existing PDF. The text to be overlaid is typeset and positioned
+% normally as you would any other \LaTeX{} document. Some or all of the
+% pages of the PDF can be included and not all pages of the PDF need have
+% overlaid text. It's also possible to include text between pages of the
+% PDF.
% \end{abstract}
%
% \tableofcontents
@@ -41,32 +43,25 @@
%
% \section{Introduction}
%
-% It's often desirable to take an exisiting PDF and easily add annotations or
+% It's often desirable to take an existing PDF and easily add annotations or
% text overlaying the PDF. This might arise if you wish to add comments to a
% PDF, fill in a PDF form, or add text to a PDF where space has been left for
% notes.
%
% This package provides a simple interface to do this without having to resort
% to inserting one page at a time. Some or all of the pages of the PDF can be
-% included and not all pages of the PDF need have overlayed text. It's also
+% included and not all pages of the PDF need have overlaid text. It's also
% possible to include text between pages of the PDF.
%
-% Another advantage of this package is that the overlayed text can be set as
+% Another advantage of this package is that the overlaid text can be set as
% normal flowing from one page to another or with manual page breaks if you
% wish. It's also possible to use any standard method to position text at
% arbitrary places on a given page.
%
-% \section{Acknowlegements}
-%
-% This package is particularly indebted to the \pkg{pdfpages} package to count
-% the number of pages in the PDF file, the \pkg{eso-pic} package to output
-% pages from the PDF file in the document background, and the \pkg{everypage}
-% package to ensure that PDF pages are inserted at every page in the document.
-%
% \section{Bug Reports and Feature Requests}
%
% Bug reports and feature requests can be made at the \pkg{pdfoverlay} package
-% GitHub respoitory. See \url{https://github.com/dcpurton/pdfoverlay}.
+% GitHub repository. See \url{https://github.com/dcpurton/pdfoverlay}.
%
% \section{Documentation}
%
@@ -107,10 +102,12 @@
% \end{syntax}
% Set the \meta{Options} to be passed to \cs{includegraphics} when each page
% of the PDF is output. See the \pkg{graphicx} package documentation for
-% valid options. \textbf{Note} that it is not necessary to specify the
-% \texttt{page} option as this is appended automatically in the right format.
-% The default options are: \texttt{keepaspectratio,
-% width=}\cs{paperwidth}\texttt{, height=}\cs{paperheight}.
+% valid options.
+%
+% \textbf{Note} that it is not necessary to specify the \texttt{page} option
+% as this is appended automatically in the right format. The default
+% options are: \texttt{keepaspectratio, width=}\cs{paperwidth}\texttt{,
+% height=}\cs{paperheight}.
% \end{function}
%
% \begin{function}{\pdfoverlayIncludeToPage, \pdfoverlay_include_to_page:n}
@@ -165,34 +162,30 @@
% \end{macrocode}
%
% \begin{macrocode}
-\RequirePackage{xparse}
-% \end{macrocode}
-%
-% \begin{macrocode}
-\ProvidesExplPackage{pdfoverlay}{2019/11/03}{1.1}
+\NeedsTeXFormat{LaTeX2e}[2020-10-01]
+\ProvidesExplPackage{pdfoverlay}{2020/10/18}{1.2}
{Overlay text on an existing PDF document (DCP)}
% \end{macrocode}
%
-% \noindent The \pkg{everypage} and \pkg{pdfpages} packages are required.
+% \noindent The \pkg{graphicx} package is required.
%
% \begin{macrocode}
-\RequirePackage{everypage,pdfpages}
+\RequirePackage{graphicx}
% \end{macrocode}
%
-% \noindent Call \cs{@@_output_pdf_page:} on every page using the
-% \pkg{everypage} package.
+% \noindent Call \cs{@@_output_pdf_page:} on every page.
% \begin{macrocode}
-\AddEverypageHook { \@@_output_pdf_page: }
+\AddToHook { shipout/background } { \@@_output_pdf_page: }
% \end{macrocode}
%
-% \noindent Add \cs{null} to the end of the document if an action is pending.
-% This is required to ensure that the last requested page from the PDF file is
-% output even if there isn't any other content on the page.
+% \noindent Add an empty \cs{hbox:n} to the end of the document if an action
+% is pending. This is required to ensure that the last requested page from the
+% PDF file is output even if there isn't any other content on the page.
% \begin{macrocode}
\AtEndDocument {
\bool_if:NT \g_@@_action_pending_bool
{
- \null
+ \hbox:n { }
}
}
% \end{macrocode}
@@ -241,6 +234,26 @@
Specify~a~page~between~#2~and~#3. }
% \end{macrocode}
%
+% \noindent Error message when running in DVI mode. The \pkg{pdfoverlay}
+% package does not support DVI mode for either \texttt{pdflatex} or
+% \texttt{lualatex}.
+% \begin{macrocode}
+\msg_new:nnnn { pdfoverlay } { dvi-mode }
+ { DVI~mode~not~supported. }
+ { DVI~mode~of~#1~is~not~supported. \\
+ You~must~use~PDF~mode. }
+% \end{macrocode}
+%
+% \noindent Error message for unsupported engine. Only \texttt{pdftex},
+% \texttt{luatex}, and \texttt{xetex} are supported.
+% \begin{macrocode}
+\msg_new:nnnn { pdfoverlay } { unsupported-engine }
+ { #1~not~supported. }
+ { The~#1~engine~is~not~supported. \\
+ Use~one~of~pdftex,~luatex,~or~xetex. }
+% \end{macrocode}
+%
+%
% \subsection{Private Variables and Helper Functions}
%
% \begin{macro}{\g_@@_pdf_file_name_str}
@@ -296,9 +309,17 @@
% \end{macrocode}
% \end{macro}
%
+% \begin{macro}{\g_@@_pdf_page_coffin}
+% The current PDF page is set in this coffin which can then be positioned on
+% the page.
+% \begin{macrocode}
+\coffin_new:N \g_@@_pdf_page_coffin
+% \end{macrocode}
+% \end{macro}
+%
% \begin{macro}{\@@_output_pdf_page:}
% Main function to output the current page of the PDF file. This is called
-% before every page is shipped using the \pkg{everypage} package.
+% before every page is shipped using the \texttt{shipout/background} hook.
% \begin{macrocode}
\cs_new:Nn \@@_output_pdf_page:
{
@@ -317,18 +338,16 @@
}
{
% \end{macrocode}
-% Place requested page from the PDF file in the background of the
-% document page with the specified format.
-% \begin{macrocode}
- \AddToShipoutPictureBG*
- {
- \@@_format_pdf_page:
- }
-% \end{macrocode}
% Increment the current page counter.
% \begin{macrocode}
\int_gincr:N \g_@@_page_int
% \end{macrocode}
+% Place requested page from the PDF file in the background of the
+% document page with the specified format.
+% \begin{macrocode}
+ \@@_format_pdf_page:
+ \@@_place_pdf_page:
+% \end{macrocode}
% Set action pending flag to false.
% \begin{macrocode}
\bool_gset_false:N \g_@@_action_pending_bool
@@ -338,23 +357,100 @@
% \end{macro}
%
% \begin{macro}{\@@_format_pdf_page:}
-% Format the PDF page in the centre of the document page with options from
-% \cs{g_@@_graphics_options_clist}. Although marked as private, this function
-% could be redifined to position the PDF page at a different location on the
-% document page. See the \pkg{eso-pic} package documentation for hints on how
-% to position the PDF page.
+% Format the PDF page with options from \cs{g_@@_graphics_options_clist} and
+% place it in \cs{g_@@_pdf_page_coffin}.
% \begin{macrocode}
\cs_new:Nn \@@_format_pdf_page:
{
- \AtPageCenter
+ \hcoffin_gset:Nn \g_@@_pdf_page_coffin
+ {
+ \use:x
+ {
+ \exp_not:N \includegraphics
+ [ \clist_use:Nn \g_@@_graphics_options_clist { , } ]
+ { \g_@@_pdf_file_name_str }
+ }
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@@_place_pdf_page:}
+% Place the PDF page in the centre of the document page.
+%
+% Although marked as private, this function could be redefined to position
+% the PDF page at a different location on the document page.
+%
+% This macro is called from within the \texttt{shipout\slash background}
+% hook, which adds a picture environment into the background of the page
+% with the (0, 0) coordinate in the top-left corner using a \cs{unitlength}
+% of 1pt. It should therefore only receive \cs{put} commands or other
+% commands suitable in a picture environment and the vertical coordinate
+% values would normally be negative.
+%
+% The PDF page to be placed is available as the coffin
+% \cs{g_@@_pdf_page_coffin}.
+% \begin{macrocode}
+\cs_new:Nn \@@_place_pdf_page:
+ {
+ \put ( 0.5 \paperwidth, -0.5 \paperheight )
{
- \makebox (0, 0)
+ \coffin_typeset:Nnnnn \g_@@_pdf_page_coffin
+ { hc } { vc } { 0pt } { 0pt }
+ }
+ }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@@_count_pdf_pages:}
+% Count the number of pages in the current \cs{g_@@_pdf_file_name_str} and
+% store the result in \cs{g_@@_pdf_page_count_int}. If no PDF has been set
+% with \cs{pdfoverlay_set_pdf} then \cs{g_@@_pdf_page_count_int} is set to
+% zero.
+% \begin{macrocode}
+\cs_new:Nn \@@_count_pdf_pages:
+ {
+ \int_gzero:N \g_@@_page_count_int
+ \str_if_empty:NTF \g_@@_pdf_file_name_str
+ {
+ \msg_error:nn { pdfoverlay } { file-not-set }
+ }
+ {
+ \sys_if_engine_xetex:TF
{
- \use:x
+ \int_gset:Nn \g_@@_page_count_int
+ {
+ \XeTeXpdfpagecount " \g_@@_pdf_file_name_str "
+ }
+ }
+ {
+ \sys_if_output_pdf:TF
+ {
+ \sys_if_engine_pdftex:TF
+ {
+ \pdfximage { \g_@@_pdf_file_name_str }
+ \int_gset_eq:NN
+ \g_@@_page_count_int
+ \pdflastximagepages
+ }
+ {
+ \sys_if_engine_luatex:TF
+ {
+ \saveimageresource
+ { \g_@@_pdf_file_name_str }
+ \int_gset_eq:NN
+ \g_@@_page_count_int
+ \lastsavedimageresourcepages
+ }
+ {
+ \msg_error:nnx { pdfoverlay } { unsupported-engine }
+ { \c_sys_engine_str }
+ }
+ }
+ }
{
- \exp_not:N \includegraphics
- [ \clist_use:Nn \g_@@_graphics_options_clist { , } ]
- { \g_@@_pdf_file_name_str }
+ \msg_error:nnx { pdfoverlay } { dvi-mode }
+ { \c_sys_engine_str }
}
}
}
@@ -408,15 +504,13 @@
{
\str_gset:Nn \g_@@_pdf_file_name_str { #1 }
% \end{macrocode}
-% Use the \pkg{pdfpages} package to find the number of pages in the PDF file.
+% Find the number of pages in the PDF file.
% \begin{macrocode}
- \edef \AM@currentdocname { #1 }
- \AM@getpagecount
+ \@@_count_pdf_pages:
% \end{macrocode}
% Initialise variables.
% \begin{macrocode}
- \int_gset_eq:NN \g_@@_page_count_int \AM@pagecount
- \int_gset_eq:NN \g_@@_page_int \c_zero_int
+ \int_gzero:N \g_@@_page_int
\bool_gset_true:N \g_@@_output_active_bool
\bool_gset_false:N \g_@@_action_pending_bool
}
@@ -447,8 +541,8 @@
% \begin{macro}{\pdfoverlay_include_to_page:n}
% Output all pages in the PDF file up until the specified page. Since the
% actual PDF page is inserted by \cs{__pdfoverlay_output_pdf_page:} using the
-% \pkg{everypage} package before the page is shipped, we just insert the
-% required number of blank pages into the document.
+% \texttt{shipout/background} hook, we just insert the required number of
+% blank pages into the document.
% \begin{macrocode}
\cs_new:Npn \pdfoverlay_include_to_page:n #1
{
@@ -476,7 +570,7 @@
{ \int_compare_p:n { #1 != \g_@@_page_int + 1 } }
}
{
- \null
+ \hbox:n { }
\clearpage
}
% \end{macrocode}
@@ -484,12 +578,12 @@
% \begin{macrocode}
\int_while_do:nNnn { \g_@@_page_int } < { #1 - 1 }
{
- \null
+ \hbox:n { }
\clearpage
}
% \end{macrocode}
% Set the action pending flag, so final page is output even if no text is
-% overlayed on it.
+% overlaid on it.
% \begin{macrocode}
\bool_gset_true:N \g_@@_action_pending_bool
}
@@ -526,16 +620,16 @@
% \begin{macrocode}
\bool_if:nT { \g_@@_action_pending_bool }
{
- \null
+ \hbox:n { }
\clearpage
}
% \end{macrocode}
-% Set the page numer for the next page to be output.
+% Set the page number for the next page to be output.
% \begin{macrocode}
\int_gset:Nn \g_@@_page_int { #1 - 1 }
% \end{macrocode}
% Set the action pending flag, so final page is output even if no text is
-% overlayed on it.
+% overlaid on it.
% \begin{macrocode}
\bool_gset_true:N \g_@@_action_pending_bool
}
diff --git a/Master/texmf-dist/source/latex/pdfoverlay/pdfoverlay.ins b/Master/texmf-dist/source/latex/pdfoverlay/pdfoverlay.ins
index 7f2a4200f95..743dbdca593 100644
--- a/Master/texmf-dist/source/latex/pdfoverlay/pdfoverlay.ins
+++ b/Master/texmf-dist/source/latex/pdfoverlay/pdfoverlay.ins
@@ -1,6 +1,6 @@
\iffalse meta-comment
-Copyright (c) 2018-2019 David Purton <dcpurton@marshwiggle.net>
+Copyright (c) 2018-2020 David Purton <dcpurton@marshwiggle.net>
This work may be distributed and/or modified under the conditions of
the LaTeX Project Public License, either version 1.3c of this license
@@ -19,7 +19,7 @@ version 2005/12/01 or later.
This is a generated file.
-Copyright (c) 2018-2019 David Purton <dcpurton@marshwiggle.net>
+Copyright (c) 2018-2020 David Purton <dcpurton@marshwiggle.net>
This work may be distributed and/or modified under the conditions of
the LaTeX Project2 Public License, either version 1.3c of this license