summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/l3backend/l3backend-basics.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/l3backend/l3backend-basics.dtx')
-rw-r--r--macros/latex/contrib/l3backend/l3backend-basics.dtx497
1 files changed, 0 insertions, 497 deletions
diff --git a/macros/latex/contrib/l3backend/l3backend-basics.dtx b/macros/latex/contrib/l3backend/l3backend-basics.dtx
deleted file mode 100644
index 4d3b68225a..0000000000
--- a/macros/latex/contrib/l3backend/l3backend-basics.dtx
+++ /dev/null
@@ -1,497 +0,0 @@
-% \iffalse meta-comment
-%
-%% File: l3backend-basics.dtx
-%
-% Copyright (C) 2019-2024 The LaTeX 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 "l3backend 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 \pkg{l3backend-basics} module\\ Backend basics^^A
-% }
-%
-% \author{^^A
-% The \LaTeX{} Project\thanks
-% {^^A
-% E-mail:
-% \href{mailto:latex-team@latex-project.org}
-% {latex-team@latex-project.org}^^A
-% }^^A
-% }
-%
-% \date{Released 2024-03-14}
-%
-% \maketitle
-%
-% \begin{documentation}
-%
-% \end{documentation}
-%
-% \begin{implementation}
-%
-% \section{\pkg{l3backend-basics} implementation}
-%
-% \begin{macrocode}
-%<*package>
-% \end{macrocode}
-%
-% Whilst there is a reasonable amount of code overlap between backends,
-% it is much clearer to have the blocks more-or-less separated than run
-% in together and DocStripped out in parts. As such, most of the following
-% is set up on a per-backend basis, though there is some common code (again
-% given in blocks not interspersed with other material).
-%
-% All the file identifiers are up-front so that they come out in the right
-% place in the files.
-% \begin{macrocode}
-\ProvidesExplFile
-%<*dvipdfmx>
- {l3backend-dvipdfmx.def}{2024-03-14}{}
- {L3 backend support: dvipdfmx}
-%</dvipdfmx>
-%<*dvips>
- {l3backend-dvips.def}{2024-03-14}{}
- {L3 backend support: dvips}
-%</dvips>
-%<*dvisvgm>
- {l3backend-dvisvgm.def}{2024-03-14}{}
- {L3 backend support: dvisvgm}
-%</dvisvgm>
-%<*luatex>
- {l3backend-luatex.def}{2024-03-14}{}
- {L3 backend support: PDF output (LuaTeX)}
-%</luatex>
-%<*pdftex>
- {l3backend-pdftex.def}{2024-03-14}{}
- {L3 backend support: PDF output (pdfTeX)}
-%</pdftex>
-%<*xetex>
- {l3backend-xetex.def}{2024-03-14}{}
- {L3 backend support: XeTeX}
-%</xetex>
-% \end{macrocode}
-%
-% Check if the loaded kernel is at least enough to load this file.
-% The kernel date has to be at least equal to \cs{ExplBackendFileDate}
-% or later. If \cs{__kernel_dependency_version_check:Nn} doesn't
-% exist we're loading in an older kernel, so it's an error anyway.
-% With time, this test should vanish and only the dependency check
-% should remain.
-% \begin{macrocode}
-\cs_if_exist:NTF \__kernel_dependency_version_check:nn
- {
- \__kernel_dependency_version_check:nn {2023-10-10}
-%<dvipdfmx> {l3backend-dvipdfmx.def}
-%<dvips> {l3backend-dvips.def}
-%<dvisvgm> {l3backend-dvisvgm.def}
-%<luatex> {l3backend-luatex.def}
-%<pdftex> {l3backend-pdftex.def}
-%<xetex> {l3backend-xetex.def}
- }
- {
- \cs_if_exist_use:cF { @latex@error } { \errmessage }
- {
- Mismatched~LaTeX~support~files~detected. \MessageBreak
- Loading~aborted!
- }
- { \use:c { @ehd } }
- \tex_endinput:D
- }
-% \end{macrocode}
-%
-% The order of the backend code here is such that we get somewhat logical
-% outcomes in terms of code sharing whilst keeping things readable. (Trying to
-% mix all of the code by concept is almost unmanageable.) The key parts which
-% are shared are
-% \begin{itemize}
-% \item Color support is either \texttt{dvips}-like or \LuaTeX{}/pdfTeX{}-like.
-% \item \LuaTeX{}/pdfTeX{} and \texttt{dvipdfmx}/\XeTeX{} share drawing routines.
-% \item \XeTeX{} is the same as \texttt{dvipdfmx} other than image size
-% extraction so takes most of the same code.
-% \end{itemize}
-%
-% \begin{macro}
-% {
-% \__kernel_backend_literal:e,
-% \__kernel_backend_literal:n
-% }
-% The one shared function for all backends is access to the basic
-% \tn{special} primitive: it has slightly odd expansion behaviour
-% so a wrapper is provided.
-% \begin{macrocode}
-\cs_new_eq:NN \__kernel_backend_literal:e \tex_special:D
-\cs_new_protected:Npn \__kernel_backend_literal:n #1
- { \__kernel_backend_literal:e { \exp_not:n {#1} } }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\__kernel_backend_first_shipout:n}
-% We need to write at first shipout in a few places. As we want to use the
-% most up-to-date method,
-% \begin{macrocode}
-\cs_if_exist:NTF \@ifl@t@r
- {
- \@ifl@t@r \fmtversion { 2020-10-01 }
- {
- \cs_new_protected:Npn \__kernel_backend_first_shipout:n #1
- { \hook_gput_code:nnn { shipout / firstpage } { l3backend } {#1} }
- }
- { \cs_new_eq:NN \__kernel_backend_first_shipout:n \AtBeginDvi }
- }
- { \cs_new_eq:NN \__kernel_backend_first_shipout:n \use:n }
-% \end{macrocode}
-% \end{macro}
-%
-% \subsection{\texttt{dvips} backend}
-%
-% \begin{macrocode}
-%<*dvips>
-% \end{macrocode}
-%
-% \begin{macro}
-% {\__kernel_backend_literal_postscript:n, \__kernel_backend_literal_postscript:e}
-% Literal PostScript can be included using a few low-level formats. Here,
-% we use the form with no positioning: this is overall more convenient as
-% a wrapper. Note that this does require that where position is important,
-% an appropriate wrapper is included.
-% \begin{macrocode}
-\cs_new_protected:Npn \__kernel_backend_literal_postscript:n #1
- { \__kernel_backend_literal:n { ps:: #1 } }
-\cs_generate_variant:Nn \__kernel_backend_literal_postscript:n { e }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\__kernel_backend_postscript:n, \__kernel_backend_postscript:e}
-% PostScript data that does have positioning, and also applying
-% a shift to |SDict| (which is not done automatically by
-% |ps:| or |ps::|, in contrast to |!| or |"|).
-% \begin{macrocode}
-\cs_new_protected:Npn \__kernel_backend_postscript:n #1
- { \__kernel_backend_literal:n { ps: SDict ~ begin ~ #1 ~ end } }
-\cs_generate_variant:Nn \__kernel_backend_postscript:n { e }
-% \end{macrocode}
-% \end{macro}
-%
-% PostScript for the header: a small saving but makes the code clearer.
-% This is held until the start of shipout such that a document with no
-% actual output does not write anything.
-% \begin{macrocode}
-\bool_if:NT \g__kernel_backend_header_bool
- {
- \__kernel_backend_first_shipout:n
- { \__kernel_backend_literal:n { header = l3backend-dvips.pro } }
- }
-% \end{macrocode}
-%
-% \begin{macro}
-% {
-% \__kernel_backend_align_begin:,
-% \__kernel_backend_align_end:
-% }
-% In \texttt{dvips} there is no built-in saving of the current
-% position, and so some additional PostScript is required to set up the
-% transformation matrix and also to restore it afterwards. Notice the use
-% of the stack to save the current position \enquote{up front} and to
-% move back to it at the end of the process. Notice that the |[begin]|/^^A
-% |[end]| pair here mean that we can use a run of PostScript statements
-% in separate lines: not \emph{required} but does make the code and
-% output more clear.
-% \begin{macrocode}
-\cs_new_protected:Npn \__kernel_backend_align_begin:
- {
- \__kernel_backend_literal:n { ps::[begin] }
- \__kernel_backend_literal_postscript:n { currentpoint }
- \__kernel_backend_literal_postscript:n { currentpoint~translate }
- }
-\cs_new_protected:Npn \__kernel_backend_align_end:
- {
- \__kernel_backend_literal_postscript:n { neg~exch~neg~exch~translate }
- \__kernel_backend_literal:n { ps::[end] }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\__kernel_backend_scope_begin:, \__kernel_backend_scope_end:}
-% Saving/restoring scope for general operations needs to be done with
-% \texttt{dvips} positioning (try without to see this!). Thus we need the
-% |ps:| version of the special here. As only the graphics state is ever
-% altered within this pairing, we use the lower-cost |g|-versions.
-% \begin{macrocode}
-\cs_new_protected:Npn \__kernel_backend_scope_begin:
- { \__kernel_backend_literal:n { ps:gsave } }
-\cs_new_protected:Npn \__kernel_backend_scope_end:
- { \__kernel_backend_literal:n { ps:grestore } }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macrocode}
-%</dvips>
-% \end{macrocode}
-%
-% \subsection{\LuaTeX{} and \pdfTeX{} backends}
-%
-% \begin{macrocode}
-%<*luatex|pdftex>
-% \end{macrocode}
-%
-% Both \LuaTeX{} and \pdfTeX{} write PDFs directly rather than via an
-% intermediate file. Although there are similarities, the move of \LuaTeX{}
-% to have more code in Lua means we create two independent files using
-% shared DocStrip code.
-%
-% \begin{macro}{\__kernel_backend_literal_pdf:n, \__kernel_backend_literal_pdf:e}
-% This is equivalent to \verb|\special{pdf:}| but the engine can
-% track it. Without the \texttt{direct} keyword everything is kept in
-% sync: the transformation matrix is set to the current point automatically.
-% Note that this is still inside the text (\texttt{BT} \dots \texttt{ET}
-% block).
-% \begin{macrocode}
-\cs_new_protected:Npn \__kernel_backend_literal_pdf:n #1
- {
-%<*luatex>
- \tex_pdfextension:D literal
-%</luatex>
-%<*pdftex>
- \tex_pdfliteral:D
-%</pdftex>
- { \exp_not:n {#1} }
- }
-\cs_generate_variant:Nn \__kernel_backend_literal_pdf:n { e }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\__kernel_backend_literal_page:n, \__kernel_backend_literal_page:e}
-% Page literals are pretty simple. To avoid an expansion, we write out
-% by hand.
-% \begin{macrocode}
-\cs_new_protected:Npn \__kernel_backend_literal_page:n #1
- {
-%<*luatex>
- \tex_pdfextension:D literal ~
-%</luatex>
-%<*pdftex>
- \tex_pdfliteral:D
-%</pdftex>
- page { \exp_not:n {#1} }
- }
-\cs_new_protected:Npn \__kernel_backend_literal_page:e #1
- {
-%<*luatex>
- \tex_pdfextension:D literal ~
-%</luatex>
-%<*pdftex>
- \tex_pdfliteral:D
-%</pdftex>
- page {#1}
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\__kernel_backend_scope_begin:, \__kernel_backend_scope_end:}
-% Higher-level interfaces for saving and restoring the graphic state.
-% \begin{macrocode}
-\cs_new_protected:Npn \__kernel_backend_scope_begin:
- {
-%<*luatex>
- \tex_pdfextension:D save \scan_stop:
-%</luatex>
-%<*pdftex>
- \tex_pdfsave:D
-%</pdftex>
- }
-\cs_new_protected:Npn \__kernel_backend_scope_end:
- {
-%<*luatex>
- \tex_pdfextension:D restore \scan_stop:
-%</luatex>
-%<*pdftex>
- \tex_pdfrestore:D
-%</pdftex>
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\__kernel_backend_matrix:n, \__kernel_backend_matrix:e}
-% Here the appropriate function is set up to insert an affine matrix
-% into the PDF. With \pdfTeX{} and \LuaTeX{} in direct PDF output mode there
-% is a primitive for this, which only needs the rotation/scaling/skew part.
-% \begin{macrocode}
-\cs_new_protected:Npn \__kernel_backend_matrix:n #1
- {
-%<*luatex>
- \tex_pdfextension:D setmatrix
-%</luatex>
-%<*pdftex>
- \tex_pdfsetmatrix:D
-%</pdftex>
- { \exp_not:n {#1} }
- }
-\cs_generate_variant:Nn \__kernel_backend_matrix:n { e }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macrocode}
-%</luatex|pdftex>
-% \end{macrocode}
-%
-% \subsection{\texttt{dvipdfmx} backend}
-%
-% \begin{macrocode}
-%<*dvipdfmx|xetex>
-% \end{macrocode}
-%
-% The \texttt{dvipdfmx} shares code with the PDF mode one (using the common
-% section to this file) but also with \XeTeX{}. The latter is close
-% to identical to \texttt{dvipdfmx} and so all of the code here is extracted
-% for both backends, with some \texttt{clean up} for \XeTeX{} as
-% required.
-%
-% \begin{macro}{\__kernel_backend_literal_pdf:n, \__kernel_backend_literal_pdf:e}
-% Undocumented but equivalent to \pdfTeX{}'s |literal| keyword. It's similar to
-% be not the same as the documented |contents| keyword as that adds a |q|/|Q|
-% pair.
-% \begin{macrocode}
-\cs_new_protected:Npn \__kernel_backend_literal_pdf:n #1
- { \__kernel_backend_literal:n { pdf:literal~ #1 } }
-\cs_generate_variant:Nn \__kernel_backend_literal_pdf:n { e }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\__kernel_backend_literal_page:n}
-% Whilst the manual says this is like |literal direct| in \pdfTeX{},
-% it closes the |BT| block!
-% \begin{macrocode}
-\cs_new_protected:Npn \__kernel_backend_literal_page:n #1
- { \__kernel_backend_literal:n { pdf:literal~direct~ #1 } }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\__kernel_backend_scope_begin:, \__kernel_backend_scope_end:}
-% Scoping is done using the backend-specific specials. We use the versions
-% originally from \texttt{xdvidfpmx} (\texttt{x:}) as these are well-tested
-% \enquote{in the wild}.
-% \begin{macrocode}
-\cs_new_protected:Npn \__kernel_backend_scope_begin:
- { \__kernel_backend_literal:n { x:gsave } }
-\cs_new_protected:Npn \__kernel_backend_scope_end:
- { \__kernel_backend_literal:n { x:grestore } }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macrocode}
-%</dvipdfmx|xetex>
-% \end{macrocode}
-%
-% \subsection{\texttt{dvisvgm} backend}
-%
-% \begin{macrocode}
-%<*dvisvgm>
-% \end{macrocode}
-%
-% \begin{macro}{\__kernel_backend_literal_svg:n, \__kernel_backend_literal_svg:e}
-% Unlike the other backends, the requirements for making SVG files mean
-% that we can't conveniently transform all operations to the current point.
-% That makes life a bit more tricky later as that needs to be accounted for.
-% A new line is added after each call to help to keep the output readable
-% for debugging.
-% \begin{macrocode}
-\cs_new_protected:Npn \__kernel_backend_literal_svg:n #1
- { \__kernel_backend_literal:n { dvisvgm:raw~ #1 { ?nl } } }
-\cs_generate_variant:Nn \__kernel_backend_literal_svg:n { e }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{variable}{\g__kernel_backend_scope_int, \l__kernel_backend_scope_int}
-% In SVG, we need to track scope nesting as properties attach to scopes; that
-% requires a pair of \texttt{int} registers.
-% \begin{macrocode}
-\int_new:N \g__kernel_backend_scope_int
-\int_new:N \l__kernel_backend_scope_int
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{macro}{\__kernel_backend_scope_begin:, \__kernel_backend_scope_end:}
-% \begin{macro}{\__kernel_backend_scope_begin:n, \__kernel_backend_scope_begin:e}
-% \begin{macro}{\__kernel_backend_scope:n, \__kernel_backend_scope:e}
-% In SVG, the need to attach concepts to a scope means we need to be sure we
-% will close all of the open scopes. That is easiest done if we only need
-% an outer \enquote{wrapper} \texttt{begin}/\texttt{end} pair, and within
-% that we apply operations as a simple scoped statements. To keep down the
-% non-productive groups, we also have a \texttt{begin} version that does take
-% an argument.
-% \begin{macrocode}
-\cs_new_protected:Npn \__kernel_backend_scope_begin:
- {
- \__kernel_backend_literal_svg:n { <g> }
- \int_set_eq:NN
- \l__kernel_backend_scope_int
- \g__kernel_backend_scope_int
- \group_begin:
- \int_gset:Nn \g__kernel_backend_scope_int { 1 }
- }
-\cs_new_protected:Npn \__kernel_backend_scope_end:
- {
- \prg_replicate:nn
- { \g__kernel_backend_scope_int }
- { \__kernel_backend_literal_svg:n { </g> } }
- \group_end:
- \int_gset_eq:NN
- \g__kernel_backend_scope_int
- \l__kernel_backend_scope_int
- }
-\cs_new_protected:Npn \__kernel_backend_scope_begin:n #1
- {
- \__kernel_backend_literal_svg:n { <g ~ #1 > }
- \int_set_eq:NN
- \l__kernel_backend_scope_int
- \g__kernel_backend_scope_int
- \group_begin:
- \int_gset:Nn \g__kernel_backend_scope_int { 1 }
- }
-\cs_generate_variant:Nn \__kernel_backend_scope_begin:n { e }
-\cs_new_protected:Npn \__kernel_backend_scope:n #1
- {
- \__kernel_backend_literal_svg:n { <g ~ #1 > }
- \int_gincr:N \g__kernel_backend_scope_int
- }
-\cs_generate_variant:Nn \__kernel_backend_scope:n { e }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-%
-% \begin{macrocode}
-%</dvisvgm>
-% \end{macrocode}
-%
-% \begin{macrocode}
-%</package>
-% \end{macrocode}
-%
-% \end{implementation}
-%
-% \PrintIndex