xsavebox (7mar16)

git-svn-id: svn://tug.org/texlive/trunk@39965 c570f23f-e606-0410-a88d-b1316a301751

4 files changed, 56 insertions, 41 deletions

diff --git a/Master/texmf-dist/doc/latex/xsavebox/ChangeLog b/Master/texmf-dist/doc/latex/xsavebox/ChangeLog
index af04ecf527b..f9cb95adba1 100644
--- a/Master/texmf-dist/doc/latex/xsavebox/ChangeLog
+++ b/Master/texmf-dist/doc/latex/xsavebox/ChangeLog
@@ -1,2 +1,6 @@
+2016-03-07
+	* v0.2
+	* new: package option `margin=<dimension>' added
+
 2016-02-25
 	* initial release (v0.1) to CTAN
diff --git a/Master/texmf-dist/doc/latex/xsavebox/xsavebox.pdf b/Master/texmf-dist/doc/latex/xsavebox/xsavebox.pdf
index 7969d6d31b2..b0661205e9f 100644
--- a/Master/texmf-dist/doc/latex/xsavebox/xsavebox.pdf
+++ b/Master/texmf-dist/doc/latex/xsavebox/xsavebox.pdf
diff --git a/Master/texmf-dist/source/latex/xsavebox/xsavebox.tex b/Master/texmf-dist/source/latex/xsavebox/xsavebox.tex
index ea35dcc8039..32d0fdd1bf8 100644
--- a/Master/texmf-dist/source/latex/xsavebox/xsavebox.tex
+++ b/Master/texmf-dist/source/latex/xsavebox/xsavebox.tex
@@ -14,7 +14,7 @@
 \usepackage{color}
 \usepackage{lmodern}
 \usepackage[T1]{fontenc}
-\usepackage[protrusion,expansion]{microtype}
+%\usepackage[protrusion,expansion]{microtype}
 \usepackage{parskip}
 \usepackage[bookmarksnumbered,linktocpage]{hyperref}
 \usepackage{fancyvrb}
@@ -65,7 +65,7 @@
 \section{Introduction}
 Whenever the standard \LaTeX{} command \verb+\usebox{+\emph{save-box}\verb+}+ is issued to insert a previously defined \emph{save-box} more than once, the typeset content stored therein is written as DVI or PDF code into the output file again. The redundant code adds to the overall file size and may impair the page caching facilities built into some PDF viewers.
 
-The PDF file format defines a powerful mechanism for packing readily typeset content once into self-contained entities, so-called \enquote{XObjects}, that can be referenced at other places within the PDF document.
+The PDF file format defines a powerful mechanism for packing readily typeset content once into self-contained entities, so-called \enquote{Form XObjects}, that can be referenced at other places within the PDF document.
 
 The `\verb+xsavebox+' package makes this PDF feature accessible on the \LaTeX{} level as a set of user commands which look similar to and are used in a similar way as the well-known \emph{save-box} related \LaTeX{} commands.
 
@@ -79,7 +79,13 @@ All common \TeX{} engines and back-ends are supported, which are:
 
 To enable `\verb+dvipdfmx+', pass it as a document class option.
 
-It should be emphasized that \enquote{XObjects} is a PDF feature. Content saved and referenced using \enquote{XObjects} is only visible in the final PDF output, but not in intermediate formats of the work-flow if those are involved, namely DVI and PostScript. Of course, PostScript converted back from PDF displays the content correctly.
+It should be emphasized that \enquote{Form XObjects} is a PDF feature. Content saved and referenced using \enquote{Form XObjects} is only visible in the final PDF output, but not in intermediate formats of the work-flow if those are involved, namely DVI and PostScript. Of course, PostScript converted back from PDF displays the content correctly.
+
+\section{Package Options}
+\begin{Verbatim}
+margin=<dimension>  
+\end{Verbatim}
+When content is converted into a Form XObject, it is clipped to its bounding box. However, the glyphs of the fonts which are used for typesetting tend to be slightly bigger than their boxes. In order to avoid clipping, the `\verb+xsavebox+' package \emph{temporarily} adds an additional margin of \verb+3pt+ around the content. In rare cases, \verb+3pt+ may turn out to be insufficient, e.\,g. if text is up-scaled before being put into a save box. This option allows the setting of a larger margin to ensure that the content gets entirely into the save box. Note that whichever value is chosen for `\verb+margin+', the spacing of the boxes, when inserted into the document, remains unchanged. This is what every user definitely wants.
 
 \section{User commands}
 \subsection*{Content saving}
@@ -162,7 +168,7 @@ An example with colour injection (pdf\LaTeX/Lua\LaTeX-only) follows:
   \begin{minipage}[b]{1in}
   silly boxed paragraph that no one will ever use
   \end{minipage}
-\end{xlrbox*}
+\end{xlrbox*}%
 Here is a \fbox{\color{blue}\theSavedPar} for anything.
 
 The same \fbox{\color{green}\rotatebox{90}{\theSavedPar}} was inserted again but with a different colour and rotated by 90 degree.
diff --git a/Master/texmf-dist/tex/latex/xsavebox/xsavebox.sty b/Master/texmf-dist/tex/latex/xsavebox/xsavebox.sty
index cbbd3b25f76..976507d9545 100644
--- a/Master/texmf-dist/tex/latex/xsavebox/xsavebox.sty
+++ b/Master/texmf-dist/tex/latex/xsavebox/xsavebox.sty
@@ -47,9 +47,10 @@
 
 \RequirePackage{xparse}
 \RequirePackage{pdfbase} %everything with `pbs_' prefix
+\RequirePackage{l3keys2e}
 
-\def\g@xsb@version@tl{0.1}
-\def\g@xsb@date@tl{2016/02/25}
+\def\g@xsb@version@tl{0.2}
+\def\g@xsb@date@tl{2016/03/07}
 \ProvidesExplPackage{xsavebox}{\g@xsb@date@tl}{\g@xsb@version@tl}
 {saveboxes for repeating content without code replication}
 
@@ -59,11 +60,33 @@
   Please~install~an~up~to~date~version~of~`#1'.\\
   Loading~xsavebox~will~abort!
 }
-\@ifpackagelater{pdfbase}{2016/02/25}{}{
-  \msg_error:nnn{xsavebox}{support~outdated}{pdfbase}
+\@ifpackagelater{pdfbase}{2016/03/07}{}{
+  \msg_error:nnn{xsavebox}{support~outdated}{pdfbase.sty}
   \tex_endinput:D
 }
 
+%package options
+
+%unknown package option error message
+\msg_set:nnnn{xsavebox}{unknown~package~option}{Unknown~package~option~`#1'.}{
+  Package option~'#1'~is~unknown;\\
+  perhaps~it~is~spelled~incorrectly.
+}
+
+\tl_gset:Nn\g_xsb_margin_tl{3pt}
+\keys_define:nn{xsavebox}{
+  margin .code:n = {
+    \setlength\l_tmpa_dim{#1}
+    \tl_gset:Nx\g_xsb_margin_tl{\dim_use:N\l_tmpa_dim}
+  },
+
+  unknown .code:n = {
+    \msg_error:nnx{xsavebox}{unknown~package~option}{\l_keys_key_tl}
+  }
+}
+
+\ProcessKeysOptions{xsavebox}
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 % content insertion (referencing, actually)
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -107,7 +130,7 @@
       \xsb_process_box:nnnN{#2}{#3}{#4}\l_xsb_raw_box
     }
   }{
-    \xsb_process_box:nN{#2}\l_xsb_box
+    \xsb_process_box:nnnN{#2}{\width}{c}\l_xsb_box
   }
   \group_end:
 }
@@ -137,7 +160,7 @@
   \unskip
   \egroup\egroup
   \sbox\l_xsb_box{\hbox_unpack_clear:N\l_xsb_box}
-  \xsb_process_box:nN{#1}\l_xsb_box
+  \xsb_process_box:nnnN{#1}{\width}{c}\l_xsb_box
   \group_end:
 }
 
@@ -150,35 +173,12 @@
 \cs_new_nopar:Nn\xsb_endxlrbox_star:n{
   \unskip
   \color@endgroup\egroup
-  \xsb_process_box:nN{#1}\l_xsb_box
+  \xsb_process_box:nnnN{#1}{\width}{c}\l_xsb_box
   \group_end:
 }
 
-\cs_new_nopar:Nn\xsb_process_box:nN{ %process a readily resized (new width) box
-  %measure box
-  \tl_set:Nx\l_xsb_wd_tl{\dim_use:N\box_wd:N#2}
-  \tl_set:Nx\l_xsb_ht_tl{\dim_use:N\box_ht:N#2}
-  \tl_set:Nx\l_xsb_dp_tl{\dim_use:N\box_dp:N#2}
-  %push the box bounds somewhat to get everything while distilling, as
-  %glyphs tend to be larger than their bounding boxes
-  \hbox_set_to_wd:Nnn#2{\l_xsb_wd_tl+6pt}{\hss\hbox_unpack_clear:N#2\hss}
-  \box_set_ht:Nn#2{\l_xsb_ht_tl+3pt}
-  \box_set_dp:Nn#2{\l_xsb_dp_tl+3pt}
-  %distill box into PDF Form XObject
-  \pbs_pdfxform:nn{0}{#2}%
-  %define command for inserting the h-boxed XObject reference
-  \tl_gset:cx{the#1}{
-    \exp_not:N\hbox_to_wd:nn{\l_xsb_wd_tl}{
-      \exp_not:N\vrule~width~\c_zero_dim~height~\l_xsb_ht_tl~
-        depth~\l_xsb_dp_tl
-      \exp_not:N\skip_horizontal:n{\dim_eval:n{-3pt}}
-      \exp_not:N\pbs_pdfrefxform:n{\pbs_pdflastxform:}\hss
-    }
-  }
-}
-
-\cs_new_nopar:Nn\xsb_process_box:nnnN{ %first distill, then put XObject ref
-  %measure natural dimensions           into mbox of user defined size
+\cs_new_nopar:Nn\xsb_process_box:nnnN{
+  %measure natural dimensions
   \cs_set_nopar:Npn\width {\box_wd:N#4}
   \cs_set_nopar:Npn\height{\box_ht:N#4}
   \cs_set_nopar:Npn\depth {\box_dp:N#4}
@@ -189,17 +189,22 @@
   %evaluate width argument (allowing for calc-type expressions)
   \setlength\l_tmpa_dim{#2}
   \tl_set:Nx\l_xsb_new_wd_tl{\dim_use:N\l_tmpa_dim}
-  \hbox_set_to_wd:Nnn#4{\width+6pt}{\hss\hbox_unpack_clear:N#4\hss}
-  \box_set_ht:Nn#4{\height+3pt}
-  \box_set_dp:Nn#4{\depth+3pt}
-  \pbs_pdfxform:nn{0}{#4}%
+  %temporarily (for distilling) push the box bounds somewhat; glyphs tend to
+  %be bigger than their bounding boxes
+  \hbox_set_to_wd:Nnn#4{\width+\g_xsb_margin_tl+\g_xsb_margin_tl}{
+    \hss\hbox_unpack_clear:N#4\hss
+  }
+  \box_set_ht:Nn#4{\height+\g_xsb_margin_tl}
+  \box_set_dp:Nn#4{\depth+\g_xsb_margin_tl}
+  %distill box to Form XObject
+  \pbs_pdfxform:nnn{1}{0}{#4}
   %define command for inserting the m-boxed XObject reference
   \tl_gset:cx{the#1}{
     \exp_not:N\makebox[\l_xsb_new_wd_tl][#3]{
       \exp_not:N\hbox_to_wd:nn{\l_xsb_wd_tl}{
         \exp_not:N\vrule~width~\c_zero_dim~height~\l_xsb_ht_tl~
           depth~\l_xsb_dp_tl
-        \exp_not:N\skip_horizontal:n{\dim_eval:n{-3pt}}
+        \exp_not:N\skip_horizontal:n{-\g_xsb_margin_tl}
         \exp_not:N\pbs_pdfrefxform:n{\pbs_pdflastxform:}\hss
       }
     }