% \iffalse meta-comment % %% File: l3drivers.dtx % % Copyright (C) 2011-2019 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 % % https://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 development version of the bundle can be found at % % https://github.com/latex3/latex3 % % for those people who are interested. % %<*driver> \documentclass[full,kernel]{l3doc} \begin{document} \DocInput{\jobname.dtx} \end{document} % % \fi % % \title{^^A % The \textsf{l3drivers} package\\ Drivers^^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 2019-04-21} % % \maketitle % % \begin{documentation} % % \TeX{} relies on drivers in order to carry out a number of tasks, such % as using color, 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 \texttt{dvips} program, which works in % conjugation with \pdfTeX{} or \LuaTeX{} in DVI mode. % \item \texttt{dvipdfmx}: The \texttt{dvipdfmx} program, which works in % conjugation with \pdfTeX{} or \LuaTeX{} in DVI mode. % \item \texttt{dvisvgm}: The \texttt{dvisvgm} program, which works in % conjugation with \pdfTeX{} or \LuaTeX{} when run in DVI mode as well % as with (u)\pTeX{} and \XeTeX{}. % \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 % in format to those used by the underlying driver. % % Given the close coupling of these functions to higher-level interfaces, at % present the functions given here may change if this is useful for higher-level % changes. However, equivalent \emph{functionality} will be provided for any % higher-level function which is itself stable. For example, % \cs{driver_box_use_rotate:Nn} is needed to implement the stable box rotation % functions. As such, even if \cs{driver_box_use_rotate:Nn} were to be removed, % a replacement would be provided. % % \section{Box clipping} % % \begin{function}[added = 2017-12-13]{\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 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. % \end{function} % % \section{Box rotation and scaling} % % \begin{function}[added = 2017-12-13, updated = 2018-04-26] % {\driver_box_use_rotate:Nn} % \begin{syntax} % \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} (an \meta{fp expression} expressed in degrees). % The material 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 inserted material. % \end{function} % % \begin{function}[added = 2017-12-13, updated = 2018-04-26] % {\driver_box_use_scale:Nnn} % \begin{syntax} % \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} (both \meta{fp expressions}). % 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} % % \begin{function}[added = 2018-02-20]{\driver_color_cmyk:nnnn} % \begin{syntax} % \cs{driver_color_cmyk:nnnn} \Arg{cyan} \Arg{magenta} \Arg{yellow} % \Arg{black} % \end{syntax} % Sets the color to the CMYK values specified, all of which are % fp denotations in the range $0$ and $1$. For drawing colors, see % \cs{driver_draw_stroke_cmyk:nnnn}, \emph{etc.} % \end{function} % % \begin{function}[added = 2018-02-20]{\driver_color_gray:n} % \begin{syntax} % \cs{driver_color_gray:n} \Arg{gray} % \end{syntax} % Sets the color to the grayscale value specified, which is % fp denotations in the range $0$ and $1$. For drawing colors, see % \cs{driver_draw_stroke_gray:n}, \emph{etc.} % \end{function} % % \begin{function}[added = 2018-02-20]{\driver_color_rgb:nnn} % \begin{syntax} % \cs{driver_color_rgb:nnn} \Arg{red} \Arg{green} \Arg{blue} % \end{syntax} % Sets the color to the RGB values specified, all of which are % fp denotations in the range $0$ and $1$. For drawing colors, see % \cs{driver_draw_stroke_rgb:nnn}, \emph{etc.} % \end{function} % % \begin{function}[added = 2018-02-20]{\driver_color_pickup:N} % \begin{syntax} % \cs{driver_color_pickup:N} \meta{tl} % \end{syntax} % In \LaTeXe{} package mode, collects data on the current color from % \tn{current@color} and stores it in the low-level format used by \pkg{expl3} % in the \meta{tl}. % \end{function} % % \section{Drawing} % % These functions % are inspired heavily by the system layer of \pkg{pgf} (most have the % same interface as the same functions in the latter's \cs{pgfsys@\ldots} % namespace). They are intended to form the basis for higher level drawing % interfaces, which themselves are likely to be further abstracted for user % access. Again, this model is heavily inspired by \pkg{pgf} and % Ti\textit{k}z. % % These low level drawing interfaces abstract from the driver raw requirements % but still require an appreciation of the concepts of PostScript/PDF/SVG % graphic creation. % % \begin{function} % {\driver_draw_begin:, \driver_draw_end:} % \begin{syntax} % \cs{driver_draw_begin:} % \meta{content} % \cs{driver_draw_end:} % \end{syntax} % Defines a drawing environment. This is a scope for the purposes of % the graphics state. Depending on the driver, other set up may or may not % take place here. The natural size of the \meta{content} should be zero % from the \TeX{} perspective: allowance for the size of the content must % be made at a higher level (or indeed this can be skipped if the content is % to overlap other material). % \end{function} % % \begin{function} % {\driver_draw_scope_begin:, \driver_draw_scope_end:} % \begin{syntax} % \cs{driver_draw_scope_begin:} % \meta{content} % \cs{driver_draw_scope_end:} % \end{syntax} % Defines a scope for drawing settings and so on. Changes to the graphic % state and concepts such as color or linewidth are localised to a scope. % This function pair must never be used if an partial path is under % construction: such paths must be entirely contained at one unbroken % scope level. Note that scopes do not form \TeX{} groups and may not % be aligned with them. % \end{function} % % \subsection{Path construction} % % \begin{function}{\driver_draw_moveto:nn} % \begin{syntax} % \cs{driver_draw_move:nn} \Arg{x} \Arg{y} % \end{syntax} % Moves the current drawing reference point to (\meta{x}, \meta{y}); % any active transformation matrix applies. % \end{function} % % \begin{function}{\driver_draw_lineto:nn} % \begin{syntax} % \cs{driver_draw_lineto:nn} \Arg{x} \Arg{y} % \end{syntax} % Adds a path from the current drawing reference point to % (\meta{x}, \meta{y}); any active transformation matrix applies. Note % that nothing is drawn until a fill or stroke operation is applied, and that % the path may be discarded or used as a clip without appearing itself. % \end{function} % % \begin{function}{\driver_draw_curveto:nnnnnn} % \begin{syntax} % \cs{driver_draw_curveto:nnnnnn} \Arg{x_1} \Arg{y_1} % \Arg{x_2} \Arg{y_2} \Arg{x_3} \Arg{y_3} % \end{syntax} % Adds a Bezier curve path from the current drawing reference point to % (\meta{x_3}, \meta{y_3}), using (\meta{x_1}, \meta{y_1}) and % (\meta{x_2}, \meta{y_2}) as control points; any active transformation % matrix applies. Note that nothing is drawn until a fill or stroke % operation is applied, and that the path may be discarded or used as a clip % without appearing itself. % \end{function} % % \begin{function}{\driver_draw_rectangle:nnnn} % \begin{syntax} % \cs{driver_draw_rectangle:nnnn} \Arg{x} \Arg{y} \Arg{width} \Arg{height} % \end{syntax} % Adds rectangular path from (\meta{x_1}, \meta{y_1}) of \meta{height} % and \meta{width}; any active transformation matrix applies. Note that % nothing is drawn until a fill or stroke operation is applied, and that the % path may be discarded or used as a clip without appearing itself. % \end{function} % % \begin{function}{\driver_draw_closepath:} % \begin{syntax} % \cs{driver_draw_closepath:} % \end{syntax} % Closes an existing path, adding a line from the current point to the % start of path. Note that nothing is drawn until a fill or stroke % operation is applied, and that the path may be discarded or used as a clip % without appearing itself. % \end{function} % % \subsection{Stroking and filling} % % \begin{function}{\driver_draw_stroke:, \driver_draw_closestroke:} % \begin{syntax} % \meta{path construction} % \cs{driver_draw_stroke:} % \end{syntax} % Draws a line along the current path, which is also closed in the case of % \cs{driver_draw_closestroke:}. The nature of the line drawn % is influenced by settings for % \begin{itemize} % \item Line thickness % \item Stroke color (or the current color if no specific stroke color % is set) % \item Line capping (how non-closed line ends should look) % \item Join style (how a bend in the path should be rendered) % \item Dash pattern % \end{itemize} % The path may also be used for clipping. % \end{function} % % \begin{function}{\driver_draw_fill:, \driver_draw_fillstroke:} % \begin{syntax} % \meta{path construction} % \cs{driver_draw_fill:} % \end{syntax} % Fills the area surrounded by the current path: this will be closed prior % to filling if it is not already. The \texttt{fillstroke} version also % strokes the path as described for \cs{driver_draw_stroke:}. The fill is % influenced by the setting for fill color (or the current color if no % specific stroke color is set). The path may also be used for clipping. % For paths which are self-intersecting or comprising multiple parts, the % determination of which areas are inside the path is made using the non-zero % winding number rule unless the even-odd rule is active. % \end{function} % % \begin{function}{\driver_draw_nonzero_rule:, \driver_draw_evenodd_rule:} % \begin{syntax} % \cs{driver_draw_nonzero_rule:} % \end{syntax} % Active either the non-zero winding number or the even-odd rule, % respectively, for determining what is inside a fill or clip area. % For technical reasons, these command are not influenced by scoping % and apply on an ongoing basis. % \end{function} % % \begin{function}{\driver_draw_clip:} % \begin{syntax} % \meta{path construction} % \cs{driver_draw_clip:} % \end{syntax} % Indicates that the current path should be used for clipping, such that % any subsequent material outside of the path (but within the current % scope) will not be shown. This command should be given once a path is % complete but before it is stroked or filled (if appropriate). This % command is \emph{not} affected by scoping: it applies to exactly one % path as shown. % \end{function} % % \begin{function}{\driver_draw_discardpath:} % \begin{syntax} % \meta{path construction} % \cs{driver_draw_discardpath:} % \end{syntax} % Discards the current path without stroking or filling. This is primarily % useful for paths constructed purely for clipping, as this alone does not % end the paths existence. % \end{function} % % \subsection{Stroke options} % % \begin{function}{\driver_draw_linewidth:n} % \begin{syntax} % \cs{driver_draw_linewidth:n} \Arg{dimexpr} % \end{syntax} % Sets the width to be used for stroking to \meta{dimexpr}. % \end{function} % % \begin{function}{\driver_draw_dash_pattern:nn} % \begin{syntax} % \cs{driver_draw_dash:nn} \Arg{dash pattern} \Arg{phase} % \end{syntax} % Sets the pattern of dashing to be used when stroking a line. The % \meta{dash pattern} should be a comma-separated list of dimension % expressions. This is then interpreted as a series of pairs of line-on % and line-off lengths. For example \texttt{3pt, 4pt} means that $3$\,pt on, % $4$\,pt off, $3$\,pt on, and so on. A more complex pattern will also % repeat: \texttt{3pt, 4pt, 1pt, 2pt} results in $3$\,pt on, $4$\,pt off, % $1$\,pt on, $2$\,pt off, $3$\,pt on, and so on. An odd number of entries % means that the last is repeated, for example \texttt{3pt} is equal to % \texttt{3pt, 3pt}. An empty pattern yields a solid line. % % The \meta{phase} specifies an offset at the start of the cycle. For % example, with a pattern \texttt{3pt} a phase of \texttt{1pt} means % that the output is $2$\,pt on, $3$\,pt off, $3$\,pt on, $3$\,pt on, % \emph{etc.} % \end{function} % % \begin{function} % { % \driver_draw_cap_butt: , % \driver_draw_cap_rectangle: , % \driver_draw_cap_round: % } % \begin{syntax} % \cs{driver_draw_cap_butt:} % \end{syntax} % Sets the style of terminal stroke position to one of butt, rectangle or % round. % \end{function} % % \begin{function} % { % \driver_draw_join_bevel: , % \driver_draw_join_miter: , % \driver_draw_join_round: % } % \begin{syntax} % \cs{driver_draw_cap_butt:} % \end{syntax} % Sets the style of stroke joins to one of bevel, miter or round. % \end{function} % % \begin{function}{\driver_draw_miterlimit:n} % \begin{syntax} % \cs{driver_draw_miterlimit:n} \Arg{factor} % \end{syntax} % Sets the miter limit of lines joined as a miter, as described in the % PDF and PostScript manuals. The \meta{factor} here is an % \meta{fp expression}. % \end{function} % % \subsection{Color} % % \begin{function} % { % \driver_draw_color_fill_cmyk:nnnn , % \driver_draw_color_stroke_cmyk:nnnn % } % \begin{syntax} % \cs{driver_draw_color_fill_cmyk:nnnn} \Arg{cyan} \Arg{magenta} \Arg{yellow} % \Arg{black} % \end{syntax} % Sets the color for drawing to the CMYK values specified, all of which are % fp denotations in the range $0$ and $1$. % \end{function} % % \begin{function} % { % \driver_draw_color_fill_gray:n , % \driver_draw_color_stroke_gray:n % } % \begin{syntax} % \cs{driver_draw_color_fill_gray:n} \Arg{gray} % \end{syntax} % Sets the color for drawing to the grayscale value specified, which is % fp denotations in the range $0$ and $1$. % \end{function} % % \begin{function} % { % \driver_draw_color_fill_rgb:nnn , % \driver_draw_color_stroke_rgb:nnn % } % \begin{syntax} % \cs{driver_draw_color_fill_rgb:nnn} \Arg{red} \Arg{green} \Arg{blue} % \end{syntax} % Sets the color for drawing to the RGB values specified, all of which are % fp denotations in the range $0$ and $1$. % \end{function} % % \subsection{Inserting \TeX{} material} % % \begin{function}{\driver_draw_box_use:Nnnnn} % \begin{syntax} % \cs{driver_draw_box:Nnnnnnn} \meta{box} % \Arg{a} \Arg{b} \Arg{c} \Arg{d} \Arg{x} \Arg{y} % \end{syntax} % Inserts the \meta{box} as an hbox with the box reference point placed % at ($x$, $y$). The transformation matrix $[a b c d]$ is applied % to the box, allowing it to be in synchronisation with any scaling, rotation % or skewing applying more generally. Note that \TeX{} material should not % be inserted directly into a drawing as it would not be in the correct % location. Also note that as for other drawing elements the box here % has no size from a \TeX{} perspective. % \end{function} % % \subsection{Coordinate system transformations} % % \begin{function}{\driver_draw_cm:nnnn} % \begin{syntax} % \cs{driver_draw_cm:nnnn} \Arg{a} \Arg{b} \Arg{c} \Arg{d} % \end{syntax} % Applies the transformation matrix $[a b c d]$ to the current graphic state. % This affects any subsequent items in the same scope but not those already % given. % \end{function} % % \section{PDF Features} % % A range of PDF features are exposed by \pdfTeX{} and \LuaTeX{} in direct PDF % output mode, and the vast majority of these are also controllable using % the \texttt{(x)dvipdfmx} driver (as DVI instructions are converted directly % to PDF). Some of these functions are also available for cases where PDFs % are generated by \texttt{dvips}: this depends on being able to pass % information through correctly. % % \subsection{PDF Annotations} % % \begin{function}[added = 2019-04-10] % {\driver_pdf_annotation:nnnn} % \begin{syntax} % \cs{driver_pdf_annotation:nnnn} \Arg{width} \Arg{height} \Arg{depth} \Arg{dictionary} % \end{syntax} % Creates a generic PDF annotation of the given \meta{height}, \meta{width} % and \meta{depth} and featuring the \meta{dictionary}. % \end{function} % % \begin{function}[added = 2019-04-17] % { % \driver_pdf_link_begin_goto:nnw, % \driver_pdf_link_begin_user:nnw, % \driver_pdf_link_end: % } % \begin{syntax} % \cs{driver_pdf_link_begin_user:nnw} \Arg{attributes} \Arg{action} % \Arg{content} % \cs{driver_pdf_link_end:} % \end{syntax} % Creates a link of the \meta{type} |goto| or |user| with the given % \meta{attributes}, points toward the \meta{action} and surround the % \TeX{} \meta{content}. The |begin| and |end| functions must be given % at the same box level. Depending upon the back-end in use, the % \meta{content} may be placed in a hbox as part of processing. % \end{function} % % \begin{function}[EXP, added = 2019-04-09]{\driver_pdf_link_last:} % \begin{syntax} % \cs{driver_pdf_link_last:} % \end{syntax} % Expands to the object reference % \end{function} % % \begin{function}[EXP, added = 2019-04-11]{\driver_pdf_link_margin:n} % \begin{syntax} % \cs{driver_pdf_link_margin:} \Arg{dimen} % \end{syntax} % Sets the length of the margin between content and the border of a link. % Different back-ends treat the scoping of this value in different ways: % \pdfTeX{} and \LuaTeX{} treat it as scoped by \TeX{}, whilst with % \texttt{dvips} the scope is managed at the PostScript level. % \end{function} % % \subsection{PDF Objects} % % Objects are used to provide a range of data structures in a PDF. At the % driver level, different PDF object types are declared separately. Objects % are only \emph{written} to the PDF when referenced. % % \begin{function}{\driver_pdf_object_new:nn} % \begin{syntax} % \cs{driver_pdf_object_new:n} \Arg{name} \Arg{type} % \end{syntax} % Declares \meta{name} as a PDF object. The \texttt{type} should be one of % |array| or |dict|, |fstream| or |stream|. % \end{function} % % \begin{function}[EXP]{\driver_pdf_object_ref:n} % \begin{syntax} % \cs{driver_pdf_object_ref:n} \Arg{object} % \end{syntax} % Inserts the appropriate information to reference the \meta{object} % in for example page resource allocation. % \end{function} % % \begin{function}{\driver_pdf_object_write:nn} % \begin{syntax} % \cs{driver_pdf_object_write:nn} \Arg{name} \Arg{data} % \end{syntax} % Writes the \meta{data} as content of the \meta{object}. Depending on the % \meta{type} declared for the object, the format required for the % \meta{data} will vary % \begin{itemize} % \item[\texttt{array}] A space-separated list of values % \item[\texttt{dict}] Key--value pairs in the form % \texttt{/\meta{key} \meta{value}} % \item[\texttt{fstream}] Two brace groups: \meta{content} and % \meta{file name} % \item[\texttt{stream}] Two brace groups: \meta{content} and % \meta{additional attributes} % \end{itemize} % \end{function} % % \subsection{PDF structure} % % \begin{function}{\driver_pdf_compresslevel:n} % \begin{syntax} % \cs{driver_pdf_compresslevel:n} \Arg{level} % \end{syntax} % Sets the degree of compression used for PDF files: the \meta{level} should % be in the range $0$ to $9$ (higher is more compression). Typically, either % compression is disables ($0$) or maximised ($9$). When used with % \texttt{(x)dvipdfmx}, this setting may only be applied globally: it should % be set only once. % \end{function} % % \begin{function}{\driver_pdf_objects_enable:, \driver_pdf_objects_disable:} % \begin{syntax} % \cs{driver_pdf_objects_disable:} % \end{syntax} % Enables or disables the creation of PDF objects. These objects are used to % reduce the size of PDFs, and typically are enabled as standard. When used % with \texttt{(x)dvipdfmx}, object creation can be disabled but not % re-enabled, and this setting may only be applied globally: it should % be set only once. % \end{function} % % \begin{function}[EXP, added = 2019-04-11] % {\driver_pdf_version_major:, \driver_pdf_version_minor:} % \begin{syntax} % \cs{driver_pdf_version_major:} % \cs{driver_pdf_version_minor:} % \end{syntax} % Expands to the current value of the major or minor version of PDF being % created, a non-negative integer. Where a value is not available at the % \TeX{} run level, the result is $-1$. (This is necessary as the minor % version may be $0$.) % \end{function} % % \begin{function}[EXP, added = 2019-04-11] % {\driver_pdf_version_major_gset:n, \driver_pdf_version_minor_gset:n} % \begin{syntax} % \cs{driver_pdf_version_major_gset:n} \Arg{integer} % \cs{driver_pdf_version_minor_gset:n} \Arg{integer} % \end{syntax} % Sets the PDF version as specified: the allowable range is not checked % at this level. % \end{function} % % \end{documentation} % % \begin{implementation} % % \section{\pkg{l3drivers} Implementation} % % Nothing to see here: everything is in the subfiles! % % \end{implementation} % % \PrintIndex