bytefield (31oct20)

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

1 files changed, 197 insertions, 46 deletions

diff --git a/Master/texmf-dist/source/latex/bytefield/bytefield.dtx b/Master/texmf-dist/source/latex/bytefield/bytefield.dtx
index 4354a50e784..8af3e52bbff 100644
--- a/Master/texmf-dist/source/latex/bytefield/bytefield.dtx
+++ b/Master/texmf-dist/source/latex/bytefield/bytefield.dtx
@@ -22,7 +22,7 @@
 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
 %<package>\ProvidesPackage{bytefield}
 %<*package>
-    [2020/10/22 v2.5 Network protocol diagrams]
+    [2020/10/31 v2.6 Network protocol diagrams]
 %</package>
 %
 %<*driver>
@@ -68,7 +68,7 @@
 %</driver>
 % \fi
 %
-% \CheckSum{1161}
+% \CheckSum{1194}
 %
 % \CharacterTable
 %  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
@@ -108,6 +108,11 @@
 % \changes{v2.5}{2020/10/22}{Accept a new \protect\optname{perword}
 %   option to execute a macro for each word in a word box.  This addresses
 %   a feature request by Victor Toni}
+% \changes{v2.6}{2020/10/29}{Accept new \protect\optname{curlystyle},
+%   \protect\optname{leftcurlystyle}, and
+%   \protect\optname{rightcurlystyle} options to control the styling
+%   (e.g.,~color) of curly braces.  This addresses a feature request by
+%   Victor Toni}
 %
 % \GetFileInfo{bytefield.dtx}
 %
@@ -607,12 +612,12 @@
 %
 % \begin{decl}
 %   \SpecialEnvIndex{rightwordgroup}
-%   |\begin{rightwordgroup}| \marg{text} \\
+%   |\begin{rightwordgroup}| \oarg{options} \marg{text} \\
 %   \meta{rows of bit boxes and word boxes} \\
 %   |\end{rightwordgroup}| \\
 %   \\
 %   \SpecialEnvIndex{leftwordgroup}
-%   |\begin{leftwordgroup}| \marg{text} \\
+%   |\begin{leftwordgroup}| \oarg{options} \marg{text} \\
 %   \meta{rows of bit boxes and word boxes} \\
 %   |\end{leftwordgroup}|
 % \end{decl}
@@ -627,6 +632,12 @@
 % |\end{|\meta{side}|wordgroup}| must lie right \emph{before} the end of
 % the row (i.e.,~right before a ``|\\|'').
 %
+% The optional argument is a comma-separated list of
+% \meta{key}=\meta{value} pairs from the set described in
+% Section~\ref{sec:options}.  In practice, only \optname{curlystyle},
+% \optname{leftcurlystyle}, and \optname{rightcurlystyle}, make sense
+% within the context of a |\begin{|\meta{side}|wordgroup}|.
+%
 % Unlike other \LaTeX\ environments, |rightwordgroup| and
 % |leftwordgroup| do not have to nest properly with each other.
 % However, they cannot overlap themselves.  In other words,
@@ -751,7 +762,7 @@
 % A document author can customize many of the \pkgname{bytefield}
 % package's figure-formatting parameters, either globally or on a
 % per-figure basis.  The parameters described below can be specified in
-% five locations:
+% six locations:
 %
 % \begin{itemize}
 %   \item as package options (i.e.,~in the
@@ -769,6 +780,10 @@
 %     that particular header.  (Only a few parameters are meaningful in
 %     this context.)
 %
+%   \item as the optional argument to a |\begin{leftwordgroup}| or
+%     |\begin{rightwordgroup}|, which affects only that particular word
+%     group.  (Only a few parameters are meaningful in this context.)
+%
 %   \item as the second optional argument to a \cs{bitbox}, \cs{wordbox},
 %     or \cs{bitboxes}, which affects only that particular box.  (Only a
 %     few parameters are meaningful in this context.)
@@ -799,7 +814,7 @@
 %
 % As a special case, if \optname{bitwidth} is set to the word
 % ``|auto|'', it will be set to the width of ``|99i|'' in the current
-% bit-number formatting (cf.~\optname{bitformatting} below).  This
+% bit-number formatting (see \optname{bitformatting} below).  This
 % feature provides a convenient way to adjust the bit width after a
 % formatting change.
 %
@@ -1081,6 +1096,55 @@
 % different heights.
 %
 % \begin{decl}
+%   \optname{leftcurlystyle} = \meta{command} \\
+%   \optname{rightcurlystyle} = \meta{command} \\
+%   \optname{curlystyle} = \meta{command}
+% \end{decl}
+%
+% Provide a macro that will be invoked before the code that draws left,
+% right, or both curly braces.  The macro must accept either zero or one
+% argument.  It can be used, for example, to color the curly brace:
+%
+% \begin{verbatim}
+%       \begin{bytefield}[curlystyle=\color{blue}]{16}
+%         \bitheader{0-15} \\
+%         \begin{rightwordgroup}{Sign-extended}
+%             \bitbox{4}{Tag} & \bitbox{12}{Data}
+%         \end{rightwordgroup} \\
+%       \end{bytefield}
+% \end{verbatim}
+%
+% \begin{bffigure}
+%       \begin{bytefield}[curlystyle=\color{blue}]{16}
+%         \bitheader{0-15} \\
+%         \begin{rightwordgroup}{Sign-extended}
+%             \bitbox{4}{Tag} & \bitbox{12}{Data}
+%         \end{rightwordgroup} \\
+%       \end{bytefield}
+% \end{bffigure}
+%
+% \noindent
+% or
+%
+% \begin{verbatim}
+%       \begin{bytefield}{16}
+%         \bitheader{0-15} \\
+%         \begin{rightwordgroup}[curlystyle=\color{blue}]{Sign-extended}
+%             \bitbox{4}{Tag} & \bitbox{12}{Data}
+%         \end{rightwordgroup} \\
+%       \end{bytefield}
+% \end{verbatim}
+%
+% \begin{bffigure}
+%       \begin{bytefield}{16}
+%         \bitheader{0-15} \\
+%         \begin{rightwordgroup}[curlystyle=\color{blue}]{Sign-extended}
+%             \bitbox{4}{Tag} & \bitbox{12}{Data}
+%         \end{rightwordgroup} \\
+%       \end{bytefield}
+% \end{bffigure}
+%
+% \begin{decl}
 %   \optname{lsb} = \meta{integer}
 % \end{decl}
 %
@@ -2052,7 +2116,7 @@
 % \changes{v2.3}{2015/10/28}{Rewrote the macro based on discussions with
 %   David Carlisle to avoid producing ``\texttt{No room for a new
 %   \string\string\string\dimen}'' errors in newer versions of $\varepsilon$-\TeX\
-%   (cf.~\url{http://tex.stackexchange.com/q/275042})}
+%   (see \url{http://tex.stackexchange.com/q/275042})}
 %    \begin{macrocode}
 \AtBeginDocument{%
   \expandafter\ifx\csname e@alloc\endcsname\relax
@@ -2160,6 +2224,7 @@
 %    \begin{macrocode}
   \vbox\bgroup\ialign\bgroup##\amp##\amp##\cr\amp
 }{%
+  \unskip
   \amp\show@wordlabelr\cr\egroup\egroup
   \end{lrbox}%
   \usebox{\entire@bytefield@picture}%
@@ -2581,7 +2646,7 @@
 %    \begin{macrocode}
 \def\bf@bitboxes@star@i#1#2{%
   \def\bf@call@box@arg@iv{#1}%
-  \def\bf@bitboxes@arg@ii{#2}%  
+  \def\bf@bitboxes@arg@ii{#2}%
   \ifx\bf@bitboxes@arg@ii\bf@relax
     \bf@bitbox
     \let\next=\relax
@@ -2978,6 +3043,17 @@
 % \end{macro}
 % \end{macro}
 %
+% \begin{macro}{\bf@leftcurlystyle}
+% \begin{macro}{\bf@rightcurlystyle}
+% Define the default formatting for left and right curly braces as ``do
+% nothing special''.
+%    \begin{macrocode}
+\let\bf@leftcurlystyle=\relax
+\let\bf@rightcurlystyle=\relax
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
 % \begin{macro}{\curly@box}
 % Define a box in which to temporarily store formatted curly braces.
 % \changes{v1.2}{2004/06/14}{Bug fix: Defined \cs{curly@box} globally
@@ -3009,11 +3085,13 @@
     \setlength{\curly@shift}{\half@curly@height + 0.5\curly@shift}%
     \global\sbox{#1}{\raisebox{\curly@shift}{%
       $\xdef\old@axis{\the\fontdimen22\textfont2}$%
-      $\fontdimen22\textfont2=0pt%
-       \left.
-       \vrule height\half@curly@height
-              width 0pt
-              depth\half@curly@height\right\bf@rightcurly$%
+      \bf@rightcurlystyle{%
+        $\fontdimen22\textfont2=0pt%
+         \left.
+         \vrule height\half@curly@height
+                width 0pt
+                depth\half@curly@height\right\bf@rightcurly$%
+      }%
       $\fontdimen22\textfont2=\old@axis$}}%
   \endgroup
 }
@@ -3042,11 +3120,13 @@
     \setlength{\curly@shift}{\half@curly@height + 0.5\curly@shift}%
     \global\sbox{#1}{\raisebox{\curly@shift}{%
       $\xdef\old@axis{\the\fontdimen22\textfont2}$%
-      $\fontdimen22\textfont2=0pt%
-       \left\bf@leftcurly
-       \vrule height\half@curly@height
-              width 0pt
-              depth\half@curly@height\right.$%
+      \bf@leftcurlystyle{%
+        $\fontdimen22\textfont2=0pt%
+         \left\bf@leftcurly
+         \vrule height\half@curly@height
+                width 0pt
+                depth\half@curly@height\right.$%
+      }%
       $\fontdimen22\textfont2=\old@axis$}}%
   \endgroup
 }
@@ -3081,12 +3161,17 @@
 %
 % \begin{environment}{rightwordgroup}
 % \usermacro
-% Label the words defined between |\begin{rightwordgroup}| and |\end{rightwordgroup}|
-% on the right side of the bit field.
-% The argument is the text of the label.  The label is typeset to the
-% right of a large curly brace, which groups the words together.
-%    \begin{macrocode}
-\newenvironment{rightwordgroup}[1]{%
+% Label the words defined between |\begin{rightwordgroup}| and
+% |\end{rightwordgroup}| on the right side of the bit field.  The first,
+% optional, argument is a list of parameters, as defined in
+% Section~\ref{sec:options}.  The second, mandatory, argument is the
+% text of the label.  The label is typeset to the right of a large curly
+% brace, which groups the words together.
+% \changes{v2.6}{2020/10/29}{Suppress spaces following the
+%   \protect\cs{end}\protect\texttt{\{rightwordgroup\}}}
+% \changes{v2.6}{2020/10/31}{Accept key/value options}
+%    \begin{macrocode}
+\newenvironment{rightwordgroup}[2][]{%
 %    \end{macrocode}
 % We begin by ending the group that |\begin{rightwordgroup}| created.  This
 % lets the |rightwordgroup| environment span rows (because we're technically
@@ -3095,21 +3180,25 @@
   \endgroup
 %    \end{macrocode}
 % \begin{macro}{\wordlabelr@start}
+% \begin{macro}{\wordlabelr@params}
 % \begin{macro}{\wordlabelr@text}
-% |\begin{rightwordgroup}| merely stores the starting height in |\wordlabelr@start|
-% and the user-supplied text in |\wordlabelr@text|.  |\end{rightwordgroup}|
-% does most of the work.
+% |\begin{rightwordgroup}| merely stores the starting height in
+% |\wordlabelr@start| and the user-supplied text in |\wordlabelr@text|.
+% |\end{rightwordgroup}| does most of the work.
 %    \begin{macrocode}
   \global\wordlabelr@start=\bytefield@height
-  \gdef\wordlabelr@text{#1}%
+  \gdef\wordlabelr@params{#1}%
+  \gdef\wordlabelr@text{#2}%
   \ignorespaces
 }{%
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}
+% \end{macro}
 % \begin{macro}{\wordlabelr@end}
-% Because we already ended the group that |\begin{rightwordgroup}| created
-% we now have to begin a group for |\end{rightwordgroup}| to end.
+% Because we already ended the group that |\begin{rightwordgroup}|
+% created we now have to begin a group for |\end{rightwordgroup}| to
+% end.
 %    \begin{macrocode}
   \begingroup
   \global\wordlabelr@end=\bytefield@height
@@ -3125,23 +3214,32 @@
 %    \begin{macrocode}
   \gdef\show@wordlabelr{%
     \sbox{\word@label@box}{%
-      \begin{tabular}[b]{@{}l@{}}\wordlabelr@text\end{tabular}}%
+      \begin{tabular}[b]{@{}l@{}}\wordlabelr@text\end{tabular}%
+    }%
     \settowidth{\label@box@width}{\usebox{\word@label@box}}%
     \setlength{\label@box@height}{\wordlabelr@end-\wordlabelr@start}%
+%    \end{macrocode}
+% Evaluate any parameters passed to |\begin{rightwordgroup}| right
+% before we render the curly brace.
+%    \begin{macrocode}
+    \expandafter\bf@bytefieldsetup\expandafter{\wordlabelr@params}%
     \store@rcurly{\curly@box}{\label@box@height}%
     \bf@newdimen\total@box@width
     \setlength{\total@box@width}{%
       \bf@rightcurlyspace +
       \widthof{\usebox{\curly@box}} +
       \bf@rightlabelspace +
-      \label@box@width}%
+      \label@box@width
+    }%
     \begin{picture}(\strip@pt\total@box@width,0)
       \put(0,0){%
         \hspace*{\bf@rightcurlyspace}%
         \usebox{\curly@box}%
         \hspace*{\bf@rightlabelspace}%
         \makebox(\strip@pt\label@box@width,\strip@pt\label@box@height){%
-          \usebox{\word@label@box}}}
+          \usebox{\word@label@box}%
+        }%
+      }%
     \end{picture}%
 %    \end{macrocode}
 % The last thing |\show@wordlabelr| does is redefine itself back to a no-op.
@@ -3156,7 +3254,7 @@
 % |\begin|.
 %    \begin{macrocode}
   \def\@currenvir{rightwordgroup}%
-  \ignorespaces
+  \ignorespacesafterend
 }
 %    \end{macrocode}
 % \end{macro}
@@ -3220,25 +3318,28 @@
 % there will eventually be enough space to accomodate the label, we know
 % that the label won't overlap the bit field or extend beyond the bit-field
 % boundaries.
+% \changes{v2.6}{2020/10/29}{Suppress spaces following the
+%   \protect\cs{end}\protect\texttt{\{leftwordgroup\}}}
+% \changes{v2.6}{2020/10/31}{Accept key/value options}
 %    \begin{macrocode}
-\newenvironment{leftwordgroup}[1]{%
-%    \end{macrocode}
-% We begin by ending the group that |\begin{rightwordgroup}| created.  This
-% lets the |leftwordgroup| environment span rows (because we're technically
-% no longer within the environment).
-%    \begin{macrocode}
-  \endgroup
+\newenvironment{leftwordgroup}[2][]{%
 %    \end{macrocode}
 % \begin{macro}{\wordlabell@start}
+% \begin{macro}{\wordlabell@params}
 % \begin{macro}{\wordlabell@text}
-% We store the starting height and label text, which are needed by the
-% |\end{leftwordgroup}|.
+% We store the starting height, optional parameters (see
+% Section~\ref{sec:options}), and label text, all of which are needed by
+% the |\end{leftwordgroup}|.  We immediately parse the parameters
+% because they may affect the \cs{store@lcurly} invocation below.
 %    \begin{macrocode}
   \global\wordlabell@start=\bytefield@height
-  \gdef\wordlabell@text{#1}%
+  \gdef\wordlabell@params{#1}%
+  \gdef\wordlabell@text{#2}%
+  \bf@bytefieldsetup{#1}%
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}
+% \end{macro}
 % Next, we typeset a draft version of the label into |\word@label@box|,
 % which we measure (into |\total@lbox@width|) and then discard.
 % We can't typeset the final version of the label until we reach the
@@ -3269,7 +3370,14 @@
 %    \begin{macrocode}
   \gdef\make@lspace{%
     \hspace*{\total@lbox@width}%
-    \gdef\make@lspace{}}%
+    \gdef\make@lspace{}%
+  }%
+%    \end{macrocode}
+% We now end the group that |\begin{rightwordgroup}| created.  This lets
+% the |leftwordgroup| environment span rows (because we're technically
+% no longer within the environment).
+%    \begin{macrocode}
+  \endgroup
   \ignorespaces
 }{%
 %    \end{macrocode}
@@ -3288,6 +3396,10 @@
 % that we typeset the entire label in the second column, but in a $0
 % \times 0$ |picture| environment and with a negative horizontal offset
 % (|\starting@point|), thereby making it overlap the first column.
+% Before typesetting the curly brace we re-parse the optional parameters
+% because we're in a new group from the one in which we parsed them
+% before, and the parameters can affect the second \cs{store@lcurly}
+% invocation just they could have affected the first.
 %    \begin{macrocode}
   \global\wordlabell@end=\bytefield@height
   \bf@newdimen\starting@point
@@ -3297,6 +3409,7 @@
     \begin{tabular}[b]{@{}l@{}}\wordlabell@text\end{tabular}}%
   \settowidth{\label@box@width}{\usebox{\word@label@box}}%
   \setlength{\label@box@height}{\wordlabell@end-\wordlabell@start}%
+  \expandafter\bf@bytefieldsetup\expandafter{\wordlabell@params}%
   \store@lcurly{\curly@box}{\label@box@height}%
   \begin{picture}(0,0)
     \put(\strip@pt\starting@point,0){%
@@ -3314,7 +3427,7 @@
 % |\begin|.
 %    \begin{macrocode}
   \def\@currenvir{leftwordgroup}%
-  \ignorespaces
+  \ignorespacesafterend
 }
 %    \end{macrocode}
 % \end{macro}
@@ -3530,6 +3643,8 @@
 %
 % \begin{macro}{\KV@bytefield@leftcurly}
 % \begin{macro}{\KV@bytefield@rightcurly}
+% \begin{macro}{\bf@leftcurly}
+% \begin{macro}{\bf@rightcurly}
 % Specify the symbol to use for bracketing a left or right word group.
 % This must be an extensible math delimiter (i.e.,~something that can
 % immediately follow |\left| or |\right| in math mode).
@@ -3539,10 +3654,14 @@
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}
+% \end{macro}
+% \end{macro}
 %
 % \begin{macro}{\KV@bytefield@leftcurlyspace}
 % \begin{macro}{\KV@bytefield@rightcurlyspace}
 % \begin{macro}{\KV@bytefield@curlyspace}
+% \begin{macro}{\bf@leftcurlyspace}
+% \begin{macro}{\bf@rightcurlyspace}
 % Specify the amount of space between the bit fields in a word group and
 % the adjacent left or right curly brace.  The \optname{curlyspace}
 % option is a shortcut that puts the same space before both left and
@@ -3558,10 +3677,14 @@
 % \end{macro}
 % \end{macro}
 % \end{macro}
+% \end{macro}
+% \end{macro}
 %
 % \begin{macro}{\KV@bytefield@leftlabelspace}
 % \begin{macro}{\KV@bytefield@rightlabelspace}
 % \begin{macro}{\KV@bytefield@labelspace}
+% \begin{macro}{\bf@leftlabelspace}
+% \begin{macro}{\bf@rightlabelspace}
 % Specify the amount of space between a left or right word group's curly
 % brace and the associated label text.  The |labelspace| option is a
 % shortcut that puts the same space after both left and right curly
@@ -3577,10 +3700,14 @@
 % \end{macro}
 % \end{macro}
 % \end{macro}
+% \end{macro}
+% \end{macro}
 %
 % \begin{macro}{\KV@bytefield@leftcurlyshrinkage}
 % \begin{macro}{\KV@bytefield@rightcurlyshrinkage}
 % \begin{macro}{\KV@bytefield@curlyshrinkage}
+% \begin{macro}{\bf@leftcurlyshrinkage}
+% \begin{macro}{\bf@rightcurlyshrinkage}
 % Specify the number of points by which to reduce the height of a curly
 % brace (left, right, or both) so its ends don't overlap whatever's
 % above or below it.
@@ -3595,6 +3722,30 @@
 % \end{macro}
 % \end{macro}
 % \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\KV@bytefield@leftcurlystyle}
+% \begin{macro}{\KV@bytefield@rightcurlystyle}
+% \begin{macro}{\KV@bytefieldcurlystyle}
+% \begin{macro}{\bf@leftcurlystyle}
+% \begin{macro}{\bf@rightcurlystyle}
+% Specify a macro that takes either zero or one argument and that
+% precedes the text that draws a left curly brace, right curly brace, or
+% either curly brace.
+%    \begin{macrocode}
+\define@key{bytefield}{leftcurlystyle}{\def\bf@leftcurlystyle{#1}}
+\define@key{bytefield}{rightcurlystyle}{\def\bf@rightcurlystyle{#1}}
+\define@key{bytefield}{curlystyle}{%
+  \def\bf@leftcurlystyle{#1}%
+  \def\bf@rightcurlystyle{#1}%
+}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
 %
 % \begin{macro}{\KV@bytefield@endianness}
 % \begin{macro}{\bf@parse@endianness}