summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/bytefield
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2014-06-20 18:19:57 +0000
committerKarl Berry <karl@freefriends.org>2014-06-20 18:19:57 +0000
commit6c90a4d7ac1f533fbce95fa5cf0bc77c4739c603 (patch)
tree3110a6e06548211a24566823cc6b8ed0d4f097f4 /Master/texmf-dist/source/latex/bytefield
parentf45d5c69a1891adff596350eaf5a16354e0fcd1b (diff)
bytefield (7jun14)
git-svn-id: svn://tug.org/texlive/trunk@34336 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/bytefield')
-rw-r--r--Master/texmf-dist/source/latex/bytefield/bytefield.dtx296
-rw-r--r--Master/texmf-dist/source/latex/bytefield/bytefield.ins4
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