bytefield (7jun14)

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

2 files changed, 268 insertions, 32 deletions

diff --git a/Master/texmf-dist/source/latex/bytefield/bytefield.dtx b/Master/texmf-dist/source/latex/bytefield/bytefield.dtx
index 22d17e4d4eb..fe5b22e933e 100644
--- a/Master/texmf-dist/source/latex/bytefield/bytefield.dtx
+++ b/Master/texmf-dist/source/latex/bytefield/bytefield.dtx
@@ -1,6 +1,6 @@
 % \iffalse meta-comment
 %
-% Copyright (C) 2011 by Scott Pakin <scott+bf@pakin.org>
+% Copyright (C) 2014 by Scott Pakin <scott+bf@pakin.org>
 % ------------------------------------------------------
 %
 % This file may be distributed and/or modified under the
@@ -22,7 +22,7 @@
 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
 %<package>\ProvidesPackage{bytefield}
 %<*package>
-    [2011/06/19 v2.1 Network protocol diagrams]
+    [2014/06/03 v2.2 Network protocol diagrams]
 %</package>
 %
 %<*driver>
@@ -59,7 +59,7 @@
 %</driver>
 % \fi
 %
-% \CheckSum{917}
+% \CheckSum{1020}
 %
 % \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
@@ -400,11 +400,14 @@
 %
 % 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.  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.
+% 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.
 %
 % The following example shows how to produce a simple 16-bit-wide field:
 %
@@ -437,6 +440,78 @@
 % example of how these lengths may be utilized.
 %
 % \begin{decl}
+%   \SpecialUsageIndex{\bitboxes}
+%   |\bitboxes| \oarg{sides} \marg{width} \marg{tokens} \\
+%   |\bitboxes*| \oarg{sides} \marg{width} \marg{tokens} \\
+% \end{decl}
+%
+% The |\bitboxes| command provides a shortcut for typesetting a sequence
+% of fields of the same width.  It takes essentially the same arguments
+% as |\bitbox| but interpets these differently.  Instead of representing
+% a single piece of text to typeset within a field of width
+% \meta{width}, |\bitboxes|'s \meta{tokens} argument represents a list
+% of tokens (e.g,~individual characters), each of which is typeset
+% within a separate box of width \meta{width}.  Consider, for example,
+% the following sequence of |\bitbox| commands:
+%
+% \begin{verbatim}
+%       \begin{bytefield}{8}
+%         \bitbox{1}{D} & \bitbox{1}{R} & \bitbox{1}{M} & \bitbox{1}{F} &
+%         \bitbox{1}{S} & \bitbox{1}{L} & \bitbox{1}{T} & \bitbox{1}{D}
+%       \end{bytefield}
+% \end{verbatim}
+%
+% \begin{bffigure}
+%       \begin{bytefield}{8}
+%         \bitbox{1}{D} & \bitbox{1}{R} & \bitbox{1}{M} & \bitbox{1}{F} &
+%         \bitbox{1}{S} & \bitbox{1}{L} & \bitbox{1}{T} & \bitbox{1}{D}
+%       \end{bytefield}
+% \end{bffigure}
+%
+% \noindent
+% With |\bitboxes| this can be abbreviated to
+%
+% \begin{verbatim}
+%       \begin{bytefield}{8}
+%         \bitboxes{1}{DRMFSLTD}
+%       \end{bytefield}
+% \end{verbatim}
+%
+% Spaces are ignored within |\bitboxes|'s \meta{text} argument, and
+% curly braces can be used to group multiple characters into a single
+% token:
+%
+% \begin{verbatim}
+%       \begin{bytefield}{24}
+%         \bitboxes{3}{{DO} {RE} {MI} {FA} {SOL} {LA} {TI} {DO}}
+%       \end{bytefield}
+% \end{verbatim}
+%
+% \begin{bffigure}
+%       \begin{bytefield}{24}
+%         \bitboxes{3}{{DO} {RE} {MI} {FA} {SOL} {LA} {TI} {DO}}
+%       \end{bytefield}
+% \end{bffigure}
+%
+% The starred form of |\bitboxes| is identical except that it suppresses
+% all internal vertical lines.  It can therefore be quite convenient for
+% typesetting binary constants:
+%
+% \begin{verbatim}
+%       \begin{bytefield}{16}
+%         \bitboxes*{1}{01000010} & \bitbox{4}{src\strut} &
+%         \bitbox{4}{dest\strut} & \bitbox{4}{const\strut}
+%       \end{bytefield}
+% \end{verbatim}
+%
+% \begin{bffigure}
+%       \begin{bytefield}{16}
+%         \bitboxes*{1}{01000010} & \bitbox{4}{src\strut} &
+%         \bitbox{4}{dest\strut} & \bitbox{4}{const\strut}
+%       \end{bytefield}
+% \end{bffigure}
+%
+% \begin{decl}
 %   \SpecialUsageIndex{\bitheader}
 %   |\bitheader| \oarg{parameters} \marg{bit-positions}
 % \end{decl}
@@ -608,12 +683,12 @@
 %
 % \begin{decl}
 %   \SpecialUsageIndex{\bytefieldsetup}
-%   |\bytefieldsetup| \marg{key=value list}
+%   |\bytefieldsetup| \marg{key-value list}
 % \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} item 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
@@ -1671,7 +1746,7 @@
 %         \bitbox{16}{Data~$N-1$} & \bitbox{16}{Data~$N$} \\
 %         \bitbox{20}{\[ \mbox{A5A5}_{\mbox{\scriptsize H}} \oplus
 %           \left(\sum_{i=1}^N \mbox{Data}_i \right) \bmod 2^{20} \]} &
-%           \bitbox{12}{Command} \\
+%           \bitboxes*{1}{000010 000110} \\
 %         \wordbox{2}{64-bit random number}
 %       \end{bytefield}
 % \end{verbatim}
@@ -1717,7 +1792,7 @@
 %         \bitbox{16}{Data~$N-1$} & \bitbox{16}{Data~$N$} \\
 %         \bitbox{20}{\[ \mbox{A5A5}_{\mbox{\scriptsize H}} \oplus
 %           \left(\sum_{i=1}^N \mbox{Data}_i \right) \bmod 2^{20} \]} &
-%           \bitbox{12}{Command} \\
+%         \bitboxes*{1}{000010 000110} \\
 %         \wordbox{2}{64-bit random number}
 %       \end{bytefield}
 %     \end{lrbox}
@@ -1944,7 +2019,7 @@
 %
 % \begin{macro}{\bytefield@height}
 % \begin{macro}{\ifcounting@words}
-% When |\ifcounting@words| is \textsc{True}, add the height of the next
+% When |\ifcounting@words| is \textsc{true}, add the height of the next
 % \texttt{picture} environment to |\bytefield@height|.  We set
 % |\counting@wordstrue| at the beginning of each word, and
 % |\counting@wordsfalse| after each |\bitbox|, |\wordbox|, or |\skippedwords|
@@ -2094,9 +2169,10 @@
 % \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 lines to draw---|[l]|eft,
-% |[r]|ight, |[t]|op, and/or |[b]|ottom (default: |lrtb|).
+% 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.
 %    \begin{macrocode}
 \DeclareRobustCommand{\bitbox}[3][lrtb]{%
   \setlength{\units@wide}{\bf@bitwidth * #2}%
@@ -2110,7 +2186,9 @@
 % 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|).
+% |[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}%
@@ -2173,16 +2251,16 @@
 %   works just fine.
 %    \begin{macrocode}
     \ifbitbox@top
-      \put(0,#2){\line(1,0){#1}}
+      \put(0,#2){\line(1,0){#1}}%
     \fi
     \ifbitbox@bottom
-      \put(0,0){\line(1,0){#1}}
+      \put(0,0){\line(1,0){#1}}%
     \fi
     \ifbitbox@left
-      \put(0,0){\line(0,1){#2}}
+      \put(0,0){\line(0,1){#2}}%
     \fi
     \ifbitbox@right
-      \put(#1,0){\line(0,1){#2}}
+      \put(#1,0){\line(0,1){#2}}%
     \fi
   \end{picture}%
 %    \end{macrocode}
@@ -2199,17 +2277,157 @@
 %    \end{macrocode}
 % \end{macro}
 %
+% \begin{macro}{\bitboxes}
+% \usermacro
+% \changes{v2.2}{2014/06/01}{Added this macro based on an idea proposed
+%   by Andrew Mertz}
+% \begin{macro}{\bitboxes*}
+% \usermacro
+% Put each token in |#3| into 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.  The |*|-form of the
+% command omits interior left and right lines.
+%    \begin{macrocode}
+\DeclareRobustCommand{\bitboxes}{%
+  \@ifstar\bf@bitboxes@star\bf@bitboxes@no@star
+}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\bf@relax}
+% Define a macro that expands to |\relax| for use with |\ifx| tests
+% against |\bf@bitboxes@arg|, which can contain either tokens to typeset
+% or |\relax|.
+%    \begin{macrocode}
+\def\bf@relax{\relax}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\bf@bitboxes@no@star}
+% Implement the unstarred version of |\bitboxes|.
+%    \begin{macrocode}
+\newcommand{\bf@bitboxes@no@star}[3][lrtb]{%
+%    \end{macrocode}
+% \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{%
+%    \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
+  \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@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
+}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
 % \subsubsection{Parsing arguments}
 %
-% The macros in this section are used to parse the optional argument
-% to |\bitbox| or |\wordbox|, which is some subset of
-% $\{ |l|, |r|, |t|, |b| \}$.
+% The macros in this section are used to parse the optional argument to
+% |\bitbox| or |\wordbox|, which is some subset of $\{ |l|, |r|, |t|,
+% |b|, |L|, |R|, |T|, |B| \}$.  Lowercase letters display the left,
+% right, top, or bottom side of a box; uppercase letters inhibit the
+% display.  The default is not to display any sides, but an uppercase
+% letter can negate the effect of a prior lowercase letter.
 %
 % \begin{macro}{\ifbitbox@top}
 % \begin{macro}{\ifbitbox@bottom}
 % \begin{macro}{\ifbitbox@left}
 % \begin{macro}{\ifbitbox@right}
-% These macros are set to \textsc{True} if we're to draw the
+% These macros are set to \textsc{true} if we're to draw the
 % corresponding edge on the subsequent |\bitbox| or |\wordbox|.
 %    \begin{macrocode}
 \newif\ifbitbox@top
@@ -2237,8 +2455,8 @@
 %
 % \begin{macro}{\bf@parse@bitbox@sides}
 % The helper function for |\bf@parse@bitbox@arg| parses a single letter,
-% sets the appropriate conditional to \textsc{True}, and calls itself
-% tail-recursively until it sees an ``|X|''.
+% sets the appropriate conditional to \textsc{true}, and calls itself
+% tail-recursively until it sees an~``|X|''.
 %    \begin{macrocode}
 \def\bf@parse@bitbox@sides#1{%
   \ifx#1X%
@@ -2254,6 +2472,24 @@
         \else
           \ifx#1r%
             \bitbox@righttrue
+          \else
+            \ifx#1T%
+              \bitbox@topfalse
+            \else
+              \ifx#1B%
+                \bitbox@bottomfalse
+              \else
+                \ifx#1L%
+                  \bitbox@leftfalse
+                \else
+                  \ifx#1R%
+                    \bitbox@rightfalse
+                  \else
+                    \PackageWarning{bytefield}{Unrecognized box side `#1'}%
+                  \fi
+                \fi
+              \fi
+            \fi
           \fi
         \fi
       \fi
@@ -2372,7 +2608,7 @@
 % \begin{macro}{header@val}
 % \begin{macro}{max@header@val}
 % Define some miscellaneous variables to be used internally by
-% |\bf@parse@range|---$x$ position of header, current label to output,
+% |\bf@parse@range|: $x$~position of header, current label to output,
 % and maximum label to output ($+ 1$).
 %    \begin{macrocode}
 \newlength{\header@xpos}
@@ -2982,7 +3218,7 @@
 % \begin{macro}{\wordgroupl}
 % \begin{macro}{\endwordgroupl}
 % Issue a helpful error message for the commands that were removed in
-% \pkgname{bytefield}~v2.0.  While this won't help users who first
+% \pkgname{bytefield}~v2.0.  While this won't help users whose first
 % invalid action is to modify a no-longer-extant length register such as
 % |\bitwidth| or |\byteheight|, it may benefit at least a few users who
 % didn't realize that the \pkgname{bytefield} interface has changed
@@ -3137,7 +3373,7 @@
 %
 % \begin{macro}{\KV@bytefield@endianness}
 % \begin{macro}{\bf@parse@endianness}
-% Set the default endianness to either little-endian or big-endian.
+% Set the default endianness to either little endian or big endian.
 %    \begin{macrocode}
 \define@key{bytefield}{endianness}{\bf@parse@endianness{#1}}
 %    \end{macrocode}
diff --git a/Master/texmf-dist/source/latex/bytefield/bytefield.ins b/Master/texmf-dist/source/latex/bytefield/bytefield.ins
index 9eac6249190..62fd6fbe610 100644
--- a/Master/texmf-dist/source/latex/bytefield/bytefield.ins
+++ b/Master/texmf-dist/source/latex/bytefield/bytefield.ins
@@ -1,5 +1,5 @@
 %%
-%% Copyright (C) 2011 by Scott Pakin <scott+bf@pakin.org>
+%% Copyright (C) 2014 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) 2011 by Scott Pakin <scott+bf@pakin.org>
+Copyright (C) 2014 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