Debian Codegraph @

texmf-dist/source/latex/bytefield/bytefield.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2000-2025 by Scott Pakin <[email protected]>
4 % -----------------------------------------------------------
5 %
6 % This file may be distributed and/or modified under the
7 % conditions of the LaTeX Project Public License, either version 1.3a
8 % of this license or (at your option) any later version.
9 % The latest version of this license is in:
10 %
11 % http://www.latex-project.org/lppl.txt
12 %
13 % and version 1.3c or later is part of all distributions of LaTeX
14 % version 2006/05/20 or later.
15 %
16 % \fi
17 %
18 % \iffalse
19 %<*driver>
20 \ProvidesFile{bytefield.dtx}
21 %</driver>
22 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
23 %<package>\ProvidesPackage{bytefield}
24 %<*package>
25 [2025/01/25 v2.9 Network protocol diagrams]
26 %</package>
27 %
28 %<*driver>
29 \documentclass{ltxdoc}
30 \usepackage{textcomp}
31 \usepackage{bytefield}
32 \usepackage{color}
33 \usepackage{rotating}
34 \usepackage{multirow}
35 \usepackage{calc}
36 \usepackage{array}
37 \usepackage{wasysym}
38 \usepackage{needspace}
39 \usepackage{hypdoc}
40 \usepackage{hyperref}
41 \usepackage[figure]{hypcap}
42 \usepackage{hyperxmp}
43
44 \hypersetup{%
45 pdftitle={The bytefield package},
46 pdfauthor={Scott Pakin},
47 pdfsubject={Protocol diagrams for LaTeX},
48 pdfkeywords={bits, bytes, bit fields, communication, network protocol diagrams, LaTeX2e, memory maps},
49 pdfcopyright={Copyright (C) 2000-2025, Scott Pakin},
50 pdflicenseurl={http://www.latex-project.org/lppl/},
51 pdfcaptionwriter={Scott Pakin},
52 pdfcontactemail={[email protected]},
53 pdfcontacturl={http://www.pakin.org/\xmptilde scott/},
54 pdflang={en-US},
55 baseurl={http://mirrors.ctan.org/macros/latex/contrib/bytefield/bytefield.pdf},
56 pdfstartview=Fit,
57 colorlinks=false,
58 bookmarksopen=true}
59 \EnableCrossrefs
60 \CodelineIndex
61 \RecordChanges
62 \setcounter{IndexColumns}{2}
63 \begin{document}
64 \DocInput{bytefield.dtx}
65 \PrintChanges
66 \PrintIndex
67 \end{document}
68 %</driver>
69 % \fi
70 %
71 % \CheckSum{1205}
72 %
73 % \CharacterTable
74 % {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
75 % Lower-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
76 % Digits \0\1\2\3\4\5\6\7\8\9
77 % Exclamation \! Double quote \" Hash (number) \#
78 % Dollar \$ Percent \% Ampersand \&
79 % Acute accent \' Left paren \( Right paren \)
80 % Asterisk \* Plus \+ Comma \,
81 % Minus \- Point \. Solidus \/
82 % Colon \: Semicolon \; Less than \<
83 % Equals \= Greater than \> Question mark \?
84 % Commercial at \@ Left bracket \[ Backslash \\
85 % Right bracket \] Circumflex \^ Underscore \_
86 % Grave accent \` Left brace \{ Vertical bar \|
87 % Right brace \} Tilde \~}
88 %
89 %
90 % \changes{v1.0}{2000/07/02}{Initial version}
91 % \changes{v1.1}{2002/09/14}{Restructured the \texttt{.dtx} file}
92 % \changes{v1.4}{2011/01/09}{Made assignments to \cs{counting@words}
93 % global to prevent vertical-spacing problems with back-to-back word
94 % groups (bug fix due to Steven R. King)}
95 % \changes{v1.4}{2011/01/16}{Split \cs{curlyspace}, \cs{labelspace}, and
96 % \cs{curlyshrinkage} into \texttt{left} and \texttt{right} versions}
97 % \changes{v2.0}{2011/01/18}{Made a number of non-backwards-compatible
98 % changes, including replacing \cs{wordgroupr} and \cs{endwordgroupr}
99 % with a \texttt{rightwordgroup} environment and \cs{wordgroupl} and
100 % \cs{endwordgroupl} with a \texttt{leftwordgroup} environment and
101 % also replacing a slew of user-visible lengths and macros with a
102 % single \cs{bytefieldsetup} macro}
103 % \changes{v2.5}{2020/10/20}{Redefine the \protect\cs{bitbox},
104 % \protect\cs{wordbox}, and \protect\cs{bitboxes} commands additionally
105 % to accept key/value options}
106 % \changes{v2.5}{2020/10/20}{Accept a new \protect\optname{bgcolor}
107 % option to set a bit's background color}
108 % \changes{v2.5}{2020/10/22}{Accept a new \protect\optname{perword}
109 % option to execute a macro for each word in a word box. This addresses
110 % a feature request by Victor Toni}
111 % \changes{v2.6}{2020/10/29}{Accept new \protect\optname{curlystyle},
112 % \protect\optname{leftcurlystyle}, and
113 % \protect\optname{rightcurlystyle} options to control the styling
114 % (e.g.,~color) of curly braces. This addresses a feature request by
115 % Victor Toni}
116 % \changes{v2.8}{2023/09/24}{Corrected the documentation. Thanks to {\"O}mer
117 % Faruk Birg{\"u}l for pointing out an error in one of the examples}
118 %
119 % \GetFileInfo{bytefield.dtx}
120 %
121 % \DoNotIndex{\&,\@ifstar,\@ifundefined,\@tempcnta,\@tempdima}
122 % \DoNotIndex{\DeclareRobustCommand,\MessageBreak,\\,\addtocounter,\advance}
123 % \DoNotIndex{\begin,\begingroup,\bgroup,\catcode,\ch@ck,\count,\cr,\csname}
124 % \DoNotIndex{\def,\dimen,\dimendef,\edef,\egroup,\else,\end,\endcsname}
125 % \DoNotIndex{\endgroup,\expandafter,\fi,\gdef,\global,\hspace,\if,\ifnum}
126 % \DoNotIndex{\ifx,\ignorespaces,\insc@unt,\left,\let,\loop,\newbox}
127 % \DoNotIndex{\newcommand,\newcounter,\newenvironment,\newif,\newlength}
128 % \DoNotIndex{\newsavebox,\next,\noexpand,\par,\protect,\raisebox,\ratio}
129 % \DoNotIndex{\real,\relax,\renewcommand,\renewenvironment,\repeat,\right}
130 % \DoNotIndex{\sbox,\setcounter,\setlength,\settowidth,\space,\string}
131 % \DoNotIndex{\strip@pt,\the,\unskip,\usebox,\usepackage,\value,\vbox}
132 % \DoNotIndex{\vspace,\wlog,\xdef,\{,\},\\}
133 %
134 %
135 % \title{The \textsf{bytefield} package\thanks{This document
136 % corresponds to \textsf{bytefield}~\fileversion, dated \filedate.}}
137 % \author{Scott Pakin \\ \textit{[email protected]}}
138 %
139 % \sloppy
140 % \maketitle
141 %
142 % ^^A Define an environment for command/environment delcarations.
143 % \newsavebox{\declbox}
144 % \newenvironment{decl}{^^A
145 % \begin{lrbox}{\declbox}\begin{tabular}{l}}{^^A
146 % \end{tabular}\end{lrbox}^^A
147 % \vspace{3ex}\noindent\hspace*{-3em}\fbox{\usebox{\declbox}}\vspace*{2ex}}
148 %
149 % ^^A Define an ellipsis that permits a subsequent line break.
150 % \newcommand{\ellipsis}{$\ldots$\linebreak[0]}
151 %
152 % ^^A Define an environment for showing sample bytefield diagrams.
153 % \newenvironment{bffigure}{%
154 % \bigskip
155 % \noindent\hspace*{3em}%
156 % }{%
157 % \bigskip
158 % }
159 %
160 % ^^A Define something like \cs to use within \StopEventually.
161 % \DeclareRobustCommand{\cseq}[1]{\texttt{\string#1}}
162 %
163 % ^^A Index a package. This code was adapted from \SpecialEnvIndex.
164 % \makeatletter
165 % \def\SpecialPkgIndex#1{^^A
166 % \@bsphack
167 % \index{#1\actualchar{\protect\sffamily#1} (package)\encapchar usage}^^A
168 % \index{packages:\levelchar#1\actualchar{\protect\sffamily#1}^^A
169 % \encapchar usage}^^A
170 % \@esphack
171 % }
172 %
173 % ^^A The following was adapted from hypdoc's redefinition of \SpecialEnvIndex.
174 % \expandafter\ifx\csname c@HD@hypercount\endcsname\relax
175 % \else
176 % \let\HDorg@SpecialPkgIndex\SpecialPkgIndex
177 % \renewcommand*\SpecialPkgIndex[1]{^^A
178 % \@bsphack
179 % \begingroup
180 % \HD@target
181 % \let\HDorg@encapchar\encapchar
182 % \edef\encapchar usage{^^A
183 % \HDorg@encapchar hdpindex{usage}^^A
184 % }^^A
185 % \HDorg@SpecialPkgIndex{#1}^^A
186 % \endgroup
187 % \@esphack
188 % }
189 % \fi
190 % \makeatother
191 %
192 % ^^A Define a logical style for package names.
193 % \DeclareRobustCommand{\pkgname}[1]{^^A
194 % \textsf{#1}^^A
195 % \SpecialPkgIndex{#1}^^A
196 % }
197 %
198 %
199 % ^^A Index an option. This code was adapted from \SpecialEnvIndex.
200 % \makeatletter
201 % \def\SpecialOptionIndex#1{^^A
202 % \@bsphack
203 % \index{#1\actualchar{\protect\sffamily#1} (option)\encapchar usage}^^A
204 % \index{options:\levelchar#1\actualchar{\protect\sffamily#1}^^A
205 % \encapchar usage}^^A
206 % \@esphack
207 % }
208 %
209 % ^^A The following was adapted from hypdoc's redefinition of \SpecialEnvIndex.
210 % \expandafter\ifx\csname c@HD@hypercount\endcsname\relax
211 % \else
212 % \let\HDorg@SpecialOptionIndex\SpecialOptionIndex
213 % \renewcommand*\SpecialOptionIndex[1]{^^A
214 % \@bsphack
215 % \begingroup
216 % \HD@target
217 % \let\HDorg@encapchar\encapchar
218 % \edef\encapchar usage{^^A
219 % \HDorg@encapchar hdpindex{usage}^^A
220 % }^^A
221 % \HDorg@SpecialOptionIndex{#1}^^A
222 % \endgroup
223 % \@esphack
224 % }
225 % \fi
226 % \makeatother
227 %
228 % ^^A Define a logical style for package-option names.
229 % \DeclareRobustCommand{\optname}[1]{^^A
230 % \texttt{#1}^^A
231 % \SpecialOptionIndex{#1}^^A
232 % }
233 %
234 % ^^A We use this box to help center protocol diagrams.
235 % \newsavebox{\protocoldiagram}
236 %
237 %
238 % \begin{abstract}
239 % The \pkgname{bytefield} package helps the user create illustrations for
240 % network protocol specifications and anything else that utilizes fields of
241 % data. These illustrations show how the bits and bytes are laid out in a
242 % packet or in memory.
243 % \end{abstract}
244 %
245 %
246 % \vspace{\baselineskip}
247 % \begin{center}
248 % \fbox{%
249 % \begin{minipage}{0.65\linewidth}
250 % \textsc{Warning}: \pkgname{bytefield} version~2.\textit{x} breaks
251 % compatibility with older versions of the package. See
252 % Section~\ref{sec:upgrading} for help porting documents to the new
253 % interface.
254 % \end{minipage}%
255 % }
256 % \end{center}
257 % \vspace{\baselineskip}
258 %
259 %
260 % \section{Introduction}
261 %
262 % Network protocols are usually specified in terms of a sequence of bits
263 % and bytes arranged in a field. This is portrayed graphically as a
264 % grid of boxes. Each row in the grid represents one word (frequently,
265 % 8, 16, or 32~bits), and each column represents a bit within a word.
266 % The \pkgname{bytefield} package makes it easy to typeset these sorts
267 % of figures. \pkgname{bytefield} facilitates drawing protocol diagrams
268 % that contain
269 %
270 % \begin{itemize}
271 % \item words of any arbitrary number of bits,
272 % \item column headers showing bit positions,
273 % \item multiword fields---even non-word-aligned and even if the total
274 % number of bits is not a multiple of the word length,
275 % \item word labels on either the left or right of the figure, and
276 % \item ``skipped words'' within fields.
277 % \end{itemize}
278 %
279 % Because \pkgname{bytefield} draws its figures using only the \LaTeX{}
280 % \texttt{picture} environment, these figures are not specific to any
281 % particular backend, do not require PostScript or PDF support, and do
282 % not need support from external programs. Furthermore, unlike an
283 % imported graphic, \pkgname{bytefield} pictures can include arbitrary
284 % \LaTeX{} constructs, such as mathematical equations, |\ref|s and
285 % |\cite|s to the surrounding document, and macro calls.
286 %
287 %
288 % \section{Usage}
289 % \label{sec:usage}
290 %
291 % \subsection{A first example}
292 % \label{sec:first-example}
293 %
294 % The Internet Engineering Task Force's Request for Comments (RFC)
295 % number~3016 includes the following ASCII-graphics illustration of
296 % the RTP packetization of an \mbox{MPEG-4} Visual bitstream:
297 %
298 % \begin{verbatim}
299 % 0 1 2 3
300 % 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
301 % +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
302 % |V=2|P|X| CC |M| PT | sequence number | RTP
303 % +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
304 % | timestamp | Header
305 % +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
306 % | synchronization source (SSRC) identifier |
307 % +=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+
308 % | contributing source (CSRC) identifiers |
309 % | .... |
310 % +=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+
311 % | | RTP
312 % | MPEG-4 Visual stream (byte aligned) | Pay-
313 % | | load
314 % | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
315 % | :...OPTIONAL RTP padding |
316 % +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
317 % \end{verbatim}
318 %
319 % \noindent
320 % The following \LaTeX\ code shows how straightforward it is to typeset
321 % that illustration using the \pkgname{bytefield} package:
322 %
323 % \begin{verbatim}
324 % \begin{bytefield}[bitwidth=1.1em]{32}
325 % \bitheader{0-31} \\
326 % \begin{rightwordgroup}{RTP \\ Header}
327 % \bitbox{2}{V=2} & \bitbox{1}{P} & \bitbox{1}{X}
328 % & \bitbox{4}{CC} & \bitbox{1}{M} & \bitbox{7}{PT}
329 % & \bitbox{16}{sequence number} \\
330 % \bitbox{32}{timestamp}
331 % \end{rightwordgroup} \\
332 % \bitbox{32}{synchronization source (SSRC) identifier} \\
333 % \wordbox[tlr]{1}{contributing source (CSRC) identifiers} \\
334 % \wordbox[blr]{1}{$\cdots$} \\
335 % \begin{rightwordgroup}{RTP \\ Payload}
336 % \wordbox[tlr]{3}{MPEG-4 Visual stream (byte aligned)} \\
337 % \bitbox[blr]{16}{}
338 % & \bitbox{16}{\dots\emph{optional} RTP padding}
339 % \end{rightwordgroup}
340 % \end{bytefield}
341 % \end{verbatim}
342 %
343 % Figure~\ref{fig:rtp-mpeg4} presents the typeset output of the
344 % preceding code. Sections~\ref{sec:basic-cmds} and~\ref{sec:options}
345 % explain each of the environments, macros, and arguments that were
346 % utilized plus many additional features of the \pkgname{bytefield}
347 % package.
348 %
349 % \begin{figure}[hbp]
350 % \centering
351 % \begin{lrbox}{\protocoldiagram}
352 % \begin{bytefield}[bitwidth=1.1em]{32}
353 % \bitheader{0-31} \\
354 % \begin{rightwordgroup}{RTP \\ Header}
355 % \bitbox{2}{V=2} & \bitbox{1}{P} & \bitbox{1}{X}
356 % & \bitbox{4}{CC} & \bitbox{1}{M} & \bitbox{7}{PT}
357 % & \bitbox{16}{sequence number} \\
358 % \bitbox{32}{timestamp}
359 % \end{rightwordgroup} \\
360 % \bitbox{32}{synchronization source (SSRC) identifier} \\
361 % \wordbox[tlr]{1}{contributing source (CSRC) identifiers} \\
362 % \wordbox[blr]{1}{$\cdots$} \\
363 % \begin{rightwordgroup}{RTP \\ Payload}
364 % \wordbox[tlr]{3}{MPEG-4 Visual stream (byte aligned)} \\
365 % \bitbox[blr]{16}{}
366 % & \bitbox{16}{\dots\emph{optional} RTP padding}
367 % \end{rightwordgroup}
368 % \end{bytefield}
369 % \end{lrbox}
370 % \makebox[0pt][c]{\usebox{\protocoldiagram}}
371 % \caption{Sample \pkgname{bytefield} output}
372 % \label{fig:rtp-mpeg4}
373 % \end{figure}
374 %
375 %
376 % \subsection{Basic commands}
377 % \label{sec:basic-cmds}
378 %
379 % This section explains how to use the \pkgname{bytefield} package. It
380 % lists all of the exported macros and environments in approximately
381 % decreasing order of usefulness.
382 %
383 % \begin{decl}
384 % \SpecialEnvIndex{bytefield}
385 % |\begin{bytefield}| \oarg{options} \marg{bit-width} \\
386 % \meta{fields} \\
387 % |\end{bytefield}|
388 % \end{decl}
389 %
390 % The \pkgname{bytefield} package's top-level environment is called, not
391 % surprisingly, ``|bytefield|''. It takes one mandatory argument, which
392 % is the number of bits in each word, and one optional argument, which
393 % is a comma-separated list of \meta{key}=\meta{value} pairs, described
394 % in Section~\ref{sec:options}, for formatting the bit-field's layout.
395 % One can think of a |bytefield| as being analogous to a |tabular|:
396 % words are separated by~``|\\|'', and fields within a word are
397 % separated by~``|&|''. As in a |tabular|, ``|\\|'' accepts a
398 % \meta{length} as an optional argument, and this specifies the amount
399 % of additional vertical whitespace to include after the current word is
400 % typeset.
401 %
402 % \begin{decl}
403 % \SpecialUsageIndex{\bitbox}
404 % |\bitbox| \oarg{sides} \marg{width} \oarg{options} \marg{text} \\
405 % \SpecialUsageIndex{\wordbox}
406 % |\wordbox| \oarg{sides} \marg{height} \oarg{options} \marg{text}
407 % \end{decl}
408 %
409 % The two main commands one uses within a \pkgname{bytefield}
410 % environment are |\bitbox| and |\wordbox|. The former typesets a field
411 % that is one or more bits wide and a single word tall. The latter
412 % typesets a field that is an entire word wide and one or more words
413 % tall.
414 %
415 % The first, optional, argument, \meta{sides}, is a list of letters
416 % specifying which sides of the field box to draw---[|l|]eft, [|r|]ight,
417 % [|t|]op, and/or [|b|]ottom. The default is ``|lrtb|'' (i.e.,~all
418 % sides are drawn). The second, required, argument is the width in bits
419 % of a bit box or the height in words of a word box. The third argument
420 % is an optional, comma-separated list of \meta{key}=\meta{value} pairs,
421 % described in Section~\ref{sec:options}. The fourth, required,
422 % argument is the text to typeset within the box. It is typeset
423 % horizontally centered within a vertically centered |\parbox|. Hence,
424 % words will wrap, and ``|\\|'' can be used to break lines manually.
425 %
426 % The following example shows how to produce a simple 16-bit-wide field:
427 %
428 % \begin{verbatim}
429 % \begin{bytefield}{16}
430 % \wordbox{1}{A 16-bit field} \\
431 % \bitbox{8}{8 bits} & \bitbox{8}{8 more bits} \\
432 % \wordbox{2}{A 32-bit field. Note that text wraps within the box.}
433 % \end{bytefield}
434 % \end{verbatim}
435 %
436 % The resulting bit field looks like this:
437 %
438 % \begin{bffigure}
439 % \begin{bytefield}{16}
440 % \wordbox{1}{A 16-bit field} \\
441 % \bitbox{8}{8 bits} & \bitbox{8}{8 more bits} \\
442 % \wordbox{2}{A 32-bit field. Note that text wraps within the box.}
443 % \end{bytefield}
444 % \end{bffigure}
445 %
446 % It is the user's responsibility to ensure that the total number of
447 % bits in each row adds up to the number of bits in a single word (the
448 % mandatory argument to the |bytefield| environment);
449 % \pkgname{bytefield} does not currently check for under- or overruns.
450 %
451 % Here's an example of using the \optname{bgcolor} option to fill each
452 % box with a different color:
453 %
454 % \begin{verbatim}
455 % \definecolor{lightcyan}{rgb}{0.84,1,1}
456 % \definecolor{lightgreen}{rgb}{0.64,1,0.71}
457 % \definecolor{lightred}{rgb}{1,0.7,0.71}
458 % \begin{bytefield}[bitheight=\widthof{~Sign~},
459 % boxformatting={\centering\small}]{32}
460 % \bitheader[endianness=big]{31,23,0} \\
461 % \bitbox{1}[bgcolor=lightcyan]{\rotatebox{90}{Sign}} &
462 % \bitbox{8}[bgcolor=lightgreen]{Exponent} &
463 % \bitbox{23}[bgcolor=lightred]{Mantissa}
464 % \end{bytefield}
465 % \end{verbatim}
466 %
467 % \begin{bffigure}
468 % \definecolor{lightcyan}{rgb}{0.84,1,1}
469 % \definecolor{lightgreen}{rgb}{0.64,1,0.71}
470 % \definecolor{lightred}{rgb}{1,0.7,0.71}
471 % \begin{bytefield}[bitheight=\widthof{~Sign~},
472 % boxformatting={\centering\small}]{32}
473 % \bitheader[endianness=big]{31,23,0} \\
474 % \bitbox{1}[bgcolor=lightcyan]{\rotatebox{90}{Sign}} &
475 % \bitbox{8}[bgcolor=lightgreen]{Exponent} &
476 % \bitbox{23}[bgcolor=lightred]{Mantissa}
477 % \end{bytefield}
478 % \end{bffigure}
479 %
480 % Within a |\bitbox| or |\wordbox|, the \pkgname{bytefield} package
481 % defines |\height|, |\depth|, |\totalheight|, and |\width| to the
482 % corresponding dimensions of the box. Section~\ref{sec:tricks} gives an
483 % example of how these lengths may be utilized.
484 %
485 % \begin{decl}
486 % \SpecialUsageIndex{\bitboxes}
487 % |\bitboxes| \oarg{sides} \marg{width} \oarg{options} \marg{tokens} \\
488 % |\bitboxes*| \oarg{sides} \marg{width} \oarg{options} \marg{tokens} \\
489 % \end{decl}
490 %
491 % The |\bitboxes| command provides a shortcut for typesetting a sequence
492 % of fields of the same width. It takes essentially the same arguments
493 % as |\bitbox| but interpets these differently. Instead of representing
494 % a single piece of text to typeset within a field of width
495 % \meta{width}, |\bitboxes|'s \meta{tokens} argument represents a list
496 % of tokens (e.g,~individual characters), each of which is typeset
497 % within a separate box of width \meta{width}. Consider, for example,
498 % the following sequence of |\bitbox| commands:
499 %
500 % \begin{verbatim}
501 % \begin{bytefield}{8}
502 % \bitbox{1}{D} & \bitbox{1}{R} & \bitbox{1}{M} & \bitbox{1}{F} &
503 % \bitbox{1}{S} & \bitbox{1}{L} & \bitbox{1}{T} & \bitbox{1}{D}
504 % \end{bytefield}
505 % \end{verbatim}
506 %
507 % \begin{bffigure}
508 % \begin{bytefield}{8}
509 % \bitbox{1}{D} & \bitbox{1}{R} & \bitbox{1}{M} & \bitbox{1}{F} &
510 % \bitbox{1}{S} & \bitbox{1}{L} & \bitbox{1}{T} & \bitbox{1}{D}
511 % \end{bytefield}
512 % \end{bffigure}
513 %
514 % \noindent
515 % With |\bitboxes| this can be abbreviated to
516 %
517 % \begin{verbatim}
518 % \begin{bytefield}{8}
519 % \bitboxes{1}{DRMFSLTD}
520 % \end{bytefield}
521 % \end{verbatim}
522 %
523 % Spaces are ignored within |\bitboxes|'s \meta{text} argument, and
524 % curly braces can be used to group multiple characters into a single
525 % token:
526 %
527 % \begin{verbatim}
528 % \begin{bytefield}{24}
529 % \bitboxes{3}{{DO} {RE} {MI} {FA} {SOL} {LA} {TI} {DO}}
530 % \end{bytefield}
531 % \end{verbatim}
532 %
533 % \begin{bffigure}
534 % \begin{bytefield}{24}
535 % \bitboxes{3}{{DO} {RE} {MI} {FA} {SOL} {LA} {TI} {DO}}
536 % \end{bytefield}
537 % \end{bffigure}
538 %
539 % The starred form of |\bitboxes| is identical except that it suppresses
540 % all internal vertical lines. It can therefore be quite convenient for
541 % typesetting binary constants:
542 %
543 % \begin{verbatim}
544 % \begin{bytefield}{16}
545 % \bitboxes*{1}{01000010} & \bitbox{4}{src\strut} &
546 % \bitbox{4}{dest\strut} & \bitbox{4}{const\strut}
547 % \end{bytefield}
548 % \end{verbatim}
549 %
550 % \begin{bffigure}
551 % \begin{bytefield}{16}
552 % \bitboxes*{1}{01000010} & \bitbox{4}{src\strut} &
553 % \bitbox{4}{dest\strut} & \bitbox{4}{const\strut}
554 % \end{bytefield}
555 % \end{bffigure}
556 %
557 % \begin{decl}
558 % \SpecialUsageIndex{\bitheader}
559 % |\bitheader| \oarg{options} \marg{bit-positions}
560 % \end{decl}
561 %
562 % To make the bit field more readable, it helps to label bit positions
563 % across the top. The |\bitheader| command provides a flexible way to
564 % do that. The optional argument is a comma-separated list of
565 % \meta{key}=\meta{value} pairs from the set described in
566 % Section~\ref{sec:options}. In practice, the only parameters that are
567 % meaningful in the context of |\bitheader| are |bitformatting|,
568 % |endianness|, and |lsb|. See Section~\ref{sec:options} for
569 % descriptions and examples of those parameters.
570 %
571 % |\bitheader|'s mandatory argument, \meta{bit-positions}, is a
572 % comma-separated list of bit positions to label. For example,
573 % ``|0,2,4,6,8,10,12,14|'' means to label those bit positions. The
574 % numbers must be listed in increasing order. (Use the
575 % \optname{endianness} parameter to display the header in reverse
576 % order.) Hyphen-separated ranges are also valid. For example,
577 % ``|0-15|'' means to label all bits from~0 to~15, inclusive. Ranges
578 % and single numbers can even be intermixed, as in ``|0-3,8,12-15|''.
579 %
580 % The following example shows how |\bitheader| may be used:
581 %
582 % \begin{verbatim}
583 % \begin{bytefield}{32}
584 % \bitheader{0-31} \\
585 % \bitbox{4}{Four} & \bitbox{8}{Eight} &
586 % \bitbox{16}{Sixteen} & \bitbox{4}{Four}
587 % \end{bytefield}
588 % \end{verbatim}
589 %
590 % The resulting bit field looks like this:
591 %
592 % \begin{bffigure}
593 % \begin{bytefield}{32}
594 % \bitheader{0-31} \\
595 % \bitbox{4}{Four} & \bitbox{8}{Eight} &
596 % \bitbox{16}{Sixteen} & \bitbox{4}{Four}
597 % \end{bytefield}
598 % \end{bffigure}
599 %
600 %
601 % \begin{decl}
602 % \SpecialEnvIndex{rightwordgroup}
603 % |\begin{rightwordgroup}| \oarg{options} \marg{text} \\
604 % \meta{rows of bit boxes and word boxes} \\
605 % |\end{rightwordgroup}| \\
606 % \\
607 % \SpecialEnvIndex{leftwordgroup}
608 % |\begin{leftwordgroup}| \oarg{options} \marg{text} \\
609 % \meta{rows of bit boxes and word boxes} \\
610 % |\end{leftwordgroup}|
611 % \end{decl}
612 %
613 % When a set of words functions as a single, logical unit, it helps to
614 % group these words together visually. All words defined between
615 % |\begin{rightwordgroup}| and |\end{rightwordgroup}| will be labeled on
616 % the right with \meta{text}. Similarly, all words defined between
617 % |\begin{leftwordgroup}| and |\end{leftwordgroup}| will be labeled on
618 % the left with \meta{text}. |\begin{|\meta{side}|wordgroup}| must lie
619 % at the beginning of a row (i.e.,~right after a ``|\\|''), and
620 % |\end{|\meta{side}|wordgroup}| must lie right \emph{before} the end of
621 % the row (i.e.,~right before a ``|\\|'').
622 %
623 % The optional argument is a comma-separated list of
624 % \meta{key}=\meta{value} pairs from the set described in
625 % Section~\ref{sec:options}. In practice, only \optname{curlystyle},
626 % \optname{leftcurlystyle}, and \optname{rightcurlystyle}, make sense
627 % within the context of a |\begin{|\meta{side}|wordgroup}|.
628 %
629 % Unlike other \LaTeX\ environments, |rightwordgroup| and
630 % |leftwordgroup| do not have to nest properly with each other.
631 % However, they cannot overlap themselves. In other words,
632 % |\begin{rightwordgroup}|\ellipsis |\begin{leftwordgroup}|\ellipsis
633 % |\end{rightwordgroup}|\ellipsis |\end{leftwordgroup}| is a valid
634 % sequence, but |\begin{rightwordgroup}|\ellipsis
635 % |\begin{rightwordgroup}|\ellipsis |\end{rightwordgroup}|\ellipsis
636 % |\end{rightwordgroup}| is not.
637 %
638 % The following example presents the basic usage of
639 % |\begin{rightwordgroup}| and |\end{rightwordgroup}|:
640 %
641 % \begin{verbatim}
642 % \begin{bytefield}{16}
643 % \bitheader{0,7,8,15} \\
644 % \begin{rightwordgroup}{Header}
645 % \bitbox{4}{Tag} & \bitbox{12}{Mask} \\
646 % \bitbox{8}{Source} & \bitbox{8}{Destination}
647 % \end{rightwordgroup} \\
648 % \wordbox{3}{Data}
649 % \end{bytefield}
650 % \end{verbatim}
651 %
652 % \noindent
653 % Note the juxtaposition of ``|\\|'' to the |\begin{rightwordgroup}| and
654 % the |\end{rightwordgroup}| in the above. The resulting bit field
655 % looks like this:
656 %
657 % \begin{bffigure}
658 % \begin{bytefield}{16}
659 % \bitheader{0,7,8,15} \\
660 % \begin{rightwordgroup}{Header}
661 % \bitbox{4}{Tag} & \bitbox{12}{Mask} \\
662 % \bitbox{8}{Source} & \bitbox{8}{Destination}
663 % \end{rightwordgroup} \\
664 % \wordbox{3}{Data}
665 % \end{bytefield}
666 % \end{bffigure}
667 %
668 % \noindent
669 % As a more complex example, the following nests left and right labels:
670 %
671 % \begin{verbatim}
672 % \begin{bytefield}{16}
673 % \bitheader{0,7,8,15} \\
674 % \begin{rightwordgroup}{Header}
675 % \bitbox{4}{Tag} & \bitbox{12}{Mask} \\
676 % \begin{leftwordgroup}{Node IDs}
677 % \bitbox{8}{Source} & \bitbox{8}{Destination}
678 % \end{leftwordgroup}
679 % \end{rightwordgroup} \\
680 % \wordbox{3}{Data}
681 % \end{bytefield}
682 % \end{verbatim}
683 %
684 % \begin{bffigure}
685 % \begin{bytefield}{16}
686 % \bitheader{0,7,8,15} \\
687 % \begin{rightwordgroup}{Header}
688 % \bitbox{4}{Tag} & \bitbox{12}{Mask} \\
689 % \begin{leftwordgroup}{Node IDs}
690 % \bitbox{8}{Source} & \bitbox{8}{Destination}
691 % \end{leftwordgroup}
692 % \end{rightwordgroup} \\
693 % \wordbox{3}{Data}
694 % \end{bytefield}
695 % \end{bffigure}
696 %
697 % \noindent
698 % Because |rightwordgroup| and |leftwordgroup| are not required to nest
699 % properly, the resulting bit field would look the same if the
700 % |\end{leftwordgroup}| and |\end{rightwordgroup}| were swapped. Again,
701 % note the justaposition of ``|\\|'' to the various word-grouping
702 % commands in the above.
703 %
704 % \begin{decl}
705 % \SpecialUsageIndex{\skippedwords}
706 % |\skippedwords|
707 % \end{decl}
708 %
709 % Draw a graphic representing a number of words that are not shown.
710 % |\skippedwords| is intended to work with the \meta{sides} argument
711 % to |\wordbox|, as in the following example:
712 %
713 % \begin{verbatim}
714 % \begin{bytefield}{16}
715 % \wordbox{1}{Some data} \\
716 % \wordbox[lrt]{1}{Lots of data} \\
717 % \skippedwords \\
718 % \wordbox[lrb]{1}{} \\
719 % \wordbox{2}{More data}
720 % \end{bytefield}
721 % \end{verbatim}
722 %
723 % \begin{bffigure}
724 % \begin{bytefield}{16}
725 % \wordbox{1}{Some data} \\
726 % \wordbox[lrt]{1}{Lots of data} \\
727 % \skippedwords \\
728 % \wordbox[lrb]{1}{} \\
729 % \wordbox{2}{More data}
730 % \end{bytefield}
731 % \end{bffigure}
732 %
733 % \begin{decl}
734 % \SpecialUsageIndex{\bytefieldsetup}
735 % |\bytefieldsetup| \marg{options}
736 % \end{decl}
737 %
738 % Alter the formatting of all subsequent bit fields.
739 % Section~\ref{sec:options} describes the possible values for each
740 % \meta{key}=\meta{value} pair in the comma-separated list that
741 % |\bytefieldsetup| accepts as its argument. Note that changes made
742 % with |\bytefieldsetup| are local to their current scope. Hence, if
743 % used within an environment (e.g.,~|figure|), |\bytefieldsetup| does
744 % not impact bit fields drawn outside that environment.
745 %
746 %
747 % \subsection{Formatting options}
748 % \label{sec:options}
749 %
750 % A document author can customize many of the \pkgname{bytefield}
751 % package's figure-formatting parameters, either globally or on a
752 % per-figure basis. The parameters described below can be specified in
753 % six locations:
754 %
755 % \begin{itemize}
756 % \item as package options (i.e.,~in the
757 % |\usepackage|\oarg{options}|{bytefield}| line), which affects all
758 % |bytefield| environments in the entire document,
759 %
760 % \item anywhere in the document using the |\bytefieldsetup| command,
761 % which affects all subsequent |bytefield| environments in the
762 % current scope,
763 %
764 % \item as the optional argument to a |\begin{bytefield}|, which
765 % affects only that single bit-field figure, or
766 %
767 % \item as the optional argument to a |\bitheader|, which affects only
768 % that particular header. (Only a few parameters are meaningful in
769 % this context.)
770 %
771 % \item as the optional argument to a |\begin{leftwordgroup}| or
772 % |\begin{rightwordgroup}|, which affects only that particular word
773 % group. (Only a few parameters are meaningful in this context.)
774 %
775 % \item as the second optional argument to a \cs{bitbox}, \cs{wordbox},
776 % or \cs{bitboxes}, which affects only that particular box. (Only a
777 % few parameters are meaningful in this context.)
778 % \end{itemize}
779 %
780 % Unfortunately, \LaTeX\ tends to abort with a ``\texttt{TeX capacity
781 % exceeded}'' or ``\texttt{Missing \cs{endcsname} inserted}'' error
782 % when a control sequence (i.e.,~|\|\meta{name}) or |\|\meta{symbol}) is
783 % encountered within the optional argument to |\usepackage|. Hence,
784 % parameters that typically expect a control sequence in their
785 % argument---in particular, \optname{bitformatting},
786 % \optname{boxformatting}, \optname{leftcurly}, and
787 % \optname{rightcurly}---should best be avoided within the
788 % |\usepackage|\oarg{options}|{bytefield}| line.
789 %
790 % \begin{decl}
791 % \optname{bitwidth} = \meta{length} \\
792 % \optname{bitheight} = \meta{length}
793 % \end{decl}
794 %
795 % The above parameters represent the width and height of each bit in a
796 % bit field. The default value of \optname{bitwidth} is the width of
797 % ``|{\tiny 99i}|'', i.e.,~the width of a two-digit number plus a small
798 % amount of extra space. This enables |\bitheader| to show two-digit
799 % numbers without overlap. The default value of \optname{bitheight}
800 % is~|2ex|, which should allow a normal piece of text to appear within a
801 % |\bitbox| or |\wordbox| without abutting the box's top or bottom edge.
802 %
803 % As a special case, if \optname{bitwidth} is set to the word
804 % ``|auto|'', it will be set to the width of ``|99i|'' in the current
805 % bit-number formatting (see \optname{bitformatting} below). This
806 % feature provides a convenient way to adjust the bit width after a
807 % formatting change.
808 %
809 % \begin{decl}
810 % \optname{endianness} = |little| \emph{or} |big|
811 % \end{decl}
812 %
813 % Specify either little-endian (left-to-right) or big-endian
814 % (right-to-left) ordering of the bit numbers. The default is
815 % little-endian numbering. Contrast the following two examples. The
816 % first formats a bit field in little-endian ordering using an explicit
817 % |endianness=little|, and the second formats the same bit field in
818 % big-endian ordering using |endianness=big|.
819 %
820 % \begin{verbatim}
821 % \begin{bytefield}[endianness=little,bitwidth=0.11111\linewidth]{8}
822 % \bitheader{0-7} \\
823 % \bitbox{1}{Res} & \bitbox{1}{BE} & \bitbox{1}{CF}
824 % & \bitbox{3}{$\mbox{Name\_Len}-1$} & \bitbox{2}{Len\_Len} \\
825 % \end{bytefield}
826 % \end{verbatim}
827 %
828 % \begin{bffigure}
829 % \begin{bytefield}[endianness=little,bitwidth=0.11111\linewidth]{8}
830 % \bitheader{0-7} \\
831 % \bitbox{1}{Res} & \bitbox{1}{BE} & \bitbox{1}{CF}
832 % & \bitbox{3}{$\mbox{Name\_Len}-1$} & \bitbox{2}{Len\_Len} \\
833 % \end{bytefield}
834 % \end{bffigure}
835 %
836 % \begin{verbatim}
837 % \begin{bytefield}[endianness=big,bitwidth=0.11111\linewidth]{8}
838 % \bitheader{0-7} \\
839 % \bitbox{2}{Len\_Len} & \bitbox{3}{$\mbox{Name\_Len}-1$}
840 % & \bitbox{1}{CF} & \bitbox{1}{BE} & \bitbox{1}{Res} \\
841 % \end{bytefield}
842 % \end{verbatim}
843 %
844 % \begin{bffigure}
845 % \begin{bytefield}[endianness=big,bitwidth=0.11111\linewidth]{8}
846 % \bitheader{0-7} \\
847 % \bitbox{2}{Len\_Len} & \bitbox{3}{$\mbox{Name\_Len}-1$}
848 % & \bitbox{1}{CF} & \bitbox{1}{BE} & \bitbox{1}{Res} \\
849 % \end{bytefield}
850 % \end{bffigure}
851 %
852 % \begin{decl}
853 % \optname{bitformatting} = \meta{command} \emph{or} \marg{commands}
854 % \end{decl}
855 %
856 % The numbers that appear in a bit header are typeset in the
857 % \optname{bitformatting} style, which defaults to |\tiny|. To alter
858 % the style of bit numbers in the bit header, set
859 % \optname{bitformatting} to a macro that takes a single argument (like
860 % |\textbf|) or no arguments (like |\small|). Groups of commands
861 % (e.g.,~|{\large\itshape}|) are also acceptable.
862 %
863 % When \optname{bitformatting} is set, \optname{bitwidth} usually needs
864 % to be recalculated as well to ensure that a correct amount of spacing
865 % surrounds each number in the bit header. As described above, setting
866 % |bitwidth=auto| is a convenient shortcut for recalculating the
867 % bit-width in the common case of bit fields containing no more than 99
868 % bits per line and no particularly wide labels in bit boxes that
869 % contain only a few bits.
870 %
871 % The following example shows how to use \optname{bitformatting} and
872 % \optname{bitwidth} to format a bit header with small, boldface text:
873 %
874 % \begin{verbatim}
875 % \begin{bytefield}[bitformatting={\small\bfseries},
876 % bitwidth=auto,
877 % endianness=big]{20}
878 % \bitheader{0-19} \\
879 % \bitbox{1}{\tiny F/E} & \bitbox{1}{\tiny T0} & \bitbox{1}{\tiny T1}
880 % & \bitbox{1}{\tiny Fwd} & \bitbox{16}{Data value} \\
881 % \end{bytefield}
882 % \end{verbatim}
883 %
884 % \noindent
885 % The resulting bit field looks like this:
886 %
887 % \begin{bffigure}
888 % \begin{bytefield}[bitformatting={\small\bfseries},
889 % bitwidth=auto,
890 % endianness=big]{20}
891 % \bitheader{0-19} \\
892 % \bitbox{1}{\tiny F/E} & \bitbox{1}{\tiny T0} & \bitbox{1}{\tiny T1}
893 % & \bitbox{1}{\tiny Fwd} & \bitbox{16}{Data value} \\
894 % \end{bytefield}
895 % \end{bffigure}
896 %
897 % \begin{decl}
898 % \optname{boxformatting} = \meta{command} \emph{or} \marg{commands}
899 % \end{decl}
900 %
901 % The text that appears in a |\bitbox| or |\wordbox| is formatted in the
902 % \optname{boxformatting} style, which defaults to |\centering|. To
903 % alter the style of bit numbers in the bit header, set
904 % \optname{boxformatting} to a macro that takes a single argument (like
905 % |\textbf| but not |\textbf|---see below) or no arguments (like
906 % |\small|). Groups of commands (e.g.,~|{\large\itshape}|) are also
907 % acceptable.
908 %
909 % If \optname{boxformatting} is set to a macro that takes an argument,
910 % the macro must be defined as a ``long'' macro, which means it can
911 % accept more than one paragraph as an argument. Commands defined with
912 % |\newcommand| are automatically made long, but commands defined with
913 % |\newcommand*| are not. \LaTeX's |\text|\dots\ formatting commands
914 % (e.g.,~|\textbf|) are not long and therefore cannot be used directly
915 % in \optname{boxformatting}; use the zero-argument versions
916 % (e.g.,~|\bfseries|) instead.
917 %
918 % The following example shows how to use \optname{boxformatting} to
919 % format the text within each box horizontally centered and italicized:
920 %
921 % \begin{verbatim}
922 % \begin{bytefield}[boxformatting={\centering\itshape},
923 % bitwidth=1.5em,
924 % endianness=big]{20}
925 % \bitheader{0-19} \\
926 % \bitbox{1}{\tiny F/E} & \bitbox{1}{\tiny T0} & \bitbox{1}{\tiny T1}
927 % & \bitbox{1}{\tiny Fwd} & \bitbox{16}{Data value} \\
928 % \end{bytefield}
929 % \end{verbatim}
930 %
931 % \noindent
932 % The resulting bit field looks like this:
933 %
934 % \begin{bffigure}
935 % \begin{bytefield}[boxformatting={\centering\itshape},
936 % bitwidth=1.5em,
937 % endianness=big]{20}
938 % \bitheader{0-19} \\
939 % \bitbox{1}{\tiny F/E} & \bitbox{1}{\tiny T0} & \bitbox{1}{\tiny T1}
940 % & \bitbox{1}{\tiny Fwd} & \bitbox{16}{Data value} \\
941 % \end{bytefield}
942 % \end{bffigure}
943 %
944 % \begin{decl}
945 % \optname{bgcolor} = \meta{color}
946 % \end{decl}
947 %
948 % Bit and word boxes are normally left unfilled. The \optname{bgcolor}
949 % option fills them with a specified background color. A document will
950 % need to include the \pkgname{color}, \pkgname{xcolor}, or similar
951 % package to expose color names to \pkgname{bytefield}. The
952 % \optname{boxformatting} option described above can be used to set the
953 % foreground color.
954 %
955 % \begin{decl}
956 % \optname{leftcurly} = \meta{delimiter} \\
957 % \optname{rightcurly} = \meta{delimiter}
958 % \end{decl}
959 %
960 % Word groups are normally indicated by a curly brace spanning all of
961 % its rows. However, the curly brace can be replaced by any other
962 % extensible math delimiter (i.e.,~a symbol that can meaningfully follow
963 % |\left| or |\right| in math mode) via a suitable redefinition of
964 % \optname{leftcurly} or \optname{rightcurly}. As in math mode, ``|.|''
965 % means ``no symbol'', as in the following example (courtesy of
966 % Steven~R. King):
967 %
968 % \begin{verbatim}
969 % \begin{bytefield}[rightcurly=., rightcurlyspace=0pt]{32}
970 % \bitheader[endianness=big]{0,7,8,15,16,23,24,31} \\
971 % \begin{rightwordgroup}{0Ch}
972 % \bitbox{8}{Byte 15 \\ \tiny (highest address)}
973 % & \bitbox{8}{Byte 14}
974 % & \bitbox{8}{Byte 13}
975 % & \bitbox{8}{Byte 12}
976 % \end{rightwordgroup} \\
977 % \begin{rightwordgroup}{08h}
978 % \bitbox{32}{Long 0}
979 % \end{rightwordgroup} \\
980 % \begin{rightwordgroup}{04h}
981 % \bitbox{16}{Word 1} & \bitbox{16}{Word 0}
982 % \end{rightwordgroup} \\
983 % \begin{rightwordgroup}{00h}
984 % \bitbox{8}{Byte 3}
985 % & \bitbox{8}{Byte 2}
986 % & \bitbox{8}{Byte 1}
987 % & \bitbox{8}{Byte 0 \\ \tiny (lowest address)}
988 % \end{rightwordgroup}
989 % \end{bytefield}
990 % \end{verbatim}
991 %
992 % \begin{bffigure}
993 % \begin{bytefield}[rightcurly=., rightcurlyspace=0pt]{32}
994 % \bitheader[endianness=big]{0,7,8,15,16,23,24,31} \\
995 % \begin{rightwordgroup}{0Ch}
996 % \bitbox{8}{Byte 15 \\ \tiny (highest address)}
997 % & \bitbox{8}{Byte 14}
998 % & \bitbox{8}{Byte 13}
999 % & \bitbox{8}{Byte 12}
1000 % \end{rightwordgroup} \\
1001 % \begin{rightwordgroup}{08h}
1002 % \bitbox{32}{Long 0}
1003 % \end{rightwordgroup} \\
1004 % \begin{rightwordgroup}{04h}
1005 % \bitbox{16}{Word 1} & \bitbox{16}{Word 0}
1006 % \end{rightwordgroup} \\
1007 % \begin{rightwordgroup}{00h}
1008 % \bitbox{8}{Byte 3}
1009 % & \bitbox{8}{Byte 2}
1010 % & \bitbox{8}{Byte 1}
1011 % & \bitbox{8}{Byte 0 \\ \tiny (lowest address)}
1012 % \end{rightwordgroup}
1013 % \end{bytefield}
1014 % \end{bffigure}
1015 %
1016 % \begin{decl}
1017 % \optname{leftcurlyspace} = \meta{length} \\
1018 % \optname{rightcurlyspace} = \meta{length} \\
1019 % \optname{curlyspace} = \meta{length}
1020 % \end{decl}
1021 %
1022 % \optname{leftcurlyspace} and \optname{rightcurlyspace} specify the
1023 % space to insert between the bit field and the curly brace in a left or
1024 % right word group (default:~|1ex|). Setting \optname{curlyspace} is a
1025 % shortcut for setting both \optname{leftcurlyspace} and
1026 % \optname{rightcurlyspace} to the same value.
1027 %
1028 % \begin{decl}
1029 % |leftlabelspace| = \meta{length} \\
1030 % |rightlabelspace| = \meta{length} \\
1031 % |labelspace| = \meta{length}
1032 % \end{decl}
1033 %
1034 % |leftlabelspace| and |rightlabelspace| specify the space to insert
1035 % between the curly brace and the text label in a left or right word
1036 % group (default:~|0.5ex|). Setting |labelspace| is a shortcut for
1037 % setting both |leftlabelbrace| and |rightlabelspace| to the same value.
1038 %
1039 % \bigskip
1040 %
1041 % Figure~\ref{fig:rightspace} illustrates the juxtaposition of
1042 % \optname{rightcurlyspace} and |rightlabelspace| to a word group and
1043 % its label. The \optname{leftcurlyspace} and |leftlabelspace|
1044 % parameters are symmetric.
1045 %
1046 % \begin{figure}[htbp]
1047 % \[
1048 % \begin{array}{*5{@{}c}@{}}
1049 % \cline{1-1}
1050 % \multicolumn{1}{c|}{\cdots\quad\meta{bit-field rows}}
1051 % &
1052 % & \left.\rule{0pt}{3ex}\right\}
1053 % &
1054 % & \meta{label} \\[2ex] \cline{1-1}
1055 % & \underbrace{\hspace*{6em}}_{\mathtt{rightcurlyspace}}
1056 % &
1057 % & \underbrace{\hspace*{6em}}_{\mathtt{rightlabelspace}} \\
1058 % \end{array}
1059 % \]
1060 % \caption{Role of \texttt{rightcurlyspace} and \texttt{rightlabelspace}}
1061 % \label{fig:rightspace}
1062 % \end{figure}
1063 %
1064 % \begin{decl}
1065 % \optname{leftcurlyshrinkage} = \meta{length} \\
1066 % \optname{rightcurlyshrinkage} = \meta{length} \\
1067 % \optname{curlyshrinkage} = \meta{length}
1068 % \end{decl}
1069 %
1070 % In \TeX/\LaTeX, the height of a curly brace does not include the tips.
1071 % Hence, in a word group label, the tips of the curly brace will extend
1072 % beyond the height of the word group.
1073 % \optname{leftcurlyshrinkage}\slash \optname{rightcurlyshrinkage} is an
1074 % amount by which to reduce the height of the curly brace in a
1075 % left\slash right word group's label. Setting \optname{curlyshrinkage}
1076 % is a shortcut for setting both \optname{leftcurlyshrinkage} and
1077 % \optname{rightcurlyshrinkage} to the same value. Shrinkages default
1078 % to~|5pt|, and it is extremely unlikely that one would ever need to
1079 % change them. Nevertheless, these parameters are included here in case
1080 % a document is typeset with a math font containing radically different
1081 % curly braces from the ones that come with \TeX/\LaTeX\ or that
1082 % replaces the curly braces (using \optname{leftcurly}\slash
1083 % \optname{rightcurly}, described above) with symbols of substantially
1084 % different heights.
1085 %
1086 % \begin{decl}
1087 % \optname{leftcurlystyle} = \meta{command} \\
1088 % \optname{rightcurlystyle} = \meta{command} \\
1089 % \optname{curlystyle} = \meta{command}
1090 % \end{decl}
1091 %
1092 % Provide a macro that will be invoked before the code that draws left,
1093 % right, or both curly braces. The macro must accept either zero or one
1094 % argument. It can be used, for example, to color the curly brace:
1095 %
1096 % \begin{verbatim}
1097 % \begin{bytefield}[curlystyle=\color{blue}]{16}
1098 % \bitheader{0-15} \\
1099 % \begin{rightwordgroup}{Sign-extended}
1100 % \bitbox{4}{Tag} & \bitbox{12}{Data}
1101 % \end{rightwordgroup} \\
1102 % \end{bytefield}
1103 % \end{verbatim}
1104 %
1105 % \begin{bffigure}
1106 % \begin{bytefield}[curlystyle=\color{blue}]{16}
1107 % \bitheader{0-15} \\
1108 % \begin{rightwordgroup}{Sign-extended}
1109 % \bitbox{4}{Tag} & \bitbox{12}{Data}
1110 % \end{rightwordgroup} \\
1111 % \end{bytefield}
1112 % \end{bffigure}
1113 %
1114 % \noindent
1115 % or
1116 %
1117 % \begin{verbatim}
1118 % \begin{bytefield}{16}
1119 % \bitheader{0-15} \\
1120 % \begin{rightwordgroup}[curlystyle=\color{blue}]{Sign-extended}
1121 % \bitbox{4}{Tag} & \bitbox{12}{Data}
1122 % \end{rightwordgroup} \\
1123 % \end{bytefield}
1124 % \end{verbatim}
1125 %
1126 % \begin{bffigure}
1127 % \begin{bytefield}{16}
1128 % \bitheader{0-15} \\
1129 % \begin{rightwordgroup}[curlystyle=\color{blue}]{Sign-extended}
1130 % \bitbox{4}{Tag} & \bitbox{12}{Data}
1131 % \end{rightwordgroup} \\
1132 % \end{bytefield}
1133 % \end{bffigure}
1134 %
1135 % \begin{decl}
1136 % \optname{lsb} = \meta{integer}
1137 % \end{decl}
1138 %
1139 % Designate the least significant bit (LSB) in the bit header. By
1140 % default, the LSB is zero, which means that the first bit position in
1141 % the header corresponds to bit~0. Specifying a different LSB shifts
1142 % the bit header such that the first bit position instead corresponds to
1143 % \meta{integer}. Note that the \optname{lsb} option affects bit
1144 % \emph{positions} regardless of whether these positions are labeled, as
1145 % demonstrated by the following two examples:
1146 %
1147 % \begin{verbatim}
1148 % \begin{bytefield}{32}
1149 % \bitheader[lsb=0]{4,12,20,28} \\
1150 % \bitbox{16}{ar\$hrd} & \bitbox{16}{ar\$pro} \\
1151 % \bitbox{8}{ar\$hln} & \bitbox{8}{ar\$pln} & \bitbox{16}{ar\$op} \\
1152 % \end{bytefield}
1153 % \end{verbatim}
1154 %
1155 % \begin{bffigure}
1156 % \begin{bytefield}{32}
1157 % \bitheader[lsb=0]{4,12,20,28} \\
1158 % \bitbox{16}{ar\$hrd} & \bitbox{16}{ar\$pro} \\
1159 % \bitbox{8}{ar\$hln} & \bitbox{8}{ar\$pln} & \bitbox{16}{ar\$op} \\
1160 % \end{bytefield}
1161 % \end{bffigure}
1162 %
1163 % \begin{verbatim}
1164 % \begin{bytefield}{32}
1165 % \bitheader[lsb=4]{4,12,20,28} \\
1166 % \bitbox{16}{ar\$hrd} & \bitbox{16}{ar\$pro} \\
1167 % \bitbox{8}{ar\$hln} & \bitbox{8}{ar\$pln} & \bitbox{16}{ar\$op} \\
1168 % \end{bytefield}
1169 % \end{verbatim}
1170 %
1171 % \begin{bffigure}
1172 % \begin{bytefield}{32}
1173 % \bitheader[lsb=4]{4,12,20,28} \\
1174 % \bitbox{16}{ar\$hrd} & \bitbox{16}{ar\$pro} \\
1175 % \bitbox{8}{ar\$hln} & \bitbox{8}{ar\$pln} & \bitbox{16}{ar\$op} \\
1176 % \end{bytefield}
1177 % \end{bffigure}
1178 %
1179 % \begin{decl}
1180 % \optname{perword} = \meta{command}
1181 % \end{decl}
1182 %
1183 % Provide a macro that will be invoked once for each word in a word box
1184 % after the regular content is rendered. The macro will be passed two
1185 % arguments: the word number (starting from~0) and the total number of
1186 % words in the word box. Furthermore, the macro will be invoked within
1187 % a one-word-wide box positioned at the base of the word.
1188 % \optname{perword} can therefore be used for delineating words within a
1189 % word box, numbering words, or performing other such annotations. As a
1190 % simple example, the following code draws a gray line at the bottom of
1191 % each word in the ``Descriptive text'' word box:
1192 %
1193 % \begin{verbatim}
1194 % \newcommand{\wordline}[2]{\color[rgb]{0.7,0.7,0.7}\hrulefill}
1195 % \begin{bytefield}[bitwidth=4em]{8}
1196 % \bitheader[lsb=1,bitformatting=\small]{1-8} \\
1197 % \wordbox[lrt]{7}[perword=\wordline]{Descriptive text (60 bytes)} \\
1198 % \bitbox[lrb]{4}{} & \bitbox{4}{subsys data offset} \\
1199 % \bitbox{4}{subsys data offset} & \bitbox{2}{version} &
1200 % \bitbox{2}{endian indicator} \\
1201 % \end{bytefield}
1202 % \end{verbatim}
1203 %
1204 % \begin{bffigure}
1205 % \newcommand{\wordline}[2]{\color[rgb]{0.7,0.7,0.7}\hrulefill}
1206 % \begin{bytefield}[bitwidth=4em]{8}
1207 % \bitheader[lsb=1,bitformatting=\small]{1-8} \\
1208 % \wordbox[lrt]{7}[perword=\wordline]{Descriptive text (60 bytes)} \\
1209 % \bitbox[lrb]{4}{} & \bitbox{4}{subsys data offset} \\
1210 % \bitbox{4}{subsys data offset} & \bitbox{2}{version} &
1211 % \bitbox{2}{endian indicator} \\
1212 % \end{bytefield}
1213 % \end{bffigure}
1214 %
1215 %
1216 % \subsection{Common tricks}
1217 % \label{sec:tricks}
1218 %
1219 % This section shows some clever ways to use \pkgname{bytefield}'s commands
1220 % to produce some useful effects.
1221 %
1222 % \paragraph{Odd-sized fields}
1223 % To produce a field that is, say, 1\textonehalf{} words long, use a
1224 % |\bitbox| for the fractional part and specify appropriate values
1225 % for the various \meta{sides} parameters. For instance:
1226 %
1227 % \begin{verbatim}
1228 % \begin{bytefield}{16}
1229 % \bitheader{0,7,8,15} \\
1230 % \bitbox{8}{8-bit field} & \bitbox[lrt]{8}{} \\
1231 % \wordbox[lrb]{1}{24-bit field}
1232 % \end{bytefield}
1233 % \end{verbatim}
1234 %
1235 % \begin{bffigure}
1236 % \begin{bytefield}{16}
1237 % \bitheader{0,7,8,15} \\
1238 % \bitbox{8}{8-bit field} & \bitbox[lrt]{8}{} \\
1239 % \wordbox[lrb]{1}{24-bit field}
1240 % \end{bytefield}
1241 % \end{bffigure}
1242 %
1243 % \paragraph{Ellipses}
1244 % To skip words that appear the middle of enumerated data, put some
1245 % |\vdots| in a |\wordbox| with empty \meta{sides}:
1246 %
1247 % \begin{verbatim}
1248 % \begin{bytefield}{16}
1249 % \bitbox{8}{Type} & \bitbox{8}{\# of nodes} \\
1250 % \wordbox{1}{Node~1} \\
1251 % \wordbox{1}{Node~2} \\
1252 % \wordbox[]{1}{$\vdots$} \\[1ex]
1253 % \wordbox{1}{Node~$N$}
1254 % \end{bytefield}
1255 % \end{verbatim}
1256 %
1257 % \begin{bffigure}
1258 % \begin{bytefield}{16}
1259 % \bitbox{8}{Type} & \bitbox{8}{\# of nodes} \\
1260 % \wordbox{1}{Node~1} \\
1261 % \wordbox{1}{Node~2} \\
1262 % \wordbox[]{1}{$\vdots$} \\[1ex]
1263 % \wordbox{1}{Node~$N$}
1264 % \end{bytefield}
1265 % \end{bffigure}
1266 %
1267 % \noindent
1268 % The extra |1ex| of vertical space helps vertically center the |\vdots|
1269 % a bit better.
1270 %
1271 % \paragraph{Narrow fields}
1272 % There are a number of options for labeling a narrow field (e.g.,~one
1273 % occupying a single bit):
1274 %
1275 % \newsavebox{\defaultOK}
1276 % \begin{lrbox}{\defaultOK}
1277 % \begin{bytefield}{8}
1278 % \bitbox{1}{OK} & \bitbox{7}{Data} \\
1279 % \end{bytefield}
1280 % \end{lrbox}
1281 %
1282 % \newsavebox{\bitwidthOK}
1283 % \begin{lrbox}{\bitwidthOK}
1284 % \bytefieldsetup{bitwidth=\widthof{OK~}}\relax
1285 % \begin{bytefield}{8}
1286 % \bitbox{1}{OK} & \bitbox{7}{Data} \\
1287 % \end{bytefield}
1288 % \end{lrbox}
1289 %
1290 % \newsavebox{\tinyOK}
1291 % \begin{lrbox}{\tinyOK}
1292 % \begin{bytefield}{8}
1293 % \bitbox{1}{\tiny OK} & \bitbox{7}{Data} \\
1294 % \end{bytefield}
1295 % \end{lrbox}
1296 %
1297 % \newsavebox{\verticalOK}
1298 % \begin{lrbox}{\verticalOK}
1299 % \begin{bytefield}{8}
1300 % \bitbox{1}{\tiny O \\ K} & \bitbox{7}{Data} \\
1301 % \end{bytefield}
1302 % \end{lrbox}
1303 %
1304 % \newsavebox{\rotateOK}
1305 % \begin{lrbox}{\rotateOK}
1306 % \begin{bytefield}{8}
1307 % \bitbox{1}{\rotatebox{90}{\small OK}} & \bitbox{7}{Data} \\
1308 % \end{bytefield}
1309 % \end{lrbox}
1310 %
1311 % \newsavebox{\resizeOK}
1312 % \begin{lrbox}{\resizeOK}
1313 % \begin{bytefield}{8}
1314 % \bitbox{1}{\let\bw=\width\resizebox{\bw}{!}{~OK~}} & \bitbox{7}{Data} \\
1315 % \end{bytefield}
1316 % \end{lrbox}
1317 %
1318 % \bigskip
1319 %
1320 % \begin{tabular}{ll}
1321 % \emph{Default}: & \raisebox{-4ex}{\usebox{\defaultOK}} \\
1322 % |\bytefieldsetup{%|
1323 % & \multirow{2}*{\raisebox{-4ex}{\usebox{\bitwidthOK}}} \\
1324 % | bitwidth=\widthof{OK~}}|: & \\[2ex]
1325 % |\tiny OK|: & \raisebox{-4ex}{\usebox{\tinyOK}} \\
1326 % |\tiny O \\ K|: & \raisebox{-4ex}{\usebox{\verticalOK}} \\
1327 % |\rotatebox{90}{\small OK}|: & \raisebox{-4ex}{\usebox{\rotateOK}} \\
1328 % |\let\bw=\width| & \multirow{2}*{\raisebox{-4ex}{\usebox{\resizeOK}}} \\
1329 % |\resizebox{\bw}{!}{~OK~}|: & \\[2ex]
1330 % \end{tabular}
1331 %
1332 % \paragraph{Multi-line bit fields}
1333 % Presentations of wide registers are often easier to read when split
1334 % across multiple lines. (This capability was originally requested by
1335 % Chris L'Esperance and is currently implemented in \pkgname{bytefield}
1336 % based on code provided by Renaud Pacalet.) The trick behind the
1337 % typesetting of multi-line bit fields is to pass the \optname{lsb}
1338 % option to |\bitheader| to change the starting bit number used in each
1339 % bit header:
1340 %
1341 % \begin{verbatim}
1342 % \begin{bytefield}[endianness=big,bitwidth=2em]{16}
1343 % \bitheader[lsb=16]{16-31} \\
1344 % \bitbox{1}{\tiny Enable} & \bitbox{7}{Reserved}
1345 % & \bitbox{8}{Bus} \\[3ex]
1346 % \bitheader{0-15} \\
1347 % \bitbox{5}{Device} & \bitbox{3}{Function} & \bitbox{6}{Register}
1348 % & \bitbox{2}{00}
1349 % \end{bytefield}
1350 % \end{verbatim}
1351 %
1352 % \begin{bffigure}
1353 % \begin{bytefield}[endianness=big,bitwidth=2em]{16}
1354 % \bitheader[lsb=16]{16-31} \\
1355 % \bitbox{1}{\tiny Enable} & \bitbox{7}{Reserved}
1356 % & \bitbox{8}{Bus} \\[3ex]
1357 % \bitheader{0-15} \\
1358 % \bitbox{5}{Device} & \bitbox{3}{Function} & \bitbox{6}{Register}
1359 % & \bitbox{2}{00}
1360 % \end{bytefield}
1361 % \end{bffigure}
1362 %
1363 % Note the use of the optional argument to |\\| to introduce three
1364 % \mbox{x-heights} of additional whitespace between the two rows of
1365 % bits.
1366 %
1367 % \paragraph{Rotated bit labels}
1368 % A problem with using very large bit numbers is that the labels run
1369 % into each other, as in the following example:
1370 %
1371 % \begin{verbatim}
1372 % \begin{bytefield}[endianness=big]{8}
1373 % \bitheader[lsb=995]{995-1002} \\
1374 % \bitbox{4}{A} & \bitbox{4}{B}
1375 % \end{bytefield}
1376 % \end{verbatim}
1377 %
1378 % \begin{bffigure}
1379 % \begin{bytefield}[endianness=big]{8}
1380 % \bitheader[lsb=995]{995-1002} \\
1381 % \bitbox{4}{A} & \bitbox{4}{B}
1382 % \end{bytefield}
1383 % \end{bffigure}
1384 %
1385 % One solution is to use the \optname{bitformatting} option and the
1386 % \pkgname{graphicx} package's |\rotatebox| command to rotate each bit
1387 % label by 90\textdegree. Unfortunately, the naive use of
1388 % \optname{bitformatting} and |\rotatebox| does not typeset nicely:
1389 %
1390 % \begin{verbatim}
1391 % \begin{bytefield}[endianness=big]{8}
1392 % \bitheader[lsb=995,
1393 % bitformatting={\tiny\rotatebox[origin=B]{90}}]{995-1002} \\
1394 % \bitbox{4}{A} & \bitbox{4}{B}
1395 % \end{bytefield}
1396 % \end{verbatim}
1397 %
1398 % \begin{bffigure}
1399 % \begin{bytefield}[endianness=big]{8}
1400 % \bitheader[lsb=995,
1401 % bitformatting={\tiny\rotatebox[origin=B]{90}}]{995-1002} \\
1402 % \bitbox{4}{A} & \bitbox{4}{B}
1403 % \end{bytefield}
1404 % \end{bffigure}
1405 %
1406 % The two problems are that (1)~the numbers are left-justified, and
1407 % (2)~the numbers touch the top margin of the word box. To address these
1408 % problems we use |\makebox| to construct a right-justified region that
1409 % is sufficiently wide to hold our largest number plus some additional
1410 % space to shift the rotated numbers upwards:
1411 %
1412 % \begin{verbatim}
1413 % \newlength{\bitlabelwidth}
1414 % \newcommand{\rotbitheader}[1]{%
1415 % \tiny
1416 % \settowidth{\bitlabelwidth}{\quad 9999}%
1417 % \rotatebox[origin=B]{90}{\makebox[\bitlabelwidth][r]{#1}}%
1418 % }
1419 %
1420 % \begin{bytefield}[endianness=big]{8}
1421 % \bitheader[lsb=995,bitformatting=\rotbitheader]{995-1002} \\
1422 % \bitbox{4}{A} & \bitbox{4}{B}
1423 % \end{bytefield}
1424 % \end{verbatim}
1425 %
1426 % \begin{bffigure}
1427 % \newlength{\bitlabelwidth}
1428 % \newcommand{\rotbitheader}[1]{^^A
1429 % \tiny
1430 % \settowidth{\bitlabelwidth}{\quad 9999}%
1431 % \rotatebox[origin=B]{90}{\makebox[\bitlabelwidth][r]{#1}}^^A
1432 % }
1433 %
1434 % \begin{bytefield}[endianness=big]{8}
1435 % \bitheader[lsb=995,bitformatting=\rotbitheader]{995-1002} \\
1436 % \bitbox{4}{A} & \bitbox{4}{B}
1437 % \end{bytefield}
1438 % \end{bffigure}
1439 %
1440 % \paragraph{Unused bits}
1441 % The \optname{bgcolor} option can be used to represent unused bits by
1442 % specifying a background fill color---light gray looks nice---and empty
1443 % text:
1444 %
1445 % \begin{verbatim}
1446 % \definecolor{lightgray}{gray}{0.8}
1447 % \begin{bytefield}{32}
1448 % \bitheader{0,4,8,12,16,20,24,28} \\
1449 % \bitbox{8}{Tag} & \bitbox{8}{Value} &
1450 % \bitbox{4}[bgcolor=lightgray]{} &
1451 % \bitbox{12}{Mask} \\
1452 % \wordbox{1}{Key}
1453 % \end{bytefield}
1454 % \end{verbatim}
1455 %
1456 % \definecolor{lightgray}{gray}{0.8}
1457 % \begin{bffigure}
1458 % \begin{bytefield}{32}
1459 % \bitheader{0,4,8,12,16,20,24,28} \\
1460 % \bitbox{8}{Tag} & \bitbox{8}{Value} &
1461 % \bitbox{4}[bgcolor=lightgray]{} &
1462 % \bitbox{12}{Mask} \\
1463 % \wordbox{1}{Key}
1464 % \end{bytefield}
1465 % \end{bffigure}
1466 %
1467 % \paragraph{Aligning text on the baseline}
1468 % Because \pkgname{bytefield} internally uses \LaTeX's |picture|
1469 % environment and that environment's |\makebox| command to draw bit
1470 % boxes and word boxes, the text within a box is centered vertically
1471 % with no attention paid to the text's baseline. As a result, some
1472 % bit-field labels appear somewhat askew:
1473 %
1474 % \begin{verbatim}
1475 % \begin{bytefield}[bitwidth=1.5em]{2}
1476 % \bitbox{1}{M} & \bitbox{1}{y}
1477 % \end{bytefield}
1478 % \end{verbatim}
1479 %
1480 % \begin{bffigure}
1481 % \begin{bytefield}[bitwidth=1.5em]{2}
1482 % \bitbox{1}{M} & \bitbox{1}{y}
1483 % \end{bytefield}
1484 % \end{bffigure}
1485 %
1486 % A solution is to use the \optname{boxformatting} option to trick
1487 % |\makebox| into thinking that all text has the same height and depth.
1488 % Here we use |\raisebox| to indicate that all text is as tall as a
1489 % ``|W|'' and does not descend at all below the baseline:
1490 %
1491 % \begin{verbatim}
1492 % \newlength{\maxheight}
1493 % \setlength{\maxheight}{\heightof{W}}
1494 %
1495 % \newcommand{\baselinealign}[1]{%
1496 % \centering
1497 % \raisebox{0pt}[\maxheight][0pt]{#1}%
1498 % }
1499 %
1500 % \begin{bytefield}[boxformatting=\baselinealign,
1501 % bitwidth=1.5em]{2}
1502 % \bitbox{1}{M} & \bitbox{1}{y}
1503 % \end{bytefield}
1504 % \end{verbatim}
1505 %
1506 % \begin{bffigure}
1507 % \newlength{\maxheight}
1508 % \setlength{\maxheight}{\heightof{W}}
1509 % \newcommand{\baselinealign}[1]{^^A
1510 % \centering
1511 % \raisebox{0pt}[\maxheight][0pt]{#1}^^A
1512 % }
1513 % \begin{bytefield}[boxformatting=\baselinealign,
1514 % bitwidth=1.5em]{2}
1515 % \bitbox{1}{M} & \bitbox{1}{y}
1516 % \end{bytefield}
1517 % \end{bffigure}
1518 %
1519 % \paragraph{Register contents}
1520 % Sometimes, rather than listing the \emph{meaning} of each bit field
1521 % within each |\bitbox| or |\wordbox|, it may be desirable to list the
1522 % \emph{contents}, with the meaning described in an additional label
1523 % above each bit number in the bit header. Although the
1524 % \pkgname{register} package is more suited to this form of layout,
1525 % \pkgname{bytefield} can serve in a pinch with the help of the
1526 % |\turnbox| macro from the \pkgname{rotating} package:
1527 %
1528 % \begin{verbatim}
1529 % \newcommand{\bitlabel}[2]{%
1530 % \bitbox[]{#1}{%
1531 % \raisebox{0pt}[4ex][0pt]{%
1532 % \turnbox{45}{\fontsize{7}{7}\selectfont#2}%
1533 % }%
1534 % }%
1535 % }
1536 %
1537 % \begin{bytefield}[bitwidth=1em]{16}
1538 % \bitlabel{1}{Carry} & \bitlabel{1}{Reserved} &
1539 % \bitlabel{1}{Parity} & \bitlabel{1}{Reserved} &
1540 % \bitlabel{1}{Adjust} & \bitlabel{1}{Reserved} &
1541 % \bitlabel{1}{Zero} & \bitlabel{1}{Sign} &
1542 % \bitlabel{1}{Trap} & \bitlabel{1}{Interrupt enable} &
1543 % \bitlabel{1}{Direction} & \bitlabel{1}{Overflow} &
1544 % \bitlabel{2}{I/O privilege level (12--13)} &
1545 % \bitlabel{1}{Nested task} & \bitlabel{1}{Reserved} \\
1546 % \bitheader{0-15} \\
1547 % \bitbox{1}{0} & \bitbox{1}{1} & \bitbox{1}{0} & \bitbox{1}{0} &
1548 % \bitbox{1}{0} & \bitbox{1}{0} & \bitbox{1}{0} & \bitbox{1}{1} &
1549 % \bitbox{1}{0} & \bitbox{1}{1} & \bitbox{1}{0} & \bitbox{1}{0} &
1550 % \bitbox{1}{0} & \bitbox{1}{0} & \bitbox{1}{0} & \bitbox{1}{0}
1551 % \end{bytefield}
1552 % \end{verbatim}
1553 %
1554 % \vspace{3\baselineskip} ^^A Allow extra room for the rotated headers.
1555 % \begin{bffigure}
1556 % \newcommand{\bitlabel}[2]{%
1557 % \bitbox[]{#1}{%
1558 % \raisebox{0pt}[4ex][0pt]{%
1559 % \turnbox{45}{\fontsize{7}{7}\selectfont#2}%
1560 % }%
1561 % }%
1562 % }
1563 % \begin{bytefield}[bitwidth=1em]{16}
1564 % \bitlabel{1}{Carry} & \bitlabel{1}{Reserved} &
1565 % \bitlabel{1}{Parity} & \bitlabel{1}{Reserved} &
1566 % \bitlabel{1}{Adjust} & \bitlabel{1}{Reserved} &
1567 % \bitlabel{1}{Zero} & \bitlabel{1}{Sign} &
1568 % \bitlabel{1}{Trap} & \bitlabel{1}{Interrupt enable} &
1569 % \bitlabel{1}{Direction} & \bitlabel{1}{Overflow} &
1570 % \bitlabel{2}{I/O privilege level (12--13)} &
1571 % \bitlabel{1}{Nested task} & \bitlabel{1}{Reserved} \\
1572 % \bitheader{0-15} \\
1573 % \bitbox{1}{0} & \bitbox{1}{1} & \bitbox{1}{0} & \bitbox{1}{0} &
1574 % \bitbox{1}{0} & \bitbox{1}{0} & \bitbox{1}{0} & \bitbox{1}{1} &
1575 % \bitbox{1}{0} & \bitbox{1}{1} & \bitbox{1}{0} & \bitbox{1}{0} &
1576 % \bitbox{1}{0} & \bitbox{1}{0} & \bitbox{1}{0} & \bitbox{1}{0}
1577 % \end{bytefield}
1578 % \end{bffigure}
1579 %
1580 %
1581 % \subsection{Not-so-common tricks}
1582 %
1583 % \paragraph{Omitted bit numbers}
1584 % It is occasionally convenient to show a wide bit field in which the
1585 % middle numbers are replaced with an ellipsis. The trick to
1586 % typesetting such a thing with \pkgname{bytefield} is to point the
1587 % |bitformatting| option to a macro that conditionally modifies the
1588 % given bit number before outputting it. One catch is that
1589 % \pkgname{bytefield} measures the height of the string ``|1234567890|''
1590 % using the current bit formatting, so that needs to be a valid input.
1591 % (If \optname{bitwidth} is set to ``|auto|'', then ``|99i|'' also has
1592 % to be a valid input, but we're not using ``|auto|'' here.) The
1593 % following example shows how to \emph{conditionally} modify the bit
1594 % number: If the number is |1234567890|, it is used as is; numbers
1595 % greater than~9 are increased by 48; numbers less than~4 are
1596 % unmodified; the number~6 is replaced by an ellipsis; and all other
1597 % numbers are discarded.
1598 %
1599 % \begin{verbatim}
1600 % \newcommand{\fakesixtyfourbits}[1]{%
1601 % \tiny
1602 % \ifnum#1=1234567890
1603 % #1
1604 % \else
1605 % \ifnum#1>9
1606 % \count32=#1
1607 % \advance\count32 by 48
1608 % \the\count32%
1609 % \else
1610 % \ifnum#1<4
1611 % #1%
1612 % \else
1613 % \ifnum#1=6
1614 % $\cdots$%
1615 % \fi
1616 % \fi
1617 % \fi
1618 % \fi
1619 % }
1620 % \begin{bytefield}[%
1621 % bitwidth=\widthof{\tiny Fwd~},
1622 % bitformatting=\fakesixtyfourbits,
1623 % endianness=big]{16}
1624 % \bitheader{0-15} \\
1625 % \bitbox{1}{\tiny F/E} & \bitbox{1}{\tiny T0} & \bitbox{1}{\tiny T1}
1626 % & \bitbox{1}{\tiny Fwd} & \bitbox{12}{Data value}
1627 % \end{bytefield}
1628 % \end{verbatim}
1629 %
1630 % \begin{bffigure}
1631 % \newcommand{\fakesixtyfourbits}[1]{%
1632 % \tiny
1633 % \ifnum#1=1234567890
1634 % #1
1635 % \else
1636 % \ifnum#1>9
1637 % \count32=#1
1638 % \advance\count32 by 48
1639 % \the\count32^^A
1640 % \else
1641 % \ifnum#1<4
1642 % #1%
1643 % \else
1644 % \ifnum#1=6
1645 % $\cdots$^^A
1646 % \fi
1647 % \fi
1648 % \fi
1649 % \fi
1650 % }
1651 % \begin{bytefield}[^^A
1652 % bitwidth=\widthof{\tiny Fwd~},
1653 % bitformatting=\fakesixtyfourbits,
1654 % endianness=big]{16}
1655 % \bitheader{0-15} \\
1656 % \bitbox{1}{\tiny F/E} & \bitbox{1}{\tiny T0} & \bitbox{1}{\tiny T1}
1657 % & \bitbox{1}{\tiny Fwd} & \bitbox{12}{Data value}
1658 % \end{bytefield}
1659 % \end{bffigure}
1660 %
1661 % \paragraph{Memory-map diagrams}
1662 % While certainly not the intended purpose of the \pkgname{bytefield}
1663 % package, one can utilize word boxes with empty \meta{sides} and
1664 % word labels to produce memory-map diagrams:
1665 %
1666 % \begin{verbatim}
1667 % \newcommand{\descbox}[2]{\parbox[c][3.8\baselineskip]{0.95\width}{%
1668 % \raggedright #1\vfill #2}}
1669 % \begin{bytefield}[bitheight=4\baselineskip]{32}
1670 % \begin{rightwordgroup}{Partition 4}
1671 % \bitbox[]{8}{\texttt{0xFFFFFFFF} \\[2\baselineskip]
1672 % \texttt{0xC0000000}} &
1673 % \bitbox{24}{\descbox{1\,GB area for VxDs, memory manager,
1674 % file system code; shared by all processes.}{Read/writable.}}
1675 % \end{rightwordgroup} \\
1676 % \begin{rightwordgroup}{Partition 3}
1677 % \bitbox[]{8}{\texttt{0xBFFFFFFF} \\[2\baselineskip]
1678 % \texttt{0x80000000}} &
1679 % \bitbox{24}{\descbox{1\,GB area for memory-mapped files,
1680 % shared system \textsc{dll}s, file system code; shared by all
1681 % processes.}{Read/writable.}}
1682 % \end{rightwordgroup} \\
1683 % \begin{rightwordgroup}{Partition 2}
1684 % \bitbox[]{8}{\texttt{0x7FFFFFFF} \\[2\baselineskip]
1685 % \texttt{0x00400000}} &
1686 % \bitbox{24}{\descbox{$\sim$2\,GB area private to process,
1687 % process code, and data.}{Read/writable.}}
1688 % \end{rightwordgroup} \\
1689 % \begin{rightwordgroup}{Partition 1}
1690 % \bitbox[]{8}{\texttt{0x003FFFFF} \\[2\baselineskip]
1691 % \texttt{0x00001000}} &
1692 % \bitbox{24}{\descbox{4\,MB area for MS-DOS and Windows~3.1
1693 % compatibility.}{Read/writable.}} \\
1694 % \bitbox[]{8}{\texttt{0x00000FFF} \\[2\baselineskip]
1695 % \texttt{0x00000000}} &
1696 % \bitbox{24}{\descbox{4096~byte area for MS-DOS and Windows~3.1
1697 % compatibility.}{Protected---catches \textsc{null}
1698 % pointers.}}
1699 % \end{rightwordgroup}
1700 % \end{bytefield}
1701 % \end{verbatim}
1702 %
1703 % \begin{bffigure}
1704 % \newcommand{\descbox}[2]{\parbox[c][3.8\baselineskip]{0.95\width}{%
1705 % \raggedright #1\vfill #2}}
1706 % \begin{bytefield}[bitheight=4\baselineskip]{32}
1707 % \begin{rightwordgroup}{Partition 4}
1708 % \bitbox[]{8}{\texttt{0xFFFFFFFF} \\[2\baselineskip]
1709 % \texttt{0xC0000000}} &
1710 % \bitbox{24}{\descbox{1\,GB area for VxDs, memory manager,
1711 % file system code; shared by all processes.}{Read/writable.}}
1712 % \end{rightwordgroup} \\
1713 % \begin{rightwordgroup}{Partition 3}
1714 % \bitbox[]{8}{\texttt{0xBFFFFFFF} \\[2\baselineskip]
1715 % \texttt{0x80000000}} &
1716 % \bitbox{24}{\descbox{1\,GB area for memory-mapped files,
1717 % shared system \textsc{dll}s, file system code; shared by all
1718 % processes.}{Read/writable.}}
1719 % \end{rightwordgroup} \\
1720 % \begin{rightwordgroup}{Partition 2}
1721 % \bitbox[]{8}{\texttt{0x7FFFFFFF} \\[2\baselineskip]
1722 % \texttt{0x00400000}} &
1723 % \bitbox{24}{\descbox{$\sim$2\,GB area private to process, process
1724 % code, and data.}{Read/writable.}}
1725 % \end{rightwordgroup} \\
1726 % \begin{rightwordgroup}{Partition 1}
1727 % \bitbox[]{8}{\texttt{0x003FFFFF} \\[2\baselineskip]
1728 % \texttt{0x00001000}} &
1729 % \bitbox{24}{\descbox{4\,MB area for MS-DOS and Windows~3.1
1730 % compatibility.}{Read/writable.}} \\
1731 % \bitbox[]{8}{\texttt{0x00000FFF} \\[2\baselineskip]
1732 % \texttt{0x00000000}} &
1733 % \bitbox{24}{\descbox{4096~byte area for MS-DOS and Windows~3.1
1734 % compatibility.}{Protected---catches \textsc{null}
1735 % pointers.}}
1736 % \end{rightwordgroup}
1737 % \end{bytefield}
1738 % \end{bffigure}
1739 %
1740 % The following variation uses variable-height regions in the memory map:
1741 % \changes{v2.1}{2012/09/02}{Included in the documentation a variable-height
1742 % memory-map example suggested by Martin Demling}
1743 %
1744 % \begin{verbatim}
1745 % \newcommand{\memsection}[4]{%
1746 % % define the height of the memsection
1747 % \bytefieldsetup{bitheight=#3\baselineskip}%
1748 % \bitbox[]{10}{%
1749 % \texttt{#1}% print end address
1750 % \\
1751 % % do some spacing
1752 % \vspace{#3\baselineskip}
1753 % \vspace{-2\baselineskip}
1754 % \vspace{-#3pt}
1755 % \texttt{#2}% print start address
1756 % }%
1757 % \bitbox{16}{#4}% print box with caption
1758 % }
1759 %
1760 % \begin{bytefield}{24}
1761 % \memsection{ffff ffff}{0040 0000}{15}{-- free --}\\
1762 % \begin{rightwordgroup}{internal memory}
1763 % \memsection{003f ffff}{002f c000}{4}{Special Function
1764 % Registers}\\
1765 % \memsection{002f bfff}{0007 0000}{3}{-- reserved --}\\
1766 % \memsection{0006 ffff}{0000 0000}{8}{Internal Flash}
1767 % \end{rightwordgroup}\\
1768 % \end{bytefield}
1769 % \end{verbatim}
1770 %
1771 % \begin{bffigure}
1772 % \newcommand{\memsection}[4]{^^A
1773 % \bytefieldsetup{bitheight=#3\baselineskip}^^A
1774 % \bitbox[]{10}{^^A
1775 % \texttt{#1}^^A
1776 % \\ \vspace{#3\baselineskip}\vspace{-2\baselineskip}\vspace{-#3pt}^^A
1777 % \texttt{#2}^^A
1778 % }^^A
1779 % \bitbox{16}{#4}^^A
1780 % }
1781 % \begin{bytefield}{24}
1782 % \memsection{ffff ffff}{0040 0000}{15}{-- free --}\\
1783 % \begin{rightwordgroup}{internal memory}
1784 % \memsection{003f ffff}{002f c000}{4}{Special Function Registers}\\
1785 % \memsection{002f bfff}{0007 0000}{3}{-- reserved --}\\
1786 % \memsection{0006 ffff}{0000 0000}{8}{Internal Flash}
1787 % \end{rightwordgroup}\\
1788 % \end{bytefield}
1789 % \end{bffigure}
1790 %
1791 %
1792 % \subsection{Putting it all together}
1793 %
1794 % The following code showcases most of \pkgname{bytefield}'s features in a
1795 % single figure.
1796 %
1797 % \begin{verbatim}
1798 % \begin{bytefield}[bitheight=2.5\baselineskip]{32}
1799 % \bitheader{0,7,8,15,16,23,24,31} \\
1800 % \begin{rightwordgroup}{\parbox{6em}{\raggedright These words were taken
1801 % verbatim from the TCP header definition (RFC~793).}}
1802 % \bitbox{4}{Data offset} & \bitbox{6}{Reserved} &
1803 % \bitbox{1}{\tiny U\\R\\G} & \bitbox{1}{\tiny A\\C\\K} &
1804 % \bitbox{1}{\tiny P\\S\\H} & \bitbox{1}{\tiny R\\S\\T} &
1805 % \bitbox{1}{\tiny S\\Y\\N} & \bitbox{1}{\tiny F\\I\\N} &
1806 % \bitbox{16}{Window} \\
1807 % \bitbox{16}{Checksum} & \bitbox{16}{Urgent pointer}
1808 % \end{rightwordgroup} \\
1809 % \wordbox[lrt]{1}{Data octets} \\
1810 % \skippedwords \\
1811 % \wordbox[lrb]{1}{} \\
1812 % \begin{leftwordgroup}{\parbox{6em}{\raggedright Note that we can display,
1813 % for example, a misaligned 64-bit value with clever use of the
1814 % optional argument to \texttt{\string\wordbox} and
1815 % \texttt{\string\bitbox}.}}
1816 % \bitbox{8}{Source} & \bitbox{8}{Destination} &
1817 % \bitbox[lrt]{16}{} \\
1818 % \wordbox[lr]{1}{Timestamp} \\
1819 % \begin{rightwordgroup}{\parbox{6em}{\raggedright Why two Length fields?
1820 % No particular reason.}}
1821 % \bitbox[lrb]{16}{} & \bitbox{16}{Length}
1822 % \end{leftwordgroup} \\
1823 % \bitbox{6}{Key} & \bitbox{6}{Value} & \bitbox{4}{Unused} &
1824 % \bitbox{16}{Length}
1825 % \end{rightwordgroup} \\
1826 % \wordbox{1}{Total number of 16-bit data words that follow this
1827 % header word, excluding the subsequent checksum-type value} \\
1828 % \bitbox{16}{Data~1} & \bitbox{16}{Data~2} \\
1829 % \bitbox{16}{Data~3} & \bitbox{16}{Data~4} \\
1830 % \bitbox[]{16}{$\vdots$ \\[1ex]} &
1831 % \bitbox[]{16}{$\vdots$ \\[1ex]} \\
1832 % \bitbox{16}{Data~$N-1$} & \bitbox{16}{Data~$N$} \\
1833 % \bitbox{20}{\[ \mbox{A5A5}_{\mbox{\scriptsize H}} \oplus
1834 % \left(\sum_{i=1}^N \mbox{Data}_i \right) \bmod 2^{20} \]} &
1835 % \bitboxes*{1}{000010 000110} \\
1836 % \wordbox{2}{64-bit random number}
1837 % \end{bytefield}
1838 % \end{verbatim}
1839 %
1840 % \noindent
1841 % Figure~\ref{fig:complex-diagram} shows the resulting protocol diagram.
1842 %
1843 % \begin{figure}[phtb]
1844 % \centering
1845 % \begin{lrbox}{\protocoldiagram}
1846 % \begin{bytefield}[bitheight=2.5\baselineskip]{32}
1847 % \bitheader{0,7,8,15,16,23,24,31} \\
1848 % \begin{rightwordgroup}{\parbox{6em}{\raggedright These words were taken
1849 % verbatim from the TCP header definition (RFC~793).}}
1850 % \bitbox{4}{Data offset} & \bitbox{6}{Reserved} &
1851 % \bitbox{1}{\tiny U\\R\\G} & \bitbox{1}{\tiny A\\C\\K} &
1852 % \bitbox{1}{\tiny P\\S\\H} & \bitbox{1}{\tiny R\\S\\T} &
1853 % \bitbox{1}{\tiny S\\Y\\N} & \bitbox{1}{\tiny F\\I\\N} &
1854 % \bitbox{16}{Window} \\
1855 % \bitbox{16}{Checksum} & \bitbox{16}{Urgent pointer}
1856 % \end{rightwordgroup} \\
1857 % \wordbox[lrt]{1}{Data octets} \\
1858 % \skippedwords \\
1859 % \wordbox[lrb]{1}{} \\
1860 % \begin{leftwordgroup}{\parbox{6em}{\raggedright Note that we can display,
1861 % for example, a misaligned 64-bit value with clever use of the
1862 % optional argument to \texttt{\string\wordbox} and
1863 % \texttt{\string\bitbox}.}}
1864 % \bitbox{8}{Source} & \bitbox{8}{Destination} & \bitbox[lrt]{16}{} \\
1865 % \wordbox[lr]{1}{Timestamp} \\
1866 % \begin{rightwordgroup}{\parbox{6em}{\raggedright Why two Length fields?
1867 % No particular reason.}}
1868 % \bitbox[lrb]{16}{} & \bitbox{16}{Length}
1869 % \end{leftwordgroup} \\
1870 % \bitbox{6}{Key} & \bitbox{6}{Value} & \bitbox{4}{Unused} &
1871 % \bitbox{16}{Length}
1872 % \end{rightwordgroup} \\
1873 % \wordbox{1}{Total number of 16-bit data words that follow this
1874 % header word, excluding the subsequent checksum-type value} \\
1875 % \bitbox{16}{Data~1} & \bitbox{16}{Data~2} \\
1876 % \bitbox{16}{Data~3} & \bitbox{16}{Data~4} \\
1877 % \bitbox[]{16}{$\vdots$ \\[1ex]} & \bitbox[]{16}{$\vdots$ \\[1ex]} \\
1878 % \bitbox{16}{Data~$N-1$} & \bitbox{16}{Data~$N$} \\
1879 % \bitbox{20}{\[ \mbox{A5A5}_{\mbox{\scriptsize H}} \oplus
1880 % \left(\sum_{i=1}^N \mbox{Data}_i \right) \bmod 2^{20} \]} &
1881 % \bitboxes*{1}{000010 000110} \\
1882 % \wordbox{2}{64-bit random number}
1883 % \end{bytefield}
1884 % \end{lrbox}
1885 % \makebox[0pt][c]{\usebox{\protocoldiagram}}
1886 % \caption{Complex protocol diagram drawn with the \pkgname{bytefield}
1887 % package}
1888 % \label{fig:complex-diagram}
1889 % \end{figure}
1890 %
1891 %
1892 % \subsection{Upgrading from older versions}
1893 % \label{sec:upgrading}
1894 %
1895 % \pkgname{bytefield}'s user interface changed substantially with the
1896 % introduction of version~2.0. Because documents written for
1897 % \pkgname{bytefield}~v1.\textit{x} will not build properly under later
1898 % versions of the package, this section explains how to convert documents
1899 % to the new interface.
1900 %
1901 % \begin{decl}
1902 % \SpecialUsageIndex{\wordgroupr}
1903 % |\wordgroupr| \\
1904 % \SpecialUsageIndex{\endwordgroupr}
1905 % |\endwordgroupr|
1906 % \end{decl}
1907 %
1908 % These have been replaced with the |rightwordgroup| environment to make
1909 % their invocation more \LaTeX-like. Use |\begin{rightwordgroup}|
1910 % instead of |\wordgroupr| and |\end{rightwordgroup}| instead of
1911 % |\endwordgroupr|.
1912 %
1913 % \begin{decl}
1914 % \SpecialUsageIndex{\wordgroupl}
1915 % |\wordgroupl| \\
1916 % \SpecialUsageIndex{\endwordgroupl}
1917 % |\endwordgroupl|
1918 % \end{decl}
1919 %
1920 % These have been replaced with the |leftwordgroup| environment to make
1921 % their invocation more \LaTeX-like. Use |\begin{leftwordgroup}|
1922 % instead of |\wordgroupl| and |\end{leftwordgroup}| instead of
1923 % |\endwordgroupl|.
1924 %
1925 % \begin{decl}
1926 % \SpecialUsageIndex{\bitwidth}
1927 % |\bitwidth|
1928 % \end{decl}
1929 %
1930 % Instead of changing bit widths with
1931 % |\setlength{\bitwidth}{|\meta{width}|}|, use
1932 % |\bytefieldsetup{bitwidth=|\meta{width}|}|.
1933 %
1934 % \begin{decl}
1935 % \SpecialUsageIndex{\byteheight}
1936 % |\byteheight|
1937 % \end{decl}
1938 %
1939 % Instead of changing bit heights with
1940 % |\setlength{\byteheight}{|\meta{height}|}|, use
1941 % |\bytefieldsetup{bitheight=|\meta{height}|}| (and note the change from
1942 % ``|byte|'' to ``|bit|'' for consistency with \optname{bitwidth}).
1943 %
1944 % \begin{decl}
1945 % \SpecialUsageIndex{\curlyspace}
1946 % |\curlyspace| \\
1947 % \SpecialUsageIndex{\labelspace}
1948 % |\labelspace|
1949 % \end{decl}
1950 %
1951 % Instead of using |\setlength{\curlyspace}{|\meta{dist}|}| and
1952 % |\setlength{\labelspace}{|\meta{dist}|}| to alter the horizontal space
1953 % that appears before and after a curly brace, use
1954 % |\bytefieldsetup{curlyspace=|\meta{dist}|}| and
1955 % |\bytefieldsetup{labelspace=|\meta{dist}|}|. Note that, as described
1956 % in Section~\ref{sec:basic-cmds}, left and right spacing can be set
1957 % independently if desired.
1958 %
1959 % \begin{decl}
1960 % \SpecialUsageIndex{\curlyshrinkage}
1961 % |\curlyshrinkage|
1962 % \end{decl}
1963 %
1964 % Instead of using |\setlength{\curlyshrinkage}{|\meta{dist}|}| to
1965 % reduce the vertical space occupied by a curly brace, use
1966 % |\bytefieldsetup{curlyshrinkage=|\meta{dist}|}|. Note that, as
1967 % described in Section~\ref{sec:basic-cmds}, left and right curly-brace
1968 % height can be reduced independently if desired.
1969 %
1970 % \begin{decl}
1971 % \SpecialUsageIndex{\bitwidth}
1972 % |\bitwidth| \oarg{endianness} \marg{bit-positions}
1973 % \end{decl}
1974 %
1975 % The meaning of |\bitwidth|'s optional argument changed with
1976 % \pkgname{bytefield}~v2.1. In older versions of the package, the
1977 % optional argument was one of ``|l|'' or ``|b|'' for, respectively,
1978 % little-endian or big-endian bit ordering. Starting with version~2.1,
1979 % the optional argument can be any of the parameters described in
1980 % Section~\ref{sec:options} (but practically only |bitformatting|,
1981 % |endianness|, and |lsb|). Hence, ``|l|'' should be replaced with
1982 % |endianness=little| and ``|b|'' should be replaced with
1983 % |endianness=big|. Although more verbose, these new options can be
1984 % specified once for the entire document by listing them as package
1985 % options or as arguments to |\bytefieldsetup|.
1986 %
1987 % \bigskip
1988 %
1989 % As a crutch to help build older documents with minimal modification,
1990 % \pkgname{bytefield} provides a |compat1| package option that restores
1991 % the old interface. This option, invoked with
1992 % |\usepackage[compat1]{bytefield}|, may disappear in a future version
1993 % of the package and should therefore not be relied upon as a long-term
1994 % approach to using \pkgname{bytefield}.
1995 %
1996 %
1997 % \StopEventually{^^A
1998 %
1999 % \section{Future work}
2000 %
2001 % \pkgname{bytefield} is my first \LaTeX\ package, and, as such, there
2002 % are a number of macros that could probably have been implemented a
2003 % lot better. For example, \pkgname{bytefield} is somewhat wasteful
2004 % of \meta{dimen} registers (although it did get a lot better with
2005 % version~1.1 and again with version~1.3). The package should really
2006 % get a major overhaul now that I've gotten better at \TeX\slash
2007 % \LaTeX\ programming. One minor improvement I'd like to make in the
2008 % package is to move left, small curly braces closer to the bit field.
2009 % In the following figure, notice how distant the small curly appears
2010 % from the bit-field body:
2011 %
2012 % \begin{bffigure}
2013 % \bytefieldsetup{bitheight=4ex}
2014 % \begin{bytefield}{16}
2015 % \begin{leftwordgroup}{Too distant}
2016 % \wordbox{1}{Something}
2017 % \end{leftwordgroup} \\
2018 % \begin{leftwordgroup}{Looks okay}
2019 % \wordbox{4}{Something else}
2020 % \end{leftwordgroup}
2021 % \end{bytefield}
2022 % \end{bffigure}
2023 %
2024 % \noindent
2025 % The problem is that the curly braces are left-aligned relative to
2026 % each other, while they should be right-aligned.
2027 % }
2028 %
2029 %
2030 % \section{Implementation}
2031 %
2032 % \newcommand{\usermacro}{^^A
2033 % \Needspace{2\baselineskip}^^A
2034 % \marginpar{\huge\raisebox{-1.5ex}[0pt][1.5ex]{\strut\hspace{18pt}$\star$}\par}^^A
2035 % }
2036 %
2037 % This section contains the complete source code for \pkgname{bytefield}.
2038 % Most users will not get much out of it, but it should be of use to
2039 % those who need more precise documentation and those who want to extend
2040 % (or debug~\smiley) the \pkgname{bytefield} package.
2041 %
2042 % In this section, macros marked in the margin with a ``{\Large
2043 % $\star$}'' are intended to be called by the user (and were described
2044 % in Section~\ref{sec:usage}). All other macros are used only
2045 % internally by \pkgname{bytefield}.
2046 %
2047 % \subsection{Required packages}
2048 %
2049 % Although |\widthof| and |\heightof| were introduced in June~1998,
2050 % te\kern-1.5pt\TeX~2.0---still in widespread use at the time of this
2051 % writing (2005)---ships with an earlier |calc.sty| in the |source|
2052 % directory. Because a misconfigured system may find the |source|
2053 % version of |calc.sty| we explicitly specify a later date when loading
2054 % the |calc| package.
2055 % \changes{v1.2a}{2005/07/31}{Specified an explicit package date when
2056 % loading the \pkgname{calc} package to avoid loading an outdated
2057 % version. Thanks to Kevin Quick for discovering that outdated versions
2058 % of \pkgname{calc} are still being included in \TeX{} distributions.}
2059 % \begin{macrocode}
2060 \RequirePackage{calc}[1998/07/07]
2061 \RequirePackage{keyval}
2062 % \end{macrocode}
2063 %
2064 %
2065 % \subsection{Utility macros}
2066 %
2067 % The following macros in this section are used by the box-drawing macros
2068 % and the ``skipped words''-drawing macros.
2069 %
2070 % \begin{macro}{\bf@newdimen@old}
2071 % \LaTeX's |\newdimen| defines new \meta{dimen}s globally.
2072 % |\bf@newdimen@old| defines them locally. It simply merges
2073 % \LaTeXe's |\newdimen| and |\alloc@| macros while omitting |\alloc@|'s
2074 % ``|\global|'' declaration. The ``|old|'' in the name implies that
2075 % |\bf@newdimen@old| is intended for use with older versions of \LaTeX.
2076 % \begin{macrocode}
2077 \def\bf@newdimen@old#1{\advance\count11 by 1
2078 \ch@ck1\insc@unt\dimen
2079 \allocationnumber=\count11
2080 \dimendef#1=\allocationnumber
2081 \wlog{\string#1=\string\dimen\the\allocationnumber\space (locally)}%
2082 }
2083 % \end{macrocode}
2084 % \end{macro}
2085 %
2086 % \begin{macro}{\bf@e@alloc}
2087 % Since 2014, \LaTeX\ has provided an internal |\e@alloc| macro that is
2088 % used to define |\newcount|, |\newdimen|, |\newskip|, etc. |\bf@e@alloc|
2089 % is a version of |\e@alloc| modified to allocate only within the current
2090 % scope. (It elides all uses of |\global|.) We use |\bf@e@alloc| to
2091 % define |\bf@newdimen|, which allocates a locally scoped \meta{dimen}.
2092 % \begin{macrocode}
2093 \def\bf@e@alloc#1#2#3#4#5#6{%
2094 \advance#3\@ne
2095 \e@ch@ck{#3}{#4}{#5}#1%
2096 \allocationnumber#3\relax
2097 #2#6\allocationnumber
2098 \wlog{\string#6=\string#1\the\allocationnumber\space (locally)}%
2099 }
2100 % \end{macrocode}
2101 % \end{macro}
2102 %
2103 % \begin{macro}{\bf@newdimen}
2104 % \changes{v1.1}{2002/09/15}{Bug fix: Added \cs{bf@newdimen} to greatly
2105 % reduce the likelihood of ``\texttt{No room for a new \string\cs{dimen}}''
2106 % errors (reported by Vitaly A. Repin)}
2107 % \changes{v1.3}{2010/10/31}{Added support for $\varepsilon$-\TeX's larger
2108 % local \meta{dimen} pool (code provided by Heiko Oberdiek)}
2109 % \changes{v2.3}{2015/10/28}{Rewrote the macro based on discussions with
2110 % David Carlisle to avoid producing ``\texttt{No room for a new
2111 % \cs{dimen}}'' errors in newer versions of $\varepsilon$-\TeX\
2112 % (see \url{http://tex.stackexchange.com/q/275042})}
2113 % \changes{v2.9}{2025/01/25}{Rewrite \cs{bf@newdimen} yet again so as to
2114 % allocate \meta{dimen}s locally in newer versions of \LaTeX. Thanks to
2115 % Qian Jin for the bug report}
2116 % \pkgname{bytefield} allocates a number of \meta{dimen}s, largely for
2117 % positioning curly braces. Because \TeX\ supports only 255
2118 % \meta{dimen}s, these normally would run out quickly for documents
2119 % containing many bit fields. $\varepsilon$-\TeX\ provides many more
2120 % \meta{dimen}s that the original \TeX, but it still would be preferable
2121 % not to consume them unnecessarily.
2122 %
2123 % This is where |\bf@newdimen| comes in. If the \pkgname{elocalloc}
2124 % package is loaded, |\bf@newdimen| is bound to \pkgname{elocalloc}'s
2125 % |\locdimen| macro. Otherwise, if |\e@alloc| is defined---this is the
2126 % common case---then |\bf@newdimen| is defined in terms of |\bf@e@alloc|
2127 % just like |\newdimen| is defined in terms of |\e@alloc|. As a last
2128 % resort, |\bf@newdimen| is bound to |\bf@newdimen@old| for use with old
2129 % versions of \LaTeX.
2130 % \begin{macrocode}
2131 \AtBeginDocument{%
2132 % \end{macrocode}
2133 % Is \pkgname{elocalloc} loaded?
2134 % \begin{macrocode}
2135 \expandafter\ifx\csname locdimen\endcsname\relax
2136 % \end{macrocode}
2137 % No. Are we running a reasonably recent \LaTeX?
2138 % \begin{macrocode}
2139 \expandafter\ifx\csname e@alloc\endcsname\relax
2140 % \end{macrocode}
2141 % No. Use |\bf@newdimen@old|, which was designed in terms of primitives
2142 % found in older versions of \LaTeX.
2143 % \begin{macrocode}
2144 \global\let\bf@newdimen=\bf@newdimen@old
2145 \else
2146 % \end{macrocode}
2147 % We are running a reasonably recent \LaTeX\@. Define |\bf@newdimen|
2148 % in terms of |\bf@e@alloc|, which allocates \meta{dimen}s locally.
2149 % \begin{macrocode}
2150 \gdef\bf@newdimen{%
2151 \bf@e@alloc\dimen \dimendef {\count11}\insc@unt\float@count
2152 }%
2153 \fi
2154 \else
2155 % \end{macrocode}
2156 % \pkgname{elocalloc} is loaded. Define |\bf@newdimen| in terms of
2157 % \pkgname{elocalloc}'s |\locdimen| macro.
2158 % \begin{macrocode}
2159 \let\bf@newdimen=\locdimen
2160 \fi
2161 }
2162 % \end{macrocode}
2163 % \end{macro}
2164 %
2165 % \begin{macro}{\bytefield@height}
2166 % \begin{macro}{\ifcounting@words}
2167 % When |\ifcounting@words| is \textsc{true}, add the height of the next
2168 % \texttt{picture} environment to |\bytefield@height|. We set
2169 % |\counting@wordstrue| at the beginning of each word, and
2170 % |\counting@wordsfalse| after each |\bitbox|, |\wordbox|, or |\skippedwords|
2171 % picture.
2172 % \begin{macrocode}
2173 \newlength{\bytefield@height}
2174 \newif\ifcounting@words
2175 % \end{macrocode}
2176 % \end{macro}
2177 % \end{macro}
2178 %
2179 % \begin{macro}{\inc@bytefield@height}
2180 % We have to define a special macro to increment |\bytefield@height|
2181 % because the \pkgname{calc} package's |\addtolength| macro doesn't seem
2182 % to see the global value. So we |\setlength| a temporary (to get
2183 % \pkgname{calc}'s nice infix features) and |\advance| |\bytefield@height|
2184 % by that amount.
2185 % \begin{macrocode}
2186 \newlength{\bytefield@height@increment}
2187 \DeclareRobustCommand{\inc@bytefield@height}[1]{%
2188 \setlength{\bytefield@height@increment}{#1}%
2189 \global\advance\bytefield@height by \bytefield@height@increment
2190 }
2191 % \end{macrocode}
2192 % \end{macro}
2193 %
2194 % \subsection{Top-level environment}
2195 %
2196 % \begin{macro}{\entire@bytefield@picture}
2197 % Declare a box for containing the entire bytefield. By storing
2198 % everything in a box and then typesetting it later (at the
2199 % |\end{bytefield}|), we can center the bit field, put a box around it,
2200 % and do other operations on the entire figure.
2201 % \begin{macrocode}
2202 \newsavebox{\entire@bytefield@picture}
2203 % \end{macrocode}
2204 % \end{macro}
2205 %
2206 % \begin{environment}{bytefield}
2207 % \usermacro
2208 % \changes{v2.4}{2017/09/15}{Make the code resilient to changes in
2209 % \texttt{\string\string\string\baselinestretch}. Thanks to
2210 % Karst Koymans for the bug report}
2211 % \begin{macro}{\bits@wide}
2212 % \begin{macro}{\old@nl}
2213 % \begin{macro}{\amp}
2214 % The |bytefield| environment contains the layout of bits in a sequence
2215 % of words. This is the main environment defined by the
2216 % \pkgname{bytefield} package. The argument is the number of bits wide
2217 % the bytefield should be. We turn |&| into a space character so the
2218 % user can think of a \pkgname{bytefield} as being analogous to a
2219 % \texttt{tabular} environment, even though we're really setting the
2220 % bulk of the picture in a single column. (Row labels go in separate
2221 % columns, however.)
2222 % \begin{macrocode}
2223 \newenvironment{bytefield}[2][]{%
2224 \bf@bytefieldsetup{#1}%
2225 \renewcommand{\baselinestretch}{}%
2226 \selectfont
2227 \def\bits@wide{#2}%
2228 \let\old@nl=\\%
2229 \let\amp=&%
2230 \catcode`\&=10
2231 \openup -1pt
2232 \setlength{\bytefield@height}{0pt}%
2233 \setlength{\unitlength}{1pt}%
2234 \global\counting@wordstrue
2235 \begin{lrbox}{\entire@bytefield@picture}%
2236 % \end{macrocode}
2237 % \end{macro}
2238 % \end{macro}
2239 % \end{macro}
2240 % \begin{macro}{\\}
2241 % \usermacro
2242 % We redefine |\\| within the |bytefield| environment to make it aware
2243 % of curly braces that surround the protocol diagram.
2244 % \changes{v2.1}{2011/06/12}{Augmented the definition
2245 % of~\texttt{\string\string\string\\} to accept an optional argument,
2246 % just like in a \texttt{tabular} environment}
2247 % \begin{macrocode}
2248 \renewcommand{\\}[1][0pt]{%
2249 \unskip
2250 \vspace{##1}%
2251 \amp\show@wordlabelr\cr
2252 \ignorespaces\global\counting@wordstrue\make@lspace\amp}%
2253 % \end{macrocode}
2254 % \end{macro}
2255 % \begin{macrocode}
2256 \vbox\bgroup\ialign\bgroup##\amp##\amp##\cr\amp
2257 }{%
2258 \unskip
2259 \amp\show@wordlabelr\cr\egroup\egroup
2260 \end{lrbox}%
2261 \usebox{\entire@bytefield@picture}%
2262 }
2263 % \end{macrocode}
2264 % \end{environment}
2265 %
2266 % \subsection{Box-drawing macros}
2267 %
2268 % \subsubsection{Drawing (proper)}
2269 %
2270 % \begin{macro}{\bf@bitformatting}
2271 % Format a bit number in the bit header. |\bf@bitformatting| may be
2272 % redefined to take either a single argument (\`a~la |\textbf|) or no
2273 % argument (\`a~la |\small|).
2274 % \changes{v1.4}{2011/01/15}{Introduced this macro at Steven R. King's
2275 % request to enable users to alter the bit header's font size}
2276 % \begin{macrocode}
2277 \newcommand*{\bf@bitformatting}{\tiny}
2278 % \end{macrocode}
2279 % \end{macro}
2280 %
2281 % \begin{macro}{\bf@boxformatting}
2282 % Format the text within a bit box or word box. |\bf@boxformatting|
2283 % takes either a single argument (\`a~la |\textbf|) or no argument
2284 % (\`a~la |\small|). The text that follows |\bf@boxformatting| is
2285 % guaranteed to be a group that ends in |\par|, so if
2286 % |\bf@boxformatting| accepts an argument, the macro should be defined
2287 % with |\long| (e.g.,~with |\newcommand| but not with |\newcommand*|).
2288 % \begin{macrocode}
2289 \newcommand*{\bf@boxformatting}{\centering}
2290 % \end{macrocode}
2291 % \end{macro}
2292 %
2293 % \begin{macro}{\bf@bitwidth}
2294 % Define the width of a single bit. Note that this is wide enough to
2295 % display a two-digit number without it running into adjacent numbers.
2296 % For larger words, be sure to |\setlength| this larger.
2297 % \begin{macrocode}
2298 \newlength{\bf@bitwidth}
2299 \settowidth{\bf@bitwidth}{\bf@bitformatting{99i}}
2300 % \end{macrocode}
2301 % \end{macro}
2302 %
2303 % \begin{macro}{\bf@bitheight}
2304 % This is the height of a single bit within the bit field.
2305 % \begin{macrocode}
2306 \newlength{\bf@bitheight}
2307 \setlength{\bf@bitheight}{4ex}
2308 % \end{macrocode}
2309 % \end{macro}
2310 %
2311 % \begin{macro}{\units@wide}
2312 % \begin{macro}{\units@tall}
2313 % These are scratch variables for storing the width and height (in
2314 % points) of the box we're about to draw.
2315 % \begin{macrocode}
2316 \newlength{\units@wide}
2317 \newlength{\units@tall}
2318 % \end{macrocode}
2319 % \end{macro}
2320 % \end{macro}
2321 %
2322 % \begin{macro}{\bf@call@box@cmd}
2323 % \begin{macro}{\bf@call@box@func}
2324 % Define any box-drawing macro that accepts the same set of four
2325 % arguments. It takes as input the name of a macro that is defined with
2326 % formal parameters |[#1]#2[#3]#4|. \cs{bf@call@box@cmd} then invokes
2327 % that macro, passing it a set of lines to draw out of the set
2328 % ``\texttt{lrtbLRTB}''~(|#1|), a number of bits or words~(|#2|), a list
2329 % of key/value pairs~(|#3|), and arbitrary text to typeset~(|#4|).
2330 % \begin{macrocode}
2331 \newcommand*{\bf@call@box@cmd}[1]{%
2332 \def\bf@call@box@func{#1}%
2333 \bf@call@box@cmd@i
2334 }
2335 % \end{macrocode}
2336 % \end{macro}
2337 % \end{macro}
2338 %
2339 % \begin{macro}{\bf@call@box@cmd@i}
2340 % \begin{macro}{\bf@call@box@arg@i}
2341 % \begin{macro}{\bf@call@box@arg@ii}
2342 % Store the set of lines and the bit/word count and invoke
2343 % \cs{bf@call@box@cmd@ii}.
2344 % \begin{macrocode}
2345 \newcommand*{\bf@call@box@cmd@i}[2][lrtb]{%
2346 \def\bf@call@box@arg@i{#1}%
2347 \def\bf@call@box@arg@ii{#2}%
2348 \bf@call@box@cmd@ii
2349 }
2350 % \end{macrocode}
2351 % \end{macro}
2352 % \end{macro}
2353 % \end{macro}
2354 %
2355 % \begin{macro}{\bf@call@box@cmd@ii}
2356 % \begin{macro}{\bf@call@box@arg@iii}
2357 % \begin{macro}{\bf@call@box@arg@iv}
2358 % Store the key/value parameters and the text to typeset then invoke the
2359 % macro originally passed to \cs{bf@call@box@cmd}.
2360 % \begin{macrocode}
2361 \newcommand*{\bf@call@box@cmd@ii}[2][]{%
2362 \def\bf@call@box@arg@iii{#1}%
2363 \def\bf@call@box@arg@iv{#2}%
2364 \bf@call@box@func
2365 }
2366 % \end{macrocode}
2367 % \end{macro}
2368 % \end{macro}
2369 % \end{macro}
2370 %
2371 % \begin{macro}{\bitbox}
2372 % \usermacro
2373 % Put some text~(|#4|) in a box that's a given number of bits~(|#2|)
2374 % wide and one byte tall. An optional argument~(|#1|) specifies which
2375 % lines to draw---|[l]|eft, |[r]|ight, |[t]|op, and/or |[b]|ottom
2376 % (default: |lrtb|). Additional drawing parameters can be provided via
2377 % another optional argument~(|#3|).
2378 % \begin{macrocode}
2379 \DeclareRobustCommand{\bitbox}{\bf@call@box@cmd{\bf@bitbox}}
2380 % \end{macrocode}
2381 % \end{macro}
2382 %
2383 % \begin{macro}{\bf@bitbox}
2384 % Implement all of the \cs{bitbox} logic.
2385 % \begin{macrocode}
2386 \def\bf@bitbox{%
2387 \bgroup
2388 \expandafter\bf@parse@bitbox@arg\expandafter{\bf@call@box@arg@i}%
2389 \setlength{\units@wide}{\bf@bitwidth * \bf@call@box@arg@ii}%
2390 \expandafter\bf@bytefieldsetup\expandafter{\bf@call@box@arg@iii}%
2391 \@ifundefined{bf@bgcolor}{%
2392 }{%
2393 % \end{macrocode}
2394 % If \optname{bgcolor} was specified, draw a colored rule of the full
2395 % size of the box.
2396 % \begin{macrocode}
2397 \rlap{%
2398 \draw@bit@picture{\strip@pt\units@wide}{\strip@pt\bf@bitheight}{%
2399 \color{\bf@bgcolor}%
2400 \rule{\width}{\height}%
2401 }%
2402 }%
2403 }%
2404 % \end{macrocode}
2405 % Draw the user-provided text on top of the rule (if any).
2406 % \begin{macrocode}
2407 \draw@bit@picture{\strip@pt\units@wide}{\strip@pt\bf@bitheight}{%
2408 \bf@call@box@arg@iv
2409 }%
2410 \egroup
2411 \ignorespaces
2412 }
2413 % \end{macrocode}
2414 % \end{macro}
2415 %
2416 % \begin{macro}{\wordbox}
2417 % \usermacro
2418 % Put some text~(|#4|) in a box that's a given number of bytes~(|#2|)
2419 % tall and one word (|\bits@wide| bits) wide. An optional
2420 % argument~(|#1|) specifies which lines to draw---|[l]|eft, |[r]|ight,
2421 % |[t]|op, and/or |[b]|ottom (default: |lrtb|). Additional drawing
2422 % parameters can be provided via another optional argument~(|#3|).
2423 % \begin{macrocode}
2424 \DeclareRobustCommand{\wordbox}{\bf@call@box@cmd{\bf@wordbox}}
2425 % \end{macrocode}
2426 % \end{macro}
2427 %
2428 % \begin{macro}{\bf@wordbox}
2429 % Implement all of the \cs{wordbox} logic.
2430 % \begin{macrocode}
2431 \def\bf@wordbox{%
2432 \bgroup
2433 \expandafter\bf@parse@bitbox@arg\expandafter{\bf@call@box@arg@i}%
2434 \setlength{\units@wide}{\bf@bitwidth * \bits@wide}%
2435 \setlength{\units@tall}{\bf@bitheight * \bf@call@box@arg@ii}%
2436 \expandafter\bf@bytefieldsetup\expandafter{\bf@call@box@arg@iii}%
2437 \@ifundefined{bf@bgcolor}{%
2438 }{%
2439 % \end{macrocode}
2440 % If \optname{bgcolor} was specified, draw a colored rule of the full
2441 % size of the box.
2442 % \begin{macrocode}
2443 \rlap{%
2444 \draw@bit@picture{\strip@pt\units@wide}{\strip@pt\units@tall}{%
2445 \color{\bf@bgcolor}%
2446 \rule{\width}{\height}%
2447 }%
2448 }%
2449 }%
2450 % \end{macrocode}
2451 % Draw the user-provided text on top of the rule (if any).
2452 % \begin{macrocode}
2453 \draw@bit@picture{\strip@pt\units@wide}{\strip@pt\units@tall}{%
2454 \bf@call@box@arg@iv
2455 }%
2456 % \end{macrocode}
2457 % Invoke the user-provided \cs{bf@per@word} macro once per word.
2458 % \begin{macrocode}
2459 \@ifundefined{bf@per@word}{}{\bf@invoke@per@word{\bf@call@box@arg@ii}}%
2460 \egroup
2461 \ignorespaces
2462 }
2463 % \end{macrocode}
2464 % \end{macro}
2465 %
2466 % \begin{macro}{\draw@bit@picture}
2467 % Put some text (|#3|) in a box that's a given number of units (|#1|)
2468 % wide and a given number of units (|#2|) tall.
2469 % We format the text with a |\parbox| to enable word-wrapping and explicit
2470 % line breaks. In addition, we define |\height|, |\depth|, |\totalheight|,
2471 % and |\width| (\`a la |\makebox| and friends), so the user can utilize
2472 % those for special effects (e.g., a |\rule| that fills the entire box).
2473 % As an added bonus, we define |\widthunits| and |\heightunits|, which
2474 % are the width and height of the box in multiples of |\unitlength|
2475 % (i.e., |#1| and |#2|, respectively).
2476 % \begin{macrocode}
2477 \DeclareRobustCommand{\draw@bit@picture}[3]{%
2478 \begin{picture}(#1,#2)%
2479 % \end{macrocode}
2480 % First, we plot the user's text, with all sorts of useful lengths
2481 % predefined.
2482 % \begin{macrocode}
2483 \put(0,0){\makebox(#1,#2){\parbox{#1\unitlength}{%
2484 \bf@set@user@dimens{#1}{#2}%
2485 \bf@boxformatting{#3\par}}}}%
2486 % \end{macrocode}
2487 % Next, we draw each line individually. I suppose we could make a special
2488 % case for ``all lines'' and use a |\framebox| above, but the following
2489 % works just fine.
2490 % \begin{macrocode}
2491 \ifbitbox@top
2492 \put(0,#2){\line(1,0){#1}}%
2493 \fi
2494 \ifbitbox@bottom
2495 \put(0,0){\line(1,0){#1}}%
2496 \fi
2497 \ifbitbox@left
2498 \put(0,0){\line(0,1){#2}}%
2499 \fi
2500 \ifbitbox@right
2501 \put(#1,0){\line(0,1){#2}}%
2502 \fi
2503 \end{picture}%
2504 % \end{macrocode}
2505 % Finally, we indicate that we're no longer at the beginning of a word.
2506 % The following code structure (albeit with different arguments to
2507 % |\inc@bytefield@height|) is repeated in various places throughout this
2508 % package. We document it only here, however.
2509 % \begin{macrocode}
2510 \ifcounting@words
2511 \inc@bytefield@height{\unitlength * \real{#2}}%
2512 \global\counting@wordsfalse
2513 \fi
2514 }
2515 % \end{macrocode}
2516 % \end{macro}
2517 %
2518 % \begin{macro}{\bf@invoke@per@word}
2519 % Invoke \cs{bf@per@word} once per word, passing it the (0-indexed) word
2520 % number and total number of words.
2521 % \begin{macrocode}
2522 \newcommand{\bf@invoke@per@word}[1]{%
2523 \begin{picture}(0,0)%
2524 \@tempcnta=0
2525 \@tempdima=#1\bf@bitheight
2526 % \end{macrocode}
2527 % Make various useful dimensions available to \cs{bf@per@word}.
2528 % \begin{macrocode}
2529 \bf@set@user@dimens{\strip@pt\units@wide}{\strip@pt\units@tall}%
2530 \loop
2531 \advance\@tempdima by -\bf@bitheight
2532 \bgroup
2533 \put(-\strip@pt\units@wide, \strip@pt\@tempdima){%
2534 \expandafter\bf@per@word\expandafter{\the\@tempcnta}{#1}%
2535 }%
2536 \egroup
2537 \advance\@tempcnta by 1\relax
2538 \ifnum#1>\@tempcnta
2539 \repeat
2540 \end{picture}%
2541 }
2542 % \end{macrocode}
2543 % \end{macro}
2544 %
2545 % \begin{macro}{\bf@set@user@dimens}
2546 % \mbox{}\vspace*{-1ex}
2547 % \begin{macro}{\width}
2548 % \usermacro
2549 % \begin{macro}{\height}
2550 % \usermacro
2551 % \begin{macro}{\depth}
2552 % \usermacro
2553 % \begin{macro}{\totalheight}
2554 % \usermacro
2555 % \begin{macro}{\widthunits}
2556 % \usermacro
2557 % \begin{macro}{\heightunits}
2558 % \usermacro
2559 % Given a width in bits~(|#1|) and a height in words~(|#2|), make a
2560 % number of box dimensions available to the author: \cs{width},
2561 % \cs{height}, \cs{depth}, \cs{totalheight}. Additionally, make the
2562 % arguments available to the author via the \cs{widthunits} and
2563 % \cs{heightunits} macros.
2564 % \begin{macrocode}
2565 \newcommand{\bf@set@user@dimens}[2]{%
2566 \bf@newdimen\width
2567 \bf@newdimen\height
2568 \bf@newdimen\depth
2569 \bf@newdimen\totalheight
2570 \width=#1\unitlength
2571 \height=#2\unitlength
2572 \depth=0pt%
2573 \totalheight=#2\unitlength
2574 \def\widthunits{#1}%
2575 \def\heightunits{#2}%
2576 }
2577 % \end{macrocode}
2578 % \end{macro}
2579 % \end{macro}
2580 % \end{macro}
2581 % \end{macro}
2582 % \end{macro}
2583 % \end{macro}
2584 % \end{macro}
2585 %
2586 % \begin{macro}{\bitboxes}
2587 % \usermacro
2588 % \changes{v2.2}{2014/06/01}{Added this macro based on an idea proposed
2589 % by Andrew Mertz}
2590 % \begin{macro}{\bitboxes*}
2591 % \usermacro
2592 % Put each token in |#3| into a box that's a given number of bits (|#2|)
2593 % wide and one byte tall. An optional argument (|#1|) specifies which
2594 % lines to draw---|[l]|eft, |[r]|ight, |[t]|op, and/or |[b]|ottom
2595 % (default: |lrtb|). The |*|-form of the command omits interior left
2596 % and right lines.
2597 % \begin{macrocode}
2598 \DeclareRobustCommand{\bitboxes}{%
2599 \@ifstar
2600 {\bf@call@box@cmd{\bf@bitboxes@star}}%
2601 {\bf@call@box@cmd{\bf@bitboxes@no@star}}%
2602 }
2603 % \end{macrocode}
2604 % \end{macro}
2605 % \end{macro}
2606 %
2607 % \begin{macro}{\bf@relax}
2608 % Define a macro that expands to |\relax| for use with |\ifx| tests
2609 % against |\bf@bitboxes@arg|, which can contain either tokens to typeset
2610 % or |\relax|.
2611 % \begin{macrocode}
2612 \def\bf@relax{\relax}
2613 % \end{macrocode}
2614 % \end{macro}
2615 %
2616 % \begin{macro}{\bf@bitboxes@no@star}
2617 % Implement the unstarred version of \cs{bitboxes}. This macro simply
2618 % expands its text argument into a list of tokens followed by \cs{relax}
2619 % then invokes \cs{bf@bitboxes@no@star@i}.
2620 % \begin{macrocode}
2621 \def\bf@bitboxes@no@star{%
2622 \expandafter\bf@bitboxes@no@star@i\bf@call@box@arg@iv\relax
2623 \ignorespaces
2624 }
2625 % \end{macrocode}
2626 % \end{macro}
2627 %
2628 % \begin{macro}{\bf@bitboxes@no@star@i}
2629 % Walk the subsequent tokens one-by-one until \cs{relax} is encountered.
2630 % For each token, invoke \cs{bf@bitbox} (the internal version of
2631 % \cs{bitbox} for which \cs{bf@call@box@arg@}\meta{number} are all
2632 % defined.
2633 % \begin{macrocode}
2634 \def\bf@bitboxes@no@star@i#1{%
2635 \def\bf@call@box@arg@iv{#1}%
2636 \ifx\bf@call@box@arg@iv\bf@relax
2637 \let\next=\relax
2638 \else
2639 \bf@bitbox
2640 \let\next=\bf@bitboxes@no@star@i
2641 \fi
2642 \next
2643 }
2644 % \end{macrocode}
2645 % \end{macro}
2646 %
2647 % \begin{macro}{\bf@bitboxes@star}
2648 % \begin{macro}{\bf@bitboxes@sides}
2649 % Implement the starred version of \cs{bitboxes}. This macro simply
2650 % stores the original \meta{sides} argument in \cs{bf@bitboxes@sides},
2651 % expands its text argument into a list of tokens followed by two
2652 % \cs{relax}es, and invokes \cs{bf@bitboxes@star@i}.
2653 % \begin{macrocode}
2654 \def\bf@bitboxes@star{%
2655 \edef\bf@bitboxes@sides{\bf@call@box@arg@i}%
2656 \expandafter\bf@bitboxes@star@i\bf@call@box@arg@iv\relax\relax
2657 \ignorespaces
2658 }
2659 % \end{macrocode}
2660 % \end{macro}
2661 % \end{macro}
2662 %
2663 % \begin{macro}{\bf@bitboxes@star@i}
2664 % \begin{macro}{\bf@call@box@arg@iv}
2665 % \begin{macro}{\bf@bitboxes@arg@ii}
2666 % \begin{macro}{\next}
2667 % Process the first token in the text argument passed to \cs{bitboxes*}.
2668 % If it's also the last token (indicated by its being followed by
2669 % \cs{relax}), draw an ordinary bit box with all sides present. If it's
2670 % not the last token, draw a bit box with the right side suppressed and
2671 % invoke \cs{bf@bitboxes@star@ii} on the remaining tokens.
2672 % \begin{macrocode}
2673 \def\bf@bitboxes@star@i#1#2{%
2674 \def\bf@call@box@arg@iv{#1}%
2675 \def\bf@bitboxes@arg@ii{#2}%
2676 \ifx\bf@bitboxes@arg@ii\bf@relax
2677 \bf@bitbox
2678 \let\next=\relax
2679 \else
2680 \edef\bf@call@box@arg@i{\bf@bitboxes@sides R}%
2681 \bf@bitbox
2682 \def\next{\bf@bitboxes@star@ii{#2}}%
2683 \fi
2684 \next
2685 }
2686 % \end{macrocode}
2687 % \end{macro}
2688 % \end{macro}
2689 % \end{macro}
2690 % \end{macro}
2691 %
2692 % \begin{macro}{\bf@bitboxes@star@ii}
2693 % \begin{macro}{\bf@call@box@arg@iv}
2694 % \begin{macro}{\bf@bitboxes@arg@ii}
2695 % \begin{macro}{\next}
2696 % Process the second and subsequent tokens in the text argument passed
2697 % to \cs{bitboxes*}. If the next token in the stream is the final one
2698 % (indicated by its being followed by \cs{relax}), draw a bit box with
2699 % the left side suppressed. If it's not the final token, draw a bit box
2700 % with both the left and right sides suppressed and invoke itself
2701 % recursively on the remaining tokens.
2702 % \begin{macrocode}
2703 \def\bf@bitboxes@star@ii#1#2{%
2704 \def\bf@call@box@arg@iv{#1}%
2705 \def\bf@bitboxes@arg@ii{#2}%
2706 \ifx\bf@bitboxes@arg@ii\bf@relax
2707 \edef\bf@call@box@arg@i{\bf@bitboxes@sides L}%
2708 \else
2709 \edef\bf@call@box@arg@i{\bf@bitboxes@sides LR}%
2710 \fi
2711 \ifx\bf@call@box@arg@iv\bf@relax
2712 \let\next=\relax
2713 \else
2714 \bf@bitbox
2715 \def\next{\bf@bitboxes@star@ii{#2}}%
2716 \fi
2717 \next
2718 }
2719 % \end{macrocode}
2720 % \end{macro}
2721 % \end{macro}
2722 % \end{macro}
2723 % \end{macro}
2724 %
2725 %
2726 % \subsubsection{Parsing arguments}
2727 %
2728 % The macros in this section are used to parse the optional argument to
2729 % \cs{bitbox}, \cs{wordbox}, and \cs{bitboxes}, which is some subset of
2730 % $\{ |l|, |r|, |t|, |b|, |L|, |R|, |T|, |B| \}$ and defaults to
2731 % ``|lrtb|'' for all three user macros. If the argument is empty, no
2732 % lines are drawn. Lowercase letters in the argument display,
2733 % respectively, the left, right, top, or bottom side of a box.
2734 % Uppercase letters undo the effect of the corresponding, prior,
2735 % lowercase letter and are used internally by \cs{bitboxes} to suppress
2736 % internal left and right lines.
2737 %
2738 % \begin{macro}{\ifbitbox@top}
2739 % \begin{macro}{\ifbitbox@bottom}
2740 % \begin{macro}{\ifbitbox@left}
2741 % \begin{macro}{\ifbitbox@right}
2742 % These macros are set to \textsc{true} if we're to draw the
2743 % corresponding edge on the subsequent |\bitbox| or |\wordbox|.
2744 % \begin{macrocode}
2745 \newif\ifbitbox@top
2746 \newif\ifbitbox@bottom
2747 \newif\ifbitbox@left
2748 \newif\ifbitbox@right
2749 % \end{macrocode}
2750 % \end{macro}
2751 % \end{macro}
2752 % \end{macro}
2753 % \end{macro}
2754 %
2755 % \begin{macro}{\bf@parse@bitbox@arg}
2756 % This main parsing macro merely resets the above conditionals and
2757 % calls a helper function, |\bf@parse@bitbox@sides|.
2758 % \begin{macrocode}
2759 \def\bf@parse@bitbox@arg#1{%
2760 \bitbox@topfalse
2761 \bitbox@bottomfalse
2762 \bitbox@leftfalse
2763 \bitbox@rightfalse
2764 \bf@parse@bitbox@sides#1X%
2765 }
2766 % \end{macrocode}
2767 % \end{macro}
2768 %
2769 % \begin{macro}{\bf@parse@bitbox@sides}
2770 % The helper function for |\bf@parse@bitbox@arg| parses a single letter,
2771 % sets the appropriate conditional to \textsc{true}, and calls itself
2772 % tail-recursively until it sees an~``|X|''.
2773 % \begin{macrocode}
2774 \def\bf@parse@bitbox@sides#1{%
2775 \ifx#1X%
2776 \else
2777 \ifx#1t%
2778 \bitbox@toptrue
2779 \else
2780 \ifx#1b%
2781 \bitbox@bottomtrue
2782 \else
2783 \ifx#1l%
2784 \bitbox@lefttrue
2785 \else
2786 \ifx#1r%
2787 \bitbox@righttrue
2788 \else
2789 \ifx#1T%
2790 \bitbox@topfalse
2791 \else
2792 \ifx#1B%
2793 \bitbox@bottomfalse
2794 \else
2795 \ifx#1L%
2796 \bitbox@leftfalse
2797 \else
2798 \ifx#1R%
2799 \bitbox@rightfalse
2800 \else
2801 \PackageWarning{bytefield}{Unrecognized box side `#1'}%
2802 \fi
2803 \fi
2804 \fi
2805 \fi
2806 \fi
2807 \fi
2808 \fi
2809 \fi
2810 \expandafter\bf@parse@bitbox@sides
2811 \fi
2812 }
2813 % \end{macrocode}
2814 % \end{macro}
2815 %
2816 % \subsection{Skipped words}
2817 %
2818 % \begin{macro}{\units@high}
2819 % This is the height of each diagonal line in the |\skippedwords|
2820 % graphic. Note that |\units@high|~$=$ |\units@tall|~$-$
2821 % \textit{optional argument to} |\skippedwords|.
2822 % \begin{macrocode}
2823 \newlength{\units@high}
2824 % \end{macrocode}
2825 % \end{macro}
2826 %
2827 % \begin{macro}{\skippedwords}
2828 % \usermacro
2829 % Output a fancy graphic representing skipped words. The optional argument
2830 % is the vertical space between the two diagonal lines (default: |2ex|).
2831 % \begin{macrocode}
2832 \DeclareRobustCommand{\skippedwords}[1][2ex]{%
2833 \setlength{\units@wide}{\bf@bitwidth * \bits@wide}%
2834 \setlength{\units@high}{1pt * \ratio{\units@wide}{6.0pt}}%
2835 \setlength{\units@tall}{#1 + \units@high}%
2836 \edef\num@wide{\strip@pt\units@wide}%
2837 \edef\num@tall{\strip@pt\units@tall}%
2838 \edef\num@high{\strip@pt\units@high}%
2839 \begin{picture}(\num@wide,\num@tall)
2840 \put(0,\num@tall){\line(6,-1){\num@wide}}
2841 \put(\num@wide,0){\line(-6,1){\num@wide}}
2842 \put(0,0){\line(0,1){\num@high}}
2843 \put(\num@wide,\num@tall){\line(0,-1){\num@high}}
2844 \end{picture}%
2845 \ifcounting@words
2846 \inc@bytefield@height{\unitlength * \real{\num@tall}}%
2847 \global\counting@wordsfalse
2848 \fi
2849 }
2850 % \end{macrocode}
2851 % \end{macro}
2852 %
2853 % \subsection{Bit-position labels}
2854 %
2855 % \begin{macro}{\bf@bit@endianness}
2856 % \pkgname{bytefield} can label bit headers in either little-endian ($0,
2857 % 1, 2,~\ldots, N-1$) or big-endian ($N-1, N-2, N-3,~\ldots, 0$) fashion.
2858 % The |\bf@bit@endianness| macro specifies which to use, either ``|l|''
2859 % for little-endian (the default) or ``|b|'' for big-endian.
2860 % \begin{macrocode}
2861 \newcommand*{\bf@bit@endianness}{l}
2862 % \end{macrocode}
2863 % \end{macro}
2864 %
2865 % \begin{macro}{\bf@first@bit}
2866 % Normally, bits are numbered starting from zero. However,
2867 % |\bf@first@bit| can be altered (usually locally) to begin numbering
2868 % from a different value.
2869 % \begin{macrocode}
2870 \newcommand*{\bf@first@bit}{0}
2871 % \end{macrocode}
2872 % \end{macro}
2873 %
2874 % \begin{macro}{\bitheader}
2875 % \usermacro
2876 % Output a header of numbered bit positions. The optional argument (|#1|)
2877 % is ``|l|'' for little-endian (default) or ``|b|'' for big-endian.
2878 % The required argument (|#2|) is a list of bit positions to label.
2879 % It is composed of comma-separated ranges of numbers, for example,
2880 % ``|0-31|'', ``|0,7-8,15-16,23-24,31|'', or even something odd like
2881 % ``|0-7,15-23|''. Ranges must be specified in increasing order; use the
2882 % \optname{lsb} option to reverse the labels' direction.
2883 % \changes{v2.1}{2011/06/17}{Changed the optional argument to accept
2884 % \meta{key}!=\meta{value} pairs instead of just ``\texttt{l}'' and
2885 % ``\texttt{b}''}
2886 % \begin{macrocode}
2887 \DeclareRobustCommand{\bitheader}[2][]{%
2888 \bf@parse@bitbox@arg{lrtb}%
2889 \setlength{\units@wide}{\bf@bitwidth * \bits@wide}%
2890 \setlength{\units@tall}{\heightof{\bf@bitformatting{1234567890}}}%
2891 \setlength{\units@high}{\units@tall * -1}%
2892 \bf@process@bitheader@opts{#1}%
2893 \begin{picture}(\strip@pt\units@wide,\strip@pt\units@tall)%
2894 (0,\strip@pt\units@high)
2895 \bf@parse@range@list#2,X,
2896 \end{picture}%
2897 \ifcounting@words
2898 \inc@bytefield@height{\unitlength * \real{\strip@pt\units@tall}}%
2899 \global\counting@wordsfalse
2900 \fi
2901 \ignorespaces
2902 }
2903 % \end{macrocode}
2904 % \end{macro}
2905 %
2906 % \begin{macro}{\bf@parse@range@list}
2907 % This is helper function~\#1 for |\bitheader|. It parses a
2908 % comma-separated list of ranges, calling |\bf@parse@range| on each
2909 % range.
2910 % \changes{v1.1}{2002/06/24}{Bug fix: Swapped order of arguments to
2911 % \texttt{\string\bslash\space ifx} test (suggested by Hans-Joachim
2912 % Widmaier)}
2913 % \begin{macrocode}
2914 \def\bf@parse@range@list#1,{%
2915 \ifx X#1
2916 \else
2917 \bf@parse@range#1-#1-#1\relax
2918 \expandafter\bf@parse@range@list
2919 \fi
2920 }
2921 % \end{macrocode}
2922 % \end{macro}
2923 %
2924 % \begin{macro}{\header@xpos}
2925 % \begin{macro}{header@val}
2926 % \begin{macro}{max@header@val}
2927 % Define some miscellaneous variables to be used internally by
2928 % |\bf@parse@range|: $x$~position of header, current label to output,
2929 % and maximum label to output ($+ 1$).
2930 % \begin{macrocode}
2931 \newlength{\header@xpos}
2932 \newcounter{header@val}
2933 \newcounter{max@header@val}
2934 % \end{macrocode}
2935 % \end{macro}
2936 % \end{macro}
2937 % \end{macro}
2938 %
2939 % \begin{macro}{\bf@parse@range}
2940 % This is helper function~\#2 for |\bitheader|. It parses a
2941 % hyphen-separated pair of numbers (or a single number) and displays the
2942 % number at the correct bit position.
2943 % \changes{v2.1}{2011/06/16}{Added code due to Renaud Pacalet for shifting
2944 % the bit header by a distance corresponding to
2945 % \texttt{\string\string\string\bf@first@bit}, used for typesetting
2946 % registers split across rows}
2947 % \begin{macrocode}
2948 \def\bf@parse@range#1-#2-#3\relax{%
2949 \setcounter{header@val}{#1}
2950 \setcounter{max@header@val}{#2 + 1}
2951 \loop
2952 \ifnum\value{header@val}<\value{max@header@val}%
2953 \if\bf@bit@endianness b%
2954 \setlength{\header@xpos}{%
2955 \bf@bitwidth * (\bits@wide - \value{header@val} + \bf@first@bit - 1)}%
2956 \else
2957 \setlength{\header@xpos}{\bf@bitwidth * (\value{header@val} - \bf@first@bit)}%
2958 \fi
2959 \put(\strip@pt\header@xpos,0){%
2960 \makebox(\strip@pt\bf@bitwidth,\strip@pt\units@tall){%
2961 \bf@bitformatting{\theheader@val}}}
2962 \addtocounter{header@val}{1}
2963 \repeat
2964 }
2965 % \end{macrocode}
2966 % \end{macro}
2967 %
2968 % \begin{macro}{\bf@process@bitheader@opts}
2969 % \begin{macro}{\KV@bytefield@l}
2970 % \begin{macro}{\KV@bytefield@b}
2971 % \begin{macro}{\KV@bytefield@l@default}
2972 % \begin{macro}{\KV@bytefield@b@default}
2973 % This is helper function~\#3 for |\bitheader|. It processes the
2974 % optional argument to |\bitheader|.
2975 % \begin{macrocode}
2976 \newcommand*{\bf@process@bitheader@opts}{%
2977 \let\KV@bytefield@l=\KV@bitheader@l
2978 \let\KV@bytefield@b=\KV@bitheader@b
2979 \let\KV@bytefield@l@default=\KV@bitheader@l@default
2980 \let\KV@bytefield@b@default=\KV@bitheader@b@default
2981 \setkeys{bytefield}%
2982 }
2983 % \end{macrocode}
2984 % \end{macro}
2985 % \end{macro}
2986 % \end{macro}
2987 % \end{macro}
2988 % \end{macro}
2989 %
2990 % \begin{macro}{\KV@bitheader@l}
2991 % \begin{macro}{\KV@bitheader@b}
2992 % For backwards compatibility we also accept the (now deprecated) |l| as
2993 % a synonym for |endianness=little| and |b| as a synonym for
2994 % |endianness=big|. A typical document will specify an |endianness|
2995 % option not as an argument to |\bitheader| but rather as a package
2996 % option that applies to the entire document. If the \optname{compat1}
2997 % option was provided to \pkgname{bytefield} (determined below by the
2998 % existence of the |\curlyshrinkage| control word), we suppress the
2999 % deprecation warning message.
3000 % \begin{macrocode}
3001 \define@key{bitheader}{l}[true]{%
3002 \expandafter\ifx\csname curlyshrinkage\endcsname\relax
3003 \PackageWarning{bytefield}{%
3004 The "l" argument to \protect\bitheader\space is deprecated.\MessageBreak
3005 Instead, please use "endianness=little", which can\MessageBreak
3006 even be declared globally for the entire document.\MessageBreak
3007 This warning occurred}%
3008 \fi
3009 \def\bf@bit@endianness{l}%
3010 }
3011 \define@key{bitheader}{b}[true]{%
3012 \expandafter\ifx\csname curlyshrinkage\endcsname\relax
3013 \PackageWarning{bytefield}{%
3014 The "b" argument to \protect\bitheader\space is deprecated.\MessageBreak
3015 Instead, please use "endianness=big", which can\MessageBreak
3016 even be declared globally for the entire document.\MessageBreak
3017 This warning occurred}%
3018 \fi
3019 \def\bf@bit@endianness{b}%
3020 }
3021 % \end{macrocode}
3022 % \end{macro}
3023 % \end{macro}
3024 %
3025 %
3026 % \subsection{Word labels}
3027 %
3028 % \subsubsection{Curly-brace manipulation}
3029 %
3030 % \begin{macro}{\bf@leftcurlyshrinkage}
3031 % \begin{macro}{\bf@rightcurlyshrinkage}
3032 % Reduce the height of a left (right) curly brace by
3033 % |\bf@leftcurlyshrinkage| (|\bf@rightcurlyshrinkage|) so its ends don't
3034 % overlap whatever is above or below it. The default value (5\,pt.) was
3035 % determined empirically and shouldn't need to be changed. However, on
3036 % the off-chance the user employs a math font with very different curly
3037 % braces from Computer Modern's, |\bf@leftcurlyshrinkage| and
3038 % |\bf@rightcurlyshrinkage| can be modified.
3039 % \begin{macrocode}
3040 \def\bf@leftcurlyshrinkage{5pt}
3041 \def\bf@rightcurlyshrinkage{5pt}
3042 % \end{macrocode}
3043 % \end{macro}
3044 % \end{macro}
3045 %
3046 % \begin{macro}{\bf@leftcurlyspace}
3047 % \begin{macro}{\bf@rightcurlyspace}
3048 % \begin{macro}{\bf@leftlabelspace}
3049 % \begin{macro}{\bf@rightlabelspace}
3050 % Define the amount of space to insert before a curly brace and before a
3051 % word label (i.e.,~after a curly brace).
3052 % \begin{macrocode}
3053 \def\bf@leftcurlyspace{1ex}
3054 \def\bf@rightcurlyspace{1ex}
3055 \def\bf@leftlabelspace{0.5ex}
3056 \def\bf@rightlabelspace{0.5ex}
3057 % \end{macrocode}
3058 % \end{macro}
3059 % \end{macro}
3060 % \end{macro}
3061 % \end{macro}
3062 %
3063 % \begin{macro}{\bf@leftcurly}
3064 % \begin{macro}{\bf@rightcurly}
3065 % Define the symbols to use as left and right curly braces. These
3066 % symbols must be extensible math symbols (i.e.,~they will immediately
3067 % follow |\left| or |\right| in math mode).
3068 % \begin{macrocode}
3069 \let\bf@leftcurly=\{
3070 \let\bf@rightcurly=\}
3071 % \end{macrocode}
3072 % \end{macro}
3073 % \end{macro}
3074 %
3075 % \begin{macro}{\bf@leftcurlystyle}
3076 % \begin{macro}{\bf@rightcurlystyle}
3077 % Define the default formatting for left and right curly braces as ``do
3078 % nothing special''.
3079 % \begin{macrocode}
3080 \let\bf@leftcurlystyle=\relax
3081 \let\bf@rightcurlystyle=\relax
3082 % \end{macrocode}
3083 % \end{macro}
3084 % \end{macro}
3085 %
3086 % \begin{macro}{\curly@box}
3087 % Define a box in which to temporarily store formatted curly braces.
3088 % \changes{v1.2}{2004/06/14}{Bug fix: Defined \cs{curly@box} globally
3089 % (suggested by Stefan Ulrich)}
3090 % \begin{macrocode}
3091 \newbox{\curly@box}
3092 % \end{macrocode}
3093 % \end{macro}
3094 %
3095 % \begin{macro}{\store@rcurly}
3096 % \changes{v2.7}{2021/08/17}{Properly align right curly braces under
3097 % Lua\string\LaTeX\ (bug reported by Georgi Nikiforov)}
3098 % \begin{macro}{\curly@height}
3099 % \begin{macro}{\half@curly@height}
3100 % \begin{macro}{\curly@shift}
3101 % \begin{macro}{\old@axis}
3102 % Store a ``\}'' that's |#2| tall in box |#1|.
3103 % The only unintuitive thing here is that we have to redefine
3104 % |\fontdimen22|---axis height---to~0\,pt.\ before typesetting the curly
3105 % brace. Otherwise, the brace would be vertically off-center by a few
3106 % points. When we're finished, we reset it back to its old value.
3107 % \begin{macrocode}
3108 \def\store@rcurly#1#2{%
3109 \begingroup
3110 \bf@newdimen\curly@height
3111 \setlength{\curly@height}{#2 - \bf@rightcurlyshrinkage}%
3112 \bf@newdimen\half@curly@height
3113 \setlength{\half@curly@height}{0.5\curly@height}%
3114 \bf@newdimen\curly@shift
3115 \setlength{\curly@shift}{\bf@rightcurlyshrinkage}%
3116 \setlength{\curly@shift}{\half@curly@height + 0.5\curly@shift}%
3117 \addtolength{\curly@shift}{-\fontdimen22\textfont2}%
3118 \global\sbox{#1}{\raisebox{\curly@shift}{%
3119 \bf@rightcurlystyle{%
3120 $\left.
3121 \vrule height\half@curly@height
3122 width 0pt
3123 depth\half@curly@height\right\bf@rightcurly$%
3124 }%
3125 }}%
3126 \endgroup
3127 }
3128 % \end{macrocode}
3129 % \end{macro}
3130 % \end{macro}
3131 % \end{macro}
3132 % \end{macro}
3133 % \end{macro}
3134 %
3135 % \begin{macro}{\store@lcurly}
3136 % \changes{v2.7}{2021/08/17}{Properly align left curly braces under
3137 % Lua\string\LaTeX\ (bug reported by Georgi Nikiforov)}
3138 % \begin{macro}{\curly@height}
3139 % \begin{macro}{\half@curly@height}
3140 % \begin{macro}{\curly@shift}
3141 % These are the same as |\store@rcurly|, etc.\ but using a ``\{''
3142 % instead of a ``\}''.
3143 % \begin{macrocode}
3144 \def\store@lcurly#1#2{%
3145 \begingroup
3146 \bf@newdimen\curly@height
3147 \setlength{\curly@height}{#2 - \bf@leftcurlyshrinkage}%
3148 \bf@newdimen\half@curly@height
3149 \setlength{\half@curly@height}{0.5\curly@height}%
3150 \bf@newdimen\curly@shift
3151 \setlength{\curly@shift}{\bf@leftcurlyshrinkage}%
3152 \setlength{\curly@shift}{\half@curly@height + 0.5\curly@shift}%
3153 \addtolength{\curly@shift}{-\fontdimen22\textfont2}%
3154 \global\sbox{#1}{\raisebox{\curly@shift}{%
3155 \bf@leftcurlystyle{%
3156 $\left\bf@leftcurly
3157 \vrule height\half@curly@height
3158 width 0pt
3159 depth\half@curly@height\right.$%
3160 }%
3161 }}%
3162 \endgroup
3163 }
3164 % \end{macrocode}
3165 % \end{macro}
3166 % \end{macro}
3167 % \end{macro}
3168 % \end{macro}
3169 %
3170 % \subsubsection{Right-side labels}
3171 %
3172 % \begin{macro}{\show@wordlabelr}
3173 % This macro is output in the third column of every row of the
3174 % |\ialign|ed bytefield table. It's normally a no-op, but
3175 % |\end{rightwordgroup}| defines it to output the word label and then
3176 % reset itself to a no-op.
3177 % \begin{macrocode}
3178 \def\show@wordlabelr{}
3179 % \end{macrocode}
3180 % \end{macro}
3181 %
3182 % \begin{macro}{\wordlabelr@start}
3183 % \begin{macro}{\wordlabelr@end}
3184 % Declare the starting and ending height (in points) of the set of rows
3185 % to be labeled on the right.
3186 % \begin{macrocode}
3187 \newlength{\wordlabelr@start}
3188 \newlength{\wordlabelr@end}
3189 % \end{macrocode}
3190 % \end{macro}
3191 % \end{macro}
3192 %
3193 % \begin{environment}{rightwordgroup}
3194 % \usermacro
3195 % Label the words defined between |\begin{rightwordgroup}| and
3196 % |\end{rightwordgroup}| on the right side of the bit field. The first,
3197 % optional, argument is a list of parameters, as defined in
3198 % Section~\ref{sec:options}. The second, mandatory, argument is the
3199 % text of the label. The label is typeset to the right of a large curly
3200 % brace, which groups the words together.
3201 % \changes{v2.6}{2020/10/29}{Suppress spaces following the
3202 % \protect\cs{end}\protect\texttt{\{rightwordgroup\}}}
3203 % \changes{v2.6}{2020/10/31}{Accept key/value options}
3204 % \begin{macrocode}
3205 \newenvironment{rightwordgroup}[2][]{%
3206 % \end{macrocode}
3207 % We begin by ending the group that |\begin{rightwordgroup}| created. This
3208 % lets the |rightwordgroup| environment span rows (because we're technically
3209 % no longer within the environment).
3210 % \begin{macrocode}
3211 \endgroup
3212 % \end{macrocode}
3213 % \begin{macro}{\wordlabelr@start}
3214 % \begin{macro}{\wordlabelr@params}
3215 % \begin{macro}{\wordlabelr@text}
3216 % |\begin{rightwordgroup}| merely stores the starting height in
3217 % |\wordlabelr@start| and the user-supplied text in |\wordlabelr@text|.
3218 % |\end{rightwordgroup}| does most of the work.
3219 % \begin{macrocode}
3220 \global\wordlabelr@start=\bytefield@height
3221 \gdef\wordlabelr@params{#1}%
3222 \gdef\wordlabelr@text{#2}%
3223 \ignorespaces
3224 }{%
3225 % \end{macrocode}
3226 % \end{macro}
3227 % \end{macro}
3228 % \end{macro}
3229 % \begin{macro}{\wordlabelr@end}
3230 % Because we already ended the group that |\begin{rightwordgroup}|
3231 % created we now have to begin a group for |\end{rightwordgroup}| to
3232 % end.
3233 % \begin{macrocode}
3234 \begingroup
3235 \global\wordlabelr@end=\bytefield@height
3236 % \end{macrocode}
3237 % \end{macro}
3238 % \begin{macro}{\show@wordlabelr}
3239 % Redefine |\show@wordlabelr| to output |\bf@rightcurlyspace| space,
3240 % followed by a large curly brace (in |\curlybox|), followed by
3241 % |\bf@rightlabelspace| space, followed by the user's text (previously
3242 % recorded in |\wordlabelr@text|). We typeset |\wordlabelr@text| within
3243 % a |tabular| environment, so \LaTeX\ will calculate its width
3244 % automatically.
3245 % \begin{macrocode}
3246 \gdef\show@wordlabelr{%
3247 \sbox{\word@label@box}{%
3248 \begin{tabular}[b]{@{}l@{}}\wordlabelr@text\end{tabular}%
3249 }%
3250 \settowidth{\label@box@width}{\usebox{\word@label@box}}%
3251 \setlength{\label@box@height}{\wordlabelr@end-\wordlabelr@start}%
3252 % \end{macrocode}
3253 % Evaluate any parameters passed to |\begin{rightwordgroup}| right
3254 % before we render the curly brace.
3255 % \begin{macrocode}
3256 \expandafter\bf@bytefieldsetup\expandafter{\wordlabelr@params}%
3257 \store@rcurly{\curly@box}{\label@box@height}%
3258 \bf@newdimen\total@box@width
3259 \setlength{\total@box@width}{%
3260 \bf@rightcurlyspace +
3261 \widthof{\usebox{\curly@box}} +
3262 \bf@rightlabelspace +
3263 \label@box@width
3264 }%
3265 \begin{picture}(\strip@pt\total@box@width,0)
3266 \put(0,0){%
3267 \hspace*{\bf@rightcurlyspace}%
3268 \usebox{\curly@box}%
3269 \hspace*{\bf@rightlabelspace}%
3270 \makebox(\strip@pt\label@box@width,\strip@pt\label@box@height){%
3271 \usebox{\word@label@box}%
3272 }%
3273 }%
3274 \end{picture}%
3275 % \end{macrocode}
3276 % The last thing |\show@wordlabelr| does is redefine itself back to a no-op.
3277 % \begin{macrocode}
3278 \gdef\show@wordlabelr{}}%
3279 % \end{macrocode}
3280 % \end{macro}
3281 % \begin{macro}{\@currenvir}
3282 % Because of our meddling with |\begingroup| and |\endgroup|, the
3283 % current environment is all messed up. We therefore force the
3284 % |\end{rightwordgroup}| to succeed, even if it doesn't match the preceding
3285 % |\begin|.
3286 % \begin{macrocode}
3287 \def\@currenvir{rightwordgroup}%
3288 \ignorespacesafterend
3289 }
3290 % \end{macrocode}
3291 % \end{macro}
3292 % \end{environment}
3293 %
3294 % \subsubsection{Left-side labels}
3295 %
3296 % \begin{macro}{\wordlabell@start}
3297 % \begin{macro}{\wordlabell@end}
3298 % Declare the starting and ending height (in points) of the set of rows
3299 % to be labeled on the left.
3300 % \begin{macrocode}
3301 \newlength{\wordlabell@start}
3302 \newlength{\wordlabell@end}
3303 % \end{macrocode}
3304 % \end{macro}
3305 % \end{macro}
3306 %
3307 % \begin{macro}{\total@box@width}
3308 % Declare the total width of the next label to typeset on the left of
3309 % the bit field, that is, the aggregate width of the text box, curly
3310 % brace, and spaces on either side of the curly brace.
3311 % \begin{macrocode}
3312 \newlength{\total@lbox@width}
3313 % \end{macrocode}
3314 % \end{macro}
3315 %
3316 % \begin{macro}{\make@lspace}
3317 % This macro is output in the first column of every row of the
3318 % |\ialign|ed bytefield table. It's normally a no-op, but
3319 % |\begin{leftwordgroup}| defines it to output enough space for the next word
3320 % label and then reset itself to a no-op.
3321 % \begin{macrocode}
3322 \gdef\make@lspace{}
3323 % \end{macrocode}
3324 % \end{macro}
3325 %
3326 % \begin{environment}{leftwordgroup}
3327 % \usermacro
3328 % This environment is essentially the same as the |rightwordgroup|
3329 % environment but puts the label on the left. However, the following
3330 % code is not symmetric to that of |rightwordgroup|. The problem is that we
3331 % encounter |\begin{leftwordgroup}| after entering the second
3332 % (i.e.,~figure) column, which doesn't give us a chance to reserve space
3333 % in the first (i.e.,~left label) column. When we reach the
3334 % |\end{leftwordgroup}|, we know the height of the group of words we wish
3335 % to label. However, if we try to label the words in the subsequent
3336 % first column, we won't know the vertical offset from the ``cursor'' at
3337 % which to start drawing the label, because we can't know the height of
3338 % the subsequent row until we reach the second
3339 % column.\footnote{Question: Is there a way to push the label up to the
3340 % \emph{top} of the subsequent row, perhaps with
3341 % \texttt{\string\vfill}?}
3342 %
3343 % Our solution is to allocate space for the box the next time we enter a
3344 % first column. As long as space is eventually allocated, the column
3345 % will expand to fit that space. |\end{leftwordgroup}| outputs the label
3346 % immediately. Even though |\end{leftwordgroup}| is called at the end of
3347 % the \emph{second} column, it |\put|s the label at a sufficiently
3348 % negative $x$ location for it to overlap the first column. Because
3349 % there will eventually be enough space to accomodate the label, we know
3350 % that the label won't overlap the bit field or extend beyond the bit-field
3351 % boundaries.
3352 % \changes{v2.6}{2020/10/29}{Suppress spaces following the
3353 % \protect\cs{end}\protect\texttt{\{leftwordgroup\}}}
3354 % \changes{v2.6}{2020/10/31}{Accept key/value options}
3355 % \begin{macrocode}
3356 \newenvironment{leftwordgroup}[2][]{%
3357 % \end{macrocode}
3358 % \begin{macro}{\wordlabell@start}
3359 % \begin{macro}{\wordlabell@params}
3360 % \begin{macro}{\wordlabell@text}
3361 % We store the starting height, optional parameters (see
3362 % Section~\ref{sec:options}), and label text, all of which are needed by
3363 % the |\end{leftwordgroup}|. We immediately parse the parameters
3364 % because they may affect the \cs{store@lcurly} invocation below.
3365 % \begin{macrocode}
3366 \global\wordlabell@start=\bytefield@height
3367 \gdef\wordlabell@params{#1}%
3368 \gdef\wordlabell@text{#2}%
3369 \bf@bytefieldsetup{#1}%
3370 % \end{macrocode}
3371 % \end{macro}
3372 % \end{macro}
3373 % \end{macro}
3374 % Next, we typeset a draft version of the label into |\word@label@box|,
3375 % which we measure (into |\total@lbox@width|) and then discard.
3376 % We can't typeset the final version of the label until we reach the
3377 % |\end{leftwordgroup}|, because that's when we learn the height of the
3378 % word group. Without knowing the height of the word group, we don't
3379 % how how big to make the curly brace. In the scratch version, we make
3380 % the curly brace 5\,cm.~tall. This should be more than large enough to
3381 % reach the maximum curly-brace width, which is all we really care about
3382 % at this point.
3383 % \begin{macrocode}
3384 \sbox{\word@label@box}{%
3385 \begin{tabular}[b]{@{}l@{}}\wordlabell@text\end{tabular}}%
3386 \settowidth{\label@box@width}{\usebox{\word@label@box}}%
3387 \store@lcurly{\curly@box}{5cm}%
3388 \setlength{\total@lbox@width}{%
3389 \bf@leftcurlyspace +
3390 \widthof{\usebox{\curly@box}} +
3391 \bf@leftlabelspace +
3392 \label@box@width}%
3393 \global\total@lbox@width=\total@lbox@width
3394 % \end{macrocode}
3395 % \begin{macro}{\make@lspace}
3396 % Now we know how wide the box is going to be (unless, of course,
3397 % the user is using some weird math font that scales the width of a curly
3398 % brace proportionally to its height). So we redefine |\make@lspace| to
3399 % output |\total@lbox@width|'s worth of space and then redefine itself
3400 % back to a no-op.
3401 % \begin{macrocode}
3402 \gdef\make@lspace{%
3403 \hspace*{\total@lbox@width}%
3404 \gdef\make@lspace{}%
3405 }%
3406 % \end{macrocode}
3407 % We now end the group that |\begin{rightwordgroup}| created. This lets
3408 % the |leftwordgroup| environment span rows (because we're technically
3409 % no longer within the environment).
3410 % \begin{macrocode}
3411 \endgroup
3412 \ignorespaces
3413 }{%
3414 % \end{macrocode}
3415 % \end{macro}
3416 % Because we already ended the group that |\begin{leftwordgroup}| created
3417 % we have to start the |\end{leftwordgroup}| by beginning a group for
3418 % |\end{leftwordgroup}| to end.
3419 % \begin{macrocode}
3420 \begingroup
3421 % \end{macrocode}
3422 % The |\end{leftwordgroup}| code is comparatively straightforward. We
3423 % calculate the final height of the word group, and then output the
3424 % label text, followed by |\bf@leftlabelspace| space, followed by a
3425 % curly brace (now that we know how tall it's supposed to be), followed
3426 % by |\bf@leftcurlyspace| space. The trick, as described earlier, is
3427 % that we typeset the entire label in the second column, but in a $0
3428 % \times 0$ |picture| environment and with a negative horizontal offset
3429 % (|\starting@point|), thereby making it overlap the first column.
3430 % Before typesetting the curly brace we re-parse the optional parameters
3431 % because we're in a new group from the one in which we parsed them
3432 % before, and the parameters can affect the second \cs{store@lcurly}
3433 % invocation just they could have affected the first.
3434 % \begin{macrocode}
3435 \global\wordlabell@end=\bytefield@height
3436 \bf@newdimen\starting@point
3437 \setlength{\starting@point}{%
3438 -\total@lbox@width - \bf@bitwidth*\bits@wide}%
3439 \sbox{\word@label@box}{%
3440 \begin{tabular}[b]{@{}l@{}}\wordlabell@text\end{tabular}}%
3441 \settowidth{\label@box@width}{\usebox{\word@label@box}}%
3442 \setlength{\label@box@height}{\wordlabell@end-\wordlabell@start}%
3443 \expandafter\bf@bytefieldsetup\expandafter{\wordlabell@params}%
3444 \store@lcurly{\curly@box}{\label@box@height}%
3445 \begin{picture}(0,0)
3446 \put(\strip@pt\starting@point,0){%
3447 \makebox(\strip@pt\label@box@width,\strip@pt\label@box@height){%
3448 \usebox{\word@label@box}}%
3449 \hspace*{\bf@leftlabelspace}%
3450 \usebox{\curly@box}%
3451 \hspace*{\bf@leftcurlyspace}}
3452 \end{picture}%
3453 % \end{macrocode}
3454 % \begin{macro}{\@currenvir}
3455 % Because of our meddling with |\begingroup| and |\endgroup|, the
3456 % current environment is all messed up. We therefore force the
3457 % |\end{leftwordgroup}| to succeed, even if it doesn't match the preceding
3458 % |\begin|.
3459 % \begin{macrocode}
3460 \def\@currenvir{leftwordgroup}%
3461 \ignorespacesafterend
3462 }
3463 % \end{macrocode}
3464 % \end{macro}
3465 % \end{environment}
3466 %
3467 % \subsubsection{Scratch space}
3468 %
3469 % \begin{macro}{\label@box@width}
3470 % \begin{macro}{\label@box@height}
3471 % \begin{macro}{\word@label@box}
3472 % Declare some scratch storage for the width, height, and contents of
3473 % the word label we're about to output.
3474 % \begin{macrocode}
3475 \newlength{\label@box@width}
3476 \newlength{\label@box@height}
3477 \newsavebox{\word@label@box}
3478 % \end{macrocode}
3479 % \end{macro}
3480 % \end{macro}
3481 % \end{macro}
3482 %
3483 % \subsection{Compatibility mode}
3484 %
3485 % \begin{macro}{\bf@enter@compatibility@mode@i}
3486 % \pkgname{bytefield}'s interface changed substantially with the move to
3487 % version~2.0. To give version~1.\textit{x} users a quick way to build
3488 % their old documents, we provide a version~1.\textit{x} compatibility
3489 % mode. We don't enable this by default because it exposes a number of
3490 % extra length registers (a precious resource) and because we want to
3491 % encourage users to migrate to the new interface.
3492 % \begin{macrocode}
3493 \newcommand{\bf@enter@compatibility@mode@i}{%
3494 % \end{macrocode}
3495 % \begin{macro}{\bitwidth}
3496 % \begin{macro}{\byteheight}
3497 % \begin{macro}{\curlyspace}
3498 % \begin{macro}{\labelspace}
3499 % \begin{macro}{\curlyshrinkage}
3500 % Define a handful of lengths that the user was allowed to |\setlength|
3501 % explicitly in \pkgname{bytefield}~1.\textit{x}.
3502 % \begin{macrocode}
3503 \PackageInfo{bytefield}{Entering version 1 compatibility mode}%
3504 \newlength{\bitwidth}%
3505 \newlength{\byteheight}%
3506 \newlength{\curlyspace}%
3507 \newlength{\labelspace}%
3508 \newlength{\curlyshrinkage}%
3509 % \end{macrocode}
3510 % \begin{macrocode}
3511 \settowidth{\bitwidth}{\tiny 99i}%
3512 \setlength{\byteheight}{4ex}%
3513 \setlength{\curlyspace}{1ex}%
3514 \setlength{\labelspace}{0.5ex}%
3515 \setlength{\curlyshrinkage}{5pt}%
3516 % \end{macrocode}
3517 % \end{macro}
3518 % \end{macro}
3519 % \end{macro}
3520 % \end{macro}
3521 % \end{macro}
3522 % \begin{macro}{\newbytefield}
3523 % \begin{macro}{\endnewbytefield}
3524 % \begin{environment}{bytefield}
3525 % Redefine the |bytefield| environment in terms of the existing
3526 % (new-interface) |bytefield| environment. The difference is that the
3527 % redefinition utilizes all of the preceding lengths.
3528 % \begin{macrocode}
3529 \let\newbytefield=\bytefield
3530 \let\endnewbytefield=\endbytefield
3531 \renewenvironment{bytefield}[1]{%
3532 \begin{newbytefield}[%
3533 bitwidth=\bitwidth,
3534 bitheight=\byteheight,
3535 curlyspace=\curlyspace,
3536 labelspace=\labelspace,
3537 curlyshrinkage=\curlyshrinkage]{##1}%
3538 }{%
3539 \end{newbytefield}%
3540 }
3541 % \end{macrocode}
3542 % \end{environment}
3543 % \end{macro}
3544 % \end{macro}
3545 % \begin{macro}{\wordgroupr}
3546 % \begin{macro}{\endwordgroupr}
3547 % \begin{macro}{\wordgroupl}
3548 % \begin{macro}{\endwordgroupl}
3549 % Define |\wordgroupr|, |\endwordgroupr|, |\wordgroupl|, and
3550 % |\endwordgroupl| in terms of the new |rightwordgroup| and
3551 % |leftwordgroup| environments.
3552 % \begin{macrocode}
3553 \def\wordgroupr{\begin{rightwordgroup}}
3554 \def\endwordgroupr{\end{rightwordgroup}}
3555 \def\wordgroupl{\begin{leftwordgroup}}
3556 \def\endwordgroupl{\end{leftwordgroup}}
3557 % \end{macrocode}
3558 % \end{macro}
3559 % \end{macro}
3560 % \end{macro}
3561 % \end{macro}
3562 %
3563 % \begin{macro}{\bytefieldsetup}
3564 % Disable |\bytefieldsetup| in compatibility mode because it doesn't
3565 % work as expected. (Every use of the compatibility-mode |bytefield|
3566 % environment overwrites all of the figure-formatting values.)
3567 % \begin{macrocode}
3568 \renewcommand{\bytefieldsetup}[1]{%
3569 \PackageError{bytefield}{%
3570 The \protect\bytefieldsetup\space macro is not available in\MessageBreak
3571 version 1 compatibility mode%
3572 }{%
3573 Remove [compat1] from the \protect\usepackage{bytefield} line to
3574 make \protect\bytefieldsetup\MessageBreak
3575 available to this document.\space\space (The document may also need
3576 to be modified to use\MessageBreak
3577 the new bytefield interface.)
3578 }%
3579 }%
3580 }
3581 % \end{macrocode}
3582 % \end{macro}
3583 % \end{macro}
3584 %
3585 % \begin{macro}{\wordgroupr}
3586 % \begin{macro}{\endwordgroupr}
3587 % \begin{macro}{\wordgroupl}
3588 % \begin{macro}{\endwordgroupl}
3589 % Issue a helpful error message for the commands that were removed in
3590 % \pkgname{bytefield}~v2.0. While this won't help users whose first
3591 % invalid action is to modify a no-longer-extant length register such as
3592 % |\bitwidth| or |\byteheight|, it may benefit at least a few users who
3593 % didn't realize that the \pkgname{bytefield} interface has changed
3594 % substantially with version~2.0.
3595 % \begin{macrocode}
3596 \newcommand{\wordgroupr}{%
3597 \PackageError{bytefield}{%
3598 Macros \protect\wordgroupr, \protect\wordgroupl, \protect\endwordgroupr,
3599 \MessageBreak
3600 and \protect\endwordgroupl\space no longer exist%
3601 }{%
3602 Starting with version 2.0, bytefield uses \protect\begin{wordgroupr}...
3603 \MessageBreak
3604 \protect\end{wordgroupr} and \protect\begin{wordgroupl}...%
3605 \protect\end{wordgroupl}\MessageBreak
3606 to specify word groups and a new \protect\bytefieldsetup\space macro to
3607 \MessageBreak
3608 change bytefield's various formatting parameters.%
3609 }%
3610 }
3611 \let\endwordgroupr=\wordgroupr
3612 \let\wordgroupl=\wordgroupr
3613 \let\endwordgroupl=\wordgroupr
3614 % \end{macrocode}
3615 % \end{macro}
3616 % \end{macro}
3617 % \end{macro}
3618 % \end{macro}
3619 %
3620 %
3621 % \subsection{Option processing}
3622 %
3623 % We use the \textsf{keyval} package to handle option processing.
3624 % Because all of \pkgname{bytefield}'s options have local impact, options
3625 % can be specified either as package arguments or through the use of the
3626 % |\bytefieldsetup| macro.
3627 %
3628 % \begin{macro}{\KV@bytefield@bitwidth}
3629 % \begin{macro}{\bf@bw@arg}
3630 % \begin{macro}{\bf@auto}
3631 % Specify the width of a bit number in the bit header. If the special
3632 % value ``|auto|'' is given, set the width to the width of a formatted
3633 % ``|99i|''.
3634 % \begin{macrocode}
3635 \define@key{bytefield}{bitwidth}{%
3636 \def\bf@bw@arg{#1}%
3637 \def\bf@auto{auto}%
3638 \ifx\bf@bw@arg\bf@auto
3639 \settowidth{\bf@bitwidth}{\bf@bitformatting{99i}}%
3640 \else
3641 \setlength{\bf@bitwidth}{#1}%
3642 \fi
3643 }
3644 % \end{macrocode}
3645 % \end{macro}
3646 % \end{macro}
3647 % \end{macro}
3648 %
3649 % \begin{macro}{\KV@bytefield@bf@bitheight}
3650 % Specify the height of a bit in a |\bitbox| or |\wordbox|.
3651 % \begin{macrocode}
3652 \define@key{bytefield}{bitheight}{\setlength{\bf@bitheight}{#1}}
3653 % \end{macrocode}
3654 % \end{macro}
3655 %
3656 % \begin{macro}{\KV@bytefield@bitformatting}
3657 % Specify the style of a bit number in the bit header. This should be
3658 % passed an expression that takes either one argument (e.g.,~|\textit|)
3659 % or no arguments (e.g.,~|{\small\bfseries}|).
3660 % \begin{macrocode}
3661 \define@key{bytefield}{bitformatting}{\def\bf@bitformatting{#1}}
3662 % \end{macrocode}
3663 % \end{macro}
3664 %
3665 % \begin{macro}{\KV@bytefield@boxformatting}
3666 % Specify a style to be applied to the contents of every bit box and
3667 % word box. This should be passed an expression that takes either one
3668 % argument (e.g.,~|\textit|) or no arguments
3669 % (e.g.,~|{\small\bfseries}|).
3670 % \begin{macrocode}
3671 \define@key{bytefield}{boxformatting}{\def\bf@boxformatting{#1}}
3672 % \end{macrocode}
3673 % \end{macro}
3674 %
3675 % \begin{macro}{\KV@bytefield@leftcurly}
3676 % \begin{macro}{\KV@bytefield@rightcurly}
3677 % \begin{macro}{\bf@leftcurly}
3678 % \begin{macro}{\bf@rightcurly}
3679 % Specify the symbol to use for bracketing a left or right word group.
3680 % This must be an extensible math delimiter (i.e.,~something that can
3681 % immediately follow |\left| or |\right| in math mode).
3682 % \begin{macrocode}
3683 \define@key{bytefield}{leftcurly}{\def\bf@leftcurly{#1}}
3684 \define@key{bytefield}{rightcurly}{\def\bf@rightcurly{#1}}
3685 % \end{macrocode}
3686 % \end{macro}
3687 % \end{macro}
3688 % \end{macro}
3689 % \end{macro}
3690 %
3691 % \begin{macro}{\KV@bytefield@leftcurlyspace}
3692 % \begin{macro}{\KV@bytefield@rightcurlyspace}
3693 % \begin{macro}{\KV@bytefield@curlyspace}
3694 % \begin{macro}{\bf@leftcurlyspace}
3695 % \begin{macro}{\bf@rightcurlyspace}
3696 % Specify the amount of space between the bit fields in a word group and
3697 % the adjacent left or right curly brace. The \optname{curlyspace}
3698 % option is a shortcut that puts the same space before both left and
3699 % right curly braces.
3700 % \begin{macrocode}
3701 \define@key{bytefield}{leftcurlyspace}{\def\bf@leftcurlyspace{#1}}
3702 \define@key{bytefield}{rightcurlyspace}{\def\bf@rightcurlyspace{#1}}
3703 \define@key{bytefield}{curlyspace}{%
3704 \def\bf@leftcurlyspace{#1}%
3705 \def\bf@rightcurlyspace{#1}%
3706 }
3707 % \end{macrocode}
3708 % \end{macro}
3709 % \end{macro}
3710 % \end{macro}
3711 % \end{macro}
3712 % \end{macro}
3713 %
3714 % \begin{macro}{\KV@bytefield@leftlabelspace}
3715 % \begin{macro}{\KV@bytefield@rightlabelspace}
3716 % \begin{macro}{\KV@bytefield@labelspace}
3717 % \begin{macro}{\bf@leftlabelspace}
3718 % \begin{macro}{\bf@rightlabelspace}
3719 % Specify the amount of space between a left or right word group's curly
3720 % brace and the associated label text. The |labelspace| option is a
3721 % shortcut that puts the same space after both left and right curly
3722 % braces.
3723 % \begin{macrocode}
3724 \define@key{bytefield}{leftlabelspace}{\def\bf@leftlabelspace{#1}}
3725 \define@key{bytefield}{rightlabelspace}{\def\bf@rightlabelspace{#1}}
3726 \define@key{bytefield}{labelspace}{%
3727 \def\bf@leftlabelspace{#1}%
3728 \def\bf@rightlabelspace{#1}%
3729 }
3730 % \end{macrocode}
3731 % \end{macro}
3732 % \end{macro}
3733 % \end{macro}
3734 % \end{macro}
3735 % \end{macro}
3736 %
3737 % \begin{macro}{\KV@bytefield@leftcurlyshrinkage}
3738 % \begin{macro}{\KV@bytefield@rightcurlyshrinkage}
3739 % \begin{macro}{\KV@bytefield@curlyshrinkage}
3740 % \begin{macro}{\bf@leftcurlyshrinkage}
3741 % \begin{macro}{\bf@rightcurlyshrinkage}
3742 % Specify the number of points by which to reduce the height of a curly
3743 % brace (left, right, or both) so its ends don't overlap whatever's
3744 % above or below it.
3745 % \begin{macrocode}
3746 \define@key{bytefield}{leftcurlyshrinkage}{\def\bf@leftcurlyshrinkage{#1}}
3747 \define@key{bytefield}{rightcurlyshrinkage}{\def\bf@rightcurlyshrinkage{#1}}
3748 \define@key{bytefield}{curlyshrinkage}{%
3749 \def\bf@leftcurlyshrinkage{#1}%
3750 \def\bf@rightcurlyshrinkage{#1}%
3751 }
3752 % \end{macrocode}
3753 % \end{macro}
3754 % \end{macro}
3755 % \end{macro}
3756 % \end{macro}
3757 % \end{macro}
3758 %
3759 % \begin{macro}{\KV@bytefield@leftcurlystyle}
3760 % \begin{macro}{\KV@bytefield@rightcurlystyle}
3761 % \begin{macro}{\KV@bytefieldcurlystyle}
3762 % \begin{macro}{\bf@leftcurlystyle}
3763 % \begin{macro}{\bf@rightcurlystyle}
3764 % Specify a macro that takes either zero or one argument and that
3765 % precedes the text that draws a left curly brace, right curly brace, or
3766 % either curly brace.
3767 % \begin{macrocode}
3768 \define@key{bytefield}{leftcurlystyle}{\def\bf@leftcurlystyle{#1}}
3769 \define@key{bytefield}{rightcurlystyle}{\def\bf@rightcurlystyle{#1}}
3770 \define@key{bytefield}{curlystyle}{%
3771 \def\bf@leftcurlystyle{#1}%
3772 \def\bf@rightcurlystyle{#1}%
3773 }
3774 % \end{macrocode}
3775 % \end{macro}
3776 % \end{macro}
3777 % \end{macro}
3778 % \end{macro}
3779 % \end{macro}
3780 %
3781 % \begin{macro}{\KV@bytefield@endianness}
3782 % \begin{macro}{\bf@parse@endianness}
3783 % Set the default endianness to either little endian or big endian.
3784 % \begin{macrocode}
3785 \define@key{bytefield}{endianness}{\bf@parse@endianness{#1}}
3786 % \end{macrocode}
3787 % \begin{macrocode}
3788 \newcommand{\bf@parse@endianness}[1]{%
3789 \def\bf@little{little}%
3790 \def\bf@big{big}%
3791 \def\bf@arg{#1}%
3792 \ifx\bf@arg\bf@little
3793 \def\bf@bit@endianness{l}%
3794 \else
3795 \ifx\bf@arg\bf@big
3796 \def\bf@bit@endianness{b}%
3797 \else
3798 \PackageError{bytefield}{%
3799 Invalid argument "#1" to the endianness option%
3800 }{%
3801 The endianness option must be set to either "little" or
3802 "big".\MessageBreak
3803 Please specify either endianness=little or endianness=big.
3804 }%
3805 \fi
3806 \fi
3807 }
3808 % \end{macrocode}
3809 % \end{macro}
3810 % \end{macro}
3811 %
3812 % \begin{macro}{\KV@bytefield@lsb}
3813 % Specify a numerical value for the least significant bit of a word.
3814 % \begin{macrocode}
3815 \define@key{bytefield}{lsb}{\def\bf@first@bit{#1}}
3816 % \end{macrocode}
3817 % \end{macro}
3818 %
3819 % \begin{macro}{\bf@bgcolor}
3820 % \begin{macro}{\KV@bytefield@bgcolor}
3821 % Specify a background color for a bit box or word box.
3822 % \begin{macrocode}
3823 \define@key{bytefield}{bgcolor}{\def\bf@bgcolor{#1}}
3824 % \end{macrocode}
3825 % \end{macro}
3826 % \end{macro}
3827 %
3828 % \begin{macro}{\bf@per@word}
3829 % \begin{macro}{\KV@bytefield@per@word}
3830 % Specify a macro to invoke for each word of a word box. The macro must
3831 % take two arguments: the word number (0-indexed) and the total number
3832 % of words.
3833 % \begin{macrocode}
3834 \define@key{bytefield}{perword}{\def\bf@per@word{#1}}
3835 % \end{macrocode}
3836 % \end{macro}
3837 % \end{macro}
3838 %
3839 % \begin{macro}{\bytefieldsetup}
3840 % \usermacro
3841 % \changes{v2.0}{2011/01/18}{Introduced this macro to provide a more
3842 % convenient way of configuring \pkgname{bytefield}'s parameters}
3843 % \begin{macro}{\bf@bytefieldsetup}
3844 % Reconfigure values for various \pkgname{bytefield} parameters.
3845 % Internally to the package we use the |\bf@bytefieldsetup| macro
3846 % instead of |\bytefieldsetup|. This enables us to redefine
3847 % |\bytefieldsetup| when entering version~1 compatibility mode without
3848 % impacting the rest of \pkgname{bytefield}.
3849 % \begin{macrocode}
3850 \newcommand{\bf@bytefieldsetup}{\setkeys{bytefield}}
3851 \let\bytefieldsetup=\bf@bytefieldsetup
3852 % \end{macrocode}
3853 % \end{macro}
3854 % \end{macro}
3855 %
3856 % We define only a single option that can be used only as a package
3857 % option, not as an argument to |\bytefieldsetup|: |compat1| instructs
3858 % \pkgname{bytefield} to enter version~1 compatibility mode---at the
3859 % cost of a number of additional length registers and the inability to
3860 % specify parameters in the argument to the |bytefield| environment.
3861 % \begin{macrocode}
3862 \DeclareOption{compat1}{\bf@enter@compatibility@mode@i}
3863 % \end{macrocode}
3864 %
3865 % \begin{macro}{\bf@package@options}
3866 % \begin{macro}{\next}
3867 % We want to use |\bf@bytefieldsetup| to process \pkgname{bytefield}
3868 % package options. Unfortunately, |\DeclareOption| doesn't handle
3869 % \meta{key}=\meta{value} arguments. Hence, we use |\DeclareOption*| to
3870 % catch \emph{all} options, each of which it appends to
3871 % |\bf@package@options|. |\bf@package@options| is passed to
3872 % |\bf@bytefieldsetup| only at the beginning of the document so that the
3873 % options it specifies (a)~can refer to ex-heights and (b)~override the
3874 % default values, which are also set at the beginning of the document.
3875 % \begin{macrocode}
3876 \def\bf@package@options{}
3877 \DeclareOption*{%
3878 \edef\next{%
3879 \noexpand\g@addto@macro\noexpand\bf@package@options{,\CurrentOption}%
3880 }%
3881 \next
3882 }
3883 \ProcessOptions\relax
3884 \expandafter\bf@bytefieldsetup\expandafter{\bf@package@options}
3885 % \end{macrocode}
3886 % \end{macro}
3887 % \end{macro}
3888 %
3889 % \Finale
3890 \endinput