% \iffalse meta-comment % %% File: l3drivers.dtx Copyright(C) 2011 The LaTeX3 Project %% %% It may be distributed and/or modified under the conditions of the %% LaTeX Project Public License (LPPL), either version 1.3c of this %% license or (at your option) any later version. The latest version %% of this license is in the file %% %% http://www.latex-project.org/lppl.txt %% %% This file is part of the "l3kernel bundle" (The Work in LPPL) %% and all files in that bundle must be distributed together. %% %% The released version of this bundle is available from CTAN. %% %% ----------------------------------------------------------------------- %% %% The development version of the bundle can be found at %% %% http://www.latex-project.org/svnroot/experimental/trunk/ %% %% for those people who are interested. %% %%%%%%%%%%% %% NOTE: %% %%%%%%%%%%% %% %% Snapshots taken from the repository represent work in progress and may %% not work or may contain conflicting material! We therefore ask %% people _not_ to put them into distributions, archives, etc. without %% prior consultation with the LaTeX Project Team. %% %% ----------------------------------------------------------------------- %% % %<*driver|package> \RequirePackage{l3names} \GetIdInfo$Id: l3drivers.dtx 3086 2011-12-22 17:55:46Z bruno $ {L3 Experimental drivers} % %<*driver> \documentclass[full]{l3doc} \begin{document} \DocInput{\jobname.dtx} \end{document} % % \fi % % \title{^^A % The \textsf{l3drivers} package\\ Drivers^^A % \thanks{This file describes v\ExplFileVersion, % last revised \ExplFileDate.}^^A % } % % \author{^^A % The \LaTeX3 Project\thanks % {^^A % E-mail: % \href{mailto:latex-team@latex-project.org} % {latex-team@latex-project.org}^^A % }^^A % } % % \date{Released \ExplFileDate} % % \maketitle % % \begin{documentation} % % \TeX{} relies on drivers in order to carry out a number of tasks, such % as using colour, including graphics and setting up hyper-links. The nature % of the code required depends on the exact driver in use. Currently, % \LaTeX3 is aware of the following drivers: % \begin{itemize} % \item \texttt{pdfmode}: The \enquote{driver} for direct PDF output by % \emph{both} \pdfTeX{} and \LuaTeX{} (no separate driver is used in this % case: the engine deals with PDF creation itself). % \item \texttt{dvips}: The dvips program, which works in conjugation with % \pdfTeX{} or \LuaTeX{} in DVI mode. % \item \texttt{xdvipdfmx}: The driver used by \XeTeX{}. % \end{itemize} % % The code here is all very low-level, and should not in general be used % outside of the kernel. It is also important to note that many of the % functions here are closely tied to the immediate level \enquote{up}: % several variable values must be in the correct locations for the driver % code to function. % % \section{Box clipping} % % \begin{function}[added = 2011-11-11]{\driver_box_use_clip:N} % \begin{syntax} % \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 will not be displayed % by the driver. The material in the \meta{box} is still places in the % output stream: the clipping takes place at a driver level. % \end{function} % % \section{Box rotation and scaling} % % \begin{function}[added = 2011-09-01] % {\driver_box_rotate_begin:, \driver_box_rotate_end:} % \begin{syntax} % \cs{driver_box_rotate_begin:} % \cs{box_use:N} \cs{l_box_tmp_box} % \cs{driver_box_rotate_end:} % \end{syntax} % Rotates the \meta{box material} anti-clockwise around the current % insertion point. The angle of rotation (in degrees counter-clockwise) % and the sine and cosine of this angle should be stored in % \cs{l_box_angle_fp}, \cs{l_box_sin_fp} and \cs{l_box_cos_fp}, % respectively. Typically, the box material inserted between the beginning % and end markers will be stored in \cs{l_box_tmp_box}: this fact is % required by some drivers to obtain the correct output. % \end{function} % % \begin{function}[added = 2011-09-02] % {\driver_box_scale_begin:, \driver_box_scale_end:} % \begin{syntax} % \cs{driver_box_scale_begin:} % \meta{box material} % \cs{driver_box_scale_end:} % \end{syntax} % Scales the \meta{box material} (which should be either a \cs{box_use:N} % or \cs{hbox:n} construct). The \meta{box material} is scaled by the values % stored in \cs{l_box_scale_x_fp} and \cs{l_box_scale_y_fp} in the % horizontal and vertical directions, respectively. This function is % also reused when resizing boxes: at a driver level, only scalings are % supported and so the higher-level code must convert the absolute sizes % to scale factors. % \end{function} % % \section{Colour support} % % \begin{function}[added = 2011-09-03]{\driver_color_ensure_current:} % \begin{syntax} % \cs{driver_color_ensure_current:} % \end{syntax} % Ensures that the colour used to typeset material is that which was % set when the material was placed in a box. This function is therefore % required inside any \enquote{colour safe} box to ensure that the box may % be inserted in a location where the foreground colour has been altered, % while preserving the colour used in the box. % \end{function} % % \end{documentation} % % \begin{implementation} % % \section{\pkg{l3drivers} Implementation} % % \begin{macrocode} %<*initex|package> % \end{macrocode} % % \begin{macrocode} %<*package> \ProvidesExplFile %<*dvips> {l3pdfmode.def}{\ExplFileDate}{\ExplFileVersion} {L3~Experimental~driver:~dvips} % %<*pdfmode> {l3pdfmode.def}{\ExplFileDate}{\ExplFileVersion} {L3~Experimental~driver:~PDF~mode} % %<*xdvipdfmx> {l3pdfmode.def}{\ExplFileDate}{\ExplFileVersion} {L3~Experimental~driver:~xdvipdfmx} % \package_check_loaded_expl: % % \end{macrocode} % % \subsection{Settings for direct PDF output} % % If the driver loaded is \texttt{pdfmode} then direct PDF output is required. % (This may of course alter: it might be that the driver is picked based on the % value of \cs{pdfmode_pdfoutput:D}.) % \begin{macrocode} %<*initex> %<*pdfmode> \pdftex_pdfoutput:D = 1 \scan_stop: % % % \end{macrocode} % % Set up the driver for direct PDF output to set the PDF origin equal to % \TeX{}'s standard origin. The other settings make use of PDF~$1.5$, which % is standard in \TeX{} Live 2011 and should be a reasonable baseline for % the future. % \begin{macrocode} %<*initex> %<*pdfmode> \pdftex_pdfhorigin:D = 1 true in \scan_stop: \pdftex_pdfvorigin:D = 1 true in \scan_stop: \pdftex_pdfdecimaldigits:D = 3 \scan_stop: \pdftex_pdfpkresolution:D = 600 \scan_stop: \pdftex_pdfminorversion:D = 5 \scan_stop: \pdftex_pdfcompresslevel:D = 9 \scan_stop: \pdftex_pdfobjcompresslevel:D = 2 \scan_stop: % % % \end{macrocode} % % \subsection{Driver utility functions} % % \begin{macro}{\driver_graphic_state_save:} % \begin{macro}{\driver_graphic_state_restore:} % All of the drivers have a stack for saving the graphic state. These % have slightly different interfaces. As \texttt{dvips} does not % automatically save the current location, this is set up here. % \begin{macrocode} \cs_new_protected:Npn \driver_graphic_state_save: %<*dvips> { \tex_special:D { ps:gsave } } % %<*pdfmode> { \pdftex_pdfsave:D } % %<*xdvipdfmx> { \tex_special:D { pdf:bcontent } } % \cs_new_protected:Npn \driver_graphic_state_restore: %<*dvips> { \tex_special:D { ps:grestore } } % %<*pdfmode> { \pdftex_pdfrestore:D } % %<*xdvipdfmx> { \tex_special:D { pdf:econtent } } % % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macro}{\driver_pdf_literal:n, \driver_pdf_literal_direct:n} % Both direct PDF mode and \texttt{xdvipdfmx} make use of direct PDF % special insertion. These are slightly different in the two cases. % The |direct| versions do not save the current matrix. % \begin{macrocode} %<*pdfmode|xdvipdfmx> \cs_new_protected:Npn \driver_pdf_literal:n #1 %<*pdfmode> { \pdftex_pdfliteral:D {#1} } % %<*xdvipdfmx> { \tex_special:D { pdf:content~ #1 } } % \cs_new_protected:Npn \driver_pdf_literal_direct:n #1 %<*pdfmode> { \pdftex_pdfliteral:D direct~{#1} } % %<*xdvipdfmx> { \tex_special:D { pdf:literal~direct~ #1 } } % % % \end{macrocode} % \end{macro} % % \begin{macro}{\driver_ps_literal:n} % The same concept for PostScript: these are \enquote{direct} by default, % but by keeping the same name life should be a little clearer. % \begin{macrocode} %<*dvips> \cs_new_protected:Npn \driver_ps_literal:n #1 { \tex_special:D { ps: #1 } } % % \end{macrocode} % \end{macro} % % \subsection{Box clipping} % % \begin{macro}{\driver_box_use_clip:N} % The overall logic to clipping a box is the same in all cases. 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 using % a horizontal skip before tidying up. There are other approaches that % can be taken (for example using XForm objects), but the logic here shares % as much code as possible and uses the same conversions (and so same % rounding errors) in all three cases. % \begin{macrocode} \cs_new_protected:Npn \driver_box_use_clip:N #1 { \driver_graphic_state_save: % \end{macrocode} % The business end of the code sets up the clip box, using the higher-level % rectangle operators rather than the lower level direct line drawing. This % makes sense for a simple rectangular clip. There are a couple of approaches % for \texttt{dvips}. The approach here is to save the current matrix, % then translate to the current \TeX{} position and switch to big point % measurement. The clip box can then be set up using the same conversion % as for direct PDF output: notice that here the $y$-axis is upside down. % The original matrix is then restored, so that \TeX{} inserts material % in the correct place (there is an offset between the PostScript and % \TeX{} current positions). % \begin{macrocode} %<*dvips> \driver_ps_literal:n { /savedmatrix~matrix~currentmatrix~def~ currentpoint~translate~ Resolution~72~div~VResolution~72~div~scale } \driver_ps_literal:n { 0~ -\dim_strip_bp:n { \box_dp:N #1 } ~neg~ \dim_strip_bp:n { \box_wd:N #1 } ~ \dim_strip_bp:n { \box_ht:N #1 + \box_dp:N #1 } ~neg~ rectclip } \driver_ps_literal:n { savedmatrix~setmatrix } % % \end{macrocode} % The PDF box is easier to define as it is automatically in big points and % as the driver deals with the relationship between the \TeX{} and graphics % locations automatically. % \begin{macrocode} %<*pdfmode|xdvipdfmx> \driver_pdf_literal_direct:n { 0 ~ -\dim_strip_bp:n { \box_dp:N #1 } ~ \dim_strip_bp:n { \box_wd:N #1 } ~ \dim_strip_bp:n { \box_ht:N #1 + \box_dp:N #1 } ~ re~W~n } % % \end{macrocode} % Insert the material in a box of no width, restore the graphic state % and then insert the necessary width. % \begin{macrocode} \hbox_overlap_right:n { \box_use:N #1 } \driver_graphic_state_restore: \skip_horizontal:n { \box_wd:N #1 } } % \end{macrocode} % \end{macro} % % \subsection{Box rotation and scaling} % % \begin{variable}{\l_driver_tmp_fp} % Needed for a safe sign inversion in PDF mode. % \begin{macrocode} %<*pdfmode|xdvipdfmx> \fp_new:N \l_driver_tmp_fp % % \end{macrocode} % \end{variable} % % \begin{macro}{\driver_box_rotate_begin:, \driver_box_rotate_end:} % The driver for \texttt{dvips} works with a simple rotation angle. % In PDF mode, an affine matrix is used instead. The transformation for % \texttt{xdvipdfmx} can be done either way: to have some code sharing, % the choice here is to use an affine approach (at least some code is % shared in this way). For the \texttt{dvips}, that odd-looking % |currentpoint| at the beginning is used to put this data onto the % stack for |neg exch neg exch translate| to pick up. % \begin{macrocode} \cs_new_protected:Npn \driver_box_rotate_begin: { \driver_graphic_state_save: %<*dvips> \driver_ps_literal:n { currentpoint~ currentpoint~translate~ \fp_use:N \l_box_angle_fp \c_space_tl neg~rotate~ neg~exch~neg~exch~translate } % %<*pdfmode|xdvipdfmx> \box_set_wd:Nn \l_box_tmp_box \c_zero_dim \fp_set_eq:NN \l_driver_tmp_fp \l_box_sin_fp \fp_neg:N \l_driver_tmp_fp %<*pdfmode> \pdftex_pdfsetmatrix:D % %<*xdvipdfmx> \driver_pdf_literal_direct:n % { \fp_use:N \l_box_cos_fp \c_space_tl \fp_use:N \l_box_sin_fp \c_space_tl \fp_use:N \l_driver_tmp_fp \c_space_tl \fp_use:N \l_box_cos_fp %<*xdvipdfmx> \c_space_tl 0~0~cm % } % } % \end{macrocode} % The end of a rotation means tidying up the output grouping. % \begin{macrocode} \cs_new_eq:NN \driver_box_rotate_end: \driver_graphic_state_restore: % \end{macrocode} % \end{macro} % % \begin{macro}{\driver_box_scale_begin:, \driver_box_scale_end:} % Scaling is not dissimilar to rotation, but the calculations are somewhat % less complex. % \begin{macrocode} \cs_new_protected:Npn \driver_box_scale_begin: { \driver_graphic_state_save: %<*dvips> \driver_ps_literal:n { currentpoint~ currentpoint~translate~ \fp_use:N \l_box_scale_x_fp \c_space_tl \fp_use:N \l_box_scale_y_fp \c_space_tl scale~ neg~exch~neg~exch~translate } % %<*pdfmode|xdvipdfmx> %<*pdfmode> \pdftex_pdfsetmatrix:D % %<*xdvipdfmx> \driver_pdf_literal_direct:n % { \fp_use:N \l_box_scale_x_fp \c_space_tl 0~0~ \fp_use:N \l_box_scale_y_fp %<*xdvipdfmx> \c_space_tl 0~0~cm % } % } \cs_new_eq:NN \driver_box_scale_end: \driver_graphic_state_restore: % \end{macrocode} % \end{macro} % % \subsection{Colour support} % % \begin{variable}{\l_driver_current_color_tl} % The current colour is needed by all of the engines, but the way this % is stored varies. % \begin{macrocode} \tl_new:N \l_driver_current_color_tl %<*dvips> \tl_set:Nn \l_driver_current_color_tl { Black } % %<*pdfmode> \tl_set:Nn \l_driver_current_color_tl { 0~g~0~G } % %<*xdvipdfmx> \tl_set:Nn \l_driver_current_color_tl { gray~0 } % % \end{macrocode} % \end{variable} % % \begin{variable}{\l_driver_color_stack_int} % \pdfTeX{} and \LuaTeX{} have multiple stacks available, and the colour % stack therefore needs a number. % \begin{macrocode} %<*pdfmode> \int_new:N \l_driver_color_stack_int % % \end{macrocode} % \end{variable} % % \begin{macro}{\driver_color_ensure_current:} % \begin{macro}[aux]{\driver_color_reset:} % Setting the current colour depends on the nature of the colour stack % available. In all cases there is a need to reset the colour after % the current group. % \begin{macrocode} \cs_new_protected:Npn \driver_color_ensure_current: { %<*dvips|xdvipdfmx> \tex_special:D { color~push~\l_driver_current_color_tl } % %<*pdfmode> \pdftex_pdfcolorstack:D \l_driver_color_stack_int push { \l_driver_current_color_tl } % \group_insert_after:N \driver_color_reset: } \cs_new_protected:Npn \driver_color_reset: %<*dvips|xdvipdfmx> { \tex_special:D { color~pop } } % %<*pdfmode> { \pdftex_pdfcolorstack:D \l_driver_color_stack_int pop } % % \end{macrocode} % \end{macro} % \end{macro} % % \begin{macrocode} % % \end{macrocode} % % \end{implementation} % % \PrintIndex