From 6c90a4d7ac1f533fbce95fa5cf0bc77c4739c603 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Fri, 20 Jun 2014 18:19:57 +0000 Subject: bytefield (7jun14) git-svn-id: svn://tug.org/texlive/trunk@34336 c570f23f-e606-0410-a88d-b1316a301751 --- .../source/latex/bytefield/bytefield.dtx | 296 ++++++++++++++++++--- .../source/latex/bytefield/bytefield.ins | 4 +- 2 files changed, 268 insertions(+), 32 deletions(-) (limited to 'Master/texmf-dist/source/latex') 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 +% Copyright (C) 2014 by Scott Pakin % ------------------------------------------------------ % % This file may be distributed and/or modified under the @@ -22,7 +22,7 @@ %\NeedsTeXFormat{LaTeX2e}[1999/12/01] %\ProvidesPackage{bytefield} %<*package> - [2011/06/19 v2.1 Network protocol diagrams] + [2014/06/03 v2.2 Network protocol diagrams] % % %<*driver> @@ -59,7 +59,7 @@ % % \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 +%% Copyright (C) 2014 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) 2011 by Scott Pakin +Copyright (C) 2014 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 -- cgit v1.2.3