summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3experimental/l3draw/l3draw.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3experimental/l3draw/l3draw.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3experimental/l3draw/l3draw.dtx670
1 files changed, 602 insertions, 68 deletions
diff --git a/Master/texmf-dist/source/latex/l3experimental/l3draw/l3draw.dtx b/Master/texmf-dist/source/latex/l3experimental/l3draw/l3draw.dtx
index 9b7c04d5e54..7cefc6d837d 100644
--- a/Master/texmf-dist/source/latex/l3experimental/l3draw/l3draw.dtx
+++ b/Master/texmf-dist/source/latex/l3experimental/l3draw/l3draw.dtx
@@ -25,6 +25,71 @@
%</driver|package>
%<*driver>
\documentclass[full]{l3doc}
+\usepackage[utf8]{inputenc}
+\usepackage{l3draw}
+% For creating code demonstrations
+% This needs access to some code-level interfaces in listings
+\usepackage{listings}
+\makeatletter
+\lst@RequireAspects{writefile}
+\newsavebox\demo@box
+\lstnewenvironment{demo}[1][code and example]
+ {%
+ \global\let\lst@intname\@empty
+ \edef\demo@end{%
+ \expandafter\noexpand\csname demo@@#1@end\endcsname
+ }%
+ \@nameuse{demo@@#1}%
+ }
+ {\demo@end}
+\newcommand\demo@new[3]{%
+ \@namedef{demo@@#1}{#2}%
+ \@namedef{demo@@#1@end}{#3}%
+}
+\newcommand*\demo@common{%
+ \setkeys{lst}
+ {%
+ basicstyle = \small\ttfamily,
+ basewidth = 0.51em,
+ gobble = 5,
+ language = [LaTeX]{TeX},
+ }%
+}
+\newcommand*\demo@input{%
+ \ExplSyntaxOn
+ \catcode`\^^M = 10\relax
+ \catcode`\% = 14\relax
+ \input{\jobname.tmp}%
+ \ExplSyntaxOff
+}
+\demo@new{code and example}{%
+ \setbox\demo@box=\hbox\bgroup
+ \lst@BeginAlsoWriteFile{\jobname.tmp}%
+ \demo@common
+}{%
+ \lst@EndWriteFile
+ \egroup
+ \begin{center}
+ \ifdim\wd\demo@box > 0.75\linewidth
+ \begin{minipage}{\linewidth}
+ \usebox\demo@box
+ \end{minipage}%
+ \par
+ \begin{minipage}{\linewidth}
+ \demo@input
+ \end{minipage}
+ \else
+ \begin{minipage}{0.25\linewidth}
+ \demo@input
+ \end{minipage}%
+ \hfil
+ \begin{minipage}{0.75\linewidth}
+ \usebox\demo@box
+ \end{minipage}%
+ \fi
+ \end{center}
+}
+\makeatother
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
@@ -44,7 +109,7 @@
% }^^A
% }
%
-% \date{Released 2018/02/21}
+% \date{Released 2018/03/05}
%
% \maketitle
%
@@ -82,6 +147,64 @@
% The drawing created within the environment will be inserted into
% the typesetting stream by the \cs{draw_end:} function, which will
% switch out of vertical mode if required.
+% \begin{demo}
+% \dim_new:N \l_mypos_dim
+% \draw_begin:
+% \draw_path_moveto:n { 0cm , \l_mypos_dim }
+% \draw_path_lineto:n { 1cm , \l_mypos_dim }
+% \dim_set:Nn \l_mypos_dim { 1cm }
+% \draw_path_lineto:n { 1cm , \l_mypos_dim }
+% \draw_path_close:
+% \draw_path_use_clear:n { stroke }
+% \draw_end:
+% \end{demo}
+%
+% Within a drawing, the only commands that should appear are those directly
+% aimed at drawing (from \pkg{l3draw}) and those which produce \emph{no}
+% typeset output. For example, it is possible to include loops inside a
+% drawing using |\int_step_function:nnnn| or similar. On the other hand,
+% text should not be included directly in drawings, but should rather be
+% inserted using the appropriate \pkg{l3draw} command.
+% \end{function}
+%
+% Within a drawing, there are different ways of referring to a position.
+% The co-ordinates of a point are given relative to the current
+% \emph{drawing axes}. These can be manipulated and tracked at the code
+% level. Underlying this is the \meta{canvas}, which is at the \pkg{draw}
+% level essentially fixed and in line with the paper. Initially, the two
+% sets of axes are coincident. (It is possible to manipulate the canvas
+% axes at the driver level: this is then \enquote{transparent} to the
+% \pkg{draw} level, and so should be used only when strictly required.)
+%
+% \begin{function}{\draw_suspend_begin:, \draw_suspend_end:}
+% \begin{syntax}
+% \cs{draw_suspend_begin:}
+% ...
+% \cs{draw_suspend_end:}
+% \end{syntax}
+% Suspends all of the drawing mechanisms to allow \enquote{normal}
+% material to be created. Typically, this environment will be applied
+% inside a box which may contain nested pictures.
+% \begin{demo}
+% \draw_begin:
+% \draw_path_moveto:n { 0cm , 0cm }
+% \hbox_set:Nn \l_tmpa_box
+% {
+% \draw_suspend_begin:
+% This~is~normal~text.
+% \draw_begin: % A subpicture
+% \draw_path_moveto:n { 1cm , 0cm }
+% \draw_path_lineto:n { 1cm , 1cm }
+% \draw_path_use_clear:n { stroke }
+% \draw_end:
+% More~text.
+% \draw_suspend_end:
+% }
+% \draw_box_use:N \l_tmpa_box
+% \draw_path_lineto:n { 0cm , 1cm }
+% \draw_path_use_clear:n { stroke }
+% \draw_end:
+% \end{demo}
% \end{function}
%
% \subsection{Graphics state}
@@ -90,10 +213,10 @@
% will appear. Note that these all apply \emph{globally}, though some are
% rest at the start of each drawing (\cs{draw_begin:}).
%
-% \begin{function}{\g_draw_linewidth_default_dim}
+% \begin{variable}{\g_draw_linewidth_default_dim}
% The default value of the linewidth for stokes, set at the start
% of every drawing (\cs{draw_begin:}).
-% \end{function}
+% \end{variable}
%
% \begin{function}{\draw_linewidth:n, \draw_inner_linewidth:n}
% \begin{syntax}
@@ -140,10 +263,54 @@
%
% \begin{function}{\draw_miterlimit:n}
% \begin{syntax}
-% \cs{draw_miterlimit:n} \Arg{limit}
+% \cs{draw_miterlimit:n} \Arg{factor}
% \end{syntax}
-% Sets the miter \meta{limit} of lines joined as a miter, as described in the
-% PDF and PostScript manuals. The \meta{limit} is an \meta{fp expr}.
+% Sets the miter \meta{factor} of lines joined as a miter, as described in the
+% PDF and PostScript manuals. The \meta{factor} is an \meta{fp expr}.
+% \end{function}
+%
+% \subsection{Scoping drawing elements}
+%
+% Scoping drawing elements is necessary to allowing nesting of subparts.
+% These features have specific use requirements: the preconditions must be
+% met. In particular, each type of drawing scope also constitutes a
+% group (\cs{groupd_being:}/\cs{group_end:} pair): as such, they must be
+% nested correctly.
+%
+% \begin{function}{\draw_scope_begin:, \draw_scope_end:}
+% \begin{syntax}
+% \cs{draw_scope_begin:}
+% ...
+% \cs{draw_scope_end:}
+% \end{syntax}
+% Creates a scope for localisation of state settings within a drawing.
+% A scope forms a \TeX{} group but will also localise global state
+% variables (such as \cs{g_draw_linewidth_default_dim}), and driver-level
+% concepts such as the termination of lines.
+% \begin{demo}
+% \draw_begin:
+% \draw_scope_begin:
+% \group_begin:
+% \draw_linewidth:n { 2pt }
+% \draw_path_rectangle:nn { 0 , 0 } { 2ex , 2ex }
+% \draw_path_use:n { stroke }
+% \group_end:
+% \draw_path_rectangle:nn { 3ex , 0ex } { 2ex , 2ex }
+% \draw_path_use:n { stroke }
+% \draw_scope_end:
+% \draw_path_rectangle:nn { 6ex , 0ex } { 2ex , 2ex }
+% \draw_path_use_clear:n { stroke }
+% \draw_end:
+% \end{demo}
+% Global graphical concepts restricted by scope are
+% \begin{itemize}
+% \item Line width
+% \item Stroke and fill color
+% \item Dash pattern
+% \item Line joining and capping, including the miter limit
+% \item Clipping paths
+% \item Canvas (driver) transformations
+% \end{itemize}
% \end{function}
%
% \subsection{Points}
@@ -180,7 +347,7 @@
% higher-level functions, for example path construction, and allows parts of
% a drawing to be rotated, scaled or skewed. This occurs before writing any
% data to the driver, and so such manipulations are tracked by the drawing
-% mechanisms. See \cs{driver_draw_transformcm:nnnnnn} for driver-level
+% mechanisms. See \cs{driver_draw_cm:nnnn} for driver-level
% manipulation of the canvas axes themselves.
%
% Notice that in contrast to \pkg{pgf} it is possible to give the positions
@@ -235,8 +402,8 @@
% \begin{syntax}
% \cs{draw_point_unit_vector:n} \Arg{point}
% \end{syntax}
-% Expands to the co-ordinates of a unit vector joining the \meta{point}
-% with the origin.
+% Expands to the co-ordinates of a unit vector in the direction of the
+% \meta{point} from the origin.
% \end{function}
%
% \begin{function}[EXP]{\draw_point_transform:n}
@@ -255,9 +422,9 @@
% co-incident with the standard Cartesian axes, but may be altered by
% the user.
%
-% \begin{function}{\draw_xvec_set:n, \draw_yvec_set:n, \draw_zvec_set:n}
+% \begin{function}{\draw_xvec:n, \draw_yvec:n, \draw_zvec:n}
% \begin{syntax}
-% \cs{draw_xvec_set:n} \Arg{point}
+% \cs{draw_xvec:n} \Arg{point}
% \end{syntax}
% Defines the appropriate base vector to point toward the \meta{point}
% on the canvas. The standard settings for the $x$- and $y$-vectors are
@@ -358,16 +525,86 @@
% manipulated or indeed discarded entirely. Only one path is active at
% any one time, and the path is \emph{not} affected by \TeX{} grouping.
%
-% \begin{function}{\draw_path_corner_arc:n}
+% \begin{function}{\draw_path_corner_arc:nn}
+% \begin{syntax}
+% \cs{draw_path_corner_arc:n} \Arg{length1} \Arg{length2}
+% \end{syntax}
+% Sets the degree of rounding applied to corners in a path: the two
+% \meta{length} values are the distances from the corner at which the curving
+% should start. The first \meta{length} applies to the part of the path
+% \enquote{leading in} to the corner (\emph{i.e.}~from the previous path
+% operation), and the second to that \enquote{leading out}. If both
+% values are \texttt{0pt} then corners will not be rounded. The values
+% apply within the scope of the current \TeX{} group.
+% \begin{demo}
+% \draw_begin:
+% \draw_path_corner_arc:nn { 5mm } { 5mm }
+% \draw_path_rectangle_corners:nn
+% { 0cm , 0cm } { 3cm , 2cm }
+% \draw_path_use_clear:n { stroke }
+% \draw_end:
+% \end{demo}
+% \begin{demo}
+% \draw_begin:
+% \draw_path_corner_arc:nn { 10mm } { 5mm }
+% \draw_path_moveto:n { 0cm , 0cm }
+% \draw_path_lineto:n { 0cm , 2cm }
+% \draw_path_lineto:n { 3cm , 2cm }
+% \draw_path_curveto:nnn
+% { 3cm , 0cm } { 2cm , 0cm } { 1cm , 0 cm }
+% \draw_path_use_clear:n { stroke }
+% \draw_end:
+% \end{demo}
+% The corners created are quarter-circles for exact right-angles and
+% close approximations otherwise. Closing a path will result in rounding
+% correctly.
+% \begin{demo}
+% \draw_begin:
+% \draw_path_corner_arc:nn { 4pt } { 4pt }
+% \draw_path_moveto:n
+% { \draw_point_polar:nn { 0 } { 1cm } }
+% \int_step_inline:nnnn { 72 } { 72 } { 359 }
+% {
+% \draw_path_lineto:n
+% { \draw_point_polar:nn { #1 } { 1cm } }
+% }
+% \draw_path_close:
+% \draw_path_use_clear:n { stroke }
+% \draw_end:
+% \end{demo}
+% \end{function}
+%
+% \begin{function}{\draw_path_close:}
% \begin{syntax}
-% \cs{draw_path_corner_arc:n} \Arg{length}
+% \cs{draw_path_close:}
% \end{syntax}
-% Sets the degree of rounding applied to corners in a path: if the
-% \meta{length} is \texttt{0pt} then no rounding applies. The value of the
-% \meta{length} is local to the current \TeX{} group. \emph{At present,
-% corner arcs are not activated in the code.}
+% Closes the current part of the path by appending a straight line from
+% the current point to the starting point of the path. In general, any
+% path to be \emph{filled} should include a close instructions.
% \end{function}
%
+% \begin{function}{\draw_path_use:n, \draw_path_use_clear:n}
+% \begin{syntax}
+% \cs{draw_path_use:n} \Arg{action(s)}
+% \end{syntax}
+% Inserts the current path, carrying out one ore more possible \meta{actions}
+% (a comma list):
+% \begin{itemize}
+% \item \texttt{clear} Resets the path to empty
+% \item \texttt{clip} Clips any content outside of the path
+% \item \texttt{draw}
+% \item \texttt{fill} Fills the interior of the path with the current
+% file color
+% \item \texttt{stroke} Draws a line along the current path
+% \end{itemize}
+% \end{function}
+%
+% \subsubsection{Path operations on drawing axes}
+%
+% The standard path functions are all influenced by the active transformation
+% matrix, \emph{i.e.}~the work relative to the drawing axes rather than
+% the canvas.
+%
% \begin{function}{\draw_path_moveto:n}
% \begin{syntax}
% \cs{draw_path_moveto:n} \Arg{point}
@@ -381,6 +618,32 @@
% \cs{draw_path_lineto:n} \Arg{point}
% \end{syntax}
% Joins the current path to the \meta{point} with a straight line.
+% In general, for reliable treatment by viewers, a \cs{draw_path_moveto:n}
+% operation should precede the first use of a \cs{draw_path_lineto:n}
+% on a path.
+% \begin{demo}
+% \draw_begin:
+% \draw_path_moveto:n { 0cm , 0cm }
+% \draw_path_lineto:n { 1cm , 1cm }
+% \draw_path_lineto:n { 2cm , 1cm }
+% \draw_path_lineto:n { 3cm , 0.5cm }
+% \draw_path_lineto:n { 3cm , 0cm }
+% \draw_color_fill:n { yellow!80!black }
+% \draw_path_use_clear:n { fill , stroke }
+% \draw_end:
+% \end{demo}
+% \begin{demo}
+% \draw_begin:
+% \draw_path_moveto:n { 0cm , 0cm }
+% \draw_path_lineto:n { 1cm , 1cm }
+% \draw_path_lineto:n { 2cm , 1cm }
+% \draw_path_moveto:n { 2cm , 1cm } % Begins a new part
+% \draw_path_lineto:n { 3cm , 0.5cm }
+% \draw_path_lineto:n { 3cm , 0cm }
+% \draw_color_fill:n { yellow!80!black }
+% \draw_path_use_clear:n { fill , stroke }
+% \draw_end:
+% \end{demo}
% \end{function}
%
% \begin{function}{\draw_path_curveto:nnn}
@@ -388,7 +651,21 @@
% \cs{draw_path_curveto:nnn} \Arg{control1} \Arg{control2} \Arg{end}
% \end{syntax}
% Joins the current path to the \meta{end} with a curved line defined by
-% cubic Bézier points \meta{control1} and \meta{control2}.
+% cubic Bézier points \meta{control1} and \meta{control2}. The bounding box
+% of the path (and image) will fully-contain the curve and control points,
+% \emph{i.e.}~it may be bigger than strictly necessary to contain the curve
+% \emph{alone}.
+% \begin{demo}
+% \draw_begin:
+% \draw_path_moveto:n { 0cm , 0cm }
+% \draw_path_curveto:nnn
+% { 1cm , 1cm } % First control
+% { 2cm , 1cm } % Second control
+% { 3cm , 0cm } % End
+% \draw_color_fill:n { yellow!80!black }
+% \draw_path_use_clear:n { fill , stroke }
+% \draw_end:
+% \end{demo}
% \end{function}
%
% \begin{function}{\draw_path_curveto:nn}
@@ -396,7 +673,20 @@
% \cs{draw_path_curveto:nn} \Arg{control} \Arg{end}
% \end{syntax}
% Joins the current path to the \meta{end} with a curved line defined by
-% quadratic Bézier point \meta{control}.
+% quadratic Bézier point \meta{control}. The bounding box
+% of the path (and image) will fully-contain the curve and computed (cubic)
+% control points, \emph{i.e.}~it may be bigger than strictly necessary to
+% contain the curve \emph{alone}.
+% \begin{demo}
+% \draw_begin:
+% \draw_path_moveto:n { 0cm , 0cm }
+% \draw_path_curveto:nn
+% { 1cm , 1cm }
+% { 2cm , 0cm }
+% \draw_color_fill:n { yellow!80!black }
+% \draw_path_use_clear:n { fill , stroke }
+% \draw_end:
+% \end{demo}
% \end{function}
%
% \begin{function}{\draw_path_arc:nnn, \draw_path_arc:nnnn}
@@ -407,9 +697,26 @@
% Joins the current path with an arc between \meta{angle1} and \meta{angle2}
% and of \meta{radius}. The four-argument version accepts two radii of
% different lengths.
+% \begin{demo}
+% \draw_begin:
+% \draw_path_moveto:n { 0cm , 0cm }
+% \draw_path_lineto:n { 0cm , 1cm }
+% \draw_path_arc:nnn { 180 } { 90 } { 0.5cm }
+% \draw_path_lineto:n { 3cm , 1.5cm }
+% \draw_path_arc:nnn { 90 } { -45 } { 0.5cm }
+% \draw_path_use_clear:n { fill }
+% \draw_end:
+% \end{demo}
%
% Note the interface here has a different argument ordering from that in
% \pkg{pgf}, which has the two centers then the two radii.
+% \begin{demo}
+% \draw_begin:
+% \draw_path_moveto:n { 0cm , 0cm }
+% \draw_path_arc:nnnn { 180 } { 45 } { 2cm } { 1cm }
+% \draw_path_use_clear:n { stroke }
+% \draw_end:
+% \end{demo}
% \end{function}
%
% \begin{function}{\draw_path_arc_axes:nnnn}
@@ -417,15 +724,49 @@
% \cs{draw_path_arc_axes:nnn} \Arg{angle1} \Arg{angle2} \Arg{vector1} \Arg{vector2}
% \end{syntax}
% Appends the portion of an ellipse from \meta{angle1} to \meta{angle2} of an
-% ellipse with axes along \meta{vector1} and \meta{vector2} to the current path.
+% ellipse with axes along \meta{vector1} and \meta{vector2} to the current
+% path.
+% \begin{demo}
+% \draw_begin:
+% \draw_path_moveto:n { 0cm , 0cm }
+% \draw_path_lineto:n { 2cm , 5mm }
+% \draw_path_moveto:n { 0cm , 0cm }
+% \draw_path_lineto:n { 0cm , 1cm }
+% \draw_path_moveto:n { 2cm , 5mm }
+% \draw_path_arc_axes:nnnn { 0 } { 90 }
+% { 2cm , 5mm } { 0cm , 1cm }
+% \draw_path_use_clear:n { stroke }
+% \draw_end:
+% \end{demo}
% \end{function}
%
-% \begin{function}{\draw_path_ellipse:nnnn}
+% \begin{function}{\draw_path_ellipse:nnn}
% \begin{syntax}
% \cs{draw_path_ellipse:nnn} \Arg{center} \Arg{vector1} \Arg{vector2}
% \end{syntax}
% Appends an ellipse at \meta{center} with axes along \meta{vector1} and
-% \meta{vector2} to the current path.
+% \meta{vector2} to the current path. A new part is started if the path
+% is already non-empty. Notice that the underlying drawing is constructed
+% from arcs with appropriate moves: the interfaces is a more efficient
+% convenience.
+% \begin{demo}
+% \draw_begin:
+% \draw_path_ellipse:nnn
+% { 1cm , 0cm }
+% { 1.5cm , 0cm }
+% { 0cm , 1cm }
+% \draw_path_use_clear:n { stroke }
+% \draw_color:n { red }
+% \draw_path_ellipse:nnn
+% { 1cm , 0cm }
+% { 1cm , 1cm }
+% { -0.5cm , 0.5cm }
+% \draw_path_use_clear:n { stroke }
+% \draw_end:
+% \end{demo}
+%
+% Note that any transformation is applied to the completed ellipse rather than
+% to the axes.
% \end{function}
%
% \begin{function}{\draw_path_circle:nn}
@@ -433,6 +774,7 @@
% \cs{draw_path_circle:nn} \Arg{center} \Arg{radius}
% \end{syntax}
% Appends a circle of \meta{radius} at \meta{center} to the current path.
+% This is a shortcut for \cs{draw_path_ellipse:nnn}.
% \end{function}
%
% \begin{function}{\draw_path_rectangle:nn, \draw_path_rectangle_corners:nn}
@@ -443,44 +785,179 @@
% Appends a rectangle starting at \meta{lower-left} to the current path,
% with the size of the rectangle determined either by a \meta{displacement}
% or the position of the \meta{top-right}.
+% \begin{demo}
+% \draw_begin:
+% \draw_path_rectangle:nn
+% { 1cm , 0cm }
+% { 1.5cm , 1cm }
+% \draw_path_rectangle:nn
+% { 1.5cm , 0.25cm }
+% { 1.5cm , 1cm }
+% \draw_path_rectangle:nn
+% { 2cm , 0.5cm }
+% { 1.5cm , 1cm }
+% \draw_path_use_clear:n { draw }
+% \draw_end:
+% \end{demo}
+% \begin{demo}
+% \draw_begin:
+% \draw_path_rectangle_corners:nn
+% { 1cm , 0cm }
+% { 1.5cm , 1cm }
+% \draw_path_use_clear:n { draw }
+% \draw_end:
+% \end{demo}
% \end{function}
%
% \begin{function}{\draw_path_grid:nnnn}
% \begin{syntax}
-% \cs{draw_path_grid:nnnn} \Arg{xspace} \Arg{yspace} \Arg{lower-left} \Arg{upper-right}
+% \cs{draw_path_grid:nnnn} \Arg{xstep} \Arg{ystep} \Arg{lower-left} \Arg{upper-right}
% \end{syntax}
-% Constructs a grid of \meta{xspace} and \meta{yspace} from the
-% \meta{lower-left} to the \meta{upper-right}, and appends this to the
-% current path.
+% Constructs a grid of \meta{xstep} and \meta{ystep} inside the rectangle
+% defined by the \meta{lower-left} and the \meta{upper-right}, and appends
+% this to the current path. The grid will be aligned such that grid lines
+% pass through the origin, which may result in \enquote{protruding} ends
+% if the start/end positions do not fully align.
+% \begin{demo}
+% \draw_begin:
+% \draw_linewidth:n { 0.8pt }
+% \draw_path_grid:nnnn
+% { 1cm } { 1cm }
+% { -3mm , -3mm }
+% { 33mm , 23mm }
+% \draw_path_use_clear:n { stroke }
+% \draw_linewidth:n { 0.4pt }
+% \draw_path_grid:nnnn
+% { 1mm } { 1mm }
+% { -1.5mm , -1.5mm }
+% { 31.5mm , 21.5mm }
+% \draw_path_use_clear:n { stroke }
+% \draw_end:
+% \end{demo}
+%
+% Any transformation is applied to the finished grid.
+% \begin{demo}
+% \draw_begin:
+% \draw_transform_rotate:n { 10 }
+% \draw_path_grid:nnnn
+% { 1mm } { 2mm }
+% { 0mm , 0mm }
+% { 30mm , 30mm }
+% \draw_path_use_clear:n { stroke }
+% \draw_end:
+% \end{demo}
% \end{function}
%
-% \begin{function}{\draw_path_close:}
+% \subsubsection{Path scope}
+%
+% \begin{function}{\draw_path_scope_begin:, \draw_path_scope_end:}
% \begin{syntax}
-% \cs{draw_path_close:}
+% \cs{draw_path_scope_begin:}
+% ...
+% \cs{draw_path_scope_end:}
% \end{syntax}
-% Closes the current part of the path by appending a straight line from
-% the current point to the starting point of the path.
+% Suspends (and saves) the current (partial) path, initialising a new
+% path within the scope. Path operations are written to output only when
+% used, so the scoped path is stored at the \pkg{expl3} level, not
+% in the output.
% \end{function}
%
-% \begin{function}{\draw_path_use:n, \draw_path_use_clear:n}
+% \subsubsection{Path operations on canvas axes}
+%
+% For \emph{specialist} work, a small number of functions are provided
+% which work relative to the canvas axes, \emph{i.e.}~these functions
+% ignore the transformation matrix.
+%
+% \begin{function}{\draw_path_canvas_moveto:n}
% \begin{syntax}
-% \cs{draw_path_use:n} \Arg{action(s)}
+% \cs{draw_path_canvas_moveto:n} \Arg{canvas point}
% \end{syntax}
-% Inserts the current path, carrying out one ore more possible \meta{actions}
-% (a comma list):
-% \begin{itemize}
-% \item \texttt{clear} Resets the path to empty
-% \item \texttt{clip} Clips any content outside of the path
-% \item \texttt{draw}
-% \item \texttt{fill} Fills the interior of the path with the current
-% file color
-% \item \texttt{stroke} Draws a line along the current path
-% \end{itemize}
+% Moves the reference point of the path to the \meta{canvas point}, but will
+% not join this to any previous point.
+% \end{function}
+%
+% \begin{function}{\draw_path_canvas_lineto:n}
+% \begin{syntax}
+% \cs{draw_path_canvas_lineto:n} \Arg{canvas point}
+% \end{syntax}
+% Joins the current path to the \meta{canvas point} with a straight line.
+% \end{function}
+%
+% \begin{function}{\draw_path_canvas_curveto:nnn}
+% \begin{syntax}
+% \cs{draw_path_canvas_curveto:nnn} \Arg{control1} \Arg{control2} \Arg{end}
+% \end{syntax}
+% Joins the current path to the \meta{end} with a curved line defined by
+% cubic Bézier points \meta{control1} and \meta{control2}. These positions
+% are given as canvas points.
+% \end{function}
+%
+% \subsection{Bounding box}
+%
+% \begin{variable}{\l_draw_bb_update_bool}
+% All functions automatically update the bounding box of the image, unless
+% specified otherwise. This behavior is selectable using the
+% \cs{l_draw_bb_update_bool} boolean.
+% \end{variable}
+%
+% \subsection{Boxes and coffins}
+%
+% \begin{function}{\draw_box_use:N}
+% \begin{syntax}
+% \cs{draw_box_use:N} \meta{box}
+% \end{syntax}
+% Inserts the \meta{box} into a drawing, taking account of the current
+% transformation matrix and shift, and adjusting the drawing bounding
+% box to contain the (apparent) size of the box if this is active
+% (see \cs{l_draw_bb_update_bool}).
+% \begin{demo}
+% \draw_begin:
+% \draw_path_moveto:n { 0cm , 0cm }
+% \draw_path_lineto:n { 0cm , 1cm }
+% \draw_path_use_clear:n { stroke }
+% \hbox_set:Nn \l_tmpa_box
+% { This~is~text. }
+% \draw_box_use:N \l_tmpa_box
+% \draw_end:
+% \end{demo}
+% \begin{demo}
+% \draw_begin:
+% \draw_transform_matrix:nnnn { 2 } { 0 } { 1 } { 2 }
+% \draw_path_moveto:n { 0cm , 0cm }
+% \draw_path_lineto:n { 0cm , 1cm }
+% \draw_path_use_clear:n { stroke }
+% \hbox_set:Nn \l_tmpa_box
+% { This~is~text. }
+% \draw_box_use:N \l_tmpa_box
+% \draw_end:
+% \end{demo}
+% \end{function}
+%
+% \begin{function}{\draw_coffin_use:Nnn}
+% \begin{syntax}
+% \cs{draw_coffin_use:N} \meta{coffin} \Arg{hpole} \Arg{vpole}
+% \end{syntax}
+% Inserts the \meta{coffin} into a drawing, taking account of the current
+% transformation matrix and shift, and adjusting the drawing bounding
+% box to contain the (apparent) size of the box if this is active
+% (see \cs{l_draw_bb_update_bool}). The alignment point of the coffin to
+% the origin is specified by the intersection of the \meta{hpole} and the
+% \meta{vpole}.
+% \begin{demo}
+% \draw_begin:
+% \draw_path_moveto:n { 0cm , 0cm }
+% \draw_path_lineto:n { 0cm , 1cm }
+% \draw_path_use_clear:n { stroke }
+% \hcoffin_set:Nn \l_tmpa_coffin
+% { This~is~text. }
+% \draw_coffin_use:Nnn \l_tmpa_coffin { hc } { vc }
+% \draw_end:
+% \end{demo}
% \end{function}
%
% \subsection{Color}
%
-% \begin{function}{\draw_color:n, \draw_fill:n, \draw_stroke:n}
+% \begin{function}{\draw_color:n, \draw_color_fill:n, \draw_color_stroke:n}
% \begin{syntax}
% \cs{draw_color:n} \Arg{color expression}
% \end{syntax}
@@ -491,34 +968,28 @@
%
% Points are normally used unchanged relative to the canvas axes. This can
% be modified by applying a transformation matrix. The canvas axes themselves
-% may be adjusted using \cs{driver_draw_transformcm:nnnnnn}: note that this
+% may be adjusted using \cs{driver_draw_cm:nnnn}: note that this
% is transparent to the drawing code so is not tracked.
%
-% \begin{function}{\draw_transform_reset:}
-% \begin{syntax}
-% \cs{draw_transform_reset:}
-% \end{syntax}
-% Resets the matrix to the identity.
-% \end{function}
-%
-% \begin{function}{\draw_transform_concat:nnnnn}
+% \begin{function}
+% {\draw_transform_matrix:nnnn, \draw_transform_matrix_concat:nnnn}
% \begin{syntax}
-% \cs{draw_transform_concat:nnnnn}
-% \Arg{a} \Arg{b} \Arg{c} \Arg{d} \Arg{vector}
+% \cs{draw_transform_matrix:nnnnn}
+% \Arg{a} \Arg{b} \Arg{c} \Arg{d}
% \end{syntax}
-% Appends the given transformation to the currently-active one. The
-% transformation is made up of a matrix \meta{a}, \meta{b}, \meta{c} and
-% \meta{d}, and a shift by the \meta{vector}.
+% Applies the transformation matrix $[ \meta{a} \meta{b} \meta{c} \meta{d}]$.
+% The basic version over-writes the current matrix, the |concat| version
+% concatenates.
+% This assignment is local.
% \end{function}
%
-% \begin{function}{\draw_transform:nnnnn}
+% \begin{function}{\draw_transform_shift:n, \draw_transform_shift_concat:n}
% \begin{syntax}
-% \cs{draw_transform:nnnnn}
-% \Arg{a} \Arg{b} \Arg{c} \Arg{d} \Arg{vector}
+% \cs{draw_transform_shift:n} \Arg{vector}
% \end{syntax}
-% Applies the transformation matrix specified, over-writing any existing
-% matrix. The transformation is made up of a matrix \meta{a}, \meta{b},
-% \meta{c} and \meta{d}, and a shift by the \meta{vector}.
+% Applies the transformation \meta{vector} to points. The basic version
+% over-writes the current vector, the |concat| version concatenates.
+% This assignment is local.
% \end{function}
%
% \begin{function}{\draw_transform_triangle:nnn}
@@ -529,14 +1000,77 @@
% Applies a transformation such that the co-ordinates $(0, 0)$, $(1, 0)$
% and $(0, 1)$ are given by the \meta{origin}, \meta{point1} and
% \meta{point2}, respectively.
+% This assignment is local.
+% \end{function}
+%
+% \begin{function}{\draw_transform_rotate:n}
+% \begin{syntax}
+% \cs{draw_transform_rotate:n} \Arg{angle}
+% \end{syntax}
+% Applies a rotation by the \meta{angle}, measured anti-clockwise in degrees.
+% This rotation is \emph{additional} to any prevailing transformation.
+% This assignment is local.
% \end{function}
%
-% \begin{function}{\draw_transform_invert:}
+% \begin{function}
+% {
+% \draw_transform_scale:n,
+% \draw_transform_xscale:n,
+% \draw_transform_xscale:n
+% }
+% \begin{syntax}
+% \cs{draw_transform_scale:n} \Arg{scale}
+% \end{syntax}
+% Applies the \meta{scale} in either $x$ or $y$ (or both).
+% This scale is \emph{added} to any prevailing transformation.
+% This assignment is local.
+% \end{function}
+%
+% \begin{function}
+% {
+% \draw_transform_xshift:n,
+% \draw_transform_yshift:n
+% }
+% \begin{syntax}
+% \cs{draw_transform_shift:n} \Arg{vector}
+% \cs{draw_transform_xshift:n} \Arg{xshift}
+% \end{syntax}
+% Applies an \meta{xshift} or \meta{yshift}, as appropriate. This shift is
+% \emph{added} to any prevailing one.
+% This assignment is local.
+% \end{function}
+%
+% \begin{function}
+% {
+% \draw_transform_xslant:n,
+% \draw_transform_yslant:n
+% }
+% \begin{syntax}
+% \cs{draw_transform_xslant:n} \Arg{slant}
+% \end{syntax}
+% Applies the \meta{slant} (a factor) in either $x$ or $y$.
+% This slant is \emph{added} to any prevailing transformation.
+% This assignment is local.
+% \end{function}
+%
+% \begin{function}
+% {\draw_transform_matrix_invert:, \draw_transform_shift_invert:}
+% \begin{syntax}
+% \cs{draw_transform_matrix_invert:}
+% \end{syntax}
+% Inverts the current transformation matrix or shift vector, as
+% appropriate.
+% This assignment is local.
+% \end{function}
+%
+% \begin{function}
+% {\draw_transform_matrix_reset, \draw_transform_shift_reset:}
% \begin{syntax}
-% \cs{draw_transform_invert:}
+% \cs{draw_transform_matrix_reset:}
% \end{syntax}
-% Inverts the current transformation matrix and reverses the current
-% shift vector.
+% Resets the current transformation matrix or shift vector, as
+% appropriate.
+% This assignment is local.
% \end{function}
%
% \end{documentation}
@@ -555,7 +1089,7 @@
%
% \begin{macrocode}
%<*package>
-\ProvidesExplPackage{l3draw}{2018/02/21}{}
+\ProvidesExplPackage{l3draw}{2018/03/05}{}
{L3 Experimental core drawing support}
%</package>
% \end{macrocode}