[latex3-commits] [latex3/latex2e] latexlab/rcb: added a few pdfs for easier consumption during development (d25b67a6)
github at latex-project.org
github at latex-project.org
Mon Jul 31 23:03:57 CEST 2023
Repository : https://github.com/latex3/latex2e
On branch : latexlab/rcb
Link : https://github.com/latex3/latex2e/commit/d25b67a6d2b2db38ae7072d954075a833c91a9f4
>---------------------------------------------------------------
commit d25b67a6d2b2db38ae7072d954075a833c91a9f4
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date: Mon Jul 31 23:03:57 2023 +0200
added a few pdfs for easier consumption during development
>---------------------------------------------------------------
d25b67a6d2b2db38ae7072d954075a833c91a9f4
required/latex-lab/latex-lab-footnotes.pdf | Bin 0 -> 815374 bytes
required/latex-lab/latex-lab-new-or-2.pdf | Bin 0 -> 631851 bytes
required/latex-lab/latex-lab-socket.pdf | Bin 0 -> 602559 bytes
required/latex-lab/socket-sample.tex | 411 -----------------------------
4 files changed, 411 deletions(-)
diff --git a/required/latex-lab/latex-lab-footnotes.pdf b/required/latex-lab/latex-lab-footnotes.pdf
new file mode 100644
index 00000000..a2318465
Binary files /dev/null and b/required/latex-lab/latex-lab-footnotes.pdf differ
diff --git a/required/latex-lab/latex-lab-new-or-2.pdf b/required/latex-lab/latex-lab-new-or-2.pdf
new file mode 100644
index 00000000..e6a0d8ab
Binary files /dev/null and b/required/latex-lab/latex-lab-new-or-2.pdf differ
diff --git a/required/latex-lab/latex-lab-socket.pdf b/required/latex-lab/latex-lab-socket.pdf
new file mode 100644
index 00000000..ee1675c2
Binary files /dev/null and b/required/latex-lab/latex-lab-socket.pdf differ
diff --git a/required/latex-lab/socket-sample.tex b/required/latex-lab/socket-sample.tex
deleted file mode 100644
index a1eea2c2..00000000
--- a/required/latex-lab/socket-sample.tex
+++ /dev/null
@@ -1,411 +0,0 @@
-\documentclass{article}
-
-
-\ExplSyntaxOn
-
-% Declaring a socket creates a str to hold the name (a pointer) to the code
-% that should be used when the socket is used, and an integer to hold the
-% number of arguments of that socket. Initially, an "unassigned" code
-% chunk is created and assigned so the socket cannot be used without a
-% proper code block being assigned.
-
-\cs_new_protected:Npn \socket_new:nn #1 #2 {
- \str_if_exist:cTF { g__socket_#1_code_str }
- {
- \errmessage { socket~ '#1'~ already~ declared! }
- }
- {
- \str_new:c { g__socket_#1_code_str }
- \int_const:cn { c__socket_#1_args_int } {#2}
-%FMi changed
- \DeclaresocketCode {#1} { __socket_unassigned:w }
- { \errmessage { No~socket~code~for~'#1'~assigned! } }
- \Assignsocketcode {#1} { __socket_unassigned:w }
- }
-}
-
-% Declaring a code for an socket is just doing a definition, taking the
-% number of arguments from the saved int.
-
-\cs_new_protected:Npn \socket_new_code:nnn #1 #2 #3 {
- \str_if_exist:cTF { g__socket_#1_code_str }
- {
- \cs_generate_from_arg_count:cNnn
- { __socket_#1_code_#2:w }
- \cs_new_protected:Npn
- { \int_use:c { c__socket_#1_args_int } }
- {#3}
- }
- {
- \errmessage { socket~ '#1'~ not~ declared! }
- }
-}
-
-
-
-% Assigning a socket just changes the name in the socket string.
-
-\cs_new_protected:Npn \socket_assign_code:nn #1 #2 {
- \str_if_exist:cTF { g__socket_#1_code_str }
- {
- \cs_if_exist:cTF { __socket_#1_code_#2:w }
- {
- \str_gset:cn { g__socket_#1_code_str } {#2}
- }
- {
- \errmessage { socket~ instance~ '#2'~ for~ socket~ '#1'~ not~ declared! }
- }
- }
- {
- \errmessage { socket~ '#1'~ not~ declared! }
- }
-}
-
-
-% And using it is just a \csname...\endcsname. We do not add a runtime
-% check for speed reasons!
-
-\cs_new_protected:Npn \socket_use:n #1 {
- \use:c { __socket_#1_code_ \str_use:c { g__socket_#1_code_str } :w }
-}
-
-
-\cs_new_eq:NN \NewSocket \socket_new:nn
-
-\cs_new_eq:NN \DeclareSocketCode \socket_new_code:nnn
-
-\cs_new_eq:NN \AssignSocketcode \socket_assign_code:nn
-
-\cs_new_eq:NN \UseSocket \socket_use:n
-
-\ExplSyntaxOff
-
-\usepackage[T1]{fontenc}
-\usepackage{csquotes}
-
-\newcommand\pkg[1]{\texttt{#1}}
-\newcommand\cs[1]{\texttt{\textbackslash #1}}
-\newcommand\meta[1]{\textlangle\textit{#1}\textrangle}
-\newcommand\marg[1]{\texttt\{\meta{#1}\texttt\}}
-
-
-\begin{document}
-
-
-\title{Sockets (aka Replaceable Code Blocks)}
-\author{Frank Mittelbach}
-\date{2023-06-20}
-
-\maketitle
-
-\tableofcontents
-
-\section{Introduction}
-
-A \LaTeX{} source file is transformed into a typeset document by
-executing code for each command or environment in the document
-source. Through various steps this code transforms the input and
-eventually generates typeset output appearing in a \enquote{galley}
-from which individual pages are cut off in an asyncronous way. This
-page generating process is normally not directly associated with
-commands in the input\footnote{Excepts for directives such as
- \cs{newpage}.} but is triggered whenever the galley has received
-enough material to form another page (giving current settings).
-
-As part of this transformation input data may get stored in some form
-and later reused, for example, as part of the output routine
-processing.
-
-\section{Configuration of the transformation process}
-
-There are three different major methods offered by \LaTeX to configure
-the transformation process:
-\begin{itemize}
-\item through the template mechanism,
-\item through the hook mechanism, or
-\item through sockets.
-\end{itemize}
-They offer different possibilities (with different features and
-limitations) and are intended for specific use cases, though it is
-possible to combine them.
-
-\subsection{The template mechanism}
-
-The template mechanism is intended for more complex document-level
-elements (e.g., headings such as \verb=\section= or environments like
-\texttt{itemize}). The template code implements the overall processing
-logic for such an element and offers a set of parameters to influence
-the final result.
-
-The document element is then implemented by a) selecting a suitable
-template (there may be more than one available for the kind of
-document element) and b) by setting its parameters to desired
-values. This then forms a so-called instance which is executed when
-the document element is found in the source.
-
-By altering the parameter values (in a document class or in the
-document preamble) or, if more drastic layout changes are desired, by
-selecting a different template and then adjusting its parameters, a
-wide variety of layouts can be realized through simple configuration
-setups without the need to develop new code.
-
-The target audience of this method are therefore document class
-developers or users who wish to alter an existing layout (implemented
-by a document class) in certain (minor) ways.
-
-The template mechanism is currently documented as part of the
-\pkg{xtemplate} package and one more elaborate implementation can be
-found as part of the \texttt{latex-lab} code for lists (to be
-documented further).
-
-\subsection{The hook mechanism}
-
-Hooks are places in the kernel code (or in packages) that offer
-packages to inject additional code at specific points in the
-processing in a controlled way without the need to replace the
-existing code block (and thereby overwriting modifications/extensions
-made by other packages). The target audience is therefore mainly
-package developers, even though some hooks can be useful for document
-authors.
-
-Obviously, what can reasonably be added into a hook depends on the
-individual hook (hopefully documented as part of the hook
-documentation) but in general the idea behind hooks is that more than
-one package could add code into the hook at the same time. Perhaps the
-most famous hook (that \LaTeX{} had for a very long time) is
-\texttt{begindocument} into which many packages add code to through
-\cs{AtBeginDocument}\marg{code} (which is nowadays implemented as a
-shorthand for \cs{AddToHook}\texttt{\{begindocument\}}\marg{code}). To
-resolve possible conflicts between injections by different packages
-there is a rule mechanism by which code chunks in a hook can be
-ordered in a certain way and by which incompatible packages can be
-detected if a resolution is impossible.
-
-In contrast to template code, there is no standard configuration method
-through parameters for hooks, i.e., the code added to a hook \enquote{is} the
-configuration. If it provides for configuration through parameters it
-has to also provide its own method to set such parameters in some way.
-
-In most cases, hooks do not take any arguments as input. Instead, the data
-that they can (and are allowed to) access depends on the surrounding
-context.
-
-For example, the various hooks available during the page shipout
-process in \LaTeX's output routine can (and have to) access the
-accumulated page material stored in a box named
-\verb=\ShipoutBox=. This way, code added to, say, the
-\texttt{shipout/before} hook could access the page content, alter it,
-and then write it back into \verb=\ShipoutBox= and any other code
-added to this hook could then operate on the modified content. Of
-course, for such a scheme to work the code prior to executing the hook
-would need to setup up data in appropriate places and the hook
-documentation would need to document what kind of storage can be
-accessed (and possibly altered) by the hook.
-
-There are also hooks that take arguments (typically portions of
-document data) and in that case the hook code can access these
-arguments through \verb=#1=, \verb=#2=, etc.
-
-The hook mechanism is documented in \texttt{lthooks-doc.pdf}.
-
-\subsection{Sockets}
-
-In some cases there is code that implements a certain programming
-logic (for example, combining footnotes, floats, and the text for the
-current page to be shipped out) and if this logic should change (e.g.,
-footnotes to be placed above bottom floats instead of below) then this
-whole code (block) needs to be replaced with different code.
-
-In theory, this could be implemented with templates, i.e., the code
-simply calls some instance that implements the logic and that instance
-is altered by selecting a different templates and/or adjusting their
-parameters. However, in many cases customization through parameters is
-overkill in such a case (or otherwise awkward, because paramerization
-is better done on a higher level instead of individually for small
-blocks of code) and using the template mechanism just to replace one
-block of code with a different one results in a fairly high
-performance hit. It is therefore usually not a good choice.
-
-In theory, it would also be possible to use a hook, but again that is
-basically a misuse of the concept, because in this case there should
-never be more that one block of code inside such a \enquote{special hook}, so that to alter
-the processing logic one would need to set up rules that replace code
-rather than (as intended in the hook mechanism) execute all code added to a hook.
-
-
-
-For this reason \LaTeX{} now offers a third mechanism: sockets
-which are \enquote{replaceable code blocks} that are referred to by name.
-%
-In a nutshell: instead of having a fixed code block somewhere as part
-of the code that implements a certain programming logic, there is a named socket
-which is assigned a chunk of code to be executed in this place.
-
-This is done by first declaring the socket with:
-\begin{quote}
-\cs{NewSocket}\marg{socket-name}\marg{number-of-arguments}
-\end{quote}
-This is then used in code through
-\begin{quote}
- \cs{UseSocket}\marg{socket-name}
-\end{quote}
-or, if the socket takes a number of arguments with
-\begin{quote}
- \cs{UseSocket}\marg{socket-name}\marg{arg\textsubscript{1}}\ldots
- \marg{arg\textsubscript{number-of-arguments}}
-\end{quote}
-
-In addition, one or several named chunks of code implementing different logic for this
-socket are set up, each with a declaration of the form:
-\begin{quote}
- \cs{DeclareSocketCode}\marg{socket-name}\marg{chunk-name}\marg{code}
-\end{quote}
-Finally,
-one of them is assigned to the socket:
-\begin{quote}
-\cs{AssignSocketCode}\marg{socket-name}\marg{chunk-name}
-\end{quote}
-If the programming logic should change, then all that is necessary is
-to make a new assignment with \cs{AssignSocketCode} to a different
-\marg{chunk-name}.
-
-If the socket takes arguments, then those need to be provided to
-\cs{UseSocket} and in that case they can be referenced in the \meta{code}
-argument of \cs{DeclareSocketCode} with \verb=#1=, \verb=#2=, etc.
-
-In most cases a named socket is used only in a single place, but there
-is, of course, nothing wrong wth using it in several places, as long
-as the code in all places is supposed to change in the same way if the socket gets reassigned a different chunk of code.
-
-
-\section{Alternative names}
-
-
-By the way:
-\begin{itemize}
-\item
- should it be \texttt{gassign} ? or some other verb?
-\item
- And what about \cs{socket\_use:n}? Should that be \texttt{:nw}
- as we don't really control the arguments or should we have
- \cs{socket\_use:nn}, \cs{socket\_use:nnn}, \ldots, just to make it
- clearer how many arguments are (supposed to be) picked up?
-\end{itemize}
-
-
-
-
-\section{Example and testing}
-
-From here on we scroll through errors because the example explicitly generate a few:
-\begin{verbatim}
- \scrollmode
-\end{verbatim}
-\scrollmode
-
-We declare a new socket named \texttt{foo} expecting 2 arguments:
-\begin{verbatim}
- \NewSocket{foo}{2}
-\end{verbatim}
-\NewSocket{foo}{2}
-
-Such a declaration has do be unique across the whole \LaTeX{} run so
-if another package attempts to use the same name (regardless of the
-number of arguments) it will generate an error:
-\begin{verbatim}
- \NewSocket{foo}{2} % Error (already declared)
- \NewSocket{foo}{1} % Error (already declared)
-\end{verbatim}
-\NewSocket{foo}{2}
-\NewSocket{foo}{1}
-
-You also get an error if you attempt to declare some socket code and the
-socket name is not yet defined, e.g.,
-\begin{verbatim}
- \DeclareSocketCode{baz}{undeclared}{} % Error (Socket not declared)
-\end{verbatim}
-\DeclareSocketCode{baz}{undeclared}{}
-
-
-Setting up code for the socket is done like this:
-\begin{verbatim}
- \DeclareSocketCode{foo}{code-A}
- {\begin{quote}\itshape foo-A: #1|#2\end{quote}}
- \DeclareSocketCode{foo}{code-B}
- {\begin{quote}\sffamily foo-B: #2\textsuperscript{2}\end{quote}}
-\end{verbatim}
-which will set up instances \texttt{code-A} and \texttt{code-B} for
-this socket.
-
-\DeclareSocketCode{foo}{code-A}{\begin{quote}\itshape foo-A: #1|#2\end{quote}}
-\DeclareSocketCode{foo}{code-B}{\begin{quote}\sffamily foo-B: #2\textsuperscript{2}\end{quote}}
-
-We still have to assign one or the other so without it
-\begin{verbatim}
- \UseSocket{foo}{hello}{world} % Error (nothing assigned)
-\end{verbatim}
-will give us an error.
-
-\UseSocket{foo}{hello}{world} % Error (nothing assigned)
-
-So let's do the assignment and then
-\begin{verbatim}
- \AssignSocketcode{foo}{code-A}
- \UseSocket{foo}{hello}{world}
-\end{verbatim}
-will properly typeset
- \AssignSocketcode{foo}{code-A}\UseSocket{foo}{hello}{world}
-and after
-\begin{verbatim}
- \AssignSocketcode{foo}{code-B}
-\end{verbatim}
-and another call to
-\begin{verbatim}
- \UseSocket{foo}{hello}{world}
-\end{verbatim}
-we get
- \AssignSocketcode{foo}{code-B}\UseSocket{foo}{hello}{world}
-
-If we attempt to assign an instance that was not defined, e.g.,
-\begin{verbatim}
- \AssignSocketcode{foo}{code-C}
-\end{verbatim}
-then we get some error during the assignment and the previous assignment remains in place.
-
-\AssignSocketcode{foo}{code-C}
-
-\subsection{Rationale for error handling}
-
-The errors during the declarations are produced to help
-with typos --- after all, such declarations might be part of a document
-preamble (not that likely, but possible). However, \cs{UseSocket} is not doing much checking, e.g.,
-\begin{verbatim}
- \UseSocket{fou}{hello}{world}
-\end{verbatim}
-will generate a rather low-level error and then typesets
-%
-``\UseSocket{fou}{hello}{world}''
-%
-because there is no dedicated runtime check that \texttt{fou} is a known socket.
-
-The reason is that if the misspelling is in the code, then this is a
-programming error in the package and for speed reasons \LaTeX{} does
-not repeatedly make runtime checks for coding errors unless they can or
-are likely to be user-introduced.
-
-\subsection{Performance}
-
-A call to \cs{UseSocket}\marg{name} is just a fancy way to write something like
-\begin{quote}
- \verb=\csname __socket_=\meta{name}\verb=_code_=\meta{assigned-instance-name}\verb=:w\endcsname=
-\end{quote}
-and is thus very light-weight.
-
-
-
-\section{Prototype implementation}
-
-\begin{verbatim}
-\end{verbatim}
-
-\end{document}
More information about the latex3-commits
mailing list.