Make driver box functions public

These all have well-defined interfaces so there is no issue really. They
are low-level in the sense things like box size adjustment have to apply
elsewhere, but the updated docs make that clear.

l3kernel/l3box.dtx

@@ -1674,7 +1674,7 @@
         \tex_kern:D -\l_@@_left_new_dim
         \hbox:n
           {
-            \__driver_box_use_rotate:Nn
+            \driver_box_use_rotate:Nn
               \l_@@_internal_box
               \l_@@_angle_fp
           }
@@ -2012,7 +2012,7 @@
   {
     \hbox_set:Nn \l_@@_internal_box
       {
-        \__driver_box_use_scale:Nnn
+        \driver_box_use_scale:Nnn
           #1
           \l_@@_scale_x_fp
           \l_@@_scale_y_fp

l3kernel/l3candidates.dtx

@@ -1146,7 +1146,7 @@
 %   A wrapper around the driver-dependent code.
 %    \begin{macrocode}
 \cs_new_protected:Npn \box_clip:N #1
-  { \hbox_set:Nn #1 { \__driver_box_use_clip:N #1 } }
+  { \hbox_set:Nn #1 { \driver_box_use_clip:N #1 } }
 \cs_generate_variant:Nn \box_clip:N { c }
 %    \end{macrocode}
 % \end{macro}

l3kernel/l3drivers.dtx

@@ -69,6 +69,13 @@
 %   \item \texttt{xdvipdfmx}: The driver used by \XeTeX{}.
 % \end{itemize}
 %
+% This module provides code closely tied to the exact driver in use: broadly,
+% the functions here are implemented entirely independently for each case.
+% As such, they often rely on higher-level code to provide necessary but
+% shared operations. For example, in box rotation and scaling the functions
+% here do no correct the final size of the box: this will always be required
+% and thus is handled in the \pkg{box} module.
+%
 % Several of the operations here are low-level, and so may be used only in
 % restricted contexts. Some also require understanding of PostScript/PDF
 % concepts to be used corrected as they take \enquote{raw} arguments, similar
@@ -82,49 +89,39 @@
 %
 % \section{Box clipping}
 %
-% \begin{function}[added = 2011-11-11]{\__driver_box_use_clip:N}
+% \begin{function}[added = 2017-12-13]{\driver_box_use_clip:N}
 %   \begin{syntax}
-%     \cs{__driver_box_use_clip:N} \meta{box}
+%     \cs{driver_box_use_clip:N} \meta{box}
 %   \end{syntax}
 %   Inserts the content of the \meta{box} at the current insertion point
 %   such that any material outside of the bounding box is not displayed
 %   by the driver. The material in the \meta{box} is still placed in the
 %   output stream: the clipping takes place at a driver level.
-%
-%   This function should only be used within a surrounding horizontal
-%   box construct.
 % \end{function}
 %
 % \section{Box rotation and scaling}
 %
-% \begin{function}[added = 2016-05-12]{\__driver_box_use_rotate:Nn}
+% \begin{function}[added = 2017-12-13]{\driver_box_use_rotate:Nn}
 %   \begin{syntax}
-%     \cs{__driver_box_use_rotate:Nn} \meta{box} \Arg{angle}
+%     \cs{driver_box_use_rotate:Nn} \meta{box} \Arg{angle}
 %   \end{syntax}
 %   Inserts the content of the \meta{box} at the current insertion point
 %   rotated by the \meta{angle} (expressed in degrees). The material is
-%   inserted with no apparent height or width, and is rotated such the
-%   the \TeX{} reference point of the box is the center of rotation and
-%   remains the reference point after rotation. It is the responsibility of
-%   the code using this function to adjust the apparent size of the box to
-%   be correct at the \TeX{} side.
-%
-%   This function should only be used within a surrounding horizontal
-%   box construct.
+%   rotated such the the \TeX{} reference point of the box is the center of
+%   rotation and remains the reference point after rotation. It is the
+%   responsibility of the code using this function to adjust the apparent
+%   size of the inserted material.
 % \end{function}
 %
-% \begin{function}[added = 2016-05-12]{\__driver_box_use_scale:Nnn}
+% \begin{function}[added = 2017-12-13]{\driver_box_use_scale:Nnn}
 %   \begin{syntax}
-%     \cs{__driver_box_use_scale:Nnn} \meta{box} \Arg{x-scale} \Arg{y-scale}
+%     \cs{driver_box_use_scale:Nnn} \meta{box} \Arg{x-scale} \Arg{y-scale}
 %   \end{syntax}
 %   Inserts the content of the \meta{box} at the current insertion point
-%   scale by the \meta{x-scale} and \meta{y-scale}. The material is
-%   inserted with no apparent height or width. It is the responsibility of
-%   the code using this function to adjust the apparent size of the box to
-%   be correct at the \TeX{} side.
-%
-%   This function should only be used within a surrounding horizontal
-%   box construct.
+%   scale by the \meta{x-scale} and \meta{y-scale}. The reference point
+%   of the material will be unchanged. It is the responsibility of the
+%   code using this function to adjust the apparent size of the inserted
+%   material.
 % \end{function}
 %
 % \section{Color support}
@@ -782,12 +779,12 @@
 %
 % \subsubsection{Box operations}
 %
-% \begin{macro}{\@@_box_use_clip:N}
+% \begin{macro}{\driver_box_use_clip:N}
 %   Much the same idea as for the PDF mode version but with a slightly
 %   different syntax for creating the clip path. To avoid any scaling
 %   issues we need the absolute length auxiliary here.
 %    \begin{macrocode}
-\cs_new_protected:Npn \@@_box_use_clip:N #1
+\cs_new_protected:Npn \driver_box_use_clip:N #1
   {
     \@@_scope_begin:
     \@@_literal:n
@@ -808,12 +805,12 @@
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}{\@@_box_use_rotate:Nn}
+% \begin{macro}{\driver_box_use_rotate:Nn}
 %   Rotating using \texttt{dvips} does not require that the box dimensions
 %   are altered and has a very convenient built-in operation. Zero rotation
 %   must be written as |0| not |-0| so there is a quick test.
 %    \begin{macrocode}
-\cs_new_protected:Npn \@@_box_use_rotate:Nn #1#2
+\cs_new_protected:Npn \driver_box_use_rotate:Nn #1#2
   {
     \@@_scope_begin:
     \@@_literal:n
@@ -829,11 +826,11 @@
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}{\@@_box_use_scale:Nnn}
+% \begin{macro}{\driver_box_use_scale:Nnn}
 %   The \texttt{dvips} driver once again has a dedicated operation we can
 %   use here.
 %    \begin{macrocode}
-\cs_new_protected:Npn \@@_box_use_scale:Nnn #1#2#3
+\cs_new_protected:Npn \driver_box_use_scale:Nnn #1#2#3
   {
     \@@_scope_begin:
     \@@_literal:n
@@ -1361,7 +1358,7 @@
 %
 % \subsubsection{Box operations}
 %
-% \begin{macro}{\@@_box_use_clip:N}
+% \begin{macro}{\driver_box_use_clip:N}
 %   The general method is to save the current location, define a clipping path
 %   equivalent to the bounding box, then insert the content at the current
 %   position and in a zero width box. The \enquote{real} width is then made up
@@ -1370,7 +1367,7 @@
 %   as much code as possible and uses the same conversions (and so same
 %   rounding errors) in all cases.
 %    \begin{macrocode}
-\cs_new_protected:Npn \@@_box_use_clip:N #1
+\cs_new_protected:Npn \driver_box_use_clip:N #1
   {
     \@@_scope_begin:
     \@@_literal:n
@@ -1388,7 +1385,7 @@
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}{\@@_box_use_rotate:Nn}
+% \begin{macro}{\driver_box_use_rotate:Nn}
 % \begin{variable}{\l_@@_cos_fp, \l_@@_sin_fp}
 %   Rotations are set using an affine transformation matrix which therefore
 %   requires sine/cosine values not the angle itself. We store the rounded
@@ -1397,7 +1394,7 @@
 %   with problematic display programs.  Note that numbers are compared to~$0$
 %   after rounding.
 %    \begin{macrocode}
-\cs_new_protected:Npn \@@_box_use_rotate:Nn #1#2
+\cs_new_protected:Npn \driver_box_use_rotate:Nn #1#2
   {
     \@@_scope_begin:
     \box_set_wd:Nn #1 { 0pt }
@@ -1427,11 +1424,11 @@
 % \end{variable}
 % \end{macro}
 %
-% \begin{macro}{\@@_box_use_scale:Nnn}
+% \begin{macro}{\driver_box_use_scale:Nnn}
 %   The same idea as for rotation but without the complexity of signs and
 %   cosines.
 %    \begin{macrocode}
-\cs_new_protected:Npn \@@_box_use_scale:Nnn #1#2#3
+\cs_new_protected:Npn \driver_box_use_scale:Nnn #1#2#3
   {
     \@@_scope_begin:
     \@@_matrix:n
@@ -1609,11 +1606,11 @@
 %
 % \subsubsection{Box operations}
 %
-% \begin{macro}{\@@_box_use_clip:N}
-%   The code here is idential to that for \texttt{pdfmode}: unlike rotation and
+% \begin{macro}{\driver_box_use_clip:N}
+%   The code here is identical to that for \texttt{pdfmode}: unlike rotation and
 %   scaling, there is no higher-level support in the driver for clipping.
 %    \begin{macrocode}
-\cs_new_protected:Npn \@@_box_use_clip:N #1
+\cs_new_protected:Npn \driver_box_use_clip:N #1
   {
     \@@_scope_begin:
     \@@_literal:n
@@ -1631,7 +1628,7 @@
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}{\@@_box_use_rotate:Nn}
+% \begin{macro}{\driver_box_use_rotate:Nn}
 %   Rotating in \texttt{(x)}dvipdmfx can be implemented using either PDF or
 %   driver-specific code. The former approach however is not \enquote{aware}
 %   of the content of boxes: this means that any embedded links would not be
@@ -1640,7 +1637,7 @@
 %   version (notice the rotation angle here is positive). As for
 %   \texttt{dvips}, zero rotation is written as |0| not |-0|.
 %    \begin{macrocode}
-\cs_new_protected:Npn \@@_box_use_rotate:Nn #1#2
+\cs_new_protected:Npn \driver_box_use_rotate:Nn #1#2
   {
     \@@_scope_begin:
     \tex_special:D
@@ -1656,11 +1653,11 @@
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}{\@@_box_use_scale:Nnn}
+% \begin{macro}{\driver_box_use_scale:Nnn}
 %   Much the same idea for scaling: use the higher-level driver operation to allow
 %   for box content.
 %    \begin{macrocode}
-\cs_new_protected:Npn \@@_box_use_scale:Nnn #1#2#3
+\cs_new_protected:Npn \driver_box_use_scale:Nnn #1#2#3
   {
     \@@_scope_begin:
     \tex_special:D
@@ -2312,7 +2309,7 @@
 %
 % \subsubsection{Box operations}
 %
-% \begin{macro}{\@@_box_use_clip:N}
+% \begin{macro}{\driver_box_use_clip:N}
 % \begin{variable}{\g_@@_clip_path_int}
 %   Clipping in SVG is more involved than with other drivers. The first issue
 %   is that the clipping path must be defined separately from where it is used,
@@ -2323,7 +2320,7 @@
 %   up and down using scopes to allow for the depth of the \TeX{} box and
 %   keep the reference point the same!
 %    \begin{macrocode}
-\cs_new_protected:Npn \@@_box_use_clip:N #1
+\cs_new_protected:Npn \driver_box_use_clip:N #1
   {
     \int_gincr:N \g_@@_clip_path_int
     \@@_literal:n
@@ -2387,12 +2384,12 @@
 % \end{variable}
 % \end{macro}
 %
-% \begin{macro}{\@@_box_use_rotate:Nn}
+% \begin{macro}{\driver_box_use_rotate:Nn}
 %   Rotation has a dedicated operation which includes a centre-of-rotation
 %   optional pair. That can be picked up from the driver syntax, so there is
 %   no need to worry about the transformation matrix.
 %    \begin{macrocode}
-\cs_new_protected:Npn \@@_box_use_rotate:Nn #1#2
+\cs_new_protected:Npn \driver_box_use_rotate:Nn #1#2
   {
     \@@_scope_begin:n
       {
@@ -2408,12 +2405,12 @@
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}{\@@_box_use_scale:Nnn}
+% \begin{macro}{\driver_box_use_scale:Nnn}
 %   In contrast to rotation, we have to account for the current position in this
 %   case. That is done using a couple of translations in addition to the scaling
 %   (which is therefore done backward with a flip).
 %    \begin{macrocode}
-\cs_new_protected:Npn \@@_box_use_scale:Nnn #1#2#3
+\cs_new_protected:Npn \driver_box_use_scale:Nnn #1#2#3
   {
     \@@_scope_begin:n
       {

l3kernel/testfiles/m3expl001.luatex.tlg

@@ -5835,10 +5835,10 @@ Defining \__driver_scope_begin: on line ...
 Defining \__driver_scope_end: on line ...
 Defining \__driver_matrix:n on line ...
 Defining \__driver_box_use_clip:N on line ...
-Defining \__driver_box_use_rotate:Nn on line ...
+Defining \driver_box_use_rotate:Nn on line ...
 Defining \l__driver_cos_fp on line ...
 Defining \l__driver_sin_fp on line ...
-Defining \__driver_box_use_scale:Nnn on line ...
+Defining \driver_box_use_scale:Nnn on line ...
 Defining \l__driver_image_attr_tl on line ...
 Defining \__driver_image_getbb_jpg:n on line ...
 Defining \__driver_image_getbb_png:n on line ...

l3kernel/testfiles/m3expl001.ptex.tlg

@@ -5820,9 +5820,9 @@ Defining \__driver_color_reset: on line ...
 Defining \__driver_literal:n on line ...
 Defining \__driver_scope_begin: on line ...
 Defining \__driver_scope_end: on line ...
-Defining \__driver_box_use_clip:N on line ...
-Defining \__driver_box_use_rotate:Nn on line ...
-Defining \__driver_box_use_scale:Nnn on line ...
+Defining \driver_box_use_clip:N on line ...
+Defining \driver_box_use_rotate:Nn on line ...
+Defining \driver_box_use_scale:Nnn on line ...
 Defining \__driver_image_getbb_eps:n on line ...
 Defining \__driver_image_getbb_jpg:n on line ...
 Defining \__driver_image_getbb_png:n on line ...

l3kernel/testfiles/m3expl001.tlg

@@ -6027,10 +6027,10 @@ Defining \__driver_scope_begin: on line ...
 Defining \__driver_scope_end: on line ...
 Defining \__driver_matrix:n on line ...
 Defining \__driver_box_use_clip:N on line ...
-Defining \__driver_box_use_rotate:Nn on line ...
+Defining \driver_box_use_rotate:Nn on line ...
 Defining \l__driver_cos_fp on line ...
 Defining \l__driver_sin_fp on line ...
-Defining \__driver_box_use_scale:Nnn on line ...
+Defining \driver_box_use_scale:Nnn on line ...
 Defining \l__driver_image_attr_tl on line ...
 Defining \__driver_image_getbb_jpg:n on line ...
 Defining \__driver_image_getbb_png:n on line ...

l3kernel/testfiles/m3expl001.uptex.tlg

@@ -6019,9 +6019,9 @@ Defining \__driver_color_reset: on line ...
 Defining \__driver_literal:n on line ...
 Defining \__driver_scope_begin: on line ...
 Defining \__driver_scope_end: on line ...
-Defining \__driver_box_use_clip:N on line ...
-Defining \__driver_box_use_rotate:Nn on line ...
-Defining \__driver_box_use_scale:Nnn on line ...
+Defining \driver_box_use_clip:N on line ...
+Defining \driver_box_use_rotate:Nn on line ...
+Defining \driver_box_use_scale:Nnn on line ...
 Defining \__driver_image_getbb_eps:n on line ...
 Defining \__driver_image_getbb_jpg:n on line ...
 Defining \__driver_image_getbb_png:n on line ...

l3kernel/testfiles/m3expl001.xetex.tlg

@@ -5803,9 +5803,9 @@ Defining \__driver_color_reset: on line ...
 Defining \__driver_literal:n on line ...
 Defining \__driver_scope_begin: on line ...
 Defining \__driver_scope_end: on line ...
-Defining \__driver_box_use_clip:N on line ...
-Defining \__driver_box_use_rotate:Nn on line ...
-Defining \__driver_box_use_scale:Nnn on line ...
+Defining \driver_box_use_clip:N on line ...
+Defining \driver_box_use_rotate:Nn on line ...
+Defining \driver_box_use_scale:Nnn on line ...
 Defining \__driver_image_getbb_eps:n on line ...
 Defining \g__driver_image_int on line ...
 \g__driver_image_int=\count...

l3kernel/testfiles/m3expl003.luatex.tlg

@@ -5835,10 +5835,10 @@ Defining \__driver_scope_begin: on line ...
 Defining \__driver_scope_end: on line ...
 Defining \__driver_matrix:n on line ...
 Defining \__driver_box_use_clip:N on line ...
-Defining \__driver_box_use_rotate:Nn on line ...
+Defining \driver_box_use_rotate:Nn on line ...
 Defining \l__driver_cos_fp on line ...
 Defining \l__driver_sin_fp on line ...
-Defining \__driver_box_use_scale:Nnn on line ...
+Defining \driver_box_use_scale:Nnn on line ...
 Defining \l__driver_image_attr_tl on line ...
 Defining \__driver_image_getbb_jpg:n on line ...
 Defining \__driver_image_getbb_png:n on line ...

l3kernel/testfiles/m3expl003.ptex.tlg

@@ -5820,9 +5820,9 @@ Defining \__driver_color_reset: on line ...
 Defining \__driver_literal:n on line ...
 Defining \__driver_scope_begin: on line ...
 Defining \__driver_scope_end: on line ...
-Defining \__driver_box_use_clip:N on line ...
-Defining \__driver_box_use_rotate:Nn on line ...
-Defining \__driver_box_use_scale:Nnn on line ...
+Defining \driver_box_use_clip:N on line ...
+Defining \driver_box_use_rotate:Nn on line ...
+Defining \driver_box_use_scale:Nnn on line ...
 Defining \__driver_image_getbb_eps:n on line ...
 Defining \__driver_image_getbb_jpg:n on line ...
 Defining \__driver_image_getbb_png:n on line ...

l3kernel/testfiles/m3expl003.tlg

@@ -6027,10 +6027,10 @@ Defining \__driver_scope_begin: on line ...
 Defining \__driver_scope_end: on line ...
 Defining \__driver_matrix:n on line ...
 Defining \__driver_box_use_clip:N on line ...
-Defining \__driver_box_use_rotate:Nn on line ...
+Defining \driver_box_use_rotate:Nn on line ...
 Defining \l__driver_cos_fp on line ...
 Defining \l__driver_sin_fp on line ...
-Defining \__driver_box_use_scale:Nnn on line ...
+Defining \driver_box_use_scale:Nnn on line ...
 Defining \l__driver_image_attr_tl on line ...
 Defining \__driver_image_getbb_jpg:n on line ...
 Defining \__driver_image_getbb_png:n on line ...