bytefield 2011/06/19 v2.1

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

5 files changed, 757 insertions, 354 deletions

diff --git a/Master/texmf-dist/doc/latex/bytefield/README b/Master/texmf-dist/doc/latex/bytefield/README
index 24710fe8d9b..ee6bddfc607 100644
--- a/Master/texmf-dist/doc/latex/bytefield/README
+++ b/Master/texmf-dist/doc/latex/bytefield/README
@@ -10,7 +10,7 @@ Description
 The bytefield package helps the user create illustrations for network
 protocol specifications and anything else that utilizes fields of
 data.  These illustrations show how the bits and bytes are laid out in
-a packet or in memory.
+a packet, register, or memory.
 
 
 Building bytefield
diff --git a/Master/texmf-dist/doc/latex/bytefield/bf-example.pdf b/Master/texmf-dist/doc/latex/bytefield/bf-example.pdf
index 44f931eea43..adf30c5deb5 100644
--- a/Master/texmf-dist/doc/latex/bytefield/bf-example.pdf
+++ b/Master/texmf-dist/doc/latex/bytefield/bf-example.pdf
diff --git a/Master/texmf-dist/doc/latex/bytefield/bytefield.pdf b/Master/texmf-dist/doc/latex/bytefield/bytefield.pdf
index e8f3f1ee01e..f2718df17d8 100644
--- a/Master/texmf-dist/doc/latex/bytefield/bytefield.pdf
+++ b/Master/texmf-dist/doc/latex/bytefield/bytefield.pdf
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
diff --git a/Master/texmf-dist/tex/latex/bytefield/bytefield.sty b/Master/texmf-dist/tex/latex/bytefield/bytefield.sty
index e720839514f..319866f4b23 100644
--- a/Master/texmf-dist/tex/latex/bytefield/bytefield.sty
+++ b/Master/texmf-dist/tex/latex/bytefield/bytefield.sty
@@ -22,7 +22,7 @@
 %% 
 \NeedsTeXFormat{LaTeX2e}[1999/12/01]
 \ProvidesPackage{bytefield}
-    [2011/02/09 v2.0a Network protocol diagrams]
+    [2011/06/19 v2.1 Network protocol diagrams]
 \RequirePackage{calc}[1998/07/07]
 \RequirePackage{keyval}
 \def\bf@newdimen#1{\advance\count11 by 1
@@ -44,11 +44,10 @@
 \DeclareRobustCommand{\inc@bytefield@height}[1]{%
   \setlength{\bytefield@height@increment}{#1}%
   \global\advance\bytefield@height by \bytefield@height@increment}
-\newcounter{bits@wide}
 \newsavebox{\entire@bytefield@picture}
 \newenvironment{bytefield}[2][]{%
   \bf@bytefieldsetup{#1}%
-  \setcounter{bits@wide}{#2}%
+  \def\bits@wide{#2}%
   \let\old@nl=\\%
   \let\amp=&%
   \catcode`\&=10
@@ -57,8 +56,9 @@
   \setlength{\unitlength}{1pt}%
   \global\counting@wordstrue
   \begin{lrbox}{\entire@bytefield@picture}%
-  \renewcommand{\\}{%
+  \renewcommand{\\}[1][0pt]{%
     \unskip
+    \vspace{##1}%
     \amp\show@wordlabelr\cr
     \ignorespaces\global\counting@wordstrue\make@lspace\amp}%
   \vbox\bgroup\ialign\bgroup##\amp##\amp##\cr\amp
@@ -76,12 +76,12 @@
 \newlength{\units@tall}
 \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}}
 \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}}
 \DeclareRobustCommand{\draw@bit@picture}[3]{%
   \begin{picture}(#1,#2)%
@@ -119,13 +119,13 @@
 \newif\ifbitbox@bottom
 \newif\ifbitbox@left
 \newif\ifbitbox@right
-\def\parse@bitbox@arg#1{%
+\def\bf@parse@bitbox@arg#1{%
   \bitbox@topfalse
   \bitbox@bottomfalse
   \bitbox@leftfalse
   \bitbox@rightfalse
-  \parse@bitbox@sides#1X}
-\def\parse@bitbox@sides#1{%
+  \bf@parse@bitbox@sides#1X}
+\def\bf@parse@bitbox@sides#1{%
   \ifx#1X%
   \else
     \ifx#1t%
@@ -143,11 +143,11 @@
         \fi
       \fi
     \fi
-    \expandafter\parse@bitbox@sides
+    \expandafter\bf@parse@bitbox@sides
   \fi}
 \newlength{\units@high}
 \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}%
@@ -163,56 +163,81 @@
     \inc@bytefield@height{\unitlength * \real{\num@tall}}%
     \global\counting@wordsfalse
   \fi}
-\DeclareRobustCommand{\bitheader}[2][l]{%
-  \parse@bitbox@arg{lrtb}%
-  \setlength{\units@wide}{\bf@bitwidth * \value{bits@wide}}%
+\newcommand*{\bf@bit@endianness}{l}
+\newcommand*{\bf@first@bit}{0}
+\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}}%
     \global\counting@wordsfalse
   \fi
   \ignorespaces}
-\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}
 \newlength{\header@xpos}
 \newcounter{header@val}
 \newcounter{max@header@val}
-\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){%
           \bf@bitformatting{\theheader@val}}}
       \addtocounter{header@val}{1}
   \repeat}
+\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}%
+}
+\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}%
+}
 \def\bf@leftcurlyshrinkage{5pt}
 \def\bf@rightcurlyshrinkage{5pt}
-\def\bf@leftcurlyspace{0pt}
-\def\bf@rightcurlyspace{0pt}
-\def\bf@leftlabelspace{0pt}
-\def\bf@rightlabelspace{0pt}
-\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}
 \let\bf@leftcurly=\{
 \let\bf@rightcurly=\}
 \newbox{\curly@box}
@@ -316,7 +341,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}}%
@@ -426,6 +451,28 @@
   \def\bf@leftcurlyshrinkage{#1}%
   \def\bf@rightcurlyshrinkage{#1}%
 }
+\define@key{bytefield}{endianness}{\bf@parse@endianness{#1}}
+\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
+}
+\define@key{bytefield}{lsb}{\def\bf@first@bit{#1}}
 \newcommand{\bf@bytefieldsetup}{\setkeys{bytefield}}
 \let\bytefieldsetup=\bf@bytefieldsetup
 \DeclareOption{compat1}{\bf@enter@compatibility@mode@i}