From 3d43e658a41ca0b37fc5f2191ec5a8d57642734b Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Sun, 25 Oct 2020 03:01:38 +0000 Subject: CTAN sync 202010250301 --- macros/latex/contrib/bytefield/README | 2 +- macros/latex/contrib/bytefield/bytefield.dtx | 728 +++++++++++++++++---------- macros/latex/contrib/bytefield/bytefield.ins | 4 +- macros/latex/contrib/bytefield/bytefield.pdf | Bin 405723 -> 487156 bytes 4 files changed, 479 insertions(+), 255 deletions(-) (limited to 'macros/latex/contrib/bytefield') 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 -% ------------------------------------------------------ +% Copyright (C) 2000-2020 by Scott Pakin +% ----------------------------------------------------------- % % 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 @@ %\NeedsTeXFormat{LaTeX2e}[1999/12/01] %\ProvidesPackage{bytefield} %<*package> - [2017/09/15 v2.4 Network protocol diagrams] + [2020/10/22 v2.5 Network protocol diagrams] % % %<*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 @@ % % \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 +%% Copyright (C) 2000-2020 by Scott Pakin %% %% 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 +Copyright (C) 2000-2020 by Scott Pakin 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 Binary files a/macros/latex/contrib/bytefield/bytefield.pdf and b/macros/latex/contrib/bytefield/bytefield.pdf differ -- cgit v1.2.3