summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3drivers.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3drivers.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3drivers.dtx749
1 files changed, 0 insertions, 749 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/l3drivers.dtx b/Master/texmf-dist/source/latex/l3kernel/l3drivers.dtx
deleted file mode 100644
index 8e22549f2ae..00000000000
--- a/Master/texmf-dist/source/latex/l3kernel/l3drivers.dtx
+++ /dev/null
@@ -1,749 +0,0 @@
-% \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}
-%</driver>
-% \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-05-28}
-%
-% \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_use:Nnnnn} \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 this function must be used inside a box of zero
-% size, shifted appropriately for the correct result; a low-level engine
-% error may result if this is not the case.
-% \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{Graphics inclusion}
-%
-% Graphics inclusion support is closely tied to the higher-level \pkg{l3graphics}
-% module. This arises as information concerning images (\emph{e.g.}~page
-% numbers in multi-page files) is needed to correct cache image data. As
-% such, the driver code here assumes the following are defined
-% \begin{itemize}
-% \item \cs{l_image_decodearray_tl}
-% \item \cs{l_image_interpolate_tl}
-% \item \cs{l_image_page_tl}
-% \item \cs{l_image_pagebox_tl}
-% \end{itemize}
-%
-% Note also that the functions defined will depend on the file types supported
-% by the driver. As such, a calling function should typically test for the
-% existence of an appropriate function to determine if the image file is
-% supported.
-%
-% \begin{function}[added = 2019-05-07]
-% {
-% \driver_graphics_getbb_eps:n,
-% \driver_graphics_getbb_jpg:n,
-% \driver_graphics_getbb_pdf:n,
-% \driver_graphics_getbb_png:n
-% }
-% \begin{syntax}
-% \cs{driver_graphics_getbb_pdf:n} \Arg{file}
-% \end{syntax}
-% These functions load the requested image \meta{file} and obtain the
-% bounding box information on the file. They may also cache the image for
-% subsequent inclusion: this is driver-dependent. The bounding box data
-% will be stored in \cs{l_image_llx_dim}, \cs{l_image_lly_dim},
-% \cs{l_image_urx_dim}, and \cs{l_image_ury_dim} after use of these
-% functions.
-% \end{function}
-%
-% \begin{function}[added = 2019-05-07]
-% {
-% \driver_graphics_include_eps:n,
-% \driver_graphics_include_jpg:n,
-% \driver_graphics_include_pdf:n,
-% \driver_graphics_include_png:n
-% }
-% \begin{syntax}
-% \cs{driver_graphics_include_pdf:n} \Arg{file}
-% \end{syntax}
-% These functions include the appropriate image type at the current position.
-% They should be preceded by use of the matching \texttt{getbb} function to
-% set the bounding box correctly; in some drivers, the \texttt{getbb}
-% function is also responsible for caching the image for later inclusion.
-% \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, updated = 2019-05-03]
-% {
-% \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:}
-% \cs{driver_pdf_link_begin_goto:nnw} \Arg{attributes} \Arg{target}
-% \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.
-% The |goto| type will automatically add |/Subtype /Link| to the PDF
-% dictionary for the annotation produced; other classes do not add
-% this, so the |/Subtype| must be provided as part of the \meta{action}.
-% \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:n} \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{} apply this at shipout (so it is global, once per
-% page), whilst with
-% \texttt{dvips} the scope is managed at the PostScript level. For
-% \texttt{(x)dvipdfmx}, this setting applies to \emph{all} annotations
-% (\emph{i.e.}~it is global), and thus it may be necessary to set to
-% \texttt{0pt} to avoid breaking for example animations. In general,
-% this setting should be applied once per document, prior to the
-% first page being shipped out.
-% \end{function}
-%
-% \begin{function}[added = 2019-04-26]{\driver_pdf_destination:nn}
-% \begin{syntax}
-% \cs{driver_pdf_destination:nn} \Arg{name} \Arg{action}
-% \end{syntax}
-% Creates a destination (anchor) called \meta{name}; when a jump is made
-% by a link to the destination, one of the following actions may take
-% place
-% \begin{itemize}
-% \item \texttt{xyz} Move the view such that the target point is at the
-% top-left of the viewer screen
-% \item \texttt{\meta{scale}} As for \texttt{xyz}, but also sets the
-% viewer \meta{scale}
-% \item \texttt{fit} Display the page containing the destination and fit
-% the entire page within the viewer window
-% \item \texttt{fitb} Display the page containing the destination and fit
-% the bounding box of the page within the viewer window
-% \item \texttt{fitbh} Move to the destination page such that the
-% anchor point is at the top of the viewer screen, and scale
-% such that the bounding box fills the viewer width
-% \item \texttt{fitbv} Move to the destination page such that the
-% anchor point is at the left of the viewer screen, and scale
-% such that the bounding box fills the viewer height
-% \item \texttt{fith} Move to the destination page such that the
-% anchor point is at the top of the viewer screen, and scale
-% such that the page fills the viewer width
-% \item \texttt{fitv} Move to the destination page such that the
-% anchor point is at the left of the viewer screen, and scale
-% such that the page fills the viewer height
-% \end{itemize}
-% A \meta{scale} of zero is equivalent to \texttt{xyz}.
-% \end{function}
-%
-% \begin{function}[added = 2019-04-28]{\driver_pdf_destination_rectangle:nn}
-% \begin{syntax}
-% \cs{driver_pdf_destination_rectangle:nn} \Arg{name} \Arg{content}
-% \end{syntax}
-% Creates a destination (anchor) called \meta{name}; when a jump is made
-% by a link to the destination, the viewer will set the zoom such that all
-% of the \meta{content} is visible taking up the full width or height of the
-% viewer area.
-% \end{function}
-%
-% \subsection{PDF Catalogue entries}
-%
-% \begin{function}[added = 2019-04-28]{\driver_pdf_catalog_gput:nn}
-% \begin{syntax}
-% \cs{driver_pdf_catalog_gput:nn} \Arg{key} \Arg{value}
-% \end{syntax}
-% Adds the key--value pair to the PDF catalog. The \meta{key} should
-% be given \emph{without} the leading |/|. The \meta{value} should be
-% a \enquote{raw} PDF dictionary entry, including the |(|/|)| pair for
-% a string, a leading |/| for a boolean, \emph{etc.}
-% \end{function}
-%
-% \begin{function}[added = 2019-04-28]{\driver_pdf_info_gput:nn}
-% \begin{syntax}
-% \cs{driver_pdf_info_gput:nn} \Arg{key} \Arg{value}
-% \end{syntax}
-% Adds the key--value pair to the PDF information. The \meta{key} should
-% be given \emph{without} the leading |/|. The \meta{value} should be
-% a \enquote{raw} PDF dictionary entry, including the |(|/|)| pair for
-% a string or leading |/| for a boolean.
-% \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{file name} and
-% \meta{content}
-% \item[\texttt{stream}] Two brace groups: \meta{attributes (dictionary)}
-% and \meta{content}
-% \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}[added = 2019-05-07]{\driver_pdf_objects:}
-% \begin{syntax}
-% \cs{driver_pdf_compress_objects:n} \Arg{switch}
-% \end{syntax}
-% Enables or disables the compression of non-stream objects when writing
-% the PDF. This depends on the \meta{switch}: either \texttt{true} or
-% \texttt{false}). Compression of non-stream objects is 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. Note that for \texttt{dvips} this setting has no action,
-% as control of this functionality is dependent on the conversion from
-% PostScript to PDF.
-% \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