From f3fbfce65a7de58853550aedf1b6e6acd5c29a1e Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Sun, 1 Nov 2020 03:02:20 +0000 Subject: CTAN sync 202011010302 --- macros/latex/contrib/bytefield/bytefield.dtx | 243 ++++++++++++++++++++++----- macros/latex/contrib/bytefield/bytefield.pdf | Bin 487156 -> 583061 bytes 2 files changed, 197 insertions(+), 46 deletions(-) (limited to 'macros/latex/contrib/bytefield') diff --git a/macros/latex/contrib/bytefield/bytefield.dtx b/macros/latex/contrib/bytefield/bytefield.dtx index 4354a50e78..8af3e52bbf 100644 --- a/macros/latex/contrib/bytefield/bytefield.dtx +++ b/macros/latex/contrib/bytefield/bytefield.dtx @@ -22,7 +22,7 @@ %\NeedsTeXFormat{LaTeX2e}[1999/12/01] %\ProvidesPackage{bytefield} %<*package> - [2020/10/22 v2.5 Network protocol diagrams] + [2020/10/31 v2.6 Network protocol diagrams] % % %<*driver> @@ -68,7 +68,7 @@ % % \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} diff --git a/macros/latex/contrib/bytefield/bytefield.pdf b/macros/latex/contrib/bytefield/bytefield.pdf index 44c093147a..46b2b36d09 100644 Binary files a/macros/latex/contrib/bytefield/bytefield.pdf and b/macros/latex/contrib/bytefield/bytefield.pdf differ -- cgit v1.2.3