summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/bytefield
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2020-10-25 03:01:38 +0000
committerNorbert Preining <norbert@preining.info>2020-10-25 03:01:38 +0000
commit3d43e658a41ca0b37fc5f2191ec5a8d57642734b (patch)
treef7e61ccb6d369cc9b2ac234bd06737f3a0e67998 /macros/latex/contrib/bytefield
parent77045ec1b3d5364e7cfdc8e0a2710c5453242972 (diff)
CTAN sync 202010250301
Diffstat (limited to 'macros/latex/contrib/bytefield')
-rw-r--r--macros/latex/contrib/bytefield/README2
-rw-r--r--macros/latex/contrib/bytefield/bytefield.dtx728
-rw-r--r--macros/latex/contrib/bytefield/bytefield.ins4
-rw-r--r--macros/latex/contrib/bytefield/bytefield.pdfbin405723 -> 487156 bytes
4 files changed, 479 insertions, 255 deletions
diff --git a/macros/latex/contrib/bytefield/README b/macros/latex/contrib/bytefield/README
index e1e0d208b9..b76f221d76 100644
--- a/macros/latex/contrib/bytefield/README
+++ b/macros/latex/contrib/bytefield/README
@@ -33,7 +33,7 @@ supports hyperref hyperlinks.
Copyright and license
---------------------
-Copyright (C) 2017 Scott Pakin, scott+bf@pakin.org
+Copyright (C) 2000-2020 Scott Pakin, scott+bf@pakin.org
This package may be distributed and/or modified under the conditions
of the LaTeX Project Public License, either version 1.3a of this
diff --git a/macros/latex/contrib/bytefield/bytefield.dtx b/macros/latex/contrib/bytefield/bytefield.dtx
index deb30c81be..4354a50e78 100644
--- a/macros/latex/contrib/bytefield/bytefield.dtx
+++ b/macros/latex/contrib/bytefield/bytefield.dtx
@@ -1,7 +1,7 @@
% \iffalse meta-comment
%
-% Copyright (C) 2017 by Scott Pakin <scott+bf@pakin.org>
-% ------------------------------------------------------
+% Copyright (C) 2000-2020 by Scott Pakin <scott+bf@pakin.org>
+% -----------------------------------------------------------
%
% This file may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3a
@@ -22,7 +22,7 @@
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{bytefield}
%<*package>
- [2017/09/15 v2.4 Network protocol diagrams]
+ [2020/10/22 v2.5 Network protocol diagrams]
%</package>
%
%<*driver>
@@ -35,6 +35,7 @@
\usepackage{calc}
\usepackage{array}
\usepackage{wasysym}
+\usepackage{needspace}
\usepackage{hyperxmp}
\usepackage{hypdoc}
\usepackage{hyperref}
@@ -45,7 +46,7 @@
pdfauthor={Scott Pakin},
pdfsubject={Protocol diagrams for LaTeX},
pdfkeywords={bits, bytes, bit fields, communication, network protocol diagrams, LaTeX2e, memory maps},
- pdfcopyright={Copyright (C) 2017, Scott Pakin},
+ pdfcopyright={Copyright (C) 2000-2020, Scott Pakin},
pdflicenseurl={http://www.latex-project.org/lppl/},
pdfcaptionwriter={Scott Pakin},
pdfcontactemail={scott+bf@pakin.org},
@@ -67,7 +68,7 @@
%</driver>
% \fi
%
-% \CheckSum{1028}
+% \CheckSum{1161}
%
% \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
@@ -99,6 +100,14 @@
% \cs{endwordgroupl} with a \texttt{leftwordgroup} environment and
% also replacing a slew of user-visible lengths and macros with a
% single \cs{bytefieldsetup} macro}
+% \changes{v2.5}{2020/10/20}{Redefine the \protect\cs{bitbox},
+% \protect\cs{wordbox}, and \protect\cs{bitboxes} commands additionally
+% to accept key/value options}
+% \changes{v2.5}{2020/10/20}{Accept a new \protect\optname{bgcolor}
+% option to set a bit's background color}
+% \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}
%
% \GetFileInfo{bytefield.dtx}
%
@@ -129,7 +138,7 @@
%
% \title{The \textsf{bytefield} package\thanks{This document
% corresponds to \textsf{bytefield}~\fileversion, dated \filedate.}}
-% \author{Scott Pakin \\ \texttt{scott+bf@pakin.org}}
+% \author{Scott Pakin \\ \textit{scott+bf@pakin.org}}
%
% \sloppy
% \maketitle
@@ -271,10 +280,10 @@
% \item ``skipped words'' within fields.
% \end{itemize}
%
-% Because \pkgname{bytefield} draws its figures using only
-% the \LaTeX{} \texttt{picture} environment, these figures are not
-% specific to any particular backend, do not require PostScript support,
-% and do not need support from external programs. Furthermore, unlike an
+% Because \pkgname{bytefield} draws its figures using only the \LaTeX{}
+% \texttt{picture} environment, these figures are not specific to any
+% particular backend, do not require PostScript or PDF support, and do
+% not need support from external programs. Furthermore, unlike an
% imported graphic, \pkgname{bytefield} pictures can include arbitrary
% \LaTeX{} constructs, such as mathematical equations, |\ref|s and
% |\cite|s to the surrounding document, and macro calls.
@@ -372,12 +381,12 @@
% \label{sec:basic-cmds}
%
% This section explains how to use the \pkgname{bytefield} package. It
-% lists all the exported macros and environments in approximately
+% lists all of the exported macros and environments in approximately
% decreasing order of usefulness.
%
% \begin{decl}
% \SpecialEnvIndex{bytefield}
-% |\begin{bytefield}| \oarg{parameters} \marg{bit-width} \\
+% |\begin{bytefield}| \oarg{options} \marg{bit-width} \\
% \meta{fields} \\
% |\end{bytefield}|
% \end{decl}
@@ -385,19 +394,20 @@
% The \pkgname{bytefield} package's top-level environment is called, not
% surprisingly, ``|bytefield|''. It takes one mandatory argument, which
% is the number of bits in each word, and one optional argument, which
-% is a set of parameters, described in Section~\ref{sec:options}, for
-% formatting the bit-field's layout. One can think of a |bytefield| as
-% being analogous to a |tabular|: words are separated by~``|\\|'', and
-% fields within a word are separated by~``|&|''. As in a |tabular|,
-% ``|\\|'' accepts a \meta{length} as an optional argument, and this
-% specifies the amount of additional vertical whitespace to include
-% after the current word is typeset.
+% is a comma-separated list of \meta{key}=\meta{value} pairs, described
+% in Section~\ref{sec:options}, for formatting the bit-field's layout.
+% One can think of a |bytefield| as being analogous to a |tabular|:
+% words are separated by~``|\\|'', and fields within a word are
+% separated by~``|&|''. As in a |tabular|, ``|\\|'' accepts a
+% \meta{length} as an optional argument, and this specifies the amount
+% of additional vertical whitespace to include after the current word is
+% typeset.
%
% \begin{decl}
% \SpecialUsageIndex{\bitbox}
-% |\bitbox| \oarg{sides} \marg{width} \marg{text} \\
+% |\bitbox| \oarg{sides} \marg{width} \oarg{options} \marg{text} \\
% \SpecialUsageIndex{\wordbox}
-% |\wordbox| \oarg{sides} \marg{height} \marg{text}
+% |\wordbox| \oarg{sides} \marg{height} \oarg{options} \marg{text}
% \end{decl}
%
% The two main commands one uses within a \pkgname{bytefield}
@@ -406,16 +416,19 @@
% typesets a field that is an entire word wide and one or more words
% tall.
%
-% The optional argument, \meta{sides}, is a list of letters specifying
-% which sides of the field box to draw---[|l|]eft, [|r|]ight, [|t|]op,
-% and/or [|b|]ottom.\footnote{Uppercase |L|, |R|, |T|, and |B| undo a
-% prior |l|, |r|, |t|, or |b| and may be useful for writing wrapper
-% commands around \texttt{\string\bitbox} and
+% The first, optional, argument, \meta{sides}, is a list of letters
+% specifying which sides of the field box to draw---[|l|]eft, [|r|]ight,
+% [|t|]op, and/or [|b|]ottom.\footnote{Uppercase |L|, |R|, |T|, and |B|
+% undo a prior |l|, |r|, |t|, or |b| and may be useful for writing
+% wrapper commands around \texttt{\string\bitbox} and
% \texttt{\string\wordbox}.} The default is ``|lrtb|'' (i.e.,~all
-% sides are drawn). \meta{text} is the text to include within the
-% |\bitbox| or |\wordbox|. It is typeset horizontally centered within a
-% vertically centered |\parbox|. Hence, words will wrap, and ``|\\|''
-% can be used to break lines manually.
+% sides are drawn). The second, required, argument is the width in bits
+% of a bit box or the height in words of a word box. The third argument
+% is an optional, comma-separated list of \meta{key}=\meta{value} pairs,
+% described in Section~\ref{sec:options}. The fourth, required,
+% argument is the text to typeset within the box. It is typeset
+% horizontally centered within a vertically centered |\parbox|. Hence,
+% words will wrap, and ``|\\|'' can be used to break lines manually.
%
% The following example shows how to produce a simple 16-bit-wide field:
%
@@ -442,6 +455,35 @@
% mandatory argument to the |bytefield| environment);
% \pkgname{bytefield} does not currently check for under- or overruns.
%
+% Here's an example of using the \optname{bgcolor} option to fill each
+% box with a different color:
+%
+% \begin{verbatim}
+% \definecolor{lightcyan}{rgb}{0.84,1,1}
+% \definecolor{lightgreen}{rgb}{0.64,1,0.71}
+% \definecolor{lightred}{rgb}{1,0.7,0.71}
+% \begin{bytefield}[bitheight=\widthof{~Sign~},
+% boxformatting={\centering\small}]{32}
+% \bitheader[endianness=big]{31,23,0} \\
+% \bitbox{1}[bgcolor=lightcyan]{\rotatebox{90}{Sign}} &
+% \bitbox{8}[bgcolor=lightgreen]{Exponent} &
+% \bitbox{23}[bgcolor=lightred]{Mantissa}
+% \end{bytefield}
+% \end{verbatim}
+%
+% \begin{bffigure}
+% \definecolor{lightcyan}{rgb}{0.84,1,1}
+% \definecolor{lightgreen}{rgb}{0.64,1,0.71}
+% \definecolor{lightred}{rgb}{1,0.7,0.71}
+% \begin{bytefield}[bitheight=\widthof{~Sign~},
+% boxformatting={\centering\small}]{32}
+% \bitheader[endianness=big]{31,23,0} \\
+% \bitbox{1}[bgcolor=lightcyan]{\rotatebox{90}{Sign}} &
+% \bitbox{8}[bgcolor=lightgreen]{Exponent} &
+% \bitbox{23}[bgcolor=lightred]{Mantissa}
+% \end{bytefield}
+% \end{bffigure}
+%
% Within a |\bitbox| or |\wordbox|, the \pkgname{bytefield} package
% defines |\height|, |\depth|, |\totalheight|, and |\width| to the
% corresponding dimensions of the box. Section~\ref{sec:tricks} gives an
@@ -449,8 +491,8 @@
%
% \begin{decl}
% \SpecialUsageIndex{\bitboxes}
-% |\bitboxes| \oarg{sides} \marg{width} \marg{tokens} \\
-% |\bitboxes*| \oarg{sides} \marg{width} \marg{tokens} \\
+% |\bitboxes| \oarg{sides} \marg{width} \oarg{options} \marg{tokens} \\
+% |\bitboxes*| \oarg{sides} \marg{width} \oarg{options} \marg{tokens} \\
% \end{decl}
%
% The |\bitboxes| command provides a shortcut for typesetting a sequence
@@ -521,17 +563,17 @@
%
% \begin{decl}
% \SpecialUsageIndex{\bitheader}
-% |\bitheader| \oarg{parameters} \marg{bit-positions}
+% |\bitheader| \oarg{options} \marg{bit-positions}
% \end{decl}
%
% To make the bit field more readable, it helps to label bit positions
% across the top. The |\bitheader| command provides a flexible way to
-% do that. The optional argument is a set of parameters from the set
-% described in Section~\ref{sec:options}. In practice, the only
-% parameters that are meaningful in the context of |\bitheader| are
-% |bitformatting|, |endianness|, and |lsb|. See
-% Section~\ref{sec:options} for descriptions and examples of those
-% parameters.
+% do that. 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, the only parameters that are
+% meaningful in the context of |\bitheader| are |bitformatting|,
+% |endianness|, and |lsb|. See Section~\ref{sec:options} for
+% descriptions and examples of those parameters.
%
% |\bitheader|'s mandatory argument, \meta{bit-positions}, is a
% comma-separated list of bit positions to label. For example,
@@ -691,12 +733,12 @@
%
% \begin{decl}
% \SpecialUsageIndex{\bytefieldsetup}
-% |\bytefieldsetup| \marg{key-value list}
+% |\bytefieldsetup| \marg{options}
% \end{decl}
%
% Alter the formatting of all subsequent bit fields.
% Section~\ref{sec:options} describes the possible values for each
-% \meta{key}=\meta{value} item in the comma-separated list that
+% \meta{key}=\meta{value} pair in the comma-separated list that
% |\bytefieldsetup| accepts as its argument. Note that changes made
% with |\bytefieldsetup| are local to their current scope. Hence, if
% used within an environment (e.g.,~|figure|), |\bytefieldsetup| does
@@ -709,7 +751,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
-% four locations:
+% five locations:
%
% \begin{itemize}
% \item as package options (i.e.,~in the
@@ -726,6 +768,10 @@
% \item as the optional argument to a |\bitheader|, which affects only
% that particular header. (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.)
% \end{itemize}
%
% Unfortunately, \LaTeX\ tends to abort with a ``\texttt{TeX capacity
@@ -893,6 +939,17 @@
% \end{bffigure}
%
% \begin{decl}
+% \optname{bgcolor} = \meta{color}
+% \end{decl}
+%
+% Bit and word boxes are normally left unfilled. The \optname{bgcolor}
+% option fills them with a specified background color. A document will
+% need to include the \pkgname{color}, \pkgname{xcolor}, or similar
+% package to expose color names to \pkgname{bytefield}. The
+% \optname{boxformatting} option described above can be used to set the
+% foreground color.
+%
+% \begin{decl}
% \optname{leftcurly} = \meta{delimiter} \\
% \optname{rightcurly} = \meta{delimiter}
% \end{decl}
@@ -1067,6 +1124,42 @@
% \end{bytefield}
% \end{bffigure}
%
+% \begin{decl}
+% \optname{perword} = \meta{command}
+% \end{decl}
+%
+% Provide a macro that will be invoked once for each word in a word box
+% after the regular content is rendered. The macro will be passed two
+% arguments: the word number (starting from~0) and the total number of
+% words in the word box. Furthermore, the macro will be invoked within
+% a one-word-wide box positioned at the base of the word.
+% \optname{perword} can therefore be used for delineating words within a
+% word box, numbering words, or performing other such annotations. As a
+% simple example, the following code draws a gray line at the bottom of
+% each word in the ``Descriptive text'' word box:
+%
+% \begin{verbatim}
+% \newcommand{\wordline}[2]{\color[rgb]{0.7,0.7,0.7}\hrulefill}
+% \begin{bytefield}[bitwidth=4em]{8}
+% \bitheader[lsb=1,bitformatting=\small]{1-8} \\
+% \wordbox[lrt]{7}[perword=\wordline]{Descriptive text (60 bytes)} \\
+% \bitbox[lrb]{4}{} & \bitbox{4}{subsys data offset} \\
+% \bitbox{4}{subsys data offset} & \bitbox{2}{version} &
+% \bitbox{2}{endian indicator} \\
+% \end{bytefield}
+% \end{verbatim}
+%
+% \begin{bffigure}
+% \newcommand{\wordline}[2]{\color[rgb]{0.7,0.7,0.7}\hrulefill}
+% \begin{bytefield}[bitwidth=4em]{8}
+% \bitheader[lsb=1,bitformatting=\small]{1-8} \\
+% \wordbox[lrt]{7}[perword=\wordline]{Descriptive text (60 bytes)} \\
+% \bitbox[lrb]{4}{} & \bitbox{4}{subsys data offset} \\
+% \bitbox{4}{subsys data offset} & \bitbox{2}{version} &
+% \bitbox{2}{endian indicator} \\
+% \end{bytefield}
+% \end{bffigure}
+%
%
% \subsection{Common tricks}
% \label{sec:tricks}
@@ -1293,40 +1386,16 @@
% \end{bffigure}
%
% \paragraph{Unused bits}
-% Because |\width| and |\height| are defined within bit boxes (also word
-% boxes), we can represent unused bits by filling a |\bitbox| with a
-% rule of size |\width|~$\times$ |\height|:
-%
-% \begin{verbatim}
-% \begin{bytefield}{32}
-% \bitheader{0,4,8,12,16,20,24,28} \\
-% \bitbox{8}{Tag} & \bitbox{8}{Value} &
-% \bitbox{4}{\rule{\width}{\height}} &
-% \bitbox{12}{Mask} \\
-% \wordbox{1}{Key}
-% \end{bytefield}
-% \end{verbatim}
-%
-% \begin{bffigure}
-% \begin{bytefield}{32}
-% \bitheader{0,4,8,12,16,20,24,28} \\
-% \bitbox{8}{Tag} & \bitbox{8}{Value} &
-% \bitbox{4}{\rule{\width}{\height}} &
-% \bitbox{12}{Mask} \\
-% \wordbox{1}{Key}
-% \end{bytefield}
-% \end{bffigure}
-%
-% \noindent
-% The effect is much better when the \pkgname{color} package is used to
-% draw the unused bits in color. (Light gray looks nice.)
+% The \optname{bgcolor} option can be used to represent unused bits by
+% specifying a background fill color---light gray looks nice---and empty
+% text:
%
% \begin{verbatim}
% \definecolor{lightgray}{gray}{0.8}
% \begin{bytefield}{32}
% \bitheader{0,4,8,12,16,20,24,28} \\
% \bitbox{8}{Tag} & \bitbox{8}{Value} &
-% \bitbox{4}{\color{lightgray}\rule{\width}{\height}} &
+% \bitbox{4}[bgcolor=lightgray]{} &
% \bitbox{12}{Mask} \\
% \wordbox{1}{Key}
% \end{bytefield}
@@ -1337,7 +1406,7 @@
% \begin{bytefield}{32}
% \bitheader{0,4,8,12,16,20,24,28} \\
% \bitbox{8}{Tag} & \bitbox{8}{Value} &
-% \bitbox{4}{\color{lightgray}\rule{\width}{\height}} &
+% \bitbox{4}[bgcolor=lightgray]{} &
% \bitbox{12}{Mask} \\
% \wordbox{1}{Key}
% \end{bytefield}
@@ -1459,44 +1528,6 @@
%
% \subsection{Not-so-common tricks}
%
-% \paragraph{Colored fields}
-% A similar approach to that utilized to indicate unused bits can be
-% applied to coloring an individual bit field. The trick is to use the
-% \TeX\ |\rlap| primitive to draw a colored box that overlaps whatever
-% follows it to the right:
-%
-% \begin{verbatim}
-% \newcommand{\colorbitbox}[3]{%
-% \rlap{\bitbox{#2}{\color{#1}\rule{\width}{\height}}}%
-% \bitbox{#2}{#3}}
-% \definecolor{lightcyan}{rgb}{0.84,1,1}
-% \definecolor{lightgreen}{rgb}{0.64,1,0.71}
-% \definecolor{lightred}{rgb}{1,0.7,0.71}
-% \begin{bytefield}[bitheight=\widthof{~Sign~},
-% boxformatting={\centering\small}]{32}
-% \bitheader[endianness=big]{31,23,0} \\
-% \colorbitbox{lightcyan}{1}{\rotatebox{90}{Sign}} &
-% \colorbitbox{lightgreen}{8}{Exponent} &
-% \colorbitbox{lightred}{23}{Mantissa}
-% \end{bytefield}
-% \end{verbatim}
-%
-% \begin{bffigure}
-% \newcommand{\colorbitbox}[3]{^^A
-% \rlap{\bitbox{#2}{\color{#1}\rule{\width}{\height}}}^^A
-% \bitbox{#2}{#3}}^^A
-% \definecolor{lightcyan}{rgb}{0.84,1,1}
-% \definecolor{lightgreen}{rgb}{0.64,1,0.71}
-% \definecolor{lightred}{rgb}{1,0.7,0.71}
-% \begin{bytefield}[bitheight=\widthof{~Sign~},
-% boxformatting={\centering\small}]{32}
-% \bitheader[endianness=big]{31,23,0} \\
-% \colorbitbox{lightcyan}{1}{\rotatebox{90}{Sign}} &
-% \colorbitbox{lightgreen}{8}{Exponent} &
-% \colorbitbox{lightred}{23}{Mantissa}
-% \end{bytefield}
-% \end{bffigure}
-%
% \paragraph{Omitted bit numbers}
% It is occasionally convenient to show a wide bit field in which the
% middle numbers are replaced with an ellipsis. The trick to
@@ -1951,7 +1982,10 @@
%
% \section{Implementation}
%
-% \newcommand{\usermacro}{\marginpar{\vspace*{1ex}{\strut\hspace{18pt}\huge$\star$}\vspace*{-1ex}}}
+% \newcommand{\usermacro}{^^A
+% \Needspace{2\baselineskip}^^A
+% \marginpar{\huge\raisebox{-1.5ex}[0pt][1.5ex]{\strut\hspace{18pt}$\star$}\par}^^A
+% }
%
% This section contains the complete source code for \pkgname{bytefield}.
% Most users will not get much out of it, but it should be of use to
@@ -2057,7 +2091,8 @@
\newlength{\bytefield@height@increment}
\DeclareRobustCommand{\inc@bytefield@height}[1]{%
\setlength{\bytefield@height@increment}{#1}%
- \global\advance\bytefield@height by \bytefield@height@increment}
+ \global\advance\bytefield@height by \bytefield@height@increment
+}
% \end{macrocode}
% \end{macro}
%
@@ -2127,7 +2162,8 @@
}{%
\amp\show@wordlabelr\cr\egroup\egroup
\end{lrbox}%
- \usebox{\entire@bytefield@picture}}
+ \usebox{\entire@bytefield@picture}%
+}
% \end{macrocode}
% \end{environment}
%
@@ -2187,35 +2223,151 @@
% \end{macro}
% \end{macro}
%
+% \begin{macro}{\bf@call@box@cmd}
+% \begin{macro}{\bf@call@box@func}
+% Define any box-drawing macro that accepts the same set of four
+% arguments. It takes as input the name of a macro that is defined with
+% formal parameters |[#1]#2[#3]#4|. \cs{bf@call@box@cmd} then invokes
+% that macro, passing it a set of lines to draw out of the set
+% ``\texttt{lrtbLRTB}''~(|#1|), a number of bits or words~(|#2|), a list
+% of key/value pairs~(|#3|), and arbitrary text to typeset~(|#4|).
+% \begin{macrocode}
+\newcommand*{\bf@call@box@cmd}[1]{%
+ \def\bf@call@box@func{#1}%
+ \bf@call@box@cmd@i
+}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\bf@call@box@cmd@i}
+% \begin{macro}{\bf@call@box@arg@i}
+% \begin{macro}{\bf@call@box@arg@ii}
+% Store the set of lines and the bit/word count and invoke
+% \cs{bf@call@box@cmd@ii}.
+% \begin{macrocode}
+\newcommand*{\bf@call@box@cmd@i}[2][lrtb]{%
+ \def\bf@call@box@arg@i{#1}%
+ \def\bf@call@box@arg@ii{#2}%
+ \bf@call@box@cmd@ii
+}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\bf@call@box@cmd@ii}
+% \begin{macro}{\bf@call@box@arg@iii}
+% \begin{macro}{\bf@call@box@arg@iv}
+% Store the key/value parameters and the text to typeset then invoke the
+% macro originally passed to \cs{bf@call@box@cmd}.
+% \begin{macrocode}
+\newcommand*{\bf@call@box@cmd@ii}[2][]{%
+ \def\bf@call@box@arg@iii{#1}%
+ \def\bf@call@box@arg@iv{#2}%
+ \bf@call@box@func
+}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
% \begin{macro}{\bitbox}
% \usermacro
-% Put some text (|#3|) in a box that's a given number of bits (|#2|)
-% wide and one byte tall. An optional argument (|#1|) specifies which
+% Put some text~(|#4|) in a box that's a given number of bits~(|#2|)
+% wide and one byte tall. An optional argument~(|#1|) specifies which
% lines to draw---|[l]|eft, |[r]|ight, |[t]|op, and/or |[b]|ottom
-% (default: |lrtb|). Uppercase letters suppress drawing the |[L]|eft,
-% |[R]|ight, |[T]|op, and/or |[B]|ottom sides.
+% (default: |lrtb|). Uppercase letters provide the opposite effect:
+% They suppress drawing the |[L]|eft, |[R]|ight, |[T]|op, and/or
+% |[B]|ottom sides. Additional drawing parameters can be provided via
+% another optional argument~(|#3|).
% \begin{macrocode}
-\DeclareRobustCommand{\bitbox}[3][lrtb]{%
- \setlength{\units@wide}{\bf@bitwidth * #2}%
- \bf@parse@bitbox@arg{#1}%
- \draw@bit@picture{\strip@pt\units@wide}{\strip@pt\bf@bitheight}{#3}}
+\DeclareRobustCommand{\bitbox}{\bf@call@box@cmd{\bf@bitbox}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\bf@bitbox}
+% Implement all of the \cs{bitbox} logic.
+% \begin{macrocode}
+\def\bf@bitbox{%
+ \bgroup
+ \expandafter\bf@parse@bitbox@arg\expandafter{\bf@call@box@arg@i}%
+ \setlength{\units@wide}{\bf@bitwidth * \bf@call@box@arg@ii}%
+ \expandafter\bf@bytefieldsetup\expandafter{\bf@call@box@arg@iii}%
+ \@ifundefined{bf@bgcolor}{%
+ }{%
+% \end{macrocode}
+% If \optname{bgcolor} was specified, draw a colored rule of the full
+% size of the box.
+% \begin{macrocode}
+ \rlap{%
+ \draw@bit@picture{\strip@pt\units@wide}{\strip@pt\bf@bitheight}{%
+ \color{\bf@bgcolor}%
+ \rule{\width}{\height}%
+ }%
+ }%
+ }%
+% \end{macrocode}
+% Draw the user-provided text on top of the rule (if any).
+% \begin{macrocode}
+ \draw@bit@picture{\strip@pt\units@wide}{\strip@pt\bf@bitheight}{%
+ \bf@call@box@arg@iv
+ }%
+ \egroup
+ \ignorespaces
+}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\wordbox}
% \usermacro
-% Put some text (|#3|) in a box that's a given number of bytes (|#2|)
-% tall and one word (|\bits@wide| bits) wide.
-% An optional argument (|#1|) specifies which lines to draw---|[l]|eft,
-% |[r]|ight, |[t]|op, and/or |[b]|ottom (default: |lrtb|). Uppercase
-% letters suppress drawing the |[L]|eft, |[R]|ight, |[T]|op, and/or
-% |[B]|ottom sides.
-% \begin{macrocode}
-\DeclareRobustCommand{\wordbox}[3][lrtb]{%
- \setlength{\units@wide}{\bf@bitwidth * \bits@wide}%
- \setlength{\units@tall}{\bf@bitheight * #2}%
- \bf@parse@bitbox@arg{#1}%
- \draw@bit@picture{\strip@pt\units@wide}{\strip@pt\units@tall}{#3}}
+% Put some text~(|#4|) in a box that's a given number of bytes~(|#2|)
+% tall and one word (|\bits@wide| bits) wide. An optional
+% argument~(|#1|) specifies which lines to draw---|[l]|eft, |[r]|ight,
+% |[t]|op, and/or |[b]|ottom (default: |lrtb|). Uppercase letters
+% provide the opposite effect: They suppress drawing the |[L]|eft,
+% |[R]|ight, |[T]|op, and/or |[B]|ottom sides. Additional drawing
+% parameters can be provided via another optional argument~(|#3|).
+% \begin{macrocode}
+\DeclareRobustCommand{\wordbox}{\bf@call@box@cmd{\bf@wordbox}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\bf@wordbox}
+% Implement all of the \cs{wordbox} logic.
+% \begin{macrocode}
+\def\bf@wordbox{%
+ \bgroup
+ \expandafter\bf@parse@bitbox@arg\expandafter{\bf@call@box@arg@i}%
+ \setlength{\units@wide}{\bf@bitwidth * \bits@wide}%
+ \setlength{\units@tall}{\bf@bitheight * \bf@call@box@arg@ii}%
+ \expandafter\bf@bytefieldsetup\expandafter{\bf@call@box@arg@iii}%
+ \@ifundefined{bf@bgcolor}{%
+ }{%
+% \end{macrocode}
+% If \optname{bgcolor} was specified, draw a colored rule of the full
+% size of the box.
+% \begin{macrocode}
+ \rlap{%
+ \draw@bit@picture{\strip@pt\units@wide}{\strip@pt\units@tall}{%
+ \color{\bf@bgcolor}%
+ \rule{\width}{\height}%
+ }%
+ }%
+ }%
+% \end{macrocode}
+% Draw the user-provided text on top of the rule (if any).
+% \begin{macrocode}
+ \draw@bit@picture{\strip@pt\units@wide}{\strip@pt\units@tall}{%
+ \bf@call@box@arg@iv
+ }%
+% \end{macrocode}
+% Invoke the user-provided \cs{bf@per@word} macro once per word.
+% \begin{macrocode}
+ \@ifundefined{bf@per@word}{}{\bf@invoke@per@word{\bf@call@box@arg@ii}}%
+ \egroup
+ \ignorespaces
+}
% \end{macrocode}
% \end{macro}
%
@@ -2233,40 +2385,13 @@
\DeclareRobustCommand{\draw@bit@picture}[3]{%
\begin{picture}(#1,#2)%
% \end{macrocode}
-% \begin{macro}{\height}
-% \usermacro
-% \begin{macro}{\depth}
-% \usermacro
-% \begin{macro}{\totalheight}
-% \usermacro
-% \begin{macro}{\width}
-% \usermacro
-% \begin{macro}{\widthunits}
-% \usermacro
-% \begin{macro}{\heightunits}
-% \usermacro
% First, we plot the user's text, with all sorts of useful lengths
% predefined.
% \begin{macrocode}
\put(0,0){\makebox(#1,#2){\parbox{#1\unitlength}{%
- \bf@newdimen\height
- \bf@newdimen\depth
- \bf@newdimen\totalheight
- \bf@newdimen\width
- \height=#2\unitlength
- \depth=0pt%
- \totalheight=#2\unitlength
- \width=#1\unitlength
- \def\widthunits{#1}%
- \def\heightunits{#2}%
+ \bf@set@user@dimens{#1}{#2}%
\bf@boxformatting{#3\par}}}}%
% \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
% Next, we draw each line individually. I suppose we could make a special
% case for ``all lines'' and use a |\framebox| above, but the following
% works just fine.
@@ -2294,10 +2419,78 @@
\inc@bytefield@height{\unitlength * \real{#2}}%
\global\counting@wordsfalse
\fi
- \ignorespaces}
+}
% \end{macrocode}
% \end{macro}
%
+% \begin{macro}{\bf@invoke@per@word}
+% Invoke \cs{bf@per@word} once per word, passing it the (0-indexed) word
+% number and total number of words.
+% \begin{macrocode}
+\newcommand{\bf@invoke@per@word}[1]{%
+ \begin{picture}(0,0)%
+ \@tempcnta=0
+ \@tempdima=#1\bf@bitheight
+% \end{macrocode}
+% Make various useful dimensions available to \cs{bf@per@word}.
+% \begin{macrocode}
+ \bf@set@user@dimens{\strip@pt\units@wide}{\strip@pt\units@tall}%
+ \loop
+ \advance\@tempdima by -\bf@bitheight
+ \bgroup
+ \put(-\strip@pt\units@wide, \strip@pt\@tempdima){%
+ \expandafter\bf@per@word\expandafter{\the\@tempcnta}{#1}%
+ }%
+ \egroup
+ \advance\@tempcnta by 1\relax
+ \ifnum#1>\@tempcnta
+ \repeat
+ \end{picture}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\bf@set@user@dimens}
+% \mbox{}\vspace*{-1ex}
+% \begin{macro}{\width}
+% \usermacro
+% \begin{macro}{\height}
+% \usermacro
+% \begin{macro}{\depth}
+% \usermacro
+% \begin{macro}{\totalheight}
+% \usermacro
+% \begin{macro}{\widthunits}
+% \usermacro
+% \begin{macro}{\heightunits}
+% \usermacro
+% Given a width in bits~(|#1|) and a height in words~(|#2|), make a
+% number of box dimensions available to the author: \cs{width},
+% \cs{height}, \cs{depth}, \cs{totalheight}. Additionally, make the
+% arguments available to the author via the \cs{widthunits} and
+% \cs{heightunits} macros.
+% \begin{macrocode}
+\newcommand{\bf@set@user@dimens}[2]{%
+ \bf@newdimen\width
+ \bf@newdimen\height
+ \bf@newdimen\depth
+ \bf@newdimen\totalheight
+ \width=#1\unitlength
+ \height=#2\unitlength
+ \depth=0pt%
+ \totalheight=#2\unitlength
+ \def\widthunits{#1}%
+ \def\heightunits{#2}%
+}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
% \begin{macro}{\bitboxes}
% \usermacro
% \changes{v2.2}{2014/06/01}{Added this macro based on an idea proposed
@@ -2312,7 +2505,9 @@
% command omits interior left and right lines.
% \begin{macrocode}
\DeclareRobustCommand{\bitboxes}{%
- \@ifstar\bf@bitboxes@star\bf@bitboxes@no@star
+ \@ifstar
+ {\bf@call@box@cmd{\bf@bitboxes@star}}%
+ {\bf@call@box@cmd{\bf@bitboxes@no@star}}%
}
% \end{macrocode}
% \end{macro}
@@ -2328,112 +2523,114 @@
% \end{macro}
%
% \begin{macro}{\bf@bitboxes@no@star}
-% Implement the unstarred version of |\bitboxes|.
+% Implement the unstarred version of \cs{bitboxes}. This macro simply
+% expands its text argument into a list of tokens followed by \cs{relax}
+% then invokes \cs{bf@bitboxes@no@star@i}.
% \begin{macrocode}
-\newcommand{\bf@bitboxes@no@star}[3][lrtb]{%
+\def\bf@bitboxes@no@star{%
+ \expandafter\bf@bitboxes@no@star@i\bf@call@box@arg@iv\relax
+ \ignorespaces
+}
% \end{macrocode}
+% \end{macro}
+%
% \begin{macro}{\bf@bitboxes@no@star@i}
-% Define a helper macro that walks the final argument of
-% |\bf@bitboxes@no@star| token-by-token.
-% \begin{macrocode}
- \def\bf@bitboxes@no@star@i##1{%
+% Walk the subsequent tokens one-by-one until \cs{relax} is encountered.
+% For each token, invoke \cs{bf@bitbox} (the internal version of
+% \cs{bitbox} for which \cs{bf@call@box@arg@}\meta{number} are all
+% defined.
+% \begin{macrocode}
+\def\bf@bitboxes@no@star@i#1{%
+ \def\bf@call@box@arg@iv{#1}%
+ \ifx\bf@call@box@arg@iv\bf@relax
+ \let\next=\relax
+ \else
+ \bf@bitbox
+ \let\next=\bf@bitboxes@no@star@i
+ \fi
+ \next
+}
% \end{macrocode}
-% \begin{macro}{\bf@bitboxes@arg}
-% \begin{macro}{\next}
-% Store the current argument token in |\bf@bitboxes@arg| for use with |\ifx|.
-% \begin{macrocode}
- \def\bf@bitboxes@arg{##1}%
- \ifx\bf@bitboxes@arg\bf@relax
- \let\next=\relax
- \else
- \bitbox[#1]{#2}{##1}%
- \let\next=\bf@bitboxes@no@star@i
- \fi
- \next
- }%
- \bf@bitboxes@no@star@i#3\relax
+% \end{macro}
+%
+% \begin{macro}{\bf@bitboxes@star}
+% \begin{macro}{\bf@bitboxes@sides}
+% Implement the starred version of \cs{bitboxes}. This macro simply
+% stores the original \meta{sides} argument in \cs{bf@bitboxes@sides},
+% expands its text argument into a list of tokens followed by two
+% \cs{relax}es, and invokes \cs{bf@bitboxes@star@i}.
+% \begin{macrocode}
+\def\bf@bitboxes@star{%
+ \edef\bf@bitboxes@sides{\bf@call@box@arg@i}%
+ \expandafter\bf@bitboxes@star@i\bf@call@box@arg@iv\relax\relax
\ignorespaces
}
% \end{macrocode}
% \end{macro}
% \end{macro}
-% \end{macro}
-% \end{macro}
%
-% \begin{macro}{\bf@bitboxes@star}
-% Implement the starred version of |\bitboxes|.
-% \begin{macrocode}
-\newcommand{\bf@bitboxes@star}[3][lrtb]{%
-% \end{macrocode}
% \begin{macro}{\bf@bitboxes@star@i}
-% If the argument to |\bitboxes*| contains a single (or no) token,
-% simply pass control to |\bitbox| and stop. Otherwise, suppress the
-% box's right border by appending ``|R|'' to |\bitboxes*|'s
-% argument~|#1| and proceeding with the remaining tokens in~|#3|.
-% \begin{macrocode}
- \def\bf@bitboxes@star@i##1##2{%
-% \end{macrocode}
-% \begin{macro}{\bf@bitboxes@arg}
-% \begin{macro}{\next}
-% Store the current argument token in |\bf@bitboxes@arg| for use with |\ifx|.
-% \begin{macrocode}
- \def\bf@bitboxes@arg{##2}%
- \ifx\bf@bitboxes@arg\bf@relax
- \bitbox[#1]{#2}{##1}%
- \let\next=\relax
- \else
- \bitbox[#1R]{#2}{##1}%
- \def\next{\bf@bitboxes@star@ii{##2}}%
- \fi
- \next
- }%
-% \end{macrocode}
-% \begin{macro}{\bf@bitboxes@star@ii}
-% Process all tokens in |\bitboxes*|'s argument |#3| following the first
-% argument. For each token, produce a box with the left side suppressed
-% using~``|L|''.
-% \begin{macrocode}
- \def\bf@bitboxes@star@ii##1##2{%
-% \end{macrocode}
-% \begin{macro}{\bf@bitboxes@arg@i}
+% \begin{macro}{\bf@call@box@arg@iv}
% \begin{macro}{\bf@bitboxes@arg@ii}
-% \begin{macro}{\bf@bitboxes@sides}
% \begin{macro}{\next}
-% Store the next two argument tokens in |\bf@bitboxes@arg@i| and
-% |\bf@bitboxes@arg@i| for use with |\ifx|. We use those to set
-% |\bf@bitboxes@sides| to |\bitbox*|'s argument~|#1| with the left side
-% and, for the final token, the right side suppressed.
-% \begin{macrocode}
- \def\bf@bitboxes@arg@i{##1}%
- \def\bf@bitboxes@arg@ii{##2}%
- \ifx\bf@bitboxes@arg@ii\bf@relax
- \def\bf@bitboxes@sides{#1L}%
- \else
- \def\bf@bitboxes@sides{#1LR}%
- \fi
- \ifx\bf@bitboxes@arg@i\bf@relax
- \let\next=\relax
- \else
- \expandafter\bitbox\expandafter[\bf@bitboxes@sides]{#2}{##1}%
- \def\next{\bf@bitboxes@star@ii{##2}}%
- \fi
- \next
- }%
-% \end{macrocode}
-% \begin{macrocode}
- \bf@bitboxes@star@i#3\relax\relax
- \ignorespaces
+% Process the first token in the text argument passed to \cs{bitboxes*}.
+% If it's also the last token (indicated by its being followed by
+% \cs{relax}), draw an ordinary bit box with all sides present. If it's
+% not the last token, draw a bit box with the right side suppressed and
+% invoke \cs{bf@bitboxes@star@ii} on the remaining tokens.
+% \begin{macrocode}
+\def\bf@bitboxes@star@i#1#2{%
+ \def\bf@call@box@arg@iv{#1}%
+ \def\bf@bitboxes@arg@ii{#2}%
+ \ifx\bf@bitboxes@arg@ii\bf@relax
+ \bf@bitbox
+ \let\next=\relax
+ \else
+ \edef\bf@call@box@arg@i{\bf@bitboxes@sides R}%
+ \bf@bitbox
+ \def\next{\bf@bitboxes@star@ii{#2}}%
+ \fi
+ \next
}
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
+%
+% \begin{macro}{\bf@bitboxes@star@ii}
+% \begin{macro}{\bf@call@box@arg@iv}
+% \begin{macro}{\bf@bitboxes@arg@ii}
+% \begin{macro}{\next}
+% Process the second and subsequent tokens in the text argument passed
+% to \cs{bitboxes*}. If the next token in the stream is the final one
+% (indicated by its being followed by \cs{relax}), draw a bit box with
+% the left side suppressed. If it's not the final token, draw a bit box
+% with both the left and right sides suppressed and invoke itself
+% recursively on the remaining tokens.
+% \begin{macrocode}
+\def\bf@bitboxes@star@ii#1#2{%
+ \def\bf@call@box@arg@iv{#1}%
+ \def\bf@bitboxes@arg@ii{#2}%
+ \ifx\bf@bitboxes@arg@ii\bf@relax
+ \edef\bf@call@box@arg@i{\bf@bitboxes@sides L}%
+ \else
+ \edef\bf@call@box@arg@i{\bf@bitboxes@sides LR}%
+ \fi
+ \ifx\bf@call@box@arg@iv\bf@relax
+ \let\next=\relax
+ \else
+ \bf@bitbox
+ \def\next{\bf@bitboxes@star@ii{#2}}%
+ \fi
+ \next
+}
+% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
-% \end{macro}
+%
%
% \subsubsection{Parsing arguments}
%
@@ -2470,7 +2667,8 @@
\bitbox@bottomfalse
\bitbox@leftfalse
\bitbox@rightfalse
- \bf@parse@bitbox@sides#1X}
+ \bf@parse@bitbox@sides#1X%
+}
% \end{macrocode}
% \end{macro}
%
@@ -2516,7 +2714,8 @@
\fi
\fi
\expandafter\bf@parse@bitbox@sides
- \fi}
+ \fi
+}
% \end{macrocode}
% \end{macro}
%
@@ -2552,7 +2751,8 @@
\ifcounting@words
\inc@bytefield@height{\unitlength * \real{\num@tall}}%
\global\counting@wordsfalse
- \fi}
+ \fi
+}
% \end{macrocode}
% \end{macro}
%
@@ -2604,7 +2804,8 @@
\inc@bytefield@height{\unitlength * \real{\strip@pt\units@tall}}%
\global\counting@wordsfalse
\fi
- \ignorespaces}
+ \ignorespaces
+}
% \end{macrocode}
% \end{macro}
%
@@ -2621,7 +2822,8 @@
\else
\bf@parse@range#1-#1-#1\relax
\expandafter\bf@parse@range@list
- \fi}
+ \fi
+}
% \end{macrocode}
% \end{macro}
%
@@ -2664,7 +2866,8 @@
\makebox(\strip@pt\bf@bitwidth,\strip@pt\units@tall){%
\bf@bitformatting{\theheader@val}}}
\addtocounter{header@val}{1}
- \repeat}
+ \repeat
+}
% \end{macrocode}
% \end{macro}
%
@@ -3111,7 +3314,8 @@
% |\begin|.
% \begin{macrocode}
\def\@currenvir{leftwordgroup}%
- \ignorespaces}
+ \ignorespaces
+}
% \end{macrocode}
% \end{macro}
% \end{environment}
@@ -3430,6 +3634,26 @@
% \end{macrocode}
% \end{macro}
%
+% \begin{macro}{\bf@bgcolor}
+% \begin{macro}{\KV@bytefield@bgcolor}
+% Specify a background color for a bit box or word box.
+% \begin{macrocode}
+\define@key{bytefield}{bgcolor}{\def\bf@bgcolor{#1}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\bf@per@word}
+% \begin{macro}{\KV@bytefield@per@word}
+% Specify a macro to invoke for each word of a word box. The macro must
+% take two arguments: the word number (0-indexed) and the total number
+% of words.
+% \begin{macrocode}
+\define@key{bytefield}{perword}{\def\bf@per@word{#1}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
% \begin{macro}{\bytefieldsetup}
% \usermacro
% \changes{v2.0}{2011/01/18}{Introduced this macro to provide a more
diff --git a/macros/latex/contrib/bytefield/bytefield.ins b/macros/latex/contrib/bytefield/bytefield.ins
index 37197a9ab0..d00c642405 100644
--- a/macros/latex/contrib/bytefield/bytefield.ins
+++ b/macros/latex/contrib/bytefield/bytefield.ins
@@ -1,5 +1,5 @@
%%
-%% Copyright (C) 2017 by Scott Pakin <scott+bf@pakin.org>
+%% Copyright (C) 2000-2020 by Scott Pakin <scott+bf@pakin.org>
%%
%% This file may be distributed and/or modified under the conditions of
%% the LaTeX Project Public License, either version 1.3a of this license
@@ -21,7 +21,7 @@
This is a generated file.
-Copyright (C) 2017 by Scott Pakin <scott+bf@pakin.org>
+Copyright (C) 2000-2020 by Scott Pakin <scott+bf@pakin.org>
This file may be distributed and/or modified under the conditions of
the LaTeX Project Public License, either version 1.3a of this license
diff --git a/macros/latex/contrib/bytefield/bytefield.pdf b/macros/latex/contrib/bytefield/bytefield.pdf
index 3436fa27fa..44c093147a 100644
--- a/macros/latex/contrib/bytefield/bytefield.pdf
+++ b/macros/latex/contrib/bytefield/bytefield.pdf
Binary files differ