summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/bytefield
diff options
context:
space:
mode:
authorManuel Pégourié-Gonnard <mpg@elzevir.fr>2011-08-02 19:35:47 +0000
committerManuel Pégourié-Gonnard <mpg@elzevir.fr>2011-08-02 19:35:47 +0000
commitf2d6ed458a41ef939424ba4a5727efd53812544e (patch)
tree15ca260a6691c12ac0caf48a6b974d2faff6353d /Master/texmf-dist/source/latex/bytefield
parentc3f47c95240cee16ee832b0424a5eaea71d3fff0 (diff)
bytefield 2011/06/19 v2.1
git-svn-id: svn://tug.org/texlive/trunk@23351 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/bytefield')
-rw-r--r--Master/texmf-dist/source/latex/bytefield/bytefield.dtx996
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