summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2020-10-31 21:05:36 +0000
committerKarl Berry <karl@freefriends.org>2020-10-31 21:05:36 +0000
commitc06466531bdbf8090b8acb6e2252d78d61c95c12 (patch)
tree3c443cfee76c0c7f200ac8c0b40d4b0acc500fbe /Master/texmf-dist/source
parent95c3a6321d3a4aee5ee2fbcb73d11797f4eb630f (diff)
bytefield (31oct20)
git-svn-id: svn://tug.org/texlive/trunk@56821 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source')
-rw-r--r--Master/texmf-dist/source/latex/bytefield/bytefield.dtx243
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}