bytefield 2011/06/19 v2.1

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

1 files changed, 676 insertions, 320 deletions

diff --git a/Master/texmf-dist/source/latex/bytefield/bytefield.dtx b/Master/texmf-dist/source/latex/bytefield/bytefield.dtx
index 0aba8eab386..232e5fb58dd 100644
--- a/Master/texmf-dist/source/latex/bytefield/bytefield.dtx
+++ b/Master/texmf-dist/source/latex/bytefield/bytefield.dtx
@@ -22,7 +22,7 @@
 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
 %<package>\ProvidesPackage{bytefield}
 %<*package>
-    [2011/02/09 v2.0a Network protocol diagrams]
+    [2011/06/19 v2.1 Network protocol diagrams]
 %</package>
 %
 %<*driver>
@@ -36,24 +36,17 @@
 \usepackage{array}
 \usepackage{wasysym}
 \IfFileExists{hypdoc.sty}{\usepackage{hypdoc}}{}
-\usepackage{hyperref}%
+\usepackage{hyperref}
+\IfFileExists{hypcap.sty}{\usepackage[figure]{hypcap}}{}
 
-\definecolor{darkred}{rgb}{0.5,0,0}
-\definecolor{darkgreen}{rgb}{0,0.3,0}
-\definecolor{darkblue}{rgb}{0,0,0.5}
-\definecolor{darkbrown}{rgb}{0.28,0.07,0.07}
 \hypersetup{%
   pdftitle={The bytefield package},
   pdfauthor={Scott Pakin <scott+bf@pakin.org>},
   pdfsubject={Protocol diagrams for LaTeX},
   pdfkeywords={bits, bytes, bit fields, communication, network protocol
     diagrams, LaTeX2e, memory maps},
-  bookmarksopen=true,
-  colorlinks=true,
-  citecolor=darkblue,
-  urlcolor=darkgreen,
-  linkcolor=darkred,
-  menucolor=darkbrown}
+  colorlinks=false,
+  bookmarksopen=true}
 \EnableCrossrefs
 \CodelineIndex
 \RecordChanges
@@ -66,7 +59,7 @@
 %</driver>
 % \fi
 %
-% \CheckSum{847}
+% \CheckSum{917}
 %
 % \CharacterTable
 %  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
@@ -111,17 +104,17 @@
 % \DoNotIndex{\gdef,\global}
 % \DoNotIndex{\hspace}
 % \DoNotIndex{\if,\ifnum,\ifx,\ignorespaces,\insc@unt}
-% \DoNotIndex{\let,\loop}
+% \DoNotIndex{\left,\let,\loop}
 % \DoNotIndex{\MessageBreak}
-% \DoNotIndex{\newbox,\newcommand,\newcounter,\newenvironment,\newif}
+% \DoNotIndex{\newbox,\newcommand,\newcounter,\newenvironment,\newif,\next}
 % \DoNotIndex{\newlength,\newsavebox,\noexpand}
-% \DoNotIndex{\raisebox,\ratio,\real,\relax,\renewcommand}
+% \DoNotIndex{\raisebox,\ratio,\real,\relax,\renewcommand,\right}
 % \DoNotIndex{\par,\protect}
 % \DoNotIndex{\renewenvironment,\repeat}
 % \DoNotIndex{\sbox,\setcounter,\setlength,\settowidth,\space,\string}
 % \DoNotIndex{\the}
-% \DoNotIndex{\usebox,\usepackage}
-% \DoNotIndex{\value,\vbox}
+% \DoNotIndex{\unskip,\usebox,\usepackage}
+% \DoNotIndex{\value,\vbox,\vspace}
 % \DoNotIndex{\wlog}
 % \DoNotIndex{\xdef}
 %
@@ -225,6 +218,9 @@
 %   \SpecialOptionIndex{#1}^^A
 % }
 %
+% ^^A  We use this box to help center protocol diagrams.
+% \newsavebox{\protocoldiagram}
+%
 %
 % \begin{abstract}
 % The \pkgname{bytefield} package helps the user create illustrations for
@@ -251,21 +247,20 @@
 % \section{Introduction}
 %
 % Network protocols are usually specified in terms of a sequence of bits
-% and bytes arranged in a field.  This is portrayed graphically as
-% a grid of boxes.  Each row in the grid represents one word (frequently,
-% 32~bits), and each column represents a bit within a word.
-% The \pkgname{bytefield} package makes it easy to typeset these sorts of
-% figures.
-%
-% \pkgname{bytefield} lets one draw protocol diagrams that contain:
+% and bytes arranged in a field.  This is portrayed graphically as a
+% grid of boxes.  Each row in the grid represents one word (frequently,
+% 8, 16, or 32~bits), and each column represents a bit within a word.
+% The \pkgname{bytefield} package makes it easy to typeset these sorts
+% of figures.  \pkgname{bytefield} facilitates drawing protocol diagrams
+% that contain
 %
 % \begin{itemize}
-%   \item Words of any arbitrary number of bits
-%   \item Column headers showing bit positions
-%   \item Multiword fields---even non-word-aligned and even if the total
-%         number of bits is not a multiple of the word length
-%   \item Word labels on either the left or right of the figure
-%   \item ``Skipped words'' within fields
+%   \item words of any arbitrary number of bits,
+%   \item column headers showing bit positions,
+%   \item multiword fields---even non-word-aligned and even if the total
+%         number of bits is not a multiple of the word length,
+%   \item word labels on either the left or right of the figure, and
+%   \item ``skipped words'' within fields.
 % \end{itemize}
 %
 % Because \pkgname{bytefield} draws its figures using only
@@ -280,11 +275,96 @@
 % \section{Usage}
 % \label{sec:usage}
 %
+% \subsection{A first example}
+% \label{sec:first-example}
+%
+% The Internet Engineering Task Force's Request for Comments (RFC)
+% number~3016 includes the following ASCII-graphics illustration of
+% the RTP packetization of an \mbox{MPEG-4} Visual bitstream:
+%
+% \begin{verbatim}
+%       0                   1                   2                   3
+%       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
+%       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+%       |V=2|P|X|  CC   |M|     PT      |       sequence number         | RTP
+%       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+%       |                           timestamp                           | Header
+%       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+%       |           synchronization source (SSRC) identifier            |
+%       +=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+
+%       |            contributing source (CSRC) identifiers             |
+%       |                             ....                              |
+%       +=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+
+%       |                                                               | RTP
+%       |       MPEG-4 Visual stream (byte aligned)                     | Pay-
+%       |                                                               | load
+%       |                               +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+%       |                               :...OPTIONAL RTP padding        |
+%       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+% \end{verbatim}
+%
+% \noindent
+% The following \LaTeX\ code shows how straightforward it is to typeset
+% that illustration using the \pkgname{bytefield} package:
+%
+% \begin{verbatim}
+%       \begin{bytefield}[bitwidth=1.1em]{32}
+%         \bitheader{0-31} \\
+%         \begin{rightwordgroup}{RTP \\ Header}
+%           \bitbox{2}{V=2} & \bitbox{1}{P} & \bitbox{1}{X}
+%           & \bitbox{4}{CC} & \bitbox{1}{M} & \bitbox{7}{PT}
+%           & \bitbox{16}{sequence number} \\
+%           \bitbox{32}{timestamp}
+%         \end{rightwordgroup} \\
+%         \bitbox{32}{synchronization source (SSRC) identifier} \\
+%         \wordbox[tlr]{1}{contributing source (CSRC) identifiers} \\
+%         \wordbox[blr]{1}{$\cdots$} \\
+%         \begin{rightwordgroup}{RTP \\ Payload}
+%           \wordbox[tlr]{3}{MPEG-4 Visual stream (byte aligned)} \\
+%           \bitbox[blr]{16}{}
+%           & \bitbox{16}{\dots\emph{optional} RTP padding}
+%         \end{rightwordgroup}
+%       \end{bytefield}
+% \end{verbatim}
+%
+% Figure~\ref{fig:rtp-mpeg4} presents the typeset output of the
+% preceding code.  Sections~\ref{sec:basic-cmds} and~\ref{sec:options}
+% explain each of the environments, macros, and arguments that were
+% utilized plus many additional features of the \pkgname{bytefield}
+% package.
+%
+% \begin{figure}[hbp]
+%     \centering
+%     \begin{lrbox}{\protocoldiagram}
+%       \begin{bytefield}[bitwidth=1.1em]{32}
+%         \bitheader{0-31} \\
+%         \begin{rightwordgroup}{RTP \\ Header}
+%           \bitbox{2}{V=2} & \bitbox{1}{P} & \bitbox{1}{X}
+%           & \bitbox{4}{CC} & \bitbox{1}{M} & \bitbox{7}{PT}
+%           & \bitbox{16}{sequence number} \\
+%           \bitbox{32}{timestamp}
+%         \end{rightwordgroup} \\
+%         \bitbox{32}{synchronization source (SSRC) identifier} \\
+%         \wordbox[tlr]{1}{contributing source (CSRC) identifiers} \\
+%         \wordbox[blr]{1}{$\cdots$} \\
+%         \begin{rightwordgroup}{RTP \\ Payload}
+%           \wordbox[tlr]{3}{MPEG-4 Visual stream (byte aligned)} \\
+%           \bitbox[blr]{16}{}
+%           & \bitbox{16}{\dots\emph{optional} RTP padding}
+%         \end{rightwordgroup}
+%       \end{bytefield}
+%     \end{lrbox}
+%     \makebox[0pt][c]{\usebox{\protocoldiagram}}
+%     \caption{Sample \pkgname{bytefield} output}
+%    \label{fig:rtp-mpeg4}
+% \end{figure}
+%
+%
 % \subsection{Basic commands}
 % \label{sec:basic-cmds}
 %
-% This section explains how to use the \pkgname{bytefield} package.
-% It lists all the exported environments, commands, and variables in
+% This section explains how to use the \pkgname{bytefield} package.  It
+% lists all the exported macros and environments in approximately
 % decreasing order of usefulness.
 %
 % \begin{decl}
@@ -300,7 +380,10 @@
 % is a set of parameters, described in Section~\ref{sec:options}, for
 % formatting the bit-field's layout.  One can think of a |bytefield| as
 % being analogous to a |tabular|: words are separated by~``|\\|'', and
-% fields within a word are separated by~``|&|''.
+% fields within a word are separated by~``|&|''.  As in a |tabular|,
+% ``|\\|'' accepts a \meta{length} as an optional argument, and this
+% specifies the amount of additional vertical whitespace to include
+% after the current word is typeset.
 %
 % \begin{decl}
 %   \SpecialUsageIndex{\bitbox}
@@ -312,8 +395,8 @@
 % The two main commands one uses within a \pkgname{bytefield}
 % environment are |\bitbox| and |\wordbox|.  The former typesets a field
 % that is one or more bits wide and a single word tall.  The latter
-% typesets a field that is one or more words tall and an entire word
-% wide.
+% typesets a field that is an entire word wide and one or more words
+% tall.
 %
 % The optional argument, \meta{sides}, is a list of letters specifying
 % which sides of the field box to draw---[|l|]eft, [|r|]ight, [|t|]op,
@@ -355,24 +438,26 @@
 %
 % \begin{decl}
 %   \SpecialUsageIndex{\bitheader}
-%   |\bitheader| \oarg{endianness} \marg{bit-positions}
+%   |\bitheader| \oarg{parameters} \marg{bit-positions}
 % \end{decl}
 %
-% To make the bit field more readable, it helps to label bit positions across
-% the top.  The |\bitheader| command provides a flexible way to do that.
-% The optional argument, \meta{endianness} is one of ``|b|'' or ``|l|''
-% and specifies whether the bits in each word are numbered in big-endian
-% style (right to left) or little-endian style (left to right).  The default
-% is little-endian (|l|).
+% To make the bit field more readable, it helps to label bit positions
+% across the top.  The |\bitheader| command provides a flexible way to
+% do that.  The optional argument is a set of parameters from the set
+% described in Section~\ref{sec:options}.  In practice, the only
+% parameters that are meaningful in the context of |\bitheader| are
+% |bitformatting|, |endianness|, and |lsb|.  See
+% Section~\ref{sec:options} for descriptions and examples of those
+% parameters.
 %
 % |\bitheader|'s mandatory argument, \meta{bit-positions}, is a
-% comma-separated list of bit positions to label.
-% For example, ``|0,2,4,6,8,10,12,14|'' means to label those bit positions.
-% The numbers must be listed in increasing order.  (Use \meta{endianness}
-% to display the header in reverse order.)  Hyphen-separated ranges are
-% also valid.  For example, ``|0-15|'' means to label all bits from~0 to~15,
-% inclusive.  While not particularly useful, ranges and single numbers can
-% be intermixed, as in ``|0-3,8,12-15|''.
+% comma-separated list of bit positions to label.  For example,
+% ``|0,2,4,6,8,10,12,14|'' means to label those bit positions.  The
+% numbers must be listed in increasing order.  (Use the
+% \optname{endianness} parameter to display the header in reverse
+% order.)  Hyphen-separated ranges are also valid.  For example,
+% ``|0-15|'' means to label all bits from~0 to~15, inclusive.  Ranges
+% and single numbers can even be intermixed, as in ``|0-3,8,12-15|''.
 %
 % The following example shows how |\bitheader| may be used:
 %
@@ -528,7 +613,7 @@
 %
 % Alter the formatting of all subsequent bit fields.
 % Section~\ref{sec:options} describes the possible values for each
-% \meta{key=value} item in the (comma-separated) list that
+% \meta{key}=\meta{value} item in the (comma-separated) list that
 % |\bytefieldsetup| accepts as its argument.  Note that changes made
 % with |\bytefieldsetup| are local to their current scope.  Hence, if
 % used within an environment (e.g.,~|figure|), |\bytefieldsetup| does
@@ -541,7 +626,7 @@
 % A document author can customize many of the \pkgname{bytefield}
 % package's figure-formatting parameters, either globally or on a
 % per-figure basis.  The parameters described below can be specified in
-% any of three locations:
+% four locations:
 %
 % \begin{itemize}
 %   \item as package options (i.e.,~in the
@@ -550,13 +635,17 @@
 %
 %   \item anywhere in the document using the |\bytefieldsetup| command,
 %     which affects all subsequent |bytefield| environments in the
-%     current scope, or
+%     current scope,
 %
 %   \item as the optional argument to a |\begin{bytefield}|, which
-%     affects only that single bit-field figure.
+%     affects only that single bit-field figure, or
+%
+%   \item as the optional argument to a |\bitheader|, which affects only
+%     that particular header.  (Only a few parameters are meaningful in
+%     this context.)
 % \end{itemize}
 %
-% Unfortunately, \LaTeXe\ tends to abort with a ``\texttt{TeX capacity
+% Unfortunately, \LaTeX\ tends to abort with a ``\texttt{TeX capacity
 %   exceeded}'' or ``\texttt{Missing \cs{endcsname} inserted}'' error
 % when a control sequence (i.e.,~|\|\meta{name}) or |\|\meta{symbol}) is
 % encountered within the optional argument to |\usepackage|.  Hence,
@@ -586,6 +675,49 @@
 % formatting change.
 %
 % \begin{decl}
+%   \optname{endianness} = |little| \emph{or} |big|
+% \end{decl}
+%
+% Specify either little-endian (left-to-right) or big-endian
+% (right-to-left) ordering of the bit numbers.  The default is
+% little-endian numbering.  Contrast the following two examples.  The
+% first formats a bit field in little-endian ordering using an explicit
+% |endianness=little|, and the second formats the same bit field in
+% big-endian ordering using |endianness=big|.
+%
+% \begin{verbatim}
+%       \begin{bytefield}[endianness=little,bitwidth=0.11111\linewidth]{8}
+%         \bitheader{0-7} \\
+%         \bitbox{1}{Res} & \bitbox{1}{BE} & \bitbox{1}{CF}
+%         & \bitbox{3}{$\mbox{Name\_Len}-1$} & \bitbox{2}{Len\_Len} \\
+%       \end{bytefield}
+% \end{verbatim}
+%
+% \begin{bffigure}
+%       \begin{bytefield}[endianness=little,bitwidth=0.11111\linewidth]{8}
+%         \bitheader{0-7} \\
+%         \bitbox{1}{Res} & \bitbox{1}{BE} & \bitbox{1}{CF}
+%         & \bitbox{3}{$\mbox{Name\_Len}-1$} & \bitbox{2}{Len\_Len} \\
+%       \end{bytefield}
+% \end{bffigure}
+%
+% \begin{verbatim}
+%       \begin{bytefield}[endianness=big,bitwidth=0.11111\linewidth]{8}
+%         \bitheader{0-7} \\
+%         \bitbox{2}{Len\_Len} & \bitbox{3}{$\mbox{Name\_Len}-1$}
+%         & \bitbox{1}{CF} & \bitbox{1}{BE} & \bitbox{1}{Res} \\
+%       \end{bytefield}
+% \end{verbatim}
+%
+% \begin{bffigure}
+%       \begin{bytefield}[endianness=big,bitwidth=0.11111\linewidth]{8}
+%         \bitheader{0-7} \\
+%         \bitbox{2}{Len\_Len} & \bitbox{3}{$\mbox{Name\_Len}-1$}
+%         & \bitbox{1}{CF} & \bitbox{1}{BE} & \bitbox{1}{Res} \\
+%       \end{bytefield}
+% \end{bffigure}
+%
+% \begin{decl}
 %   \optname{bitformatting} = \meta{command} \emph{or} \marg{commands}
 % \end{decl}
 %
@@ -608,8 +740,10 @@
 % \optname{bitwidth} to format a bit header with small, boldface text:
 %
 % \begin{verbatim}
-%       \begin{bytefield}[bitformatting={\small\bfseries},bitwidth=auto]{20}
-%         \bitheader[b]{0-19} \\
+%       \begin{bytefield}[bitformatting={\small\bfseries},
+%                         bitwidth=auto,
+%                         endianness=big]{20}
+%         \bitheader{0-19} \\
 %         \bitbox{1}{\tiny F/E} & \bitbox{1}{\tiny T0} & \bitbox{1}{\tiny T1}
 %         & \bitbox{1}{\tiny Fwd} & \bitbox{16}{Data value} \\
 %       \end{bytefield}
@@ -619,8 +753,10 @@
 % The resulting bit field looks like this:
 %
 % \begin{bffigure}
-%       \begin{bytefield}[bitformatting={\small\bfseries},bitwidth=auto]{20}
-%         \bitheader[b]{0-19} \\
+%       \begin{bytefield}[bitformatting={\small\bfseries},
+%                         bitwidth=auto,
+%                         endianness=big]{20}
+%         \bitheader{0-19} \\
 %         \bitbox{1}{\tiny F/E} & \bitbox{1}{\tiny T0} & \bitbox{1}{\tiny T1}
 %         & \bitbox{1}{\tiny Fwd} & \bitbox{16}{Data value} \\
 %       \end{bytefield}
@@ -652,8 +788,9 @@
 %
 % \begin{verbatim}
 %       \begin{bytefield}[boxformatting={\centering\itshape},
-%                         bitwidth=1.5em]{20}
-%         \bitheader[b]{0-19} \\
+%                         bitwidth=1.5em,
+%                         endianness=big]{20}
+%         \bitheader{0-19} \\
 %         \bitbox{1}{\tiny F/E} & \bitbox{1}{\tiny T0} & \bitbox{1}{\tiny T1}
 %         & \bitbox{1}{\tiny Fwd} & \bitbox{16}{Data value} \\
 %       \end{bytefield}
@@ -664,8 +801,9 @@
 %
 % \begin{bffigure}
 %       \begin{bytefield}[boxformatting={\centering\itshape},
-%                         bitwidth=1.5em]{20}
-%         \bitheader[b]{0-19} \\
+%                         bitwidth=1.5em,
+%                         endianness=big]{20}
+%         \bitheader{0-19} \\
 %         \bitbox{1}{\tiny F/E} & \bitbox{1}{\tiny T0} & \bitbox{1}{\tiny T1}
 %         & \bitbox{1}{\tiny Fwd} & \bitbox{16}{Data value} \\
 %       \end{bytefield}
@@ -686,7 +824,7 @@
 %
 % \begin{verbatim}
 %       \begin{bytefield}[rightcurly=., rightcurlyspace=0pt]{32}
-%         \bitheader[b]{0,7,8,15,16,23,24,31} \\
+%         \bitheader[endianness=big]{0,7,8,15,16,23,24,31} \\
 %         \begin{rightwordgroup}{0Ch}
 %           \bitbox{8}{Byte 15 \\ \tiny (highest address)}
 %           & \bitbox{8}{Byte 14}
@@ -704,13 +842,13 @@
 %           & \bitbox{8}{Byte 2}
 %           & \bitbox{8}{Byte 1}
 %           & \bitbox{8}{Byte 0 \\ \tiny (lowest address)}
-%         \end{rightwordgroup} \\
+%         \end{rightwordgroup}
 %       \end{bytefield}
 % \end{verbatim}
 %
 % \begin{bffigure}
 %       \begin{bytefield}[rightcurly=., rightcurlyspace=0pt]{32}
-%         \bitheader[b]{0,7,8,15,16,23,24,31} \\
+%         \bitheader[endianness=big]{0,7,8,15,16,23,24,31} \\
 %         \begin{rightwordgroup}{0Ch}
 %           \bitbox{8}{Byte 15 \\ \tiny (highest address)}
 %           & \bitbox{8}{Byte 14}
@@ -728,7 +866,7 @@
 %           & \bitbox{8}{Byte 2}
 %           & \bitbox{8}{Byte 1}
 %           & \bitbox{8}{Byte 0 \\ \tiny (lowest address)}
-%         \end{rightwordgroup} \\
+%         \end{rightwordgroup}
 %       \end{bytefield}
 % \end{bffigure}
 %
@@ -802,6 +940,50 @@
 % \optname{rightcurly}, described above) with symbols of substantially
 % different heights.
 %
+% \begin{decl}
+%   \optname{lsb} = \meta{integer}
+% \end{decl}
+%
+% Designate the least significant bit (LSB) in the bit header.  By
+% default, the LSB is zero, which means that the first bit position in
+% the header corresponds to bit~0.  Specifying a different LSB shifts
+% the bit header such that the first bit position instead corresponds to
+% \meta{integer}.  Note that the \optname{lsb} option affects bit
+% \emph{positions} regardless of whether these positions are labeled, as
+% demonstrated by the following two examples:
+%
+% \begin{verbatim}
+%       \begin{bytefield}{32}
+%         \bitheader[lsb=0]{4,12,20,28} \\
+%         \bitbox{16}{ar\$hrd} & \bitbox{16}{ar\$pro} \\
+%         \bitbox{8}{ar\$hln} & \bitbox{8}{ar\$pln} & \bitbox{16}{ar\$op} \\
+%       \end{bytefield}
+% \end{verbatim}
+%
+% \begin{bffigure}
+%       \begin{bytefield}{32}
+%         \bitheader[lsb=0]{4,12,20,28} \\
+%         \bitbox{16}{ar\$hrd} & \bitbox{16}{ar\$pro} \\
+%         \bitbox{8}{ar\$hln} & \bitbox{8}{ar\$pln} & \bitbox{16}{ar\$op} \\
+%       \end{bytefield}
+% \end{bffigure}
+%
+% \begin{verbatim}
+%       \begin{bytefield}{32}
+%         \bitheader[lsb=4]{4,12,20,28} \\
+%         \bitbox{16}{ar\$hrd} & \bitbox{16}{ar\$pro} \\
+%         \bitbox{8}{ar\$hln} & \bitbox{8}{ar\$pln} & \bitbox{16}{ar\$op} \\
+%       \end{bytefield}
+% \end{verbatim}
+%
+% \begin{bffigure}
+%       \begin{bytefield}{32}
+%         \bitheader[lsb=4]{4,12,20,28} \\
+%         \bitbox{16}{ar\$hrd} & \bitbox{16}{ar\$pro} \\
+%         \bitbox{8}{ar\$hln} & \bitbox{8}{ar\$pln} & \bitbox{16}{ar\$op} \\
+%       \end{bytefield}
+% \end{bffigure}
+%
 %
 % \subsection{Common tricks}
 % \label{sec:tricks}
@@ -839,8 +1021,8 @@
 %         \bitbox{8}{Type} & \bitbox{8}{\# of nodes} \\
 %         \wordbox{1}{Node~1} \\
 %         \wordbox{1}{Node~2} \\
-%         \wordbox[]{1}{$\vdots$ \\[1ex]} \\
-%         \wordbox{1}{Node~$N$} \\
+%         \wordbox[]{1}{$\vdots$} \\[1ex]
+%         \wordbox{1}{Node~$N$}
 %       \end{bytefield}
 % \end{verbatim}
 %
@@ -849,13 +1031,14 @@
 %         \bitbox{8}{Type} & \bitbox{8}{\# of nodes} \\
 %         \wordbox{1}{Node~1} \\
 %         \wordbox{1}{Node~2} \\
-%         \wordbox[]{1}{$\vdots$ \\[1ex]} \\
-%         \wordbox{1}{Node~$N$} \\
+%         \wordbox[]{1}{$\vdots$} \\[1ex]
+%         \wordbox{1}{Node~$N$}
 %       \end{bytefield}
 % \end{bffigure}
 %
 % \noindent
-% The extra |1ex| of vertical space helps center the |\vdots| a bit better.
+% The extra |1ex| of vertical space helps vertically center the |\vdots|
+% a bit better.
 %
 % \paragraph{Narrow fields}
 % There are a number of options for labeling a narrow field (e.g.,~one
@@ -897,6 +1080,13 @@
 %   \end{bytefield}
 % \end{lrbox}
 %
+% \newsavebox{\resizeOK}
+% \begin{lrbox}{\resizeOK}
+%   \begin{bytefield}{8}
+%     \bitbox{1}{\let\bw=\width\resizebox{\bw}{!}{~OK~}} & \bitbox{7}{Data} \\
+%   \end{bytefield}
+% \end{lrbox}
+%
 % \bigskip
 %
 % \begin{tabular}{ll}
@@ -907,8 +1097,118 @@
 %   |\tiny OK|: & \raisebox{-4ex}{\usebox{\tinyOK}} \\
 %   |\tiny O \\ K|: & \raisebox{-4ex}{\usebox{\verticalOK}} \\
 %   |\rotatebox{90}{\small OK}|: & \raisebox{-4ex}{\usebox{\rotateOK}} \\
+%   |\let\bw=\width| & \multirow{2}*{\raisebox{-4ex}{\usebox{\resizeOK}}} \\
+%   |\resizebox{\bw}{!}{~OK~}|: & \\[2ex]
 % \end{tabular}
 %
+% \paragraph{Multi-line bit fields}
+% Presentations of wide registers are often easier to read when split
+% across multiple lines.  (This capability was originally requested by
+% Chris L'Esperance and is currently implemented in \pkgname{bytefield}
+% based on code provided by Renaud Pacalet.)  The trick behind the
+% typesetting of multi-line bit fields is to pass the \optname{lsb}
+% option to |\bitheader| to change the starting bit number used in each
+% bit header:
+%
+% \begin{verbatim}
+%       \begin{bytefield}[endianness=big,bitwidth=2em]{16}
+%         \bitheader[lsb=16]{16-31} \\
+%         \bitbox{1}{\tiny Enable} & \bitbox{7}{Reserved}
+%         & \bitbox{8}{Bus} \\[3ex]
+%         \bitheader{0-15} \\
+%         \bitbox{5}{Device} & \bitbox{3}{Function} & \bitbox{6}{Register}
+%         & \bitbox{2}{00}
+%       \end{bytefield}
+% \end{verbatim}
+%
+% \begin{bffigure}
+%       \begin{bytefield}[endianness=big,bitwidth=2em]{16}
+%         \bitheader[lsb=16]{16-31} \\
+%         \bitbox{1}{\tiny Enable} & \bitbox{7}{Reserved}
+%         & \bitbox{8}{Bus} \\[3ex]
+%         \bitheader{0-15} \\
+%         \bitbox{5}{Device} & \bitbox{3}{Function} & \bitbox{6}{Register}
+%         & \bitbox{2}{00}
+%       \end{bytefield}
+% \end{bffigure}
+%
+% Note the use of the optional argument to |\\| to introduce three
+% \mbox{x-heights} of additional whitespace between the two rows of
+% bits.
+%
+% \paragraph{Rotated bit labels}
+% A problem with using very large bit numbers is that the labels run
+% into each other, as in the following example:
+%
+% \begin{verbatim}
+%       \begin{bytefield}[endianness=big]{8}
+%         \bitheader[lsb=995]{995-1002} \\
+%         \bitbox{4}{A} & \bitbox{4}{B}
+%       \end{bytefield}
+% \end{verbatim}
+%
+% \begin{bffigure}
+%       \begin{bytefield}[endianness=big]{8}
+%         \bitheader[lsb=995]{995-1002} \\
+%         \bitbox{4}{A} & \bitbox{4}{B}
+%       \end{bytefield}
+% \end{bffigure}
+%
+% One solution is to use the \optname{bitformatting} option and the
+% \pkgname{graphicx} package's |\rotatebox| command to rotate each bit
+% label by 90\textdegree.  Unfortunately, the naive use of
+% \optname{bitformatting} and |\rotatebox| does not typeset nicely:
+%
+% \begin{verbatim}
+%       \begin{bytefield}[endianness=big]{8}
+%         \bitheader[lsb=995,
+%                    bitformatting={\tiny\rotatebox[origin=B]{90}}]{995-1002} \\
+%         \bitbox{4}{A} & \bitbox{4}{B}
+%       \end{bytefield}
+% \end{verbatim}
+%
+% \begin{bffigure}
+%       \begin{bytefield}[endianness=big]{8}
+%         \bitheader[lsb=995,
+%                    bitformatting={\tiny\rotatebox[origin=B]{90}}]{995-1002} \\
+%         \bitbox{4}{A} & \bitbox{4}{B}
+%       \end{bytefield}
+% \end{bffigure}
+%
+% The two problems are that (1)~the numbers are left-justified, and
+% (2)~the numbers touch the top margin of the word box.  To address these
+% problems we use |\makebox| to construct a right-justified region that
+% is sufficiently wide to hold our largest number plus some additional
+% space to shift the rotated numbers upwards:
+%
+% \begin{verbatim}
+%       \newlength{\bitlabelwidth}
+%       \newcommand{\rotbitheader}[1]{%
+%         \tiny
+%         \settowidth{\bitlabelwidth}{\quad 9999}%
+%         \rotatebox[origin=B]{90}{\makebox[\bitlabelwidth][r]{#1}}%
+%       }
+%
+%       \begin{bytefield}[endianness=big]{8}
+%         \bitheader[lsb=995,bitformatting=\rotbitheader]{995-1002} \\
+%         \bitbox{4}{A} & \bitbox{4}{B}
+%       \end{bytefield}
+% \end{verbatim}
+%
+% \begin{bffigure}
+%       \newlength{\bitlabelwidth}
+%       \newcommand{\rotbitheader}[1]{^^A
+%         \tiny
+%         \settowidth{\bitlabelwidth}{\quad 9999}%
+%         \rotatebox[origin=B]{90}{\makebox[\bitlabelwidth][r]{#1}}^^A
+%       }
+%
+%       \begin{bytefield}[endianness=big]{8}
+%         \bitheader[lsb=995,bitformatting=\rotbitheader]{995-1002} \\
+%         \bitbox{4}{A} & \bitbox{4}{B}
+%       \end{bytefield}
+% \end{bffigure}
+%
 % \paragraph{Unused bits}
 % Because |\width| and |\height| are defined within bit boxes (also word
 % boxes), we can represent unused bits by filling a |\bitbox| with a
@@ -936,7 +1236,7 @@
 %
 % \noindent
 % The effect is much better when the \pkgname{color} package is used to
-% draw the unused bits in color.  (Gray looks nice.)
+% draw the unused bits in color.  (Light gray looks nice.)
 %
 % \begin{verbatim}
 %       \definecolor{lightgray}{gray}{0.8}
@@ -964,18 +1264,18 @@
 % Because \pkgname{bytefield} internally uses \LaTeX's |picture|
 % environment and that environment's |\makebox| command to draw bit
 % boxes and word boxes, the text within a box is centered vertically
-% with no attention paid to the text's baseline.  As a result, some bit
-% fields appear somewhat askew:
+% with no attention paid to the text's baseline.  As a result, some
+% bit-field labels appear somewhat askew:
 %
 % \begin{verbatim}
 %       \begin{bytefield}[bitwidth=1.5em]{2}
-%         \bitbox{1}{M} & \bitbox{1}{y} \\
+%         \bitbox{1}{M} & \bitbox{1}{y}
 %       \end{bytefield}
 % \end{verbatim}
 %
 % \begin{bffigure}
 %       \begin{bytefield}[bitwidth=1.5em]{2}
-%         \bitbox{1}{M} & \bitbox{1}{y} \\
+%         \bitbox{1}{M} & \bitbox{1}{y}
 %       \end{bytefield}
 % \end{bffigure}
 %
@@ -995,20 +1295,20 @@
 %
 %       \begin{bytefield}[boxformatting=\baselinealign,
 %                         bitwidth=1.5em]{2}
-%         \bitbox{1}{M} & \bitbox{1}{y} \\
+%         \bitbox{1}{M} & \bitbox{1}{y}
 %       \end{bytefield}
 % \end{verbatim}
 %
 % \begin{bffigure}
 %       \newlength{\maxheight}
 %       \setlength{\maxheight}{\heightof{W}}
-%       \newcommand{\baselinealign}[1]{%
+%       \newcommand{\baselinealign}[1]{^^A
 %         \centering
-%         \raisebox{0pt}[\maxheight][0pt]{#1}%
+%         \raisebox{0pt}[\maxheight][0pt]{#1}^^A
 %       }
 %       \begin{bytefield}[boxformatting=\baselinealign,
 %                         bitwidth=1.5em]{2}
-%         \bitbox{1}{M} & \bitbox{1}{y} \\
+%         \bitbox{1}{M} & \bitbox{1}{y}
 %       \end{bytefield}
 % \end{bffigure}
 %
@@ -1043,7 +1343,7 @@
 %         \bitbox{1}{0} & \bitbox{1}{1} & \bitbox{1}{0} & \bitbox{1}{0} &
 %         \bitbox{1}{0} & \bitbox{1}{0} & \bitbox{1}{0} & \bitbox{1}{1} &
 %         \bitbox{1}{0} & \bitbox{1}{1} & \bitbox{1}{0} & \bitbox{1}{0} &
-%         \bitbox{1}{0} & \bitbox{1}{0} & \bitbox{1}{0} & \bitbox{1}{0} \\
+%         \bitbox{1}{0} & \bitbox{1}{0} & \bitbox{1}{0} & \bitbox{1}{0}
 %       \end{bytefield}
 % \end{verbatim}
 %
@@ -1069,7 +1369,7 @@
 %         \bitbox{1}{0} & \bitbox{1}{1} & \bitbox{1}{0} & \bitbox{1}{0} &
 %         \bitbox{1}{0} & \bitbox{1}{0} & \bitbox{1}{0} & \bitbox{1}{1} &
 %         \bitbox{1}{0} & \bitbox{1}{1} & \bitbox{1}{0} & \bitbox{1}{0} &
-%         \bitbox{1}{0} & \bitbox{1}{0} & \bitbox{1}{0} & \bitbox{1}{0} \\
+%         \bitbox{1}{0} & \bitbox{1}{0} & \bitbox{1}{0} & \bitbox{1}{0}
 %       \end{bytefield}
 % \end{bffigure}
 %
@@ -1083,140 +1383,52 @@
 % follows it to the right:
 %
 % \begin{verbatim}
-%       \begingroup
-%         \small
-%         \newcommand{\colorbitbox}[3]{%
-%           \rlap{\bitbox{#2}{\color{#1}\rule{\width}{\height}}}%
-%           \bitbox{#2}{#3}}
-%         \definecolor{lightcyan}{rgb}{0.84,1,1}
-%         \definecolor{lightgreen}{rgb}{0.64,1,0.71}
-%         \definecolor{lightred}{rgb}{1,0.7,0.71}
-%
-%         \begin{bytefield}[bitheight=\widthof{~Sign~}]{32}
-%           \bitheader[b]{31,23,0} \\
-%           \colorbitbox{lightcyan}{1}{\rotatebox{90}{Sign}} &
-%           \colorbitbox{lightgreen}{8}{Exponent} &
-%           \colorbitbox{lightred}{23}{Mantissa} \\
-%         \end{bytefield}
-%       \endgroup
-% \end{verbatim}
-%
-% \begin{bffigure}
-%       \begingroup
-%         \small
-%         \newcommand{\colorbitbox}[3]{^^A
-%           \rlap{\bitbox{#2}{\color{#1}\rule{\width}{\height}}}^^A
-%           \bitbox{#2}{#3}}^^A
-%         \definecolor{lightcyan}{rgb}{0.84,1,1}^^A
-%         \definecolor{lightgreen}{rgb}{0.64,1,0.71}^^A
-%         \definecolor{lightred}{rgb}{1,0.7,0.71}^^A
-%         \bytefieldsetup{bitheight=\widthof{~Sign~}}^^A
-%         \begin{bytefield}[bitheight=\widthof{~Sign~}]{32}
-%           \bitheader[b]{31,23,0} \\
-%           \colorbitbox{lightcyan}{1}{\rotatebox{90}{Sign}} &
-%           \colorbitbox{lightgreen}{8}{Exponent} &
-%           \colorbitbox{lightred}{23}{Mantissa} \\
-%         \end{bytefield}
-%       \endgroup
-% \end{bffigure}
-%
-% \paragraph{Renumbered bit headers}
-% The |\bitheader| macro always numbers bits starting from~0.  However,
-% one may occasionally want to begin numbering from a different value.
-% (This was in fact a feature request from Chris L'Esperance.)  The way
-% to accomplish this is to define a macro that adds a value to its
-% argument and specify this macro to the \optname{bitformatting}
-% parameter.  This works because the argument passed to a macro named by
-% \optname{bitformatting} is always numeric except when called from
-% |bitwidth=auto|.  (Caveat: This happens automatically at the
-% |\begin{document}|.)  However, \pkgname{bytefield} sometimes passes a
-% \optname{bitformatting}-named macro the value~|1234567890| to measure
-% the height of a formatted bit number.  The examples below include a
-% case in which this value needs to be checked explicitly to ensure that
-% the height is correct even when the formatted number is rotated by
-% 90\textdegree.
-%
-% \begin{verbatim}
-%       \begin{bytefield}{16}
-%         \bitheader{0-15} \\
-%         \bitbox{8}{Header} & \bitbox{8}{First byte} \\
+%       \newcommand{\colorbitbox}[3]{%
+%         \rlap{\bitbox{#2}{\color{#1}\rule{\width}{\height}}}%
+%         \bitbox{#2}{#3}}
+%       \definecolor{lightcyan}{rgb}{0.84,1,1}
+%       \definecolor{lightgreen}{rgb}{0.64,1,0.71}
+%       \definecolor{lightred}{rgb}{1,0.7,0.71}
+%       \begin{bytefield}[bitheight=\widthof{~Sign~},
+%                         boxformatting={\centering\small}]{32}
+%         \bitheader[endianness=big]{31,23,0} \\
+%         \colorbitbox{lightcyan}{1}{\rotatebox{90}{Sign}} &
+%         \colorbitbox{lightgreen}{8}{Exponent} &
+%         \colorbitbox{lightred}{23}{Mantissa}
 %       \end{bytefield}
 % \end{verbatim}
 %
 % \begin{bffigure}
-%       \begin{bytefield}{16}
-%         \bitheader{0-15} \\
-%         \bitbox{8}{Header} & \bitbox{8}{First byte} \\
+%       \newcommand{\colorbitbox}[3]{^^A
+%         \rlap{\bitbox{#2}{\color{#1}\rule{\width}{\height}}}^^A
+%         \bitbox{#2}{#3}}^^A
+%       \definecolor{lightcyan}{rgb}{0.84,1,1}
+%       \definecolor{lightgreen}{rgb}{0.64,1,0.71}
+%       \definecolor{lightred}{rgb}{1,0.7,0.71}
+%       \begin{bytefield}[bitheight=\widthof{~Sign~},
+%                         boxformatting={\centering\small}]{32}
+%         \bitheader[endianness=big]{31,23,0} \\
+%         \colorbitbox{lightcyan}{1}{\rotatebox{90}{Sign}} &
+%         \colorbitbox{lightgreen}{8}{Exponent} &
+%         \colorbitbox{lightred}{23}{Mantissa}
 %       \end{bytefield}
 % \end{bffigure}
 %
-% \begin{verbatim}
-%       \newcommand{\formatplusXVI}[1]{%
-%         \tiny
-%         \count10=#1
-%         \advance\count10 by 16
-%         \the\count10
-%       }
-%       \begin{bytefield}[bitformatting=\formatplusXVI]{16}
-%         \bitheader{0-15} \\
-%         \bitbox{8}{Second byte} & \bitbox{8}{Third byte} \\
-%       \end{bytefield}
-% \end{verbatim}
-%
-% \begin{bffigure}
-%       \newcommand{\formatplusXVI}[1]{%
-%         \tiny
-%         \count10=#1
-%         \advance\count10 by 16
-%         \the\count10
-%       }
-%       \begin{bytefield}[bitformatting=\formatplusXVI]{16}
-%         \bitheader{0-15} \\
-%         \bitbox{8}{Second byte} & \bitbox{8}{Third byte} \\
-%       \end{bytefield}
-% \end{bffigure}
-%
-% \begin{verbatim}
-%       \newcommand{\formatplusMMMMMMMMCLXXVI}[1]{%
-%         \tiny
-%         \count10=#1
-%         \ifnum\count10=1234567890
-%           \rotatebox[origin=B]{90}{8191}%
-%         \else
-%           \advance\count10 by 8176
-%           \rotatebox[origin=B]{90}{\the\count10}%
-%         \fi
-%       }
-%
-%       \begin{bytefield}[bitformatting=\formatplusMMMMMMMMCLXXVI]{16}
-%         \bitheader{0-15} \\
-%         \bitbox{8}{1022nd byte} & \bitbox{8}{Trailer} \\
-%       \end{bytefield}
-% \end{verbatim}
-%
-% \begin{bffigure}
-%       \newcommand{\formatplusMMMMMMMMCLXXVI}[1]{%
-%         \tiny
-%         \count10=#1
-%         \ifnum\count10=1234567890
-%           \rotatebox[origin=B]{90}{8191}%
-%         \else
-%           \advance\count10 by 8176
-%           \rotatebox[origin=B]{90}{\the\count10}%
-%         \fi
-%       }
-%       \begin{bytefield}[bitformatting=\formatplusMMMMMMMMCLXXVI]{16}
-%         \bitheader{0-15} \\
-%         \bitbox{8}{1022nd byte} & \bitbox{8}{Trailer} \\
-%       \end{bytefield}
-% \end{bffigure}
-%
-% As an even trickier example of modifying bit numbers, the following
-% shows how to \emph{conditionally} modify the bit number: If the number
-% is |1234567890| (for \pkgname{bytefield}'s bit-height calculation, the
-% number is used as is; numbers greater than~9 are increased by 48;
-% numbers less than~4 are unmodified; the number~6 is replaced by an
-% ellipsis; and all other numbers are discarded.
+% \paragraph{Omitted bit numbers}
+% It is occasionally convenient to show a wide bit field in which the
+% middle numbers are replaced with an ellipsis.  The trick to
+% typesetting such a thing with \pkgname{bytefield} is to point the
+% |bitformatting| option to a macro that conditionally modifies the
+% given bit number before outputting it.  One catch is that
+% \pkgname{bytefield} measures the height of the string ``|1234567890|''
+% using the current bit formatting, so that needs to be a valid input.
+% (If \optname{bitwidth} is set to ``|auto|'', then ``|99i|'' also has
+% to be a valid input, but we're not using ``|auto|'' here.)  The
+% following example shows how to \emph{conditionally} modify the bit
+% number: If the number is |1234567890|, it is used as is; numbers
+% greater than~9 are increased by 48; numbers less than~4 are
+% unmodified; the number~6 is replaced by an ellipsis; and all other
+% numbers are discarded.
 %
 % \begin{verbatim}
 %       \newcommand{\fakesixtyfourbits}[1]{%
@@ -1241,10 +1453,11 @@
 %       }
 %       \begin{bytefield}[%
 %           bitwidth=\widthof{\tiny Fwd~},
-%           bitformatting=\fakesixtyfourbits]{16}
-%         \bitheader[b]{0-15} \\
+%           bitformatting=\fakesixtyfourbits,
+%           endianness=big]{16}
+%         \bitheader{0-15} \\
 %         \bitbox{1}{\tiny F/E} & \bitbox{1}{\tiny T0} & \bitbox{1}{\tiny T1}
-%         & \bitbox{1}{\tiny Fwd} & \bitbox{12}{Data value} \\
+%         & \bitbox{1}{\tiny Fwd} & \bitbox{12}{Data value}
 %       \end{bytefield}
 % \end{verbatim}
 %
@@ -1257,24 +1470,25 @@
 %           \ifnum#1>9
 %             \count32=#1
 %             \advance\count32 by 48
-%             \the\count32%
+%             \the\count32^^A
 %           \else
 %             \ifnum#1<4
 %               #1%
 %             \else
 %               \ifnum#1=6
-%                 $\cdots$%
+%                 $\cdots$^^A
 %               \fi
 %             \fi
 %           \fi
 %         \fi
 %       }
-%       \begin{bytefield}[%
+%       \begin{bytefield}[^^A
 %           bitwidth=\widthof{\tiny Fwd~},
-%           bitformatting=\fakesixtyfourbits]{16}
-%         \bitheader[b]{0-15} \\
+%           bitformatting=\fakesixtyfourbits,
+%           endianness=big]{16}
+%         \bitheader{0-15} \\
 %         \bitbox{1}{\tiny F/E} & \bitbox{1}{\tiny T0} & \bitbox{1}{\tiny T1}
-%         & \bitbox{1}{\tiny Fwd} & \bitbox{12}{Data value} \\
+%         & \bitbox{1}{\tiny Fwd} & \bitbox{12}{Data value}
 %       \end{bytefield}
 % \end{bffigure}
 %
@@ -1316,7 +1530,8 @@
 %           \bitbox{24}{\descbox{4096~byte area for MS-DOS and Windows~3.1
 %             compatibility.}{Protected---catches \textsc{null}
 %             pointers.}}
-%         \end{rightwordgroup} \\
+%         \end{rightwordgroup}
+%       \end{bytefield}
 % \end{verbatim}
 %
 % \begin{bffigure}
@@ -1352,7 +1567,7 @@
 %           \bitbox{24}{\descbox{4096~byte area for MS-DOS and Windows~3.1
 %             compatibility.}{Protected---catches \textsc{null}
 %             pointers.}}
-%         \end{rightwordgroup} \\
+%         \end{rightwordgroup}
 %       \end{bytefield}
 % \end{bffigure}
 %
@@ -1408,7 +1623,6 @@
 % \noindent
 % Figure~\ref{fig:complex-diagram} shows the resulting protocol diagram.
 %
-% \newsavebox{\protocoldiagram}
 % \begin{figure}[phtb]
 %    \centering
 %    \begin{lrbox}{\protocoldiagram}
@@ -1464,7 +1678,7 @@
 % \pkgname{bytefield}'s user interface changed substantially with the
 % introduction of version~2.0.  Because documents written for
 % \pkgname{bytefield}~v1.\textit{x} will not build properly under later
-% versions of the package, this section shows how to convert documents
+% versions of the package, this section explains how to convert documents
 % to the new interface.
 %
 % \begin{decl}
@@ -1536,6 +1750,23 @@
 % described in Section~\ref{sec:basic-cmds}, left and right curly-brace
 % height can be reduced independently if desired.
 %
+% \begin{decl}
+%   \SpecialUsageIndex{\bitwidth}
+%   |\bitwidth| \oarg{endianness} \marg{bit-positions}
+% \end{decl}
+%
+% The meaning of |\bitwidth|'s optional argument changed with
+% \pkgname{bytefield}~v2.1.  In older versions of the package, the
+% optional argument was one of ``|l|'' or ``|b|'' for, respectively,
+% little-endian or big-endian bit ordering.  Starting with version~2.1,
+% the optional argument can be any of the parameters described in
+% Section~\ref{sec:options} (but practically only |bitformatting|,
+% |endianness|, and |lsb|).  Hence, ``|l|'' should be replaced with
+% |endianness=little| and ``|b|'' should be replaced with
+% |endianness=big|.  Although more verbose, these new options can be
+% specified once for the entire document by listing them as package
+% options or as arguments to |\bytefieldsetup|.
+%
 % \bigskip
 %
 % As a crutch to help build older documents with minimal modification,
@@ -1581,7 +1812,7 @@
 %
 % \section{Implementation}
 %
-% \newcommand{\usermacro}{\marginpar{\vspace*{1ex}{\hspace{18pt}\huge$\star$}\vspace*{-1ex}}}
+% \newcommand{\usermacro}{\marginpar{\vspace*{1ex}{\strut\hspace{18pt}\huge$\star$}\vspace*{-1ex}}}
 %
 % This section contains the complete source code for \pkgname{bytefield}.
 % Most users will not get much out of it, but it should be of use to
@@ -1685,19 +1916,11 @@
 %
 % \subsection{Top-level environment}
 %
-% \begin{macro}{bits@wide}
-% The number of bits in each word (i.e., the argument to the |\bytefield|
-% environment).
-%    \begin{macrocode}
-\newcounter{bits@wide}
-%    \end{macrocode}
-% \end{macro}
-%
 % \begin{macro}{\entire@bytefield@picture}
-% A box containing the entire bytefield.  By storing everything in a box
-% and then typesetting it later (at the |\end{bytefield}|), we can center
-% the bit field, put a box around it, and do other operations on the entire
-% figure.
+% Declare a box for containing the entire bytefield.  By storing
+% everything in a box and then typesetting it later (at the
+% |\end{bytefield}|), we can center the bit field, put a box around it,
+% and do other operations on the entire figure.
 %    \begin{macrocode}
 \newsavebox{\entire@bytefield@picture}
 %    \end{macrocode}
@@ -1705,19 +1928,21 @@
 %
 % \begin{environment}{bytefield}
 % \usermacro
+% \begin{macro}{\bits@wide}
 % \begin{macro}{\old@nl}
 % \begin{macro}{\amp}
-% Environment containing the layout of bits in a sequence of bytes.
-% This is the main environment defined by the \pkgname{bytefield} package.
-% The argument is the number of bits wide the bytefield should be.
-% We turn |&| into a space character so the user can think of a
-% \pkgname{bytefield} as being analogous to a \texttt{tabular} environment,
-% even though we're really setting the bulk of the picture in a single
-% column.  (Row labels go in separate columns, however.)
+% The |bytefield| environment contains the layout of bits in a sequence
+% of words.  This is the main environment defined by the
+% \pkgname{bytefield} package.  The argument is the number of bits wide
+% the bytefield should be.  We turn |&| into a space character so the
+% user can think of a \pkgname{bytefield} as being analogous to a
+% \texttt{tabular} environment, even though we're really setting the
+% bulk of the picture in a single column.  (Row labels go in separate
+% columns, however.)
 %    \begin{macrocode}
 \newenvironment{bytefield}[2][]{%
   \bf@bytefieldsetup{#1}%
-  \setcounter{bits@wide}{#2}%
+  \def\bits@wide{#2}%
   \let\old@nl=\\%
   \let\amp=&%
   \catcode`\&=10
@@ -1729,12 +1954,18 @@
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}
+% \end{macro}
 % \begin{macro}{\\}
+% \usermacro
 % We redefine |\\| within the |bytefield| environment to make it aware
 % of curly braces that surround the protocol diagram.
+% \changes{v2.1}{2011/06/12}{Augmented the definition
+%   of~\texttt{\string\string\string\\} to accept an optional argument,
+%   just like in a \texttt{tabular} environment}
 %    \begin{macrocode}
-  \renewcommand{\\}{%
+  \renewcommand{\\}[1][0pt]{%
     \unskip
+    \vspace{##1}%
     \amp\show@wordlabelr\cr
     \ignorespaces\global\counting@wordstrue\make@lspace\amp}%
 %    \end{macrocode}
@@ -1753,7 +1984,7 @@
 % \subsubsection{Drawing (proper)}
 %
 % \begin{macro}{\bf@bitformatting}
-% Formats a bit number in the bit header.  |\bf@bitformatting| may be
+% Format a bit number in the bit header.  |\bf@bitformatting| may be
 % redefined to take either a single argument (\`a~la |\textbf|) or no
 % argument (\`a~la |\small|).
 % \changes{v1.4}{2011/01/15}{Introduced this macro at Steven R. King's
@@ -1764,7 +1995,7 @@
 % \end{macro}
 %
 % \begin{macro}{\bf@boxformatting}
-% Formats the text within a bit box or word box.  |\bf@boxformatting|
+% Format the text within a bit box or word box.  |\bf@boxformatting|
 % takes either a single argument (\`a~la |\textbf|) or no argument
 % (\`a~la |\small|).  The text that follows |\bf@boxformatting| is
 % guaranteed to be a group that ends in |\par|, so if
@@ -1776,9 +2007,9 @@
 % \end{macro}
 %
 % \begin{macro}{\bf@bitwidth}
-% The width of a single bit.  Note that this is wide enough to display a
-% two-digit number without it running into adjacent numbers.  For larger
-% words, be sure to |\setlength| this larger.
+% Define the width of a single bit.  Note that this is wide enough to
+% display a two-digit number without it running into adjacent numbers.
+% For larger words, be sure to |\setlength| this larger.
 %    \begin{macrocode}
 \newlength{\bf@bitwidth}
 \settowidth{\bf@bitwidth}{\bf@bitformatting{99i}}
@@ -1786,7 +2017,7 @@
 % \end{macro}
 %
 % \begin{macro}{\bf@bitheight}
-% The height of a single bit within the bit field.
+% This is the height of a single bit within the bit field.
 %    \begin{macrocode}
 \newlength{\bf@bitheight}
 \setlength{\bf@bitheight}{4ex}
@@ -1795,8 +2026,8 @@
 %
 % \begin{macro}{\units@wide}
 % \begin{macro}{\units@tall}
-% Scratch variables for storing the width and height (in points) of
-% the box we're about to draw.
+% These are scratch variables for storing the width and height (in
+% points) of the box we're about to draw.
 %    \begin{macrocode}
 \newlength{\units@wide}
 \newlength{\units@tall}
@@ -1813,7 +2044,7 @@
 %    \begin{macrocode}
 \DeclareRobustCommand{\bitbox}[3][lrtb]{%
   \setlength{\units@wide}{\bf@bitwidth * #2}%
-  \parse@bitbox@arg{#1}%
+  \bf@parse@bitbox@arg{#1}%
   \draw@bit@picture{\strip@pt\units@wide}{\strip@pt\bf@bitheight}{#3}}
 %    \end{macrocode}
 % \end{macro}
@@ -1821,14 +2052,14 @@
 % \begin{macro}{\wordbox}
 % \usermacro
 % Put some text (|#3|) in a box that's a given number of bytes (|#2|)
-% tall and one word (|bits@wide| bits) wide.
+% tall and one word (|\bits@wide| bits) wide.
 % An optional argument (|#1|) specifies which lines to draw---|[l]|eft,
 % |[r]|ight, |[t]|op, and/or |[b]|ottom (default: |lrtb|).
 %    \begin{macrocode}
 \DeclareRobustCommand{\wordbox}[3][lrtb]{%
-  \setlength{\units@wide}{\bf@bitwidth * \value{bits@wide}}%
+  \setlength{\units@wide}{\bf@bitwidth * \bits@wide}%
   \setlength{\units@tall}{\bf@bitheight * #2}%
-  \parse@bitbox@arg{#1}%
+  \bf@parse@bitbox@arg{#1}%
   \draw@bit@picture{\strip@pt\units@wide}{\strip@pt\units@tall}{#3}}
 %    \end{macrocode}
 % \end{macro}
@@ -1848,11 +2079,17 @@
   \begin{picture}(#1,#2)%
 %    \end{macrocode}
 % \begin{macro}{\height}
+% \usermacro
 % \begin{macro}{\depth}
+% \usermacro
 % \begin{macro}{\totalheight}
+% \usermacro
 % \begin{macro}{\width}
+% \usermacro
 % \begin{macro}{\widthunits}
+% \usermacro
 % \begin{macro}{\heightunits}
+% \usermacro
 %   First, we plot the user's text, with all sorts of useful lengths
 %   predefined.
 %    \begin{macrocode}
@@ -1929,25 +2166,25 @@
 % \end{macro}
 % \end{macro}
 %
-% \begin{macro}{\parse@bitbox@arg}
+% \begin{macro}{\bf@parse@bitbox@arg}
 % This main parsing macro merely resets the above conditionals and
-% calls a helper function, |\parse@bitbox@sides|.
+% calls a helper function, |\bf@parse@bitbox@sides|.
 %    \begin{macrocode}
-\def\parse@bitbox@arg#1{%
+\def\bf@parse@bitbox@arg#1{%
   \bitbox@topfalse
   \bitbox@bottomfalse
   \bitbox@leftfalse
   \bitbox@rightfalse
-  \parse@bitbox@sides#1X}
+  \bf@parse@bitbox@sides#1X}
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}{\parse@bitbox@sides}
-% The helper function for |\parse@bitbox@arg| parses a single letter,
+% \begin{macro}{\bf@parse@bitbox@sides}
+% The helper function for |\bf@parse@bitbox@arg| parses a single letter,
 % sets the appropriate conditional to \textsc{True}, and calls itself
 % tail-recursively until it sees an ``|X|''.
 %    \begin{macrocode}
-\def\parse@bitbox@sides#1{%
+\def\bf@parse@bitbox@sides#1{%
   \ifx#1X%
   \else
     \ifx#1t%
@@ -1965,7 +2202,7 @@
         \fi
       \fi
     \fi
-    \expandafter\parse@bitbox@sides
+    \expandafter\bf@parse@bitbox@sides
   \fi}
 %    \end{macrocode}
 % \end{macro}
@@ -1973,9 +2210,9 @@
 % \subsection{Skipped words}
 %
 % \begin{macro}{\units@high}
-% The height of each diagonal line in the |\skippedwords| graphic.
-% Note that |\units@high|~$=$ |\units@tall|~$-$ \textit{optional argument
-% to} |\skippedwords|.
+% This is the height of each diagonal line in the |\skippedwords|
+% graphic.  Note that |\units@high|~$=$ |\units@tall|~$-$
+% \textit{optional argument to} |\skippedwords|.
 %    \begin{macrocode}
 \newlength{\units@high}
 %    \end{macrocode}
@@ -1987,7 +2224,7 @@
 % is the vertical space between the two diagonal lines (default: |2ex|).
 %    \begin{macrocode}
 \DeclareRobustCommand{\skippedwords}[1][2ex]{%
-  \setlength{\units@wide}{\bf@bitwidth * \value{bits@wide}}%
+  \setlength{\units@wide}{\bf@bitwidth * \bits@wide}%
   \setlength{\units@high}{1pt * \ratio{\units@wide}{6.0pt}}%
   \setlength{\units@tall}{#1 + \units@high}%
   \edef\num@wide{\strip@pt\units@wide}%
@@ -2008,6 +2245,25 @@
 %
 % \subsection{Bit-position labels}
 %
+% \begin{macro}{\bf@bit@endianness}
+% \pkgname{bytefield} can label bit headers in either little-endian ($0,
+% 1, 2,~\ldots, N-1$) or big-endian ($N-1, N-2, N-3,~\ldots, 0$) fashion.
+% The |\bf@bit@endianness| macro specifies which to use, either ``|l|''
+% for little-endian (the default) or ``|b|'' for big-endian.
+%    \begin{macrocode}
+\newcommand*{\bf@bit@endianness}{l}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\bf@first@bit}
+% Normally, bits are numbered starting from zero.  However,
+% |\bf@first@bit| can be altered (usually locally) to begin numbering
+% from a different value.
+%    \begin{macrocode}
+\newcommand*{\bf@first@bit}{0}
+%    \end{macrocode}
+% \end{macro}
+%
 % \begin{macro}{\bitheader}
 % \usermacro
 % Output a header of numbered bit positions. The optional argument (|#1|)
@@ -2016,17 +2272,20 @@
 % It is composed of comma-separated ranges of numbers, for example,
 % ``|0-31|'', ``|0,7-8,15-16,23-24,31|'', or even something odd like
 % ``|0-7,15-23|''.  Ranges must be specified in increasing order; use the
-% optional argument to |\bitheader| to reverse the labels' direction.
-%    \begin{macrocode}
-\DeclareRobustCommand{\bitheader}[2][l]{%
-  \parse@bitbox@arg{lrtb}%
-  \setlength{\units@wide}{\bf@bitwidth * \value{bits@wide}}%
+% \optname{lsb} option to reverse the labels' direction.
+% \changes{v2.1}{2011/06/17}{Changed the optional argument to accept
+%   \meta{key}!=\meta{value} pairs instead of just ``\texttt{l}'' and
+%  ``\texttt{b}''}
+%    \begin{macrocode}
+\DeclareRobustCommand{\bitheader}[2][]{%
+  \bf@parse@bitbox@arg{lrtb}%
+  \setlength{\units@wide}{\bf@bitwidth * \bits@wide}%
   \setlength{\units@tall}{\heightof{\bf@bitformatting{1234567890}}}%
   \setlength{\units@high}{\units@tall * -1}%
-  \def\bit@endianness{#1}%
+  \bf@process@bitheader@opts{#1}%
   \begin{picture}(\strip@pt\units@wide,\strip@pt\units@tall)%
                  (0,\strip@pt\units@high)
-    \parse@range@list#2,X,
+    \bf@parse@range@list#2,X,
   \end{picture}%
   \ifcounting@words
     \inc@bytefield@height{\unitlength * \real{\strip@pt\units@tall}}%
@@ -2036,18 +2295,19 @@
 %    \end{macrocode}
 % \end{macro}
 %
-% \begin{macro}{\parse@range@list}
-% Helper function~\#1 for |\bitheader|---parse a comma-separated list of
-% ranges, calling |\parse@range| on each range.
+% \begin{macro}{\bf@parse@range@list}
+% This is helper function~\#1 for |\bitheader|.  It parses a
+% comma-separated list of ranges, calling |\bf@parse@range| on each
+% range.
 % \changes{v1.1}{2002/06/24}{Bug fix: Swapped order of arguments to
 %   \texttt{\string\bslash\space ifx} test (suggested by Hans-Joachim
 %   Widmaier)}
 %    \begin{macrocode}
-\def\parse@range@list#1,{%
+\def\bf@parse@range@list#1,{%
   \ifx X#1
   \else
-    \parse@range#1-#1-#1\relax
-    \expandafter\parse@range@list
+    \bf@parse@range#1-#1-#1\relax
+    \expandafter\bf@parse@range@list
   \fi}
 %    \end{macrocode}
 % \end{macro}
@@ -2055,8 +2315,9 @@
 % \begin{macro}{\header@xpos}
 % \begin{macro}{header@val}
 % \begin{macro}{max@header@val}
-% Miscellaneous variables used internally by |\parse@range|---$x$ position
-% of header, current label to output, and maximum label to output ($+ 1$).
+% Define some miscellaneous variables to be used internally by
+% |\bf@parse@range|---$x$ position of header, current label to output,
+% and maximum label to output ($+ 1$).
 %    \begin{macrocode}
 \newlength{\header@xpos}
 \newcounter{header@val}
@@ -2066,21 +2327,25 @@
 % \end{macro}
 % \end{macro}
 %
-% \begin{macro}{\parse@range}
-% Helper function~\#2 for |\bitheader|---parse a hyphen-separated pair
-% of numbers (or a single number) and display the number at the correct
-% bit position.
+% \begin{macro}{\bf@parse@range}
+% This is helper function~\#2 for |\bitheader|.  It parses a
+% hyphen-separated pair of numbers (or a single number) and displays the
+% number at the correct bit position.
+% \changes{v2.1}{2011/06/16}{Added code due to Renaud Pacalet for shifting
+%   the bit header by a distance corresponding to
+%   \texttt{\string\string\string\bf@first@bit}, used for typesetting
+%   registers split across rows}
 %    \begin{macrocode}
-\def\parse@range#1-#2-#3\relax{%
+\def\bf@parse@range#1-#2-#3\relax{%
   \setcounter{header@val}{#1}
   \setcounter{max@header@val}{#2 + 1}
   \loop
     \ifnum\value{header@val}<\value{max@header@val}%
-      \if\bit@endianness b%
+      \if\bf@bit@endianness b%
         \setlength{\header@xpos}{%
-          \bf@bitwidth * (\value{bits@wide}-\value{header@val}-1)}
+          \bf@bitwidth * (\bits@wide - \value{header@val} + \bf@first@bit - 1)}%
       \else
-        \setlength{\header@xpos}{\bf@bitwidth * \value{header@val}}
+        \setlength{\header@xpos}{\bf@bitwidth * (\value{header@val} - \bf@first@bit)}%
       \fi
       \put(\strip@pt\header@xpos,0){%
         \makebox(\strip@pt\bf@bitwidth,\strip@pt\units@tall){%
@@ -2090,6 +2355,64 @@
 %    \end{macrocode}
 % \end{macro}
 %
+% \begin{macro}{\bf@process@bitheader@opts}
+% \begin{macro}{\KV@bytefield@l}
+% \begin{macro}{\KV@bytefield@b}
+% \begin{macro}{\KV@bytefield@l@default}
+% \begin{macro}{\KV@bytefield@b@default}
+% This is helper function~\#3 for |\bitheader|.  It processes the
+% optional argument to |\bitheader|.
+%    \begin{macrocode}
+\newcommand*{\bf@process@bitheader@opts}{%
+  \let\KV@bytefield@l=\KV@bitheader@l
+  \let\KV@bytefield@b=\KV@bitheader@b
+  \let\KV@bytefield@l@default=\KV@bitheader@l@default
+  \let\KV@bytefield@b@default=\KV@bitheader@b@default
+  \setkeys{bytefield}%
+}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\KV@bitheader@l}
+% \begin{macro}{\KV@bitheader@b}
+% For backwards compatibility we also accept the (now deprecated) |l| as
+% a synonym for |endianness=little| and |b| as a synonym for
+% |endianness=big|.  A typical document will specify an |endianness|
+% option not as an argument to |\bitheader| but rather as a package
+% option that applies to the entire document.  If the \optname{compat1}
+% option was provided to \pkgname{bytefield} (determined below by the
+% existence of the |\curlyshrinkage| control word), we suppress the
+% deprecation warning message.
+%    \begin{macrocode}
+\define@key{bitheader}{l}[true]{%
+  \expandafter\ifx\csname curlyshrinkage\endcsname\relax
+    \PackageWarning{bytefield}{%
+      The "l" argument to \protect\bitheader\space is deprecated.\MessageBreak
+      Instead, please use "endianness=little", which can\MessageBreak
+      even be declared globally for the entire document.\MessageBreak
+      This warning occurred}%
+  \fi
+  \def\bf@bit@endianness{l}%
+}
+\define@key{bitheader}{b}[true]{%
+  \expandafter\ifx\csname curlyshrinkage\endcsname\relax
+    \PackageWarning{bytefield}{%
+      The "b" argument to \protect\bitheader\space is deprecated.\MessageBreak
+      Instead, please use "endianness=big", which can\MessageBreak
+      even be declared globally for the entire document.\MessageBreak
+      This warning occurred}%
+  \fi
+  \def\bf@bit@endianness{b}%
+}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
 % \subsection{Word labels}
 %
 % \subsubsection{Curly-brace manipulation}
@@ -2114,19 +2437,13 @@
 % \begin{macro}{\bf@rightcurlyspace}
 % \begin{macro}{\bf@leftlabelspace}
 % \begin{macro}{\bf@rightlabelspace}
-% Space to insert before a curly brace and before a word label
-% (i.e.,~after a curly brace).
-%    \begin{macrocode}
-\def\bf@leftcurlyspace{0pt}
-\def\bf@rightcurlyspace{0pt}
-\def\bf@leftlabelspace{0pt}
-\def\bf@rightlabelspace{0pt}
-%    \end{macrocode}
+% Define the amount of space to insert before a curly brace and before a
+% word label (i.e.,~after a curly brace).
 %    \begin{macrocode}
-\gdef\bf@leftcurlyspace{1ex}
-\gdef\bf@rightcurlyspace{1ex}
-\gdef\bf@leftlabelspace{0.5ex}
-\gdef\bf@rightlabelspace{0.5ex}
+\def\bf@leftcurlyspace{1ex}
+\def\bf@rightcurlyspace{1ex}
+\def\bf@leftlabelspace{0.5ex}
+\def\bf@rightlabelspace{0.5ex}
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}
@@ -2135,9 +2452,9 @@
 %
 % \begin{macro}{\bf@leftcurly}
 % \begin{macro}{\bf@rightcurly}
-% Symbols to use as left and right curly braces.  These symbols must be
-% extensible math symbols (i.e.,~they will immediately follow |\left| or
-% |\right| in math mode).
+% Define the symbols to use as left and right curly braces.  These
+% symbols must be extensible math symbols (i.e.,~they will immediately
+% follow |\left| or |\right| in math mode).
 %    \begin{macrocode}
 \let\bf@leftcurly=\{
 \let\bf@rightcurly=\}
@@ -2195,7 +2512,8 @@
 % \begin{macro}{\curly@height}
 % \begin{macro}{\half@curly@height}
 % \begin{macro}{\curly@shift}
-% Same as |\store@rcurly|, but using a ``\{'' instead of a ``\}''.
+% These are the same as |\store@rcurly|, etc.\ but using a ``\{''
+% instead of a ``\}''.
 %    \begin{macrocode}
 \def\store@lcurly#1#2{%
   \begingroup
@@ -2236,8 +2554,8 @@
 %
 % \begin{macro}{\wordlabelr@start}
 % \begin{macro}{\wordlabelr@end}
-% The starting and ending height (in points) of the set of rows to be
-% labeled on the right.
+% Declare the starting and ending height (in points) of the set of rows
+% to be labeled on the right.
 %    \begin{macrocode}
 \newlength{\wordlabelr@start}
 \newlength{\wordlabelr@end}
@@ -2332,8 +2650,8 @@
 %
 % \begin{macro}{\wordlabell@start}
 % \begin{macro}{\wordlabell@end}
-% The starting and ending height (in points) of the set of rows to be
-% labeled on the left.
+% Declare the starting and ending height (in points) of the set of rows
+% to be labeled on the left.
 %    \begin{macrocode}
 \newlength{\wordlabell@start}
 \newlength{\wordlabell@end}
@@ -2342,9 +2660,9 @@
 % \end{macro}
 %
 % \begin{macro}{\total@box@width}
-% The total width of the next label to typeset on the left of the bit field,
-% that is, the aggregate width of the text box, curly brace, and spaces
-% on either side of the curly brace.
+% Declare the total width of the next label to typeset on the left of
+% the bit field, that is, the aggregate width of the text box, curly
+% brace, and spaces on either side of the curly brace.
 %    \begin{macrocode}
 \newlength{\total@lbox@width}
 %    \end{macrocode}
@@ -2458,7 +2776,7 @@
   \global\wordlabell@end=\bytefield@height
   \bf@newdimen\starting@point
   \setlength{\starting@point}{%
-    -\total@lbox@width - \bf@bitwidth*\value{bits@wide}}%
+    -\total@lbox@width - \bf@bitwidth*\bits@wide}%
   \sbox{\word@label@box}{%
     \begin{tabular}[b]{@{}l@{}}\wordlabell@text\end{tabular}}%
   \settowidth{\label@box@width}{\usebox{\word@label@box}}%
@@ -2474,11 +2792,11 @@
   \end{picture}%
 %    \end{macrocode}
 % \begin{macro}{\@currenvir}
-%    \begin{macrocode}
 % Because of our meddling with |\begingroup| and |\endgroup|, the
 % current environment is all messed up.  We therefore force the
 % |\end{leftwordgroup}| to succeed, even if it doesn't match the preceding
 % |\begin|.
+%    \begin{macrocode}
   \def\@currenvir{leftwordgroup}%
   \ignorespaces}
 %    \end{macrocode}
@@ -2490,8 +2808,8 @@
 % \begin{macro}{\label@box@width}
 % \begin{macro}{\label@box@height}
 % \begin{macro}{\word@label@box}
-% Scratch storage for the width, height, and contents of the word label
-% we're about to output.
+% Declare some scratch storage for the width, height, and contents of
+% the word label we're about to output.
 %    \begin{macrocode}
 \newlength{\label@box@width}
 \newlength{\label@box@height}
@@ -2508,7 +2826,7 @@
 % version~2.0.  To give version~1.\textit{x} users a quick way to build
 % their old documents, we provide a version~1.\textit{x} compatibility
 % mode.  We don't enable this by default because it exposes a number of
-% extra length registers (a precious resource) and we therefore want to
+% extra length registers (a precious resource) and because we want to
 % encourage users to migrate to the new interface.
 %    \begin{macrocode}
 \newcommand{\bf@enter@compatibility@mode@i}{%
@@ -2761,6 +3079,44 @@
 % \end{macro}
 % \end{macro}
 %
+% \begin{macro}{\KV@bytefield@endianness}
+% \begin{macro}{\bf@parse@endianness}
+% Set the default endianness to either little-endian or big-endian.
+%    \begin{macrocode}
+\define@key{bytefield}{endianness}{\bf@parse@endianness{#1}}
+%    \end{macrocode}
+%    \begin{macrocode}
+\newcommand{\bf@parse@endianness}[1]{%
+  \def\bf@little{little}%
+  \def\bf@big{big}%
+  \def\bf@arg{#1}%
+  \ifx\bf@arg\bf@little
+    \def\bf@bit@endianness{l}%
+  \else
+    \ifx\bf@arg\bf@big
+      \def\bf@bit@endianness{b}%
+    \else
+      \PackageError{bytefield}{%
+        Invalid argument "#1" to the endianness option%
+      }{%
+        The endianness option must be set to either "little" or
+        "big".\MessageBreak
+        Please specify either endianness=little or endianness=big.
+      }%
+    \fi
+  \fi
+}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\KV@bytefield@lsb}
+% Specify a numerical value for the least significant bit of a word.
+%    \begin{macrocode}
+\define@key{bytefield}{lsb}{\def\bf@first@bit{#1}}
+%    \end{macrocode}
+% \end{macro}
+%
 % \begin{macro}{\bytefieldsetup}
 % \usermacro
 % \changes{v2.0}{2011/01/18}{Introduced this macro to provide a more