diff --git a/l3kernel/l3box.dtx b/l3kernel/l3box.dtx index ed0964312e..70e7b96ada 100644 --- a/l3kernel/l3box.dtx +++ b/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 diff --git a/l3kernel/l3candidates.dtx b/l3kernel/l3candidates.dtx index cf7967e7f0..05b2a1db6b 100644 --- a/l3kernel/l3candidates.dtx +++ b/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} diff --git a/l3kernel/l3drivers.dtx b/l3kernel/l3drivers.dtx index b2f888b305..0a3dc70c9a 100644 --- a/l3kernel/l3drivers.dtx +++ b/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 { diff --git a/l3kernel/testfiles/m3expl001.luatex.tlg b/l3kernel/testfiles/m3expl001.luatex.tlg index f1d9026fda..77dd67cda7 100644 --- a/l3kernel/testfiles/m3expl001.luatex.tlg +++ b/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 ... diff --git a/l3kernel/testfiles/m3expl001.ptex.tlg b/l3kernel/testfiles/m3expl001.ptex.tlg index bd7025b373..0fb6d8b4f6 100644 --- a/l3kernel/testfiles/m3expl001.ptex.tlg +++ b/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 ... diff --git a/l3kernel/testfiles/m3expl001.tlg b/l3kernel/testfiles/m3expl001.tlg index e148e0601d..36bb25bfbe 100644 --- a/l3kernel/testfiles/m3expl001.tlg +++ b/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 ... diff --git a/l3kernel/testfiles/m3expl001.uptex.tlg b/l3kernel/testfiles/m3expl001.uptex.tlg index f844d07cde..25cae1ab4e 100644 --- a/l3kernel/testfiles/m3expl001.uptex.tlg +++ b/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 ... diff --git a/l3kernel/testfiles/m3expl001.xetex.tlg b/l3kernel/testfiles/m3expl001.xetex.tlg index cdc9d10b8d..c08750984a 100644 --- a/l3kernel/testfiles/m3expl001.xetex.tlg +++ b/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... diff --git a/l3kernel/testfiles/m3expl003.luatex.tlg b/l3kernel/testfiles/m3expl003.luatex.tlg index f1d9026fda..77dd67cda7 100644 --- a/l3kernel/testfiles/m3expl003.luatex.tlg +++ b/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 ... diff --git a/l3kernel/testfiles/m3expl003.ptex.tlg b/l3kernel/testfiles/m3expl003.ptex.tlg index bd7025b373..0fb6d8b4f6 100644 --- a/l3kernel/testfiles/m3expl003.ptex.tlg +++ b/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 ... diff --git a/l3kernel/testfiles/m3expl003.tlg b/l3kernel/testfiles/m3expl003.tlg index e148e0601d..36bb25bfbe 100644 --- a/l3kernel/testfiles/m3expl003.tlg +++ b/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 ... diff --git a/l3kernel/testfiles/m3expl003.uptex.tlg b/l3kernel/testfiles/m3expl003.uptex.tlg index f844d07cde..25cae1ab4e 100644 --- a/l3kernel/testfiles/m3expl003.uptex.tlg +++ b/l3kernel/testfiles/m3expl003.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 ... diff --git a/l3kernel/testfiles/m3expl003.xetex.tlg b/l3kernel/testfiles/m3expl003.xetex.tlg index cdc9d10b8d..c08750984a 100644 --- a/l3kernel/testfiles/m3expl003.xetex.tlg +++ b/l3kernel/testfiles/m3expl003.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...