xsavebox (29mar18)

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

4 files changed, 56 insertions, 10 deletions

diff --git a/Master/texmf-dist/doc/latex/xsavebox/ChangeLog b/Master/texmf-dist/doc/latex/xsavebox/ChangeLog
index d2f4082ac8e..8176e20f08d 100644
--- a/Master/texmf-dist/doc/latex/xsavebox/ChangeLog
+++ b/Master/texmf-dist/doc/latex/xsavebox/ChangeLog
@@ -1,3 +1,7 @@
+2018-03-29
+	* v0.10
+	* fix: preventing creation of unused XObjects; doc updated
+
 2018-01-16
 	* v0.9
 	* fix: README.md did not render correctly on CTAN
diff --git a/Master/texmf-dist/doc/latex/xsavebox/xsavebox.pdf b/Master/texmf-dist/doc/latex/xsavebox/xsavebox.pdf
index 003743460a5..4d12890b7f2 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 245aedbdf8c..0d5e7247541 100644
--- a/Master/texmf-dist/source/latex/xsavebox/xsavebox.tex
+++ b/Master/texmf-dist/source/latex/xsavebox/xsavebox.tex
@@ -110,7 +110,7 @@ When content is converted into a Form XObject, it is clipped to its bounding box
 \vspace{-1\baselineskip}
 \hrulefill\\[-1\baselineskip]
 
-The main difference of these commands as compared to their standard \LaTeX{} counterparts without the leading `\verb+x+' is the way of naming boxes. The label \verb+<xsbox name>+ is an identifier that may be composed of arbitrary non-active characters, including spaces and numbers. A command for declaring a box register \verb+<xsbox name>+ does not exist.
+As for usage, the main difference of these commands as compared to their standard \LaTeX{} counterparts without the leading `\verb+x+' is the way of naming boxes. The label \verb+<xsbox name>+ is an identifier that may be composed of arbitrary non-active characters, such as letters, numbers, spaces, punctuation marks. A command for declaring a box register does not exist; \verb+<xsbox name>+ it is created upon using above-listed commands and environments. Also, an existing \verb+<xsbox name>+ can be re-used, which simply overwrites its old with new content. The package keeps track of box usage; the content of a box is only written to the output file if it is referenced at least once later in the document.
 
 The \verb+[<width>]+ and \verb+[<position>]+ options have the same meaning as with \verb+\savebox+ and \verb+\makebox+. As usual, the additional length commands
 \begin{Verbatim}
@@ -129,7 +129,7 @@ Note that
 \begin{Verbatim}
   \xsbox{image for frequent use}{\includegraphics{example}}  
 \end{Verbatim}
-is useful only in the \LaTeX{} $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+ work-flow, as all other engines and back-ends already take care of preventing multiple graphics file inclusion.
+is particularly useful in the \LaTeX{} $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+ work-flow. Although the other engines and back-ends already take care of preventing multiple graphics file inclusion, a noticeable reduction of compilation time will be achieved in general.
 
 Verbatim content can only be saved using the `\verb+xlrbox[*]+' environment.
 
diff --git a/Master/texmf-dist/tex/latex/xsavebox/xsavebox.sty b/Master/texmf-dist/tex/latex/xsavebox/xsavebox.sty
index 489b920f2db..124c4c0df26 100644
--- a/Master/texmf-dist/tex/latex/xsavebox/xsavebox.sty
+++ b/Master/texmf-dist/tex/latex/xsavebox/xsavebox.sty
@@ -49,8 +49,8 @@
 \RequirePackage{pdfbase} %everything with `pbs_' prefix
 \RequirePackage{l3keys2e}
 
-\def\g@xsb@version@tl{0.9}
-\def\g@xsb@date@tl{2018/01/16}
+\def\g@xsb@version@tl{0.10}
+\def\g@xsb@date@tl{2018/03/29}
 \ProvidesExplPackage{xsavebox}{\g@xsb@date@tl}{\g@xsb@version@tl}
 {saveboxes for repeating content without code replication}
 
@@ -65,7 +65,14 @@
   \tex_endinput:D
 }
 
-%package options
+%re-run message
+\msg_set:nnn{xsavebox}{rerun}{Rerun~to~get~internal~references~right!}
+\cs_new:Nn\xsb_rerun_msg:{
+  \cs_if_exist:NF\g_xsb_rerunwarned_tl{
+    \tl_new:N\g_xsb_rerunwarned_tl
+    \AtEndDocument{\msg_warning:nn{xsavebox}{rerun}}
+  }
+}
 
 %unknown package option error message
 \msg_set:nnnn{xsavebox}{unknown~package~option}{Unknown~package~option~`#1'.}{
@@ -73,6 +80,7 @@
   perhaps~it~is~spelled~incorrectly.
 }
 
+%package options
 \tl_gset:Nn\g_xsb_margin_tl{3pt}
 \keys_define:nn{xsavebox}{
   margin .code:n = {
@@ -87,10 +95,20 @@
 
 \ProcessKeysOptions{xsavebox}
 
+\int_new:N\g_xsb_id_int
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 % content insertion (referencing, actually)
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\DeclareDocumentCommand\xusebox{m}{\tl_use:c{the#1}}
+\DeclareDocumentCommand\xusebox{m}{
+  \tl_if_exist:cF{the#1}{\msg_error:nnn{xsavebox}{save-box~undefined}{#1}}
+  \tl_use:c{the#1}
+}
+\msg_set:nnnn{xsavebox}{save-box~undefined}{
+  Save-box~`#1'~undefined~\msg_line_context:.
+}{
+  Save-box~`#1'~must~be~defined~/before/~use.
+}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 % saving content
@@ -231,23 +249,47 @@
   }
   \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
+  \tl_if_exist:cF{xsb@\int_use:N\g_xsb_id_int}{
+    \tl_gset:cn{xsb@\int_use:N\g_xsb_id_int}{true}
+    \xsb_rerun_msg:
+  }
   \xsb_pop_props_to:N\l_tmpa_tl
-  \pbs_pdfxform:nnnnn{1}{0}{\l_tmpa_tl}{
-    \cs_if_exist_use:N\ocgbase_insert_oc:}{#4}
+  %distill box to Form XObject, if used (ref'ed)
+  \bool_if:cT{c_\tl_use:c{xsb@\int_use:N\g_xsb_id_int}_bool}{
+    \pbs_pdfxform:nnnnn{1}{0}{\l_tmpa_tl}{
+      \cs_if_exist_use:N\ocgbase_insert_oc:}{#4}
+  }
+  %for tracking box usage
+  \iow_now:Nx\@mainaux{
+    \token_to_str:N\pbs@newkey{xsb@\int_use:N\g_xsb_id_int}{false}
+  }
   %define command for inserting the m-boxed XObject reference
   \tl_gset:cx{the#1}{
+    \exp_not:N\tl_if_exist:cF{xsb_\int_use:N\g_xsb_id_int}{
+      %mark box as `used'
+      \exp_not:N\iow_now:Nx\@mainaux{
+        \token_to_str:N\pbs@newkey{xsb@\int_use:N\g_xsb_id_int}{true}
+      }
+      \exp_not:N\tl_new:c{xsb_\int_use:N\g_xsb_id_int}
+    }  
+    \exp_not:N\bool_if:cF{c_\tl_use:c{xsb@\int_use:N\g_xsb_id_int}_bool}{
+      \exp_not:N\xsb_rerun_msg:
+    }
     \exp_not:N\xsb_beginLTR:
     \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{-\g_xsb_margin_tl}
-        \exp_not:N\pbs_pdfrefxform:n{\pbs_pdflastxform:}\hss
+        \bool_if:cT{c_\tl_use:c{xsb@\int_use:N\g_xsb_id_int}_bool}{
+          \exp_not:N\pbs_pdfrefxform:n{\pbs_pdflastxform:}
+        }
+        \hss
       }
     }
     \exp_not:N\xsb_endLTR:
   }
+  \int_gincr:N\g_xsb_id_int
 }
 
 \box_new:N\l_xsb_box     %for saving the re-aligned content