diff options
-rw-r--r-- | Master/texmf-dist/source/latex/bytefield/bytefield.dtx | 1559 | ||||
-rw-r--r-- | Master/texmf-dist/source/latex/bytefield/bytefield.ins | 51 |
2 files changed, 1610 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/bytefield/bytefield.dtx b/Master/texmf-dist/source/latex/bytefield/bytefield.dtx new file mode 100644 index 00000000000..c5184b28d07 --- /dev/null +++ b/Master/texmf-dist/source/latex/bytefield/bytefield.dtx @@ -0,0 +1,1559 @@ +% \iffalse meta-comment +% +% Copyright (C) 2005 by Scott Pakin <scott+bf@pakin.org> +% ------------------------------------------------------ +% +% This file may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3a +% of this license or (at your option) any later version. +% The latest version of this license is in: +% +% http://www.latex-project.org/lppl.txt +% +% and version 1.3a or later is part of all distributions of LaTeX +% version 2004/10/11 or later. +% +% \fi +% +% \iffalse +%<*driver> +\ProvidesFile{bytefield.dtx} +%</driver> +%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01] +%<package>\ProvidesPackage{bytefield} +%<*package> + [2005/07/31 v1.2a Network protocol diagrams] +%</package> +% +%<*driver> +\documentclass{ltxdoc} +\usepackage{textcomp} +\usepackage{bytefield} +\IfFileExists{hyperref.sty}{% + \usepackage{color} + \usepackage{hyperref} + \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, bitfields, protocol diagrams, LaTeX, memory maps}, + bookmarksopen=true, + colorlinks=true, + citecolor=darkblue, + urlcolor=darkgreen, + linkcolor=darkred, + menucolor=darkbrown} +} +\EnableCrossrefs +\CodelineIndex +\RecordChanges +\setcounter{IndexColumns}{2} +\begin{document} + \DocInput{bytefield.dtx} + \PrintChanges + \PrintIndex +\end{document} +%</driver> +% \fi +% +% \CheckSum{599} +% +% \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 +% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z +% Digits \0\1\2\3\4\5\6\7\8\9 +% Exclamation \! Double quote \" Hash (number) \# +% Dollar \$ Percent \% Ampersand \& +% Acute accent \' Left paren \( Right paren \) +% Asterisk \* Plus \+ Comma \, +% Minus \- Point \. Solidus \/ +% Colon \: Semicolon \; Less than \< +% Equals \= Greater than \> Question mark \? +% Commercial at \@ Left bracket \[ Backslash \\ +% Right bracket \] Circumflex \^ Underscore \_ +% Grave accent \` Left brace \{ Vertical bar \| +% Right brace \} Tilde \~} +% +% +% \changes{v1.0}{2000/07/02}{Initial version} +% \changes{v1.1}{2002/09/14}{Restructured the \texttt{.dtx} file} +% +% \GetFileInfo{bytefield.dtx} +% +% \DoNotIndex{\&,\{,\}} +% \DoNotIndex{\addtocounter,\advance} +% \DoNotIndex{\begin,\begingroup,\bgroup} +% \DoNotIndex{\catcode,\ch@ck,\count,\cr} +% \DoNotIndex{\DeclareRobustCommand,\def,\dimen,\dimendef} +% \DoNotIndex{\edef,\egroup,\else,\end,\endgroup,\expandafter} +% \DoNotIndex{\fi} +% \DoNotIndex{\gdef,\global} +% \DoNotIndex{\if,\ifnum,\ifx,\ignorespaces,\insc@unt} +% \DoNotIndex{\let} +% \DoNotIndex{\newbox,\newcounter,\newenvironment,\newif,\newlength} +% \DoNotIndex{\newsavebox} +% \DoNotIndex{\raisebox,\ratio,\real,\relax,\renewcommand} +% \DoNotIndex{\sbox,\setcounter,\setlength,\settowidth,\space,\string} +% \DoNotIndex{\the} +% \DoNotIndex{\usebox} +% \DoNotIndex{\value,\vbox} +% \DoNotIndex{\wlog} +% \DoNotIndex{\xdef} +% +% +% \title{The \textsf{bytefield} package\thanks{This document +% corresponds to \textsf{bytefield}~\fileversion, dated \filedate.}} +% \author{Scott Pakin \\ \texttt{scott+bf@pakin.org}} +% +% \sloppy +% \maketitle +% +% ^^A Define an environment for command/environment delcarations. +% \newsavebox{\declbox} +% \newenvironment{decl}{^^A +% \begin{lrbox}{\declbox}\begin{tabular}{l}}{^^A +% \end{tabular}\end{lrbox}^^A +% \vspace{3ex}\noindent\hspace*{-3em}\fbox{\usebox{\declbox}}\vspace*{2ex}} +% +% ^^A Draw a cute smiley face to use within text (classier than ":-)"). +% \newcommand{\smileyface}{\raisebox{-2pt}{^^A +% \begin{picture}(9,9) +% \put(5,5){\circle{9}} +% \put(3.5,7){\circle*{2}} +% \put(6.6,7){\circle*{2}} +% \put(0,0){\makebox(9,3)[t]{\tiny $\,\smile$}} +% \end{picture}}} +% +% ^^A Define an ellipsis that permits a subsequent line break. +% \newcommand{\ellipsis}{$\ldots$\linebreak[0]} +% +% ^^A Define an environment for showing sample bytefield diagrams. +% \newenvironment{bffigure}{% +% \bigskip +% \noindent\hspace*{3em}% +% }{% +% \bigskip +% } +% +% ^^A Define something like \cs to use within \StopEventually. +% \DeclareRobustCommand{\cseq}[1]{\texttt{\string#1}} +% +% +% \begin{abstract} +% The \texttt{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. +% \end{abstract} +% +% \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 \texttt{bytefield} package makes it easy to typeset these sorts of +% figures. +% +% \texttt{bytefield} lets one draw 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 +% \end{itemize} +% +% Because \texttt{bytefield} draws its figures using only +% the \LaTeX{} \texttt{picture} environment, these figures are not +% specific to any particular backend, do not require PostScript support, +% and do not need support from external programs. Furthermore, unlike an +% imported graphic, \texttt{bytefield} pictures can include arbitrary +% \LaTeX{} constructs, such as mathematical equations, |\ref|s and +% |\cite|s to the surrounding document, and macro calls. +% +% +% \section{Usage} +% +% \subsection{Basic commands} +% +% This section explains how to use the \texttt{bytefield} package. +% It lists all the exported environments, commands, and variables in +% decreasing order of importance. +% +% \begin{decl} +% |\begin{bytefield}| \marg{bit-width} \\ +% \meta{fields} \\ +% |\end{bytefield}| +% \end{decl} +% +% The top-level environment is called, not surprisingly, +% ``|bytefield|''. It takes one (mandatory) argument, which is the +% number of bits in each word. One can think of a \texttt{bytefield} as +% being analogous to a \texttt{tabular}: words are separated +% by~|\\|, and fields within a word are separated by~|&|. +% +% \begin{decl} +% |\wordbox| \oarg{sides} \marg{height} \marg{text} \\ +% |\bitbox| \oarg{sides} \marg{width} \marg{text} +% \end{decl} +% +% The two main commands one uses within a \texttt{bytefield} environment +% are |\wordbox| and |\bitbox|. The former typesets a field +% that is one or more words tall and an entire word wide. +% The latter typesets a field that is one or more bits wide and a single +% word 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, and/or |[b]|ottom. The default is ``|lrtb|'' (i.e., all sides +% are drawn). \meta{text} is the text to include within the |\wordbox| or +% |\bitbox|. It is typeset horizontally centered within a vertically +% centered |\parbox|. Hence, words will wrap, and |\\| can +% be used to break lines manually. +% +% The following example shows how to produce a simple 16-bit-wide byte field: +% +% \begin{verbatim} +% \begin{bytefield}{16} +% \wordbox{1}{A 16-bit field} \\ +% \bitbox{8}{8 bits} & \bitbox{8}{8 more bits} \\ +% \wordbox{2}{A 32-bit field. Note that text wraps within the box.} +% \end{bytefield} +% \end{verbatim} +% +% The resulting figure looks like this: +% +% \begin{bffigure} +% \begin{bytefield}{16} +% \wordbox{1}{A 16-bit field} \\ +% \bitbox{8}{8 bits} & \bitbox{8}{8 more bits} \\ +% \wordbox{2}{A 32-bit field. Note that text wraps within the box.} +% \end{bytefield} +% \end{bffigure} +% +% It is the user's responsibility to ensure that the total +% number of bits in each row adds up to the number of bits in a single +% word (the mandatory argument to the |bytefield| environment). +% +% Within a |\wordbox| or |\bitbox|, the \texttt{bytefield} package +% defines |\height|, |\depth|, |\totalheight|, and |\width| to the +% corresponding dimensions of the box. Section~\ref{sec:tricks} gives an +% example of how these lengths may be utilized. +% +% \begin{decl} +% |\bitheader| \oarg{endianness} \marg{bit-positions} +% \end{decl} +% +% To make the figure 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|). +% +% |\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|''. +% +% The following example shows how |\bitheader| may be used: +% +% \begin{verbatim} +% \begin{bytefield}{32} +% \bitheader{0-31} \\ +% \bitbox{4}{Four} & \bitbox{8}{Eight} & +% \bitbox{16}{Sixteen} & \bitbox{4}{Four} +% \end{bytefield} +% \end{verbatim} +% +% The resulting figure looks like this: +% +% \begin{bffigure} +% \begin{bytefield}{32} +% \bitheader{0-31} \\ +% \bitbox{4}{Four} & \bitbox{8}{Eight} & +% \bitbox{16}{Sixteen} & \bitbox{4}{Four} +% \end{bytefield} +% \end{bffigure} +% +% +% \begin{decl} +% |\wordgroupr| \marg{text} \\ +% |\endwordgroupr| \\ +% \\ +% |\wordgroupl| \marg{text} \\ +% |\endwordgroupl| +% \end{decl} +% +% When a set of words functions as a single, logical unit, it helps to +% group these words together visually. All words defined between +% |\wordgroupr| and |\endwordgroupr| will be labeled on the right with +% \meta{text}. Similarly, all words defined between +% |\wordgroupl| and |\endwordgroupl| will be labeled on the left with +% \meta{text}. |\wordgroup|\textit{x} must lie at the beginning of a row +% (i.e., right after a |\\|), and |\endwordgroup|\textit{x} must lie right +% \emph{before} the end of the row (i.e., right before a |\\|). +% +% |\wordgroupr|\ellipsis|\endwordgroupr| and +% |\wordgroupl|\ellipsis|\endwordgroupl| can overlap each other. +% However, they cannot overlap themselves. In other words, +% |\wordgroupr|\ellipsis|\wordgroupl|\ellipsis|\endwordgroupr|\ellipsis|\endwordgroupl| +% is a valid sequence, but +% |\wordgroupr|\ellipsis|\wordgroupr|\ellipsis|\endwordgroupr|\ellipsis|\endwordgroupr| +% is not. +% +% The following example shows how to use |\wordgroupr| and |\endwordgroupr|: +% +% \begin{verbatim} +% \begin{bytefield}{16} +% \bitheader{0,7,8,15} \\ +% \wordgroupr{Header} +% \bitbox{4}{Tag} & \bitbox{12}{Mask} \\ +% \bitbox{8}{Source} & \bitbox{8}{Destination} +% \endwordgroupr \\ +% \wordbox{3}{Data} +% \end{bytefield} +% \end{verbatim} +% +% \noindent +% Note the justaposition of |\\| to |\wordgroupr| and |\endwordgroupr| +% in the above. The resulting figure looks like this: +% +% \begin{bffigure} +% \begin{bytefield}{16} +% \bitheader{0,7,8,15} \\ +% \wordgroupr{Header} +% \bitbox{4}{Tag} & \bitbox{12}{Mask} \\ +% \bitbox{8}{Source} & \bitbox{8}{Destination} +% \endwordgroupr \\ +% \wordbox{3}{Data} +% \end{bytefield} +% \end{bffigure} +% +% \noindent +% As a more complex example, the following nests left and right labels: +% +% \begin{verbatim} +% \begin{bytefield}{16} +% \bitheader{0,7,8,15} \\ +% \wordgroupr{Header} +% \bitbox{4}{Tag} & \bitbox{12}{Mask} \\ +% \wordgroupl{Node IDs} +% \bitbox{8}{Source} & \bitbox{8}{Destination} +% \endwordgroupl +% \endwordgroupr \\ +% \wordbox{3}{Data} +% \end{bytefield} +% \end{verbatim} +% +% \begin{bffigure} +% \begin{bytefield}{16} +% \bitheader{0,7,8,15} \\ +% \wordgroupr{Header} +% \bitbox{4}{Tag} & \bitbox{12}{Mask} \\ +% \wordgroupl{Node IDs} +% \bitbox{8}{Source} & \bitbox{8}{Destination} +% \endwordgroupl +% \endwordgroupr \\ +% \wordbox{3}{Data} +% \end{bytefield} +% \end{bffigure} +% +% \noindent +% Again, note the justaposition of |\\| to the various word-grouping +% commands in the above. +% +% \begin{decl} +% |\skippedwords| +% \end{decl} +% +% Draw a graphic representing a number of words that are not shown. +% |\skippedwords| is intended to work with the \meta{sides} argument +% to |\wordbox|. For example: +% +% \begin{verbatim} +% \begin{bytefield}{16} +% \wordbox{1}{Some data} \\ +% \wordbox[lrt]{1}{Lots of data} \\ +% \skippedwords \\ +% \wordbox[lrb]{1}{} \\ +% \wordbox{2}{More data} +% \end{bytefield} +% \end{verbatim} +% +% \begin{bffigure} +% \begin{bytefield}{16} +% \wordbox{1}{Some data} \\ +% \wordbox[lrt]{1}{Lots of data} \\ +% \skippedwords \\ +% \wordbox[lrb]{1}{} \\ +% \wordbox{2}{More data} +% \end{bytefield} +% \end{bffigure} +% +% \begin{decl} +% |\bitwidth| \\ +% |\byteheight| +% \end{decl} +% +% The above variables represent the width of each bit and height of each +% byte in the figure. Change them with |\setlength| to adjust the size +% of the figure. The default value of |\byteheight| is~|2ex|, and the +% default value of |\bitwidth| is the width of ``|{\tiny 99i}|'', +% i.e.,~the width of a two-digit number plus a small amount of extra space. +% This enables |\bitheader| to show two-digit numbers without overlap. +% +% \begin{decl} +% |\curlyspace| \\ +% |\labelspace| +% \end{decl} +% +% |\curlyspace| is the space to insert between the figure and the curly +% brace preceding a word group (default: |1ex|). |\labelspace| is the +% space to insert between the curly brace and the label (default: |0.5ex|). +% Change these with |\setlength| to adjust the spacing. +% +% \begin{decl} +% |\curlyshrinkage| +% \end{decl} +% +% In \TeX/\LaTeX, the height of a curly brace does not include the tips. +% Hence, in a word group label, the tips of the curly brace will extend +% beyond the height of the word group. |\curlyshrinkage| is an amount by +% which to reduce the height of curly braces in labels. It is set to |5pt|, +% and it is extremely unlikely that one would ever need to change it. +% Nevertheless, it is documented here in case the document is typeset with +% a math font containing radically different curly braces from the ones +% that come with \TeX/\LaTeX. +% +% \subsection{Common tricks} +% \label{sec:tricks} +% +% This section shows some clever ways to use \texttt{bytefield}'s commands +% to produce some useful effects. +% +% \paragraph{Odd-sized fields} +% To produce a field that is, say, 1\textonehalf{} words long, use a +% |\bitbox| for the fractional part and specify appropriate values +% for the various \meta{sides} parameters. For instance: +% +% \begin{verbatim} +% \begin{bytefield}{16} +% \bitheader{0,7,8,15} \\ +% \bitbox{8}{8-bit field} & \bitbox[lrt]{8}{} \\ +% \wordbox[lrb]{1}{24-bit field} +% \end{bytefield} +% \end{verbatim} +% +% \begin{bffigure} +% \begin{bytefield}{16} +% \bitheader{0,7,8,15} \\ +% \bitbox{8}{8-bit field} & \bitbox[lrt]{8}{} \\ +% \wordbox[lrb]{1}{24-bit field} +% \end{bytefield} +% \end{bffigure} +% +% \paragraph{Ellipses} +% To skip words from the middle of enumerated data, put some |\vdots| +% in a |\wordbox| with empty \meta{sides}: +% +% \begin{verbatim} +% \begin{bytefield}{16} +% \bitbox{8}{Type} & \bitbox{8}{\# of nodes} \\ +% \wordbox{1}{Node~1} \\ +% \wordbox{1}{Node~2} \\ +% \wordbox[]{1}{$\vdots$ \\[1ex]} \\ +% \wordbox{1}{Node~$N$} \\ +% \end{bytefield} +% \end{verbatim} +% +% \begin{bffigure} +% \begin{bytefield}{16} +% \bitbox{8}{Type} & \bitbox{8}{\# of nodes} \\ +% \wordbox{1}{Node~1} \\ +% \wordbox{1}{Node~2} \\ +% \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. +% +% \paragraph{Unused bits} +% Because |\width| and |\height| are defined within |\bitbox|es (also +% |\wordbox|es), we can represent unused bits by filling a |\bitbox| +% with a rule of size |\width|~$\times$| \height|. +% +% \begin{verbatim} +% \begin{bytefield}{32} +% \bitheader{0,4,8,12,16,20,24,28} \\ +% \bitbox{8}{Tag} & \bitbox{8}{Value} & +% \bitbox{4}{\rule{\width}{\height}} & \bitbox{12}{Mask} \\ +% \wordbox{1}{Key} +% \end{bytefield} +% \end{verbatim} +% +% \begin{bffigure} +% \begin{bytefield}{32} +% \bitheader{0,4,8,12,16,20,24,28} \\ +% \bitbox{8}{Tag} & \bitbox{8}{Value} & +% \bitbox{4}{\rule{\width}{\height}} & \bitbox{12}{Mask} \\ +% \wordbox{1}{Key} +% \end{bytefield} +% \end{bffigure} +% +% \noindent +% The effect is much better when the \texttt{color} package is used to +% draw the unused bits in color. (Gray looks nice.) +% +% \subsection{Not-so-common tricks} +% +% While certainly not the intended purpose of the \texttt{bytefield} +% package, one can utilize |\wordbox|es with empty \meta{sides} and +% word labels to produce memory-map diagrams: +% +% \begin{verbatim} +% \setlength{\byteheight}{4\baselineskip} +% \newcommand{\descbox}[2]{\parbox[c][3.8\baselineskip]{0.95\width}{% +% \raggedright #1\vfill #2}} +% \begin{bytefield}{32} +% \wordgroupr{Partition 4} +% \bitbox[]{8}{\texttt{0xFFFFFFFF} \\[2\baselineskip] +% \texttt{0xC0000000}} & +% \bitbox{24}{\descbox{1\,GB area for VxDs, memory manager, +% file system code; shared by all processes.}{Read/writable.}} +% \endwordgroupr \\ +% \wordgroupr{Partition 3} +% \bitbox[]{8}{\texttt{0xBFFFFFFF} \\[2\baselineskip] +% \texttt{0x80000000}} & +% \bitbox{24}{\descbox{1\,GB area for memory-mapped files, +% shared system DLLs, file system code; shared by all +% processes.}{Read/writable.}} +% \endwordgroupr \\ +% \wordgroupr{Partition 2} +% \bitbox[]{8}{\texttt{0x7FFFFFFF} \\[2\baselineskip] +% \texttt{0x00400000}} & +% \bitbox{24}{\descbox{$\sim$2\,GB area private to process, +% process code, and data.}{Read/writable.}} +% \endwordgroupr \\ +% \wordgroupr{Partition 1} +% \bitbox[]{8}{\texttt{0x003FFFFF} \\[2\baselineskip] +% \texttt{0x00001000}} & +% \bitbox{24}{\descbox{4\,MB area for MS-DOS and Windows~3.1 +% compatibility.}{Read/writable.}} \\ +% \bitbox[]{8}{\texttt{0x00000FFF} \\[2\baselineskip] +% \texttt{0x00000000}} & +% \bitbox{24}{\descbox{4096~byte area for MS-DOS and Windows~3.1 +% compatibility.}{Protected---catches {\small NULL} pointers.}} +% \endwordgroupr \\ +% \end{verbatim} +% +% \begin{bffigure} +% \setlength{\byteheight}{4\baselineskip} +% \newcommand{\descbox}[2]{\parbox[c][3.8\baselineskip]{0.95\width}{% +% \raggedright #1\vfill #2}} +% \begin{bytefield}{32} +% \wordgroupr{Partition 4} +% \bitbox[]{8}{\texttt{0xFFFFFFFF} \\[2\baselineskip] +% \texttt{0xC0000000}} & +% \bitbox{24}{\descbox{1\,GB area for VxDs, memory manager, +% file system code; shared by all processes.}{Read/writable.}} +% \endwordgroupr \\ +% \wordgroupr{Partition 3} +% \bitbox[]{8}{\texttt{0xBFFFFFFF} \\[2\baselineskip] +% \texttt{0x80000000}} & +% \bitbox{24}{\descbox{1\,GB area for memory-mapped files, +% shared system DLLs, file system code; shared by all +% processes.}{Read/writable.}} +% \endwordgroupr \\ +% \wordgroupr{Partition 2} +% \bitbox[]{8}{\texttt{0x7FFFFFFF} \\[2\baselineskip] +% \texttt{0x00400000}} & +% \bitbox{24}{\descbox{$\sim$2\,GB area private to process, process +% code, and data.}{Read/writable.}} +% \endwordgroupr \\ +% \wordgroupr{Partition 1} +% \bitbox[]{8}{\texttt{0x003FFFFF} \\[2\baselineskip] +% \texttt{0x00001000}} & +% \bitbox{24}{\descbox{4\,MB area for MS-DOS and Windows~3.1 +% compatibility.}{Read/writable.}} \\ +% \bitbox[]{8}{\texttt{0x00000FFF} \\[2\baselineskip] +% \texttt{0x00000000}} & +% \bitbox{24}{\descbox{4096~byte area for MS-DOS and Windows~3.1 +% compatibility.}{Protected---catches {\small NULL} pointers.}} +% \endwordgroupr \\ +% \end{bytefield} +% \end{bffigure} +% +% +% \subsection{Putting it all together} +% +% The following code showcases most of \texttt{bytefield}'s features in a +% single figure. +% +% \begin{verbatim} +% \setlength{\byteheight}{2.5\baselineskip} +% \begin{bytefield}{32} +% \bitheader{0,7,8,15,16,23,24,31} \\ +% \wordgroupr{\parbox{6em}{\raggedright These words were taken +% verbatim from the TCP header definition (RFC~793).}} +% \bitbox{4}{Data offset} & \bitbox{6}{Reserved} & +% \bitbox{1}{\tiny U\\R\\G} & \bitbox{1}{\tiny A\\C\\K} & +% \bitbox{1}{\tiny P\\S\\H} & \bitbox{1}{\tiny R\\S\\T} & +% \bitbox{1}{\tiny S\\Y\\N} & \bitbox{1}{\tiny F\\I\\N} & +% \bitbox{16}{Window} \\ +% \bitbox{16}{Checksum} & \bitbox{16}{Urgent pointer} +% \endwordgroupr \\ +% \wordbox[lrt]{1}{Data octets} \\ +% \skippedwords \\ +% \wordbox[lrb]{1}{} \\ +% \wordgroupl{\parbox{6em}{\raggedright Note that we can display, +% for example, a misaligned 64-bit value with clever use of the +% optional argument to \texttt{\textbackslash wordbox} and +% \texttt{\textbackslash bitbox}.}} +% \bitbox{8}{Source} & \bitbox{8}{Destination} & +% \bitbox[lrt]{16}{} \\ +% \wordbox[lr]{1}{Timestamp} \\ +% \wordgroupr{\parbox{6em}{\raggedright Why two Length fields? +% No particular reason.}} +% \bitbox[lrb]{16}{} & \bitbox{16}{Length} +% \endwordgroupl \\ +% \bitbox{6}{Key} & \bitbox{6}{Value} & \bitbox{4}{Unused} & +% \bitbox{16}{Length} +% \endwordgroupr \\ +% \wordbox{1}{Total number of 16-bit data words that follow this +% header word, excluding the subsequent checksum-type value} \\ +% \bitbox{16}{Data~1} & \bitbox{16}{Data~2} \\ +% \bitbox{16}{Data~3} & \bitbox{16}{Data~4} \\ +% \bitbox[]{16}{$\vdots$ \\[1ex]} & +% \bitbox[]{16}{$\vdots$ \\[1ex]} \\ +% \bitbox{16}{Data~$N-1$} & \bitbox{16}{Data~$N$} \\ +% \bitbox{20}{\[ \mbox{A5A5}_{\mbox{\scriptsize H}} \oplus +% \left(\sum_{i=1}^N \mbox{Data}_i \right) \bmod 2^{20} \]} & +% \bitbox{12}{Command} \\ +% \wordbox{2}{64-bit random number} +% \end{bytefield} +% \end{verbatim} +% +% \noindent +% Figure~\ref{fig:complex-diagram} shows the resulting protocol diagram. +% +% \begin{figure}[phtb] +% \setlength{\byteheight}{2.5\baselineskip} +% \begin{bytefield}{32} +% \bitheader{0,7,8,15,16,23,24,31} \\ +% \wordgroupr{\parbox{6em}{\raggedright These words were taken +% verbatim from the TCP header definition (RFC~793).}} +% \bitbox{4}{Data offset} & \bitbox{6}{Reserved} & +% \bitbox{1}{\tiny U\\R\\G} & \bitbox{1}{\tiny A\\C\\K} & +% \bitbox{1}{\tiny P\\S\\H} & \bitbox{1}{\tiny R\\S\\T} & +% \bitbox{1}{\tiny S\\Y\\N} & \bitbox{1}{\tiny F\\I\\N} & +% \bitbox{16}{Window} \\ +% \bitbox{16}{Checksum} & \bitbox{16}{Urgent pointer} +% \endwordgroupr \\ +% \wordbox[lrt]{1}{Data octets} \\ +% \skippedwords \\ +% \wordbox[lrb]{1}{} \\ +% \wordgroupl{\parbox{6em}{\raggedright Note that we can display, +% for example, a misaligned 64-bit value with clever use of the +% optional argument to \texttt{\textbackslash wordbox} and +% \texttt{\textbackslash bitbox}.}} +% \bitbox{8}{Source} & \bitbox{8}{Destination} & \bitbox[lrt]{16}{} \\ +% \wordbox[lr]{1}{Timestamp} \\ +% \wordgroupr{\parbox{6em}{\raggedright Why two Length fields? +% No particular reason.}} +% \bitbox[lrb]{16}{} & \bitbox{16}{Length} +% \endwordgroupl \\ +% \bitbox{6}{Key} & \bitbox{6}{Value} & \bitbox{4}{Unused} & +% \bitbox{16}{Length} +% \endwordgroupr \\ +% \wordbox{1}{Total number of 16-bit data words that follow this +% header word, excluding the subsequent checksum-type value} \\ +% \bitbox{16}{Data~1} & \bitbox{16}{Data~2} \\ +% \bitbox{16}{Data~3} & \bitbox{16}{Data~4} \\ +% \bitbox[]{16}{$\vdots$ \\[1ex]} & \bitbox[]{16}{$\vdots$ \\[1ex]} \\ +% \bitbox{16}{Data~$N-1$} & \bitbox{16}{Data~$N$} \\ +% \bitbox{20}{\[ \mbox{A5A5}_{\mbox{\scriptsize H}} \oplus +% \left(\sum_{i=1}^N \mbox{Data}_i \right) \bmod 2^{20} \]} & +% \bitbox{12}{Command} \\ +% \wordbox{2}{64-bit random number} +% \end{bytefield} +% \caption{Complex protocol diagram drawn with the \texttt{bytefield} +% package} +% \label{fig:complex-diagram} +% \end{figure} +% +% +% \StopEventually{^^A +% +% \section{Future work} +% +% \texttt{bytefield} is my first \LaTeX{} package, and, as such, there +% are a number of macros that could probably have been implemented a lot +% better. The package should really get a major rewrite. If I were to +% do it all over again, I would probably not use an \cseq\ialign\ for the +% main \texttt{bytefield} environment. The problem---as I discovered +% too late---is that \cseq\begin\ellipsis\cseq\end\ blocks are unable to +% cross cells of an \cseq\ialign\ (or \texttt{tabular} environment, for +% that matter). +% +% That said, I'd like the next major release of \texttt{bytefield} to +% let the user use \texttt{\cseq\begin\char'173 +% wordgroup\char'175[r]}\ellipsis \texttt{\cseq\end\char'173 +% wordgroup\char'175} instead of +% \cseq\wordgroupr\ellipsis\cseq\endwordgroupr\ and +% \texttt{\cseq\begin\char'173 wordgroup\char'175[l]}\ellipsis +% \texttt{\cseq\end\char'173 wordgroup\char'175} instead of +% \cseq\wordgroupl\ellipsis\cseq\endwordgroupl. That would make the +% word-grouping commands a little more \LaTeX-ish. +% +% Finally, a minor improvement I'd like to make in the package is to +% move left, small curly braces closer to the figure. In the following +% figure, notice how distant the small curly appears from the figure +% body: +% +% \begin{bffigure} +% \setlength{\byteheight}{4ex} +% \begin{bytefield}{16} +% \wordgroupl{Too distant} +% \wordbox{1}{Something} +% \endwordgroupl \\ +% \wordgroupl{Looks okay} +% \wordbox{4}{Something else} +% \endwordgroupl +% \end{bytefield} +% \end{bffigure} +% +% \noindent +% The problem is that the curly braces are left-aligned relative to +% each other, while they should be right-aligned. +% } +% +% +% \section{Implementation} +% +% \newcommand{\usermacro}{\marginpar{\vspace*{1ex}{\hspace{18pt}\huge$\star$}\vspace*{-1ex}}} +% +% This section contains the complete source code for \texttt{bytefield}. +% Most users will not get much out of it, but it should be of use to +% those who need more precise documentation and those who want to extend +% (or debug~\smileyface) the \texttt{bytefield} package. +% +% In this section, macros marked in the margin with a ``{\Large $\star$}'' +% are intended to be called by the user (and were described in the previous +% section). All other macros are used only internally by \texttt{bytefield}. +% +% \begin{macrocode} +%<*package> +% \end{macrocode} +% +% +% \subsection{Required packages} +% +% Although |\widthof| and |\heightof| were introduced in June~1998, +% te\kern-1.5pt\TeX~2.0---still in widespread use at the time of this +% writing (2005)---ships with an earlier |calc.sty| in the |source| +% directory. Because a misconfigured system may find the |source| +% version of |calc.sty| we explicitly specify a later date when loading +% the |calc| package. +% \changes{v1.2a}{2005/07/31}{Specified an explicit package date when +% loading the \texttt{calc} package to avoid loading an outdated +% version. Thanks to Kevin Quick for discovering that outdated versions +% of \texttt{calc} are still being included in \TeX{} distributions.} +% \begin{macrocode} +\RequirePackage{calc}[1998/07/07] +% \end{macrocode} +% +% +% \subsection{Utility macros} +% +% The following macros in this section are used by the box-drawing macros +% and the ``skipped words''-drawing macros. +% +% \begin{macro}{\bf@newdimen} +% \changes{v1.1}{2002/09/15}{Bug fix: Added +% \texttt{\string\string\string\bf@newdimen} to eliminate ``\texttt{No +% room for a new \string\string\string\dimen}'' errors (reported by +% Vitaly A. Repin)} +% |\newdimen| defines new \meta{dimen}s globally. |\bf@newdimen| +% defines them locally. It simply merges \LaTeXe's |\newdimen| and +% |\alloc@| macros while omitting |\alloc@|'s ``|\global|'' declaration. +% \begin{macrocode} +\def\bf@newdimen#1{\advance\count11 by 1 + \ch@ck1\insc@unt\dimen% Check room + \allocationnumber=\count11 + \dimendef#1=\allocationnumber + \wlog{\string#1=\string\dimen\the\allocationnumber\space (locally)}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\bytefield@height} +% \begin{macro}{\ifcounting@words} +% When |\ifcounting@words| is \textsc{True}, add the height of the next +% \texttt{picture} environment to |\bytefield@height|. We set +% |\counting@wordstrue| at the beginning of each word, and +% |\counting@wordsfalse| after each |\bitbox|, |\wordbox|, or |\skippedwords| +% picture. +% \begin{macrocode} +\newlength{\bytefield@height} +\newif\ifcounting@words +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\inc@bytefield@height} +% We have to define a special macro to increment |\bytefield@height| +% because the \texttt{calc} package's |\addtolength| macro doesn't seem +% to see the global value. So we |\setlength| a temporary (to get +% \texttt{calc}'s nice infix features) and |\advance| |\bytefield@height| +% by that amount. +% \begin{macrocode} +\newlength{\bytefield@height@increment} +\DeclareRobustCommand{\inc@bytefield@height}[1]{% + \setlength{\bytefield@height@increment}{#1}% + \global\advance\bytefield@height by \bytefield@height@increment} +% \end{macrocode} +% \end{macro} +% +% \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 bytefield, put a box around it, and do other operations on the entire +% figure. +% \begin{macrocode} +\newsavebox{\entire@bytefield@picture} +% \end{macrocode} +% \end{macro} +% +% \begin{environment}{bytefield} +% \usermacro +% Environment containing the layout of bits in a sequence of bytes. +% This is the main environment defined by the \texttt{bytefield} pacakge. +% 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 +% \texttt{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}[1]{% + \setcounter{bits@wide}{#1}% + \let\old@nl=\\% + \let\amp=&% + \catcode`\&=10 + \openup -1pt + \setlength{\bytefield@height}{0pt}% + \setlength{\unitlength}{1pt}% + \counting@wordstrue + \begin{lrbox}{\entire@bytefield@picture}% +% \end{macrocode} +% \begin{macro}{\\} +% We redefine |\\| within the |bytefield| environment to make it aware +% of curly braces that surround the protocol diagram. +% \begin{macrocode} + \renewcommand{\\}{% + \amp\show@wordlabelr\cr% + \ignorespaces\counting@wordstrue\make@lspace\amp}% +% \end{macrocode} +% \end{macro} +% \begin{macrocode} + \vbox\bgroup\ialign\bgroup##\amp##\amp##\cr\amp% +}{% + \amp\show@wordlabelr\cr\egroup\egroup% + \end{lrbox}% + \usebox{\entire@bytefield@picture}} +% \end{macrocode} +% \end{environment} +% +% \subsection{Box-drawing macros} +% +% \subsubsection{Drawing (proper)} +% +% \begin{macro}{\bitwidth} +% \usermacro +% 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{\bitwidth} +\AtBeginDocument{\settowidth{\bitwidth}{\tiny 99i}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\byteheight} +% \usermacro +% The height of a single byte. +% \begin{macrocode} +\newlength{\byteheight} +\AtBeginDocument{\setlength{\byteheight}{4ex}} +% \end{macrocode} +% \end{macro} +% +% \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. +% \begin{macrocode} +\newlength{\units@wide} +\newlength{\units@tall} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\bitbox} +% \usermacro +% Put some text (|#3|) in a box that's a given number of bits (|#2|) +% wide and one byte tall. +% An optional argument (|#1|) specifies which lines to draw---|[l]|eft, +% |[r]|ight, |[t]|op, and/or |[b]|ottom (default: |lrtb|). +% \begin{macrocode} +\DeclareRobustCommand{\bitbox}[3][lrtb]{% + \setlength{\units@wide}{\bitwidth * #2}% + \parse@bitbox@arg{#1}% + \draw@bit@picture{\strip@pt\units@wide}{\strip@pt\byteheight}{#3}} +% \end{macrocode} +% \end{macro} +% +% \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. +% 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}{\bitwidth * \value{bits@wide}}% + \setlength{\units@tall}{\byteheight * #2}% + \parse@bitbox@arg{#1}% + \draw@bit@picture{\strip@pt\units@wide}{\strip@pt\units@tall}{#3}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\draw@bit@picture} +% Put some text (|#3|) in a box that's a given number of units (|#1|) +% wide and a given number of units (|#2|) tall. +% We format the text with a |\parbox| to enable word-wrapping and explicit +% line breaks. In addition, we define |\height|, |\depth|, |\totalheight|, +% and |\width| (\`a la |\makebox| and friends), so the user can utilize +% those for special effects (e.g., a |\rule| that fills the entire box). +% As an added bonus, we define |\widthunits| and |\heightunits|, which +% are the width and height of the box in multiples of |\unitlength| +% (i.e., |#1| and |#2|, respectively). +% \begin{macrocode} +\DeclareRobustCommand{\draw@bit@picture}[3]{% + \begin{picture}(#1,#2)% +% \end{macrocode} +% \begin{macro}{\height} +% \begin{macro}{\depth} +% \begin{macro}{\totalheight} +% \begin{macro}{\width} +% \begin{macro}{\widthunits} +% \begin{macro}{\heightunits} +% First, we plot the user's text, with all sorts of useful lengths +% predefined. +% \begin{macrocode} + \put(0,0){\makebox(#1,#2){\parbox[c]{#1\unitlength}{% + \bf@newdimen\height + \bf@newdimen\depth + \bf@newdimen\totalheight + \bf@newdimen\width + \height=#2\unitlength + \depth=0pt% + \totalheight=#2\unitlength + \width=#1\unitlength + \def\widthunits{#1}% + \def\heightunits{#2}% + \centering #3}}}% +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% Next, we draw each line individually. I suppose we could make a special +% case for ``all lines'' and use a |\framebox| above, but the following +% works just fine. +% \begin{macrocode} + \ifbitbox@top + \put(0,#2){\line(1,0){#1}} + \fi + \ifbitbox@bottom + \put(0,0){\line(1,0){#1}} + \fi + \ifbitbox@left + \put(0,0){\line(0,1){#2}} + \fi + \ifbitbox@right + \put(#1,0){\line(0,1){#2}} + \fi + \end{picture}% +% \end{macrocode} +% Finally, we indicate that we're no longer at the beginning of a word. +% The following code structure (albeit with different arguments to +% |\inc@bytefield@height|) is repeated in various places throughout this +% package. We document it only here, however. +% \begin{macrocode} + \ifcounting@words + \inc@bytefield@height{\unitlength * \real{#2}}% + \counting@wordsfalse + \fi + \ignorespaces} +% \end{macrocode} +% \end{macro} +% +% \subsubsection{Parsing arguments} +% +% The macros in this section are used to parse the optional argument +% to |\bitbox| or |\wordbox|, which is some subset of +% $\{ |l|, |r|, |t|, |b| \}$. +% +% \begin{macro}{\ifbitbox@top} +% \begin{macro}{\ifbitbox@bottom} +% \begin{macro}{\ifbitbox@left} +% \begin{macro}{\ifbitbox@right} +% These macros are set to \textsc{True} if we're to draw the +% corresponding edge on the subsequent |\bitbox| or |\wordbox|. +% \begin{macrocode} +\newif\ifbitbox@top +\newif\ifbitbox@bottom +\newif\ifbitbox@left +\newif\ifbitbox@right +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\parse@bitbox@arg} +% This main parsing macro merely resets the above conditionals and +% calls a helper function, |\parse@bitbox@sides|. +% \begin{macrocode} +\def\parse@bitbox@arg#1{% + \bitbox@topfalse + \bitbox@bottomfalse + \bitbox@leftfalse + \bitbox@rightfalse + \parse@bitbox@sides#1X} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\parse@bitbox@sides} +% The helper function for |\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{% + \ifx#1X% + \else + \ifx#1t% + \bitbox@toptrue + \else + \ifx#1b% + \bitbox@bottomtrue + \else + \ifx#1l% + \bitbox@lefttrue + \else + \ifx#1r% + \bitbox@righttrue + \fi + \fi + \fi + \fi + \expandafter\parse@bitbox@sides + \fi} +% \end{macrocode} +% \end{macro} +% +% \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|. +% \begin{macrocode} +\newlength{\units@high} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\skippedwords} +% \usermacro +% Output a fancy graphic representing skipped words. The optional argument +% is the vertical space between the two diagonal lines (default: |2ex|). +% \begin{macrocode} +\DeclareRobustCommand{\skippedwords}[1][2ex]{% + \setlength{\units@wide}{\bitwidth * \value{bits@wide}}% + \setlength{\units@high}{1pt * \ratio{\units@wide}{6.0pt}}% + \setlength{\units@tall}{#1 + \units@high}% + \edef\num@wide{\strip@pt\units@wide}% + \edef\num@tall{\strip@pt\units@tall}% + \edef\num@high{\strip@pt\units@high}% + \begin{picture}(\num@wide,\num@tall) + \put(0,\num@tall){\line(6,-1){\num@wide}} + \put(\num@wide,0){\line(-6,1){\num@wide}} + \put(0,0){\line(0,1){\num@high}} + \put(\num@wide,\num@tall){\line(0,-1){\num@high}} + \end{picture}% + \ifcounting@words + \inc@bytefield@height{\unitlength * \real{\num@tall}}% + \counting@wordsfalse + \fi} +% \end{macrocode} +% \end{macro} +% +% \subsection{Bit-position labels} +% +% \begin{macro}{\bitheader} +% \usermacro +% Output a header of numbered bit positions. The optional argument (|#1|) +% is ``|l|'' for little-endian (default) or ``|b|'' for big-endian. +% The required argument (|#2|) is a list of bit positions to label. +% 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}{\bitwidth * \value{bits@wide}}% + \setlength{\units@tall}{\heightof{\tiny 9}}% + \setlength{\units@high}{\units@tall * -1}% + \def\bit@endianness{#1}% + \begin{picture}(\strip@pt\units@wide,\strip@pt\units@tall)% + (0,\strip@pt\units@high) + \parse@range@list#2,X, + \end{picture}% + \ifcounting@words + \inc@bytefield@height{\unitlength * \real{\strip@pt\units@tall}}% + \counting@wordsfalse + \fi + \ignorespaces} +% \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. +% \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,{% + \ifx X#1 + \else + \parse@range#1-#1-#1\relax + \expandafter\parse@range@list + \fi} +% \end{macrocode} +% \end{macro} +% +% \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$). +% \begin{macrocode} +\newlength{\header@xpos} +\newcounter{header@val} +\newcounter{max@header@val} +% \end{macrocode} +% \end{macro} +% \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{macrocode} +\def\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% + \setlength{\header@xpos}{% + \bitwidth * (\value{bits@wide}-\value{header@val}-1)} + \else + \setlength{\header@xpos}{\bitwidth * \value{header@val}} + \fi + \put(\strip@pt\header@xpos,0){% + \makebox(\strip@pt\bitwidth,\strip@pt\units@tall){% + \tiny \theheader@val}} + \addtocounter{header@val}{1} + \repeat} +% \end{macrocode} +% \end{macro} +% +% \subsection{Word labels} +% +% \subsubsection{Curly-brace manipulation} +% +% \begin{macro}{\curlyshrinkage} +% \usermacro +% Reduce the height of a curly brace by |\curlyshrinkage| so its ends don't +% overlap whatever is above or below it. The default value (5\,pt.) was +% determined empirically and shouldn't need to be changed. However, +% on the off-chance the user employs a math font with very different +% curly braces from Computer Modern's, |\curlyshrinkage| can be modified. +% \begin{macrocode} +\newlength{\curlyshrinkage} +\setlength{\curlyshrinkage}{5pt} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\curlyspace} +% \usermacro +% \begin{macro}{\labelspace} +% \usermacro +% Space to insert before a curly brace and before a word label +% (i.e., after a curly brace). Because the default values are specified +% in terms of $x$~heights, we wait until the |\begin{document}| to set +% them, after the default font has been selected. +% \begin{macrocode} +\newlength{\curlyspace} +\AtBeginDocument{\setlength{\curlyspace}{1ex}} +\newlength{\labelspace} +\AtBeginDocument{\setlength{\labelspace}{0.5ex}} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\curly@box} +% Define a box in which to temporarily store formatted curly braces. +% \changes{v1.2}{2004/06/14}{Bug fix: Defined +% \texttt{\string\string\string\curly@box} globally (suggested by +% Stefan Ulrich)} +% \begin{macrocode} +\newbox{\curly@box} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\store@rcurly} +% \begin{macro}{\curly@height} +% \begin{macro}{\half@curly@height} +% \begin{macro}{\curly@shift} +% Store a ``\}'' that's |#2| tall in box |#1|. +% The only unintuitive thing here is that we have to redefine +% |\fontdimen22|---axis height---to~0\,pt.\ before typesetting the curly +% brace. Otherwise, the brace would be vertically off-center by a few +% points. When we're finished, we reset it back to its old value. +% \begin{macrocode} +\def\store@rcurly#1#2{% + \begingroup + \bf@newdimen\curly@height% + \setlength{\curly@height}{#2 - \curlyshrinkage}% + \bf@newdimen\half@curly@height% + \setlength{\half@curly@height}{0.5\curly@height}% + \bf@newdimen\curly@shift% + \setlength{\curly@shift}{\half@curly@height + 0.5\curlyshrinkage}% + \global\sbox{#1}{\raisebox{\curly@shift}{% + $\xdef\old@axis{\the\fontdimen22\textfont2}$% + $\fontdimen22\textfont2=0pt% + \left.\vrule height\half@curly@height + width 0pt + depth\half@curly@height\right\}$% + $\fontdimen22\textfont2=\old@axis$}}% + \endgroup +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\store@lcurly} +% \begin{macro}{\curly@height} +% \begin{macro}{\half@curly@height} +% \begin{macro}{\curly@shift} +% Same as |\store@rcurly|, but using a ``\{'' instead of a ``\}''. +% \begin{macrocode} +\def\store@lcurly#1#2{% + \begingroup + \bf@newdimen\curly@height% + \setlength{\curly@height}{#2 - \curlyshrinkage}% + \bf@newdimen\half@curly@height% + \setlength{\half@curly@height}{0.5\curly@height}% + \bf@newdimen\curly@shift% + \setlength{\curly@shift}{\half@curly@height + 0.5\curlyshrinkage}% + \global\sbox{#1}{\raisebox{\curly@shift}{% + $\xdef\old@axis{\the\fontdimen22\textfont2}$% + $\fontdimen22\textfont2=0pt% + \left\{\vrule height\half@curly@height + width 0pt + depth\half@curly@height\right.$% + $\fontdimen22\textfont2=\old@axis$}}% + \endgroup +} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \subsubsection{Right-side labels} +% +% \begin{macro}{\show@wordlabelr} +% This macro is output in the third column of every row of the +% |\ialign|ed bytefield table. It's normally a no-op, but +% |\endwordgroupr| defines it to output the word label and then +% reset itself to a no-op. +% \begin{macrocode} +\def\show@wordlabelr{} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\wordlabelr@start} +% \begin{macro}{\wordlabelr@end} +% The starting and ending height (in points) of the set of rows to be +% labelled on the right. +% \begin{macrocode} +\newlength{\wordlabelr@start} +\newlength{\wordlabelr@end} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\wordgroupr} +% \usermacro +% \begin{macro}{\endwordgroupr} +% \usermacro +% Label the words defined between |\wordgroupr| and |\endwordgroupr| +% on the right side of the figure. +% The argument is the text of the label. The label is typeset to the +% right of a large curly brace, which groups the words together. +% \begin{macrocode} +\newenvironment{wordgroupr}[1]{% +% \end{macrocode} +% \begin{macro}{\wordlabelr@start} +% \begin{macro}{\wordlabelr@text} +% \begin{macro}{\wordlabelr@end} +% |\wordgroupr| merely stores the starting height in |\wordlabelr@start| +% and the user-supplied text in |\wordlabelr@text|. |\endwordgroupr| +% does most of the work. +% \begin{macrocode} + \global\wordlabelr@start=\bytefield@height + \gdef\wordlabelr@text{#1}% + \ignorespaces% +}{% + \global\wordlabelr@end=\bytefield@height +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \begin{macro}{\show@wordlabelr} +% Redefine |\show@wordlabelr| to output |\curlyspace| space, followed by +% a large curly brace (in |\curlybox|), followed by |\labelspace| space, +% followed by the user's text (previously recorded in |\wordlabelr@text|). +% We typeset |\wordlabelr@text| within a |tabular| environment, so +% \LaTeX\ will calculate its width automatically. +% \begin{macrocode} + \gdef\show@wordlabelr{% + \sbox{\word@label@box}{% + \begin{tabular}[b]{@{}l@{}}\wordlabelr@text\end{tabular}}% + \settowidth{\label@box@width}{\usebox{\word@label@box}}% + \setlength{\label@box@height}{\wordlabelr@end-\wordlabelr@start}% + \store@rcurly{\curly@box}{\label@box@height}% + \bf@newdimen\total@box@width% + \setlength{\total@box@width}{% + \curlyspace + + \widthof{\usebox{\curly@box}} + + \labelspace + + \label@box@width}% + \begin{picture}(\strip@pt\total@box@width,0) + \put(0,0){% + \hspace*{\curlyspace}% + \usebox{\curly@box}% + \hspace*{\labelspace}% + \makebox(\strip@pt\label@box@width,\strip@pt\label@box@height){% + \usebox{\word@label@box}}} + \end{picture}% +% \end{macrocode} +% The last thing |\show@wordlabelr| does is redefine itself back to a no-op. +% \begin{macrocode} + \gdef\show@wordlabelr{}}% + \ignorespaces} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \subsubsection{Left-side labels} +% +% \begin{macro}{\wordlabell@start} +% \begin{macro}{\wordlabell@end} +% The starting and ending height (in points) of the set of rows to be +% labelled on the left. +% \begin{macrocode} +\newlength{\wordlabell@start} +\newlength{\wordlabell@end} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\total@box@width} +% The total width of the next label to typeset on the left of the figure, +% 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} +% \end{macro} +% +% \begin{macro}{\make@lspace} +% This macro is output in the first column of every row of the +% |\ialign|ed bytefield table. It's normally a no-op, but +% |\wordgroupl| defines it to output enough space for the next word +% label and then reset itself to a no-op. +% \begin{macrocode} +\gdef\make@lspace{} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\wordgroupl} +% \usermacro +% \begin{macro}{\endwordgroupl} +% \usermacro +% Same as |\wordgroupr| and |\endwordgroupr|, but put the label on the left. +% However, the following code is not symmetric to that of |\wordgroupr| +% and |\endwordgroupr|. The problem is that we encounter |\wordgroupl| +% after entering the second (i.e., figure) column, which doesn't give us +% a chance to reserve space in the first (i.e., left label) column. +% When we reach the |\endwordgroupl|, we know the height of the group of +% words we wish to label. However, if we try to label the words in the +% subsequent first column, we won't know the vertical offset from the +% ``cursor'' at which to start drawing the label, because we can't know +% the height of the subsequent row until we reach the second +% column.\footnote{Question: Is there a way to push the label up to the +% \emph{top} of the subsequent row, perhaps with +% \texttt{\textbackslash vfill}?} +% +% Our solution is to allocate space for the box the next time we enter a +% first column. As long as space is eventually allocated, the column +% will expand to fit that space. |\endwordgroupl| outputs the label +% immediately. Even though |\endwordgroupl| is called at the end +% of the \emph{second} column, it |\put|s the label at a sufficiently +% negative $x$ location for it to overlap the first column. Because there +% will eventually be enough space to accomodate the label, we know that +% the label won't overlap the figure or extend beyond the figure boundaries. +% \begin{macrocode} +\newenvironment{wordgroupl}[1]{% +% \end{macrocode} +% \begin{macro}{\wordlabell@start} +% \begin{macro}{\wordlabell@text} +% First, we store the starting height and label text, which are needed +% by |\endwordgroupl|. +% \begin{macrocode} + \global\wordlabell@start=\bytefield@height + \gdef\wordlabell@text{#1}% +% \end{macrocode} +% \end{macro} +% \end{macro} +% Next, we typeset a draft version of the label into |\word@label@box|, +% which we measure (into |\total@lbox@width|) and then discard. +% We can't typeset the final version of the label until we reach the +% |\endwordgroupl|, because that's when we learn the height of the +% word group. Without knowing the height of the word group, we don't +% how how big to make the curly brace. In the scratch version, we make +% the curly brace 5\,cm.~tall. This should be more than large enough to +% reach the maximum curly-brace width, which is all we really care about +% at this point. +% \begin{macrocode} + \sbox{\word@label@box}{% + \begin{tabular}[b]{@{}l@{}}\wordlabell@text\end{tabular}}% + \settowidth{\label@box@width}{\usebox{\word@label@box}}% + \store@lcurly{\curly@box}{5cm}% + \setlength{\total@lbox@width}{% + \curlyspace + + \widthof{\usebox{\curly@box}} + + \labelspace + + \label@box@width}% + \global\total@lbox@width=\total@lbox@width +% \end{macrocode} +% Now we know how wide the box is going to be (unless, of course, +% the user is using some weird math font that scales the width of a curly +% brace proportionally to its height). So we redefine |\make@lspace| to +% output |\total@lbox@width|'s worth of space and then redefine itself +% back to a no-op. +% \begin{macrocode} + \gdef\make@lspace{% + \hspace*{\total@lbox@width}% + \gdef\make@lspace{}}% + \ignorespaces% +}{% +% \end{macrocode} +% |\endwordgroupl| is comparatively straightforward. We calculate the +% final height of the word group, and then output the label text, followed +% by |\labelspace| space, followed by a curly brace (now that we know how +% tall it's supposed to be), followed by |\curlyspace| space. The trick, +% as described earlier, is that we typeset the entire label in the second +% column, but in a $0 \times 0$ |picture| environment and with a negative +% horizontal offset (|\starting@point|), thereby making it overlap the +% first column. +% \begin{macrocode} + \global\wordlabell@end=\bytefield@height + \bf@newdimen\starting@point + \setlength{\starting@point}{% + -\total@lbox@width - \bitwidth*\value{bits@wide}}% + \sbox{\word@label@box}{% + \begin{tabular}[b]{@{}l@{}}\wordlabell@text\end{tabular}}% + \settowidth{\label@box@width}{\usebox{\word@label@box}}% + \setlength{\label@box@height}{\wordlabell@end-\wordlabell@start}% + \store@lcurly{\curly@box}{\label@box@height}% + \begin{picture}(0,0) + \put(\strip@pt\starting@point,0){% + \makebox(\strip@pt\label@box@width,\strip@pt\label@box@height){% + \usebox{\word@label@box}}% + \hspace*{\labelspace}% + \usebox{\curly@box}% + \hspace*{\curlyspace}} + \end{picture}% + \ignorespaces} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \subsubsection{Scratch space} +% +% \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. +% \begin{macrocode} +\newlength{\label@box@width} +\newlength{\label@box@height} +\newsavebox{\word@label@box} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macrocode} +%</package> +% \end{macrocode} +% +% \Finale +\endinput diff --git a/Master/texmf-dist/source/latex/bytefield/bytefield.ins b/Master/texmf-dist/source/latex/bytefield/bytefield.ins new file mode 100644 index 00000000000..4f762755f2c --- /dev/null +++ b/Master/texmf-dist/source/latex/bytefield/bytefield.ins @@ -0,0 +1,51 @@ +%% +%% Copyright (C) 2005 by Scott Pakin <scott+bf@pakin.org> +%% +%% This file may be distributed and/or modified under the conditions of +%% the LaTeX Project Public License, either version 1.3a of this license +%% or (at your option) any later version. The latest version of this +%% license is in: +%% +%% http://www.latex-project.org/lppl.txt +%% +%% and version 1.3a or later is part of all distributions of LaTeX version +%% 2004/10/11 or later. +%% + +\input docstrip.tex +\keepsilent + +\usedir{tex/latex/bytefield} + +\preamble + +This is a generated file. + +Copyright (C) 2005 by Scott Pakin <scott+bf@pakin.org> + +This file may be distributed and/or modified under the conditions of +the LaTeX Project Public License, either version 1.3a of this license +or (at your option) any later version. The latest version of this +license is in: + + http://www.latex-project.org/lppl.txt + +and version 1.3a or later is part of all distributions of LaTeX version +2004/10/11 or later. + +\endpreamble + +\generate{\file{bytefield.sty}{\from{bytefield.dtx}{package}}} + +\Msg{***************************************************************} +\Msg{*} +\Msg{* To finish the installation, move bytefield.sty into a} +\Msg{* directory searched by TeX.} +\Msg{*} +\Msg{* To produce the documentation, run the file bytefield.dtx} +\Msg{* through LaTeX.} +\Msg{*} +\Msg{* Happy TeXing!} +\Msg{***************************************************************} + +\endbatchfile |