Notations

This book uses some special typographical notations to represent, present, and set off special kinds of information. These notations are described below.

Boxes

Throughout this book, you will find short sections of text set off in boxes. These come in three varieties: Note, History, and Soapbox.

Note

Items of particular importance are set off in Note boxes. Pay particularly close attention to such boxes when you encounter them.

History

The historical background and evolution of particular design decisions, terms, organizations, or policies are described in History boxes. Skipping them won't cause you to miss any technical content but you may find them illuminating.

Soapbox

Scattered throughout the book, these boxes consist of personal opinions and heretical comments. You can ignore them or, if you want, you can ignore the rest of the book and just read the Soapboxes.

The name "soapbox" for heretical ravings comes from the use of actual wooden crates that had previously been used to ship soap as makeshift platforms by street-corner speakers.

Character Sequences and Code

Much of the discussion in this book needs to clearly specify character sequences and source code.

In cases where a character sequence is relatively short (sometimes only one character) and confusion seems unlikely, the sequence appears intermixed with normal text but surrounded with double curly quotes. For example, "foo" is the three-character sequence of an "f" followed by two "o" characters [RFC 3092]. In some cases, the name of the character is followed by the quoted character in parentheses. For example, this sentence contains a comma (",") and ends in a period ("."). For longer character sequences or in cases where clarity is particularly important, the characters are set off on a separate line or lines in a fixed-width font and highlighted:

 foo 

The only exceptions involve tabular contexts or a series of lines or paragraphs, each of which starts with a special character sequence. In those cases, the character sequence just appears in bold face.

Code is generally a larger character sequence intended for automated processing or a version of such a character sequence simplified for expository purposes, as in the skeletal XML given below. Code appears in the same way as longer character sequences but usually consists of multiple lines and may start with a one-line description followed by a blank line.

 Code example: Sections of code appear like this in a fixed-width font so exact spacing and line breaks can be indicated.    This line starts with three spaces. 

In some cases, code has line numbers so that detailed comments in the text can be associated with particular lines. In such cases, "[Lnn]" has been added to the beginning of each line. The space after the closing bracket is part of the line numbering.

  Line Numbered Code example: [L30] <Line> [L31] <Another>Line</Another>       An unnumbered line within numbered lines. [L32] </Line> 

References

In some cases, you may want to look up authoritative sources or more detailed explanations. These resources are indicated by a short label in square brackets ("[ ]"). For example, the reference to IETF Request for Comments number 3092 appeared earlier as [RFC 3092]. The References and Acronyms section lists these labels in alphabetic order and gives further information on the material.

Skeletal XML

XML can quickly become quite complex, voluminous, and deeply nested, making the parts of importance to a discussion difficult to see because they are scattered like trees in a very large forest. In such cases, skeletal XML is used to give an abstracted overview. A statement in main text is used to indicate skeletal XML. In skeletal XML, the following rules apply:

1. A cardinality indicator character can suffix elements. (These suffixes are similar to those used in DTD, as described in Chapter 3.) In particular,

   ? means the preceding item appears 0 or 1 times.

   + means the preceding item appears 1 or more times.

   * means the preceding item appears 0 or more times.

2. Attributes may be completely omitted or appear with no value:

    attribute= 

   Attributes may also be followed by the cardinality indicator ("?") to indicate that they are optional.

3. The appearance of an element enclosed in parentheses instead of angle brackets, such as

    (foo id=/) 

   instead of

    <foo id=value>content</foo> 

   indicates that the element's content has been omitted for the sake of simplicity.

4. Ellipses ("…") can appear where elements or levels of structure are omitted.

Byte Objects

Character coding issues, octet sequence padding, and other issues related to byte objects are discussed in this book. To refer to specific eight-bit bytes by their binary values, such octets are written as two hexadecimal digits, preceded by the lowercase letter "x", and with all three characters underlined. For example, a zero byte is x00; a byte whose value is 87 decimal, which is the ASCII code for a capital "W", is x57; and a maximum-value byte (255 decimal) is xFF.

Italics

Italics indicate variable descriptive terms that can be replaced by fixed real data values.

Bold Face

Bold face indicates important text or code. It is also sometimes used for character objects that appear in tables or at the beginnings of a sequence of lines or paragraphs, as in the description of the cardinality characters in skeletal XML, and the names of functions when functions are being described.