spacingtricks (28jul23)

git-svn-id: svn://tug.org/texlive/trunk@67754 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 225 insertions, 207 deletions

diff --git a/Master/texmf-dist/source/latex/spacingtricks/spacingtricks.dtx b/Master/texmf-dist/source/latex/spacingtricks/spacingtricks.dtx
index cea5d0322e8..f6c14e621c1 100644
--- a/Master/texmf-dist/source/latex/spacingtricks/spacingtricks.dtx
+++ b/Master/texmf-dist/source/latex/spacingtricks/spacingtricks.dtx
@@ -20,7 +20,7 @@
 %<*package> 
 \NeedsTeXFormat{LaTeX2e}[2005/12/01]
 \ProvidesPackage{spacingtricks}
-    [2023/03/05 v1.6 .dtx spacingtricks file]
+    [2023/07/28 v1.7 .dtx spacingtricks file]
 %</package>
 %<*driver>
 \documentclass{ltxdoc}
@@ -112,56 +112,60 @@
 %    - Any list symbol is followed by a space if there is no punctuation character after it,
 %    - some changes in documentation}
 %
+% \changes{v1.7}{2023/07/27}{
+%    - Minor adjustments in the documentation}
+%
 % \GetFileInfo{spacingtricks.sty}
 %
 % \title{The \textsf{spacingtricks} package\thanks{This document
 % corresponds to \textsf{spacingtricks}~\fileversion, dated \filedate.}}
 % \author{Antoine Missier \\ \texttt{antoine.missier@ac-toulouse.fr}}
-% \date{March 5, 2023}
+% \date{July  28, 2023}
 % \maketitle
 %
 % \section{Introduction}
 %
-% This package offers a few macros to deal with spacing issues. Thus:
+% This package offers several macros to address spacing issues:
 % \begin{compactlist}
-% \item \hyperlink{centered}{\texttt{\bslash centered}} yields good horizontal 
-% centering without vertical spacing;
+% \item \hyperlink{centered}{\texttt{\bslash centered}} offers horizontal 
+% centering without introducing vertical spacing.
 % \item \hyperlink{footnote}{\texttt{\bslash footnote}} has been redefined 
-% to avoid unsuitable spacing;
-% \item \hyperlink{vstrut}{\texttt{\bslash vstrut}} produces a strut 
-% with variable height or depth;
+% to avoid unsuitable spacing in certain cases.
+% \item \hyperlink{vstrut}{\texttt{\bslash vstrut}} generates a strut 
+% with variable height or depth for maintaining consistent vertical spacing.
 % \item \hyperlink{indent}{\texttt{\bslash indent}} has been redefined 
 % to indent a line at the beginning 
-% of a particular paragraph even if "\parindent" has been set to 0;
-% \item the \hyperlink{indentblock}{\texttt{indentblock}} environment 
-% produces indentation of all its content;
-% \item the \hyperlink{compactlist}{\texttt{compactlist}} environment 
-% yields a compact list, without vertical spacing between the items, like here;
-% several aliases are provided to type some \hyperlink{symbols}{list symbols} shorter:
-% "\bul", "\dash", "\ddash", "\aster", "\hand", "\checksymb", "\arrowsymb";
-% \item common abbreviations \hyperlink{ie-eg}{\ie and \eg} 
-% are typeset by the macros "\ie" and "\eg" with correct spacing;
-% \item the \hyperlink{dualboxes}{\texttt{\bslash dualboxes}} command attends to place 
+% of a particular paragraph even if "\parindent" has been set to 0.
+% \item The \hyperlink{indentblock}{\texttt{indentblock}} environment 
+% allows indentation of all its content.
+% \item The \hyperlink{compactlist}{\texttt{compactlist}} environment 
+% creates a compact list, as shown here, without vertical spacing between items.
+% Additionally, aliases are provided for shorter
+% \hyperlink{symbols}{list symbols}:
+% "\bul", "\dash", "\ddash", "\aster", "\hand", "\checksymb", "\arrowsymb".
+% \item Common abbreviations, \hyperlink{ie-eg}{\ie and \eg}, 
+% are typeset using the macros "\ie" and "\eg" ensuring correct spacing.
+% \item The \hyperlink{dualboxes}{\texttt{\bslash dualboxes}} command facilitates placing 
 % two boxes (figures, tables, text) side by side by adjusting the vertical positioning.
 % \end{compactlist}
 % 
 % \medskip
 % Three other ``spacing'' packages are loaded by \textsf{spacingtricks}:
 % \hyperlink{setspace}{\textsf{setspace}}~\cite{SETSP} (natively in \LaTeXe), 
-% for setting line spacing in a piece of text,
+% used for setting line spacing in a piece of text,
 % \textsf{xspace}~\cite{XSP}, which adds an inter-word space unless the macro 
 % is followed by a punctuation character,
 % and \hyperlink{centeredline}{\textsf{centeredline}}~\cite{CENTER} 
-% which gives an interesting alternative 
+% which offers an interesting alternative 
 % to our "\centered" macro (see further).
 % We also took over the fine \hyperlink{juxtapose}{\texttt{juxtapose}} environment 
 % from the \textsf{mafr}~\cite{MAFR}
 % distribution, as another way to place boxes side by side.
 %
-% Otherwise, we have develop the package \textsf{arraycols}~\cite{ARCOL},
-% that allows a good management of spacing in \texttt{tabular} 
+% Furthermore, we have developed the package \textsf{arraycols}~\cite{ARCOL},
+% which allows for effective management of spacing in \texttt{tabular} 
 % or \texttt{array} environments,
-% and \textsf{mismath}~\cite{MSMATH} that provides several macros to improve spacing 
+% and \textsf{mismath}~\cite{MSMATH} providing several macros to improve spacing 
 % in mathematical formulas.
 %
 % \section{Usage}
@@ -169,50 +173,50 @@
 % \hypertarget{centered}{}
 % \DescribeMacro{\centered}
 % The "\centered"\marg{text} command yields a centered line without vertical spacing.
-% It acts like "\centerline" except in lists or tables where its behavior is much better
-% (see the following examples).
-% Moreover, the line break before (but not after) the macro is automatic.
+% It functions similarly to "\centerline", except in lists or tables where its behavior
+% is notably improved (see the following examples).
+% Additionally, the line break before (but not after) the macro is applied automatically.
 %
 % Here is a comparative example of the centering commands inside a list:
 % \begin{enumerate}
-% \item Here a centered line with "\centered": 
+% \item Here is a centered line using "\centered": 
 % \centered{Lorem ipsum dolor sit amet, consectetuer adipiscing elit.}
-% \item Here another centered line with "\\ \centerline":\\
+% \item Here is another centered line using "\\ \centerline":\\
 % \centerline{Lorem ipsum dolor sit amet, consectetuer adipiscing elit.}
-% \item Here another centered line with "\par\centerline":
+% \item Here is another centered line using "\par\centerline":
 % \par\centerline{Lorem ipsum dolor sit amet, consectetuer adipiscing elit.}
-% \item Here a centered line with the \texttt{center} environment:
+% \item Here is a centered line using the \texttt{center} environment:
 % \begin{center} Lorem ipsum dolor sit amet, consectetuer adipiscing elit. \end{center}
 % \end{enumerate}
 %
-% After "\centered{...}", the end of line must be explicit, 
-% otherwise "\centered" will not work. You can use "\\",
-% which is equivalent to "\linebreak", or
+% After using "\centered{...}", the end of line must be explicit, 
+% otherwise "\centered" will not function correctly. You can use "\\",
+% which is equivalent to "\linebreak", or you can use
 % a blank line to begin a new paragraph (equivalent to "\par"). 
 % In the former case, no vertical space
-% is added after the centered line,  in the latter case, the vertical space
-% following the centered line is a bit larger. 
-% In the example above, the centered line comes to the end, without line breaking,
-% because of the next "\item" command, and the vertical space is set by the
+% is added after the centered line, while in the latter case, the vertical space
+% following the centered line is slightly larger. 
+% In the example provided, the centered line comes to an end, without line breaking
+% because of the next "\item" command, and the vertical space is determined by the
 % \texttt{enumerate} environment.
 %
 % \medskip
-% In tables, "\centered" allows to center a particular line in a cell independently of 
+% In tables, "\centered" allows you to center a specific line in a cell independently of 
 % the column alignment
-% \footnote{In tables, we can also use the powerful \texttt{\bslash makecell} command
-% of the \textsf{makecell} package~\cite{MKCELL}; on the other hand,
-% neither \texttt{\bslash centerline} nor \texttt{\bslash centering} commands
-% do work for a single line in a cell.},
-% here with "\begin{tabular}{|l|r|}":
+% \footnote{In tables, we can also utilize the powerful \texttt{\bslash makecell} command
+% from the \textsf{makecell} package~\cite{MKCELL}. However,
+% neither the \texttt{\bslash centerline} nor \texttt{\bslash centering} commands
+% work for a single line in a cell.},
+% Here's an example using "\begin{tabular}{|l|r|}":
 %
 % \begin{center}
 % \begin{tabular}{|l|r|}
 % \hline
-% left aligned column & right aligned column \\
+% left-aligned content & right-aligned content \\
 % \hline
-% the second cell fixes the width  & \centered{centered cell} \\
+% the second cell determines the width  & \centered{another centered content} \\
 % \hline
-% \centered{centered cell} & the last cell fixes the width \\
+% \centered{a centered cell} & the last cell determines the width \\
 % \hline
 % \end{tabular}
 % \end{center}
@@ -220,52 +224,56 @@
 % \medskip
 % \hypertarget{centeredline}{}
 % \DescribeMacro{\centeredline}
-% A limitation of our "\centered" macro is that it doesn't allow to use \texttt{\bslash verb}
-% commands inside its argument. For this purpose, you get
-% the "\centeredline" command, from the package
-% \textsf{centeredline} by Jean-François Burnol~\cite{CENTER}. 
+% A limitation of our "\centered" macro is that it doesn't allow the use of
+% \texttt{\bslash verb} commands inside its argument. 
+% However, you have the "\centeredline" command from the package
+% \textsf{centeredline} by Jean-François Burnol~\cite{CENTER} to address this limitation.
 % This small package is now loaded by \textsf{spacingtricks}.
-% Another advantage of "\centeredline" is that it does not require an explicit
-% end, the text can follow the command on the same line, and the line break will
+% One other advantage of "\centeredline" is that it does not require an explicit
+% end; the text can follow the command on the same line, and the line break will
 % be automatic.
 % Nevertheless, it doesn't work in tables (like in the example above),
-% except with \texttt{p} column declaration.
+% except when used with the \texttt{p} column declaration.
 %
 % \hypertarget{setspace}{}
 % \medskip
 % \DescribeEnv{onehalfspace}\DescribeEnv{doublespace}\DescribeEnv{spacing}
 % \begin{onehalfspace}
-% The \textsf{setspace} package~\cite{SETSP}, loaded by \textsf{spacingtricks}, provides
-% environments for changing the spacing between lines. The present paragraph is nested
-% in a \texttt{onhalfspace} environment as you can see.
-% The \texttt{spacing} environment can be used to get other interline spacing, \eg
-% "\begin{spacing}{2.5}".
+% The \textsf{setspace} package~\cite{SETSP}, which is loaded by \textsf{spacingtricks},
+% provides environments for changing the spacing between lines. 
+% The current paragraph is nested in a \texttt{onhalfspace} environment, as you can see.
+% The \texttt{spacing} environment can be used to achieve other interline spacing, 
+% for example "\begin{spacing}{2.5}".
 % \end{onehalfspace}
 %
 % \hypertarget{footnote}{}
 % \medskip
 % \DescribeMacro{\footnote}
-% The "\footnote" command doesn't have a good management of spacing issues,
-% in particular when the \textsf{hyperref} package has been loaded.
+% The "\footnote" command doesn't handle spacing issues well,
+% especially when the \textsf{hyperref} package has been loaded.
 % In English tradition, there is no space before numbers (or symbols) of note calls,
-% and likewise at the beginning of footnotes,
-% text begins immediately after the note number
+% and similarly at the beginning of footnotes,
+% the text begins immediately after the note number
 % \footnote{The typesetting of footnotes and note calls depends on national typographic
-% rules which are, in principle, managed by \textsf{babel}.
-% For instance, by activating the \texttt{french} option of \textsf{babel},
+% rules which are, in principle, managed by the \textsf{babel} package.
+% For instance, when activating the \texttt{french} option of \textsf{babel},
 % a thin space is added before the note calls, and the new \texttt{\bslash footnote}
 % macro does not alter this behavior.}.
-% To avoid undesirable spaces, we don't have to put some space before 
+% To avoid undesirable spaces, you don't have to leave any space before 
 % writing "\footnote{", for instance:
-% \begin{center}
-% "Here is no space\footnote{The old command} before the macro."
-% \end{center}
-% but sometimes, it is convenient to place the "\footnote" command
+% \centeredline{
+% "There is no space here\footnote{The old command} before the macro."
+% }
+% However, it may be convenient to place the "\footnote" command
 % on a new line. To achieve this, "\footnote" has been redefined to completely eliminate
 % unwanted spaces
-% \footnote{Probably it would have been enough to recommend the use of the \% symbol
-% at the end of line; its effect is to cancel the space produced by a line break,
-% but we do not always think of using it.}.
+% \footnote{Indeed, recommending the use of the \% symbol at the end of a line would suffice
+% (but not in dtx files);
+% its effect is to cancel the space produced by a line break,
+% but it's not always something that comes to mind immediately.
+% Furthermore let's note that our definition of \texttt{\bslash footnote} will have no effect
+% when using the \texttt{\bslash VerbatimFootnotes} command from the \textsf{fancyvrb} package
+% by Timothy Van Zandt~\cite{FVERB}.}.
 %
 % \medskip
 % \noindent\begin{minipage}{5.6cm}
@@ -298,39 +306,39 @@
 %
 % \medskip
 % \DescribeMacro{\footnotespace} \DescribeMacro{\footenoteindent}
-% Like the old one, the new "\footnote" command can take an optional argument
-% to force the number of the note.
-% Likewise, we have always customization macros 
-% "\footnotesize", "\footnotesep", "\footnoterule",
-% but two new macros have been added to manage spacing:
-% "\footnotespace" produces the space before the note call symbol
-% and "\footnoteindent" produces the space at the beginning of the footnote text.
+% Like the old "\footnote" command, the new one can take also 
+% an optional argument to force the number of the note.
+% Additionally, we have always had customization macros such as
+% "\footnotesize", "\footnotesep", "\footnoterule".
+% However, two new macros have been added to manage spacing:
+% "\footnotespace" which produces the space before the note call symbol,
+% and "\footnoteindent" which produces the space at the beginning of the footnote text.
 % For instance, with "\renewcommand{\footnotespace}{\,}" \\
 % and "\renewcommand{\footnoteindent}{\enskip}"
 % \footnote{\texttt{\bslash enskip} is equivalent to \texttt{\bslash hspace\{0.5em\}}.}
 % we get:
-% \renewcommand{\footnotespace}{\,}
-% \renewcommand{\footnoteindent}{\enskip}
 %
 % \begin{center}
+% \renewcommand{\footnotespace}{\,}
+% \renewcommand{\footnoteindent}{\enskip}
 % \begin{minipage}{7cm}
 % This is a note \footnote{en dash spacing at the beginning of the note.}  
 % with particular space settings.
 % \end{minipage}
 % \end{center}
-% \renewcommand{\footnotespace}{}
-% \renewcommand{\footnoteindent}{}
 % 
 % \hypertarget{vstrut}{}
-% \DescribeMacro{\vstrut} 
-% "\vstrut"\oarg{depth}\marg{height} produces a strut with variable height or depth,
-% in order to increase the line's height (above the base line) or depth 
-% (below the base line, optional);
-% this command can be used in a text line, a table, a list, a formula, etc.
-% If the values of \meta{height} and \meta{depth} are inferior to the height and depth
+% \DescribeMacro{\vstrut}
+% The command "\vstrut"\oarg{depth}\marg{height} produces a strut with a 
+% variable height or depth,
+% allowing you to increase the line's height above the baseline or its depth 
+% below (optional).
+% This command can be used in various contexts, such as a text line, a table, 
+% a list, a formula, and more.
+% If the values of \meta{height} and \meta{depth} are smaller than the height and depth
 % of the current line, the command has no effect.
-% Here are some examples.
-% \setlength{\juxtopskip}{0pt}\setlength{\juxbottomskip}{0pt}
+% Here are some examples:
+%
 % \begin{juxtapose}
 % \begin{verbatim}
 %\[\frac{\sqrt{0.5p}}{10} = 
@@ -339,22 +347,23 @@
 % \otherside
 % \[\frac{\sqrt{0.5p}}{10} = \frac{\sqrt{\vstrut{1.7ex} 0.5p}}{10}\]
 % \end{juxtapose}
+% \vspace{-2ex}
 % \noindent"\fbox{\vstrut{2ex}$\sigma(X)=1$}" gives
 % \fbox{\vstrut{2ex}$\sigma(X)=1$}
 % better than \fbox{$\sigma(X)=1$}.
 % 
 % \medskip
 % \noindent
-% The height adjustment is done by trial and error.
-% We could also have used a vertical phantom box;
-% for example in the previous square root, we get a good result with "\vphantom{\bar{t}}",
-% but it's not obvious to know what to put in the phantom box,
-% moreover, "\vstrut" allows a finer tuning.
+% Adjusting the height using "\vstrut" is done by trial and error.
+% While a vertical phantom box would provide a good result, 
+% for example "\vphantom{\bar{t}}" in the previous square root,
+% it's not obvious to know what to put in the phantom box.
+% Moreover, "\vstrut" allows a finer tuning.
 %
-% In a table,
+% In a table, using
 % "\renewcommand{\arraystretch}"\marg{stretch}
-% allows to increase the height of the rows but this command
-% has a global effect, whereas "\vstrut" allows to adjust properly the height of each row, 
+% allows you to increase the height of all rows, but it
+% has a global effect, whereas "\vstrut" allows to adjust the height of each row individually, 
 % as in the following table:
 % \[  
 % \begin{array}{|c|}
@@ -384,32 +393,33 @@
 % \end{array}
 %\]
 % However, for tables, we have the \textsf{arraycols} package~\cite{ARCOL},
-% based on \textsf{cellspace}~\cite{CELLSP}, which allows to adjust 
-% row heights automatically. Nevertheless, "\vstrut" can be useful for fine adjustments. 
+% which is based on \textsf{cellspace}~\cite{CELLSP} and it allows to automatically adjust 
+% row heights. Nevertheless, "\vstrut" can be useful for fine adjustments. 
 %
-% In a text line "\vstrut" can be used to increase line space, better than "\vspace".
+% In a text line "\vstrut" can be used to increase line space, 
+% and is better than "\vspace".
 %
 % \hypertarget{indent}{}
 % \medskip
 % \DescribeMacro{\indent} 
-% The command "\setlength{\parindent}{0cm}" allow to eliminate any indentation of lines
-% at the beginning of every paragraph. 
-% But in this case, the "\indent" command does not work anymore
-% if we want exceptional indentation of a particular paragraph.
-% So, the initial length of "\parindent" has been saved in "\parindentlength"
+% The command "\setlength{\parindent}{0cm}" eliminates 
+% indentation at the beginning of every paragraph. 
+% However, in this case, the "\indent" command does no longer works
+% if you want to apply exceptional indentation to a specific paragraph.
+% To address this issue, the initial length of "\parindent" is saved in "\parindentlength",
 % \DescribeMacro{\parindentlength} 
-% and the command "\indent" has been redefined to still allow indentation
-% of length "\parindentlength".
+% and the command "\indent" is redefined to allow indentation
+% of the length "\parindentlength".
 %
 % \hypertarget{indentblock}{}
 % \medskip
 % \DescribeEnv{indentblock}
-% The \texttt{indentblock} environment allows indentation of a whole block of lines.
-% It has an optional argument which is the length of indentation
-% (set by default to "\parindentlength").
-% The following lyrics have been indented (and typeset in italic shape) with
-% "\begin{indentblock}\itshape" and stanzas 2 and 4 have been affected by
-% an additional indentation with "\begin{indentblock}[3em]".
+% The \texttt{indentblock} environment facilitates the indentation of an entire block of lines.
+% It has an optional argument which sets the length of indentation
+% (by default it uses "\parindentlength").
+% The lyrics below have been indented (and typeset in italic shape) using
+% "\begin{indentblock}\itshape" and stanzas 2 and 4 have undergone
+% additional indentation using "\begin{indentblock}[3em]".
 %
 % \smallskip
 % \begin{indentblock}\itshape
@@ -440,16 +450,17 @@
 % 
 % \hypertarget{compactlist}{}
 % \DescribeEnv{compactlist}
-% As its name tells it, the "compactlist" environment allows to create
-% a ``compact'' list, \ie without vertical space neither above nor between items.
-% As for lists in \LaTeX, items are generated by the "\item" command.
-% The environment has an optional argument: "\begin{compactlist}"\oarg{symbol}.
+% As the name suggests, the "compactlist" environment allows you to create
+% a ``compact'' list, meaning it has no vertical space above or between items.
+% Similar to regular lists in \LaTeX, items are generated using the "\item" command.
+% The environment also accepts an optional argument: "\begin{compactlist}"\oarg{symbol}.
 % 
 % \hypertarget{symbols}{}
 % \medskip
 % \DescribeMacro{\bul}\DescribeMacro{\dash}\DescribeMacro{\ddash}\DescribeMacro{\aster}
-% The default item symbol is "\textbullet", but can be changed.
-% We provide aliases for several symbols commonly used in lists:
+% The default item symbol in the compactlist environment is "\textbullet", 
+% but it can be changed.
+% We have provided aliases for several symbols commonly used in lists:
 % "\bul" \bul\ (alias for "\textbullet"), "\dash" \dash\ (alias for "\textendash"), 
 % "\ddash" \ddash\ (alias for "\textemdash"), 
 % "\aster" \aster\ ("alias for \textasteriskcentered").
@@ -458,7 +469,7 @@
 % \DescribeEnv{[pifont]}
 % \DescribeMacro{\hand}\DescribeMacro{\checksymb}\DescribeMacro{\arrowsymb}
 % Some other common symbols can be found in the \textsf{pifont} package~\cite{PIFONT}.
-% Therefore \textsf{spacingtricks} has a \texttt{pifont} option,
+% Therefore the \textsf{spacingtricks} package includess a \texttt{pifont} option
 % that loads this package and creates the appropriate aliases:
 % "\hand" \hand for "\ding{43}", "\checksymb" \checksymb for "\ding{51}"
 % and "\arrowsymb" \arrowsymb for "\ding{226}".
@@ -472,7 +483,7 @@
 % \end{compactlist}
 % \hand These aliases can also be used directly in some text.
 % The symbol is followed by a space if there is no punctuation character 
-% just after it (thanks to the 
+% immediately after it (thanks to the 
 % macro \texttt{xspace} from the \textsf{xspace} package~\cite{XSP}).
 % Use "\"\meta{symbol}"\unskip" if you want to remove this space.
 %
@@ -480,8 +491,8 @@
 % \DescribeMacro{\compactlistindent}
 % Indentation length is set by "\compactlistindent" (fixed at 0.5\,em by default) 
 % and can be modified with "\setlength".
-% Notice that there are several other ways to construct a compact list in particular
-% with the \texttt{noitemsep} key of the \textsf{enumitem} package~\cite{ENUM}.
+% Notice that that there are several other ways to create a compact list,
+% particularly by using the \texttt{noitemsep} key of the \textsf{enumitem} package~\cite{ENUM}.
 %
 % \medskip
 % \DescribeEnv{dinglist}
@@ -498,32 +509,32 @@
 % \hypertarget{ie-eg}{}
 % \medskip
 % \DescribeMacro{\ie} \DescribeMacro{\eg}
-% In English, at the end of a sentence, the point is followed by an em space
+% In English, at the end of a sentence, the period is followed by an em space
 % which is larger than an inter-word space.
-% We provide the "\ie" (\textit{id est}) and "\eg" (\textit{exempli gratia}) macros,
-% suggested in The \LaTeX\ Companion \cite{COMP},
-% to get correct spacing after these abbreviations \eg here.
+% To achieve correct spacing after the abbreviations `\ie' (\textit{id est}) and `\eg'
+% (\textit{exempli gratia}), \eg here, we provide the "\ie" and "\eg" macros,
+% suggested in The \LaTeX\ Companion \cite{COMP}.
 % In American typography, a comma is often placed after these abbreviations,
-% what we can get with "\ie,"
+% which can be achieved using "\ie,"
 % on the other hand, some authors prefer to typeset \textit{\ie} in italic shape,
 % which is always possible with "\textit{\ie}". 
 %
 % \hypertarget{dualboxes}{}
 % \medskip
 % \DescribeMacro{\dualboxes}
-% Several packages intend to typeset text around a figure or a table,
-% but some of them need to give the width of the box containing the figure or the table.
-% We provide here another approach with the macro
+% Several packages aim to typeset text around a figure or a table,
+% but some of them require providing the width of the box containing the figure or the table.
+% Here we provide another approach with the macro
 % "\dualboxes"\oarg{pos}\marg{left}\marg{right},
 % which places two boxes, \meta{left} and \meta{right}, side by side.
-% These boxes can contain figures, tables, one small line text, 
+% These boxes can contain figures, tables, a small line of text, 
 % parbox text, \texttt{minipage} environments
 % (for several paragraphs and lists), etc.
-% The optional \meta{pos} parameter sets the vertical level on which the boxes are aligned:
-% a number between 0 (bottom) and 1 (top, default value).
+% The optional \meta{pos} parameter sets the vertical level on which the boxes are aligned,
+% and it takes a value between 0 (bottom) and 1 (top, default value).
 %
-% Here is a first example in which we have adjusted  the postion
-% of the boxes vertically, with "\dualboxes[0.6]".
+% Here is a first example in which we have adjusted the position
+% of the boxes vertically using "\dualboxes[0.6]".
 %
 % \def\myfigure{%
 % \begin{tikzpicture}[scale=0.6]\tiny 
@@ -545,13 +556,14 @@
 % \dualboxes[0.6]{\scriptsize \mytable}{\myfigure}
 %
 % \noindent
-% The horizontal space is equally shared between left margin, inter-box space 
+% The horizontal space is equally shared between left margin, inter-box space, 
 % and right margin.
 % 
 % \medskip
-% In the following example boxes are aligned by top and
+% In the following example, boxes are aligned by top, and
 % the right box has been shifted back (left) from 3\,cm
-% to make an overlapping with the left one, what \textsf{picins} cannot do. 
+% to create an overlapping effect with the left one, 
+% which cannot be achieved using \textsf{picins}. 
 % 
 % \dualboxes{\scriptsize \mytable}{\mbox{} \hspace{-3cm} \myfigure}
 % \begin{verbatim}
@@ -575,71 +587,72 @@
 % \end{verbatim}
 %
 % \DescribeMacro{\dualboxes*}
-% This command has a starred version that eliminates space before the first box
+% Indeed this command has a starred version that eliminates space before the first box
 % and after the second one, but not between them:
 % "\dualboxes*"\oarg{pos}\marg{left}\marg{right}.
 %
 % \smallskip
 % \dualboxes*[0.6]{\parbox{6.5cm}{
-%     In practice, \texttt{\bslash dualboxes} is suitable for boxes in which 
-%     you put figures or tables or small one line text.
-%     For longer text, this one must be nested in a paragraph box, \eg 
+%     In practice, the \texttt{\bslash dualboxes} macro is suitable for boxes in which 
+%     you put figures, tables, or small one-line text.
+%     However, for longer text, it must be nested in a paragraph box, \eg 
 %     here we used \texttt{\bslash parbox\{6.5cm\}\{...\}}.
-%     If you want several paragraphs, a list or a mathematical displayed formula,
-%     then you have to put them in a \texttt{minipage} environment.}
+%     If you need to include several paragraphs, a list, or a mathematical displayed formula,
+%     you should use a \texttt{minipage} environment.}
 % }{\myfigure}
 %
 % \medskip
-% Let us indicate that it is unfortunately not possible to use \texttt{verbatim} environments
+% Let us mention that, unfortunately, it is not possible to use \texttt{verbatim} environments
 % (nor the in-line \texttt{\bslash verb} command)
-% within "\dualboxes" arguments,
-% as well as it is not possible for footnotes or margin notes.  
+% within the "\dualboxes" arguments.
+% Additionally, using footnotes or margin notes within "\dualboxes" is also not possible.  
 %
 % \medskip
-% For putting two figures side by side, or a table and a figure, "\dualboxes" is perfect.
-% But for text around a figure, some other package may be more efficient.
-% Les us mention first \textsf{wrapfig}~\cite{WRAPFIG}, one of the easiest, but text must
-% contain in a single paragraph (like above), without list or you have to place it in
-% a \texttt{minipage} environment.
+% For arranging two figures side by side, or a table and a figure, "\dualboxes" is perfect.
+% However, for wrapping text around a figure, some other package may be more efficient.
+% Les us first mention \textsf{wrapfig}~\cite{WRAPFIG}, one of the easiest, but 
+% it requires the text to be contained in a single paragraph (like above), without list. 
+% Otherwise you have to place it in a \texttt{minipage} environment.
 %
 % More sophisticated is the \textsf{picins} package~\cite{PICINS},
 % cited in The \LaTeX\ Companion~\cite{COMP}.
-% Unlike most others, it can be used with lists,
-% nevertheless vertical positioning can be tricky
-% and it doesn't belong to common distributions \TeX{}\,Live or MiK\TeX.
-% A last one we mention is \textsf{picinpar}~\cite{PICINPAR} in which
-% text can begin after the first line and can flow to the two side of the figure;
-% it allows several paragraphs but neither lists, nor verbatim text.
+% Unlike most others, it can be used with lists;
+% however vertical positioning can be tricky,
+% and it is not included in common distributions \TeX{}\,Live or MiK\TeX.
+% Another package worth mentioning is \textsf{picinpar}~\cite{PICINPAR}, in which
+% text can begin after the first line and flow to both sides of the figure.
+% It allows several paragraphs, but it does not support lists or verbatim text.
 %
 % \hypertarget{juxtapose}{}
 % \medskip
 % \DescribeEnv{juxtapose}
 % As a very interesting alternative, we present the powerful \texttt{juxtapose} environment,
-% written by Christian Obrecht in the \texttt{fiche.cls class} file,
+% originally written by Christian Obrecht in the \texttt{fiche.cls class} file,
 % which is part of the \textsf{mafr} distribution~\cite{MAFR}.
-% We made small improvements, among others to work correctly with lists and
-% get customization of some lengths:
+% We have made small improvements, including ensuring proper functionality 
+% and allowing customization of certain lengths.
 % \DescribeMacro{\juxtopskip}\DescribeMacro{\juxbottomskip}
 % \DescribeMacro{\juxsepspace}
-% top and bottom lengths are set by default to "\smallskipamount" 
-% and separation space is set to 1.5\,em.
-% For spacing above or below the environment, if the default length doesn't fit well,
+% By default, the top and bottom lengths are set to "\smallskipamount",
+% and the separation space is set to 1.5\,em.
+% If the default lengths do not fit well for spacing above or below the environment,
 % you can add a "\bigskip" or a "\vspace"\marg{dimen} for example,
-% or at worst redefine the length "\juxtopskip" and "\juxbottomskip".
+% or, as a last resort, you can redefine the lengths "\juxtopskip" and "\juxbottomskip".
 % \begin{juxtapose}
-%     In this example the environment begins here.
-%     \texttt{juxtapose} can deal with figures, tables, but also:
+%     In this example the \texttt{juxtapose} environment begins here.
+%     It can handle various elements, including figures, tables, as well as:
 %     \begin{compactlist}
 %         \item verbatim text: "\mytestmacro",
 %         \item text with several paragraphs,
 %         \item lists, like here (a compact list),
 %         \item displayed mathematics as shown on the right side,
 %     \end{compactlist} 
-%     without the need of \texttt{multipage} environments.
+%     without the need for \texttt{multipage} environments.
 
 % The two boxes are aligned by their center, but
-% unlike "\dualboxes", you cannot adjust vertical positioning,
-% except using "\vspace".\smallskip
+% unlike "\dualboxes", you cannot adjust vertical positioning directly.
+% However, you can use "\vspace" inside a box to alter vertical positioning
+% and achieve the desired layout.\smallskip
 % 
 % \otherside 
 %     \myfigure
@@ -652,38 +665,40 @@
 % "\begin{juxtapose} ... \otherside ... \end{juxtapose}"
 % \end{center}
 % It has an optional argument "\begin{juxtapose}"\oarg{leftratio}
-% where \meta{leftratio} is the width ratio of the left side relatively to "\textwidth"
+% where \meta{leftratio} is the width ratio of the left side relative to "\textwidth"
 % (the default value is "0.5" which means "0.5\textwidth"). 
 %
-% Paragraphs are indented inside each side, except the first one,
-% because for a figure, there's no need to shift it to the right
-% (from indent length) and otherwise the user may forgot to 
-% put "\noindent" before the figure.
-% If you still want to indent the first paragraph use "\indent".
-% For horizontal alignment inside a box, you can use "\centering" or "\flushright"
-% (useful for a figure).
-% If you want a global indentation of the first (or the second) box, you
-% can put it in an \texttt{indentblock} environment, it works fine!
+% Paragraphs are indented inside each side, except the first one.
+% For a figure, there's no need to shift it to the right
+% (from indent length) to prevent users from forgetting to use "\noindent"
+% before the figure.
+% If you still want to indent the first paragraph, you can use "\indent".
+% For horizontal alignment inside a box, you can use "\centering" or "\flushright",
+% particularly useful for figures.
+% For a global indentation of the first (or the second) box, you
+% enclose it in an \texttt{indentblock} environment, and will work perfectly.
 %
 % \medskip
-% One may ask why not using multi column environments instead.
-% In the classic \textsf{multicol} environment you cannot choose 
+% One may ask why not using multi-column environments instead.
+% In the classic \textsf{multicol} environment, you cannot choose 
 % horizontally unbalanced
-% columns and you cannot choose where to pass to the other column.
-%
-% Some nice packages improve \textsf{multicols}, \eg \textsf{vwcol}~\cite{VWCOL} in which
-% you can fix on the columns width, but unfortunately it doesn't accept
-% verbatim text, and doesn't manage correctly lists and figures like above.
-%
-% Let us mention \textsf{paracol}~\cite{PARA} and \textsf{reledpar}~\cite{RELP},
-% which are intended to typeset two column of text in parallel, 
-% useful for translation or critical edition of text.
-% They work fine with lists, figures, verbatim text, and also footnotes and margin notes,
-% but it is not immediate to obtain just a chosen vertical positioning of two boxes.
-% They have synchronization mechanisms, convenient for text, but
-% not when you place two figures side by side.
-% Besides they are a bit oversized for our need. They don't have the same purpose.
-% So we can hope \texttt{juxtapose} or "\dualboxes" are useful.
+% columns, and you cannot control where to transition to the other column.
+%
+% Some packages improve \textsf{multicol}. 
+% For instance, \textsf{vwcol}~\cite{VWCOL} allows fixed column widths.
+% However, it still has limitations, such as not accepting verbatim text 
+% and not handling lists and figures correctly (as \texttt{juxtapose} did it above).
+%
+% Let's mention \textsf{paracol}~\cite{PARA} and \textsf{reledpar}~\cite{RELP},
+% both designed for typesetting two columns of text in parallel, 
+% making them useful for translation or critical editions of text.
+% They work fine with lists, figures, verbatim text, footnotes and margin notes.
+% However, achieving precise vertical positioning of two boxes
+% is not straightforward.
+% While they offer synchronization mechanisms, convenient for text, they may not be ideal
+% for placing two figures side by side.
+% Additionally, they are a bit over-sized for our specific need.
+% For our purposes, \texttt{juxtapose} or "\dualboxes" may be more suitable options.
 %
 % \StopEventually{}
 %
@@ -766,7 +781,7 @@
 \providecommand{\aster}{\textasteriskcentered\xspace}
 %    \end{macrocode}
 % The command "\asterisk" already exists in the \textsf{mathabx} package (for math mode only).\\
-% The following macros need the \textsf{pifont} package.
+% The following macros require the \textsf{pifont} package.
 % \smallskip
 %    \begin{macrocode}
 \ifspacingtricks@pifont
@@ -792,11 +807,12 @@
 
 %    \end{macrocode}
 %
-% The following macro has been found in the \texttt{fiche.cls} file,
+% The following macro was found in the \texttt{fiche.cls} file,
 % distributed with the \textsf{mafr} package by Christian Obrecht~\cite{MAFR}.
-% It had some tiny bugs in spacing.
-% I just made small changes: adding some lengths parameters and the "\linewidth"
-% instruction (without whom, lists in the first side send the second side out of the page).
+% It had some minor bugs in spacing.
+% I made small changes, including the addition of lengths parameters and the "\linewidth"
+% instruction (without which, lists in the first side would send the second side 
+% out of the page).
 %    \begin{macrocode}
 \newlength\juxtopskip
 \setlength\juxtopskip{\smallskipamount}
@@ -807,7 +823,7 @@
 \newlength\side@width
 
 \newenvironment{juxtapose}[1][0.5]{% left side ratio
-    \def\otherside{\egroup % internal function remembers \side@width
+    \def\otherside{\egroup % the internal function remembers \side@width
         \@tempdima=\side@width
         \side@width=\textwidth
         \advance\side@width by -\@tempdima
@@ -827,7 +843,7 @@
 %    \end{macrocode}
 %
 % \medskip
-% \begin{thebibliography}{17}
+% \begin{thebibliography}{18}
 % \begin{raggedright}
 % \bibitem{SETSP} \emph{The \textsf{setspace} Package}, Robin Fairbairns, Geoffrey Tobin,
 % CTAN, v9.7b 2022/12/04.
@@ -841,6 +857,8 @@
 % v1.2 2021/09/20.
 % \bibitem{MSMATH} \emph{\textsf{mismath} -- Miscellaneous mathematical macros}, 
 % Antoine Missier, CTAN, v2.5 2023/02/24.
+% \bibitem{FVERB} \emph{The \textsf{‘fancyvrb’} package -- Fancy Verbatims in \LaTeX},
+% Timothy Van Zandt, CTAN, v4.5a 2023/01/19.
 % \bibitem{MKCELL} \emph{The \textsf{makecell} package}, Olga Lapko, CTAN, v0.1e 2009/08/03.
 % \bibitem{CELLSP} \emph{The \textsf{cellspace} package}, Josselin Noirel, CTAN, 
 % v1.9.0 2022/01/04.