Minor markup cleanup. Also normalize some [] to ().

svn path=/trunk/vorbis/; revision=4000

diff --git a/doc/xml/01-introduction.xml b/doc/xml/01-introduction.xml
index f8d30e8..691256a 100644 (file)
--- a/doc/xml/01-introduction.xml
+++ b/doc/xml/01-introduction.xml
@@ -1,7 +1,7 @@
 <section id="vorbis-spec-intro">
 <sectioninfo>
 <releaseinfo>
- $Id: 01-introduction.xml,v 1.1 2002/10/12 20:37:11 giles Exp $
+ $Id: 01-introduction.xml,v 1.2 2002/10/13 15:18:46 giles Exp $
 <emphasis>Last update to this document: July 18, 2002</emphasis>
 </releaseinfo>
 </sectioninfo>
@@ -101,8 +101,8 @@ For these reasons, configurable aspects codec setup intentionally
 lean toward the extreme of forward adaptive.</para>
 
 <para>
-The single most controversial design decision in Vorbis [and the most
-unusual for a Vorbis developer to keep in mind] is that the entire
+The single most controversial design decision in Vorbis (and the most
+unusual for a Vorbis developer to keep in mind) is that the entire
 probability model of the codec, the Huffman and VQ codebooks, is
 packed into the bitstream header along with extensive CODEC setup
 parameters (often several hundred fields).  This makes it impossible,
@@ -136,7 +136,7 @@ The Vorbis format is well-defined by its decode specification; any
 encoder that produces packets that are correctly decoded by the
 reference Vorbis decoder described below may be considered a proper
 Vorbis encoder.  A decoder must faithfully and completely implement
-the specification defined below [except where noted] to be considered
+the specification defined below (except where noted) to be considered
 a proper Vorbis decoder.</para>
 </section>
 
@@ -337,10 +337,11 @@ sample rate and number of channels.</para>
 
 <section><title>Comment Header</title>
 <para>
-The comment header includes user text comments ["tags"] and a vendor
+The comment header includes user text comments ("tags") and a vendor
 string for the application/library that produced the bitstream.  The
 encoding of the comment header is described within this document; the
-proper use of the comment fields is described in <ulink url="v-comment.html">the Ogg Vorbis comment field specification</ulink>.</para>
+proper use of the comment fields is described in 
+<xref linkend="vorbis-spec-comment"/>.</para>
 </section>
 
 <section><title>Setup Header</title>
@@ -360,7 +361,7 @@ fundamentally the same.
 <orderedlist>
 <listitem><simpara>decode packet type flag</simpara></listitem>
 <listitem><simpara>decode mode number</simpara></listitem>
-<listitem><simpara>decode window shape [long windows only]</simpara></listitem>
+<listitem><simpara>decode window shape (long windows only)</simpara></listitem>
 <listitem><simpara>decode floor</simpara></listitem>
 <listitem><simpara>decode residue into residue vectors</simpara></listitem>
 <listitem><simpara>inverse channel coupling of residue vectors</simpara></listitem>
@@ -412,7 +413,7 @@ the mode instance index. </para>
 </section>
 
 <section id="vorbis-spec-window">
-<title>Window shape decode [long windows only]</title>
+<title>Window shape decode (long windows only)</title>
 
 <para>
 Vorbis frames may be one of two PCM sample sizes specified during

diff --git a/doc/xml/02-bitpacking.xml b/doc/xml/02-bitpacking.xml
index 1eef420..583d17f 100644 (file)
--- a/doc/xml/02-bitpacking.xml
+++ b/doc/xml/02-bitpacking.xml
@@ -1,7 +1,7 @@
 <section id="vorbis-spec-bitpacking">
 <sectioninfo>
 <releaseinfo>
- $Id: 02-bitpacking.xml,v 1.1 2002/10/12 20:37:11 giles Exp $
+ $Id: 02-bitpacking.xml,v 1.2 2002/10/13 15:18:46 giles Exp $
  <emphasis>Last update to this document: July 14, 2002</emphasis>
 </releaseinfo>
 </sectioninfo>
@@ -48,9 +48,9 @@ that a byte is one octet for purposes of example.</para>
 </section><section><title>bit order</title>
 
 <para>
-A byte has a well-defined 'least significant' bit [LSb], which is the
+A byte has a well-defined 'least significant' bit (LSb), which is the
 only bit set when the byte is storing the two's complement integer
-value +1.  A byte's 'most significant' bit [MSb] is at the opposite
+value +1.  A byte's 'most significant' bit (MSb) is at the opposite
 end of the byte. Bits in a byte are numbered from zero at the LSb to
 <emphasis>n</emphasis> (<emphasis>n</emphasis>=7 in an octet) for the
 MSb.</para>

diff --git a/doc/xml/05-comment.xml b/doc/xml/05-comment.xml
index f94c3dc..88c9cef 100644 (file)
--- a/doc/xml/05-comment.xml
+++ b/doc/xml/05-comment.xml
@@ -1,7 +1,7 @@
 <section id="vorbis-spec-comment">
 <sectioninfo>
  <releaseinfo>
- $Id: 05-comment.xml,v 1.1 2002/10/12 20:37:11 giles Exp $
+ $Id: 05-comment.xml,v 1.2 2002/10/13 15:18:46 giles Exp $
  <emphasis>Last update to this document: July 16, 2002</emphasis>
 </releaseinfo>
 </sectioninfo>
@@ -75,20 +75,20 @@ comment[1]="TITLE=the sound of Vorbis";
 </programlisting>
 
 <itemizedlist>
-<listitem>
-<para>A case-insensitive field name that may consist of ASCII 0x20
-through 0x7D, 0x3D ('=') excluded. ASCII 0x41 through 0x5A inclusive
-(A-Z) is to be considered equivalent to ASCII 0x61 through 0x7A inclusive
-(a-z).</para>
-</listitem>
-<listitem>
-<para>The field name is immediately followed by ASCII 0x3D ('=');
-this equals sign is used to terminate the field name.</para>
-</listitem>
-<listitem>
-<para>0x3D is followed by 8 bit clean UTF-8 encoded field contents
-to the end of the field.</para>
-</listitem>
+ <listitem><simpara>
+  A case-insensitive field name that may consist of ASCII 0x20
+  through 0x7D, 0x3D ('=') excluded. ASCII 0x41 through 0x5A inclusive
+  (A-Z) is to be considered equivalent to ASCII 0x61 through 0x7A inclusive
+  (a-z).
+ </simpara></listitem>
+ <listitem><simpara>
+  The field name is immediately followed by ASCII 0x3D ('=');
+  this equals sign is used to terminate the field name.
+ </simpara></listitem>
+ <listitem><simpara>
+  0x3D is followed by 8 bit clean UTF-8 encoded field contents
+  to the end of the field.
+ </simpara></listitem>
 </itemizedlist>
 
 <section><title>Field names</title>
@@ -119,23 +119,28 @@ info)
 </simpara></listitem>
 </varlistentry>
 
-<varlistentry><term>TRACKNUMBER</term><listitem><simpara>The track number of this piece if part of a specific larger collection or album
+<varlistentry><term>TRACKNUMBER</term>
+<listitem><simpara>The track number of this piece if part of a specific larger collection or album
 </simpara></listitem>
 </varlistentry>
 
-<varlistentry><term>ARTIST</term><listitem><simpara>The artist generally considered responsible for the work. In popular music this is usually the performing band or singer. For classical music it would be the composer. For an audio book it would be the author of the original text.
+<varlistentry><term>ARTIST</term>
+<listitem><simpara>The artist generally considered responsible for the work. In popular music this is usually the performing band or singer. For classical music it would be the composer. For an audio book it would be the author of the original text.
 </simpara></listitem>
 </varlistentry>
 
-<varlistentry><term>PERFORMER</term><listitem><simpara>The artist(s) who performed the work. In classical music this would be the conductor, orchestra, soloists. In an audio book it would be the actor who did the reading. In popular music this is typically the same as the ARTIST and is omitted.
+<varlistentry><term>PERFORMER</term>
+<listitem><simpara>The artist(s) who performed the work. In classical music this would be the conductor, orchestra, soloists. In an audio book it would be the actor who did the reading. In popular music this is typically the same as the ARTIST and is omitted.
 </simpara></listitem>
 </varlistentry>
 
-<varlistentry><term>COPYRIGHT</term><listitem><simpara>Copyright attribution, e.g., '2001 Nobody's Band' or '1999 Jack Moffitt'
+<varlistentry><term>COPYRIGHT</term>
+<listitem><simpara>Copyright attribution, e.g., '2001 Nobody's Band' or '1999 Jack Moffitt'
 </simpara></listitem>
 </varlistentry>
 
-<varlistentry><term>LICENSE</term><listitem><simpara>License information, eg, 'All Rights Reserved', 'Any
+<varlistentry><term>LICENSE</term>
+<listitem><simpara>License information, eg, 'All Rights Reserved', 'Any
 Use Permitted', a URL to a license such as a Creative Commons license
 ("www.creativecommons.org/blahblah/license.html") or the EFF Open
 Audio License ('distributed under the terms of the Open Audio
@@ -144,32 +149,39 @@ details'), etc.
 </simpara></listitem>
 </varlistentry>
 
-<varlistentry><term>ORGANIZATION</term><listitem><simpara>Name of the organization producing the track (i.e.
+<varlistentry><term>ORGANIZATION</term>
+<listitem><simpara>Name of the organization producing the track (i.e.
 the 'record label')
 </simpara></listitem>
 </varlistentry>
 
-<varlistentry><term>DESCRIPTION</term><listitem><simpara>A short text description of the contents
+<varlistentry><term>DESCRIPTION</term>
+<listitem><simpara>A short text description of the contents
 </simpara></listitem>
 </varlistentry>
 
-<varlistentry><term>GENRE</term><listitem><simpara>A short text indication of music genre
+<varlistentry><term>GENRE</term>
+<listitem><simpara>A short text indication of music genre
 </simpara></listitem>
 </varlistentry>
 
-<varlistentry><term>DATE</term><listitem><simpara>Date the track was recorded
+<varlistentry><term>DATE</term>
+<listitem><simpara>Date the track was recorded
 </simpara></listitem>
 </varlistentry>
 
-<varlistentry><term>LOCATION</term><listitem><simpara>Location where track was recorded
+<varlistentry><term>LOCATION</term>
+<listitem><simpara>Location where track was recorded
 </simpara></listitem>
 </varlistentry>
 
-<varlistentry><term>CONTACT</term><listitem><simpara>Contact information for the creators or distributors of the track. This could be a URL, an email address, the physical address of the producing label.
+<varlistentry><term>CONTACT</term>
+<listitem><simpara>Contact information for the creators or distributors of the track. This could be a URL, an email address, the physical address of the producing label.
 </simpara></listitem>
 </varlistentry>
 
-<varlistentry><term>ISRC</term><listitem><simpara>ISRC number for the
+<varlistentry><term>ISRC</term>
+<listitem><simpara>ISRC number for the
 track; see <ulink
 url="http://www.ifpi.org/site-content/online/isrc_intro.html">the ISRC
 intro page</ulink> for more information on ISRC numbers.
@@ -183,39 +195,39 @@ intro page</ulink> for more information on ISRC numbers.
 <section><title>Implications</title>
 
 <itemizedlist>
-<listitem>
-<para>Field names should not be 'internationalized'; this is a
+ <listitem>
+  <para>Field names should not be 'internationalized'; this is a
 concession to simplicity not an attempt to exclude the majority of
 the world that doesn't speak English. Field *contents*, however,
 are represented in UTF-8 to allow easy representation of any
 language.</para>
-</listitem>
-<listitem>
-<para>We have the length of the entirety of the field and restrictions on
+ </listitem>
+ <listitem>
+  <para>We have the length of the entirety of the field and restrictions on
 the field name so that the field name is bounded in a known way. Thus
 we also have the length of the field contents.</para>
-</listitem><listitem>
-<para>Individual 'vendors' may use non-standard field names within
+ </listitem><listitem>
+  <para>Individual 'vendors' may use non-standard field names within
 reason. The proper use of comment fields should be clear through
 context at this point.  Abuse will be discouraged.</para>
-</listitem>
-<listitem>
-<para>There is no vendor-specific prefix to 'nonstandard' field names.
+ </listitem>
+ <listitem>
+  <para>There is no vendor-specific prefix to 'nonstandard' field names.
 Vendors should make some effort to avoid arbitrarily polluting the
 common namespace. We will generally collect the more useful tags
 here to help with standardization.</para>
-</listitem>
-<listitem>
-<para>Field names are not required to be unique (occur once) within a
+ </listitem>
+ <listitem>
+  <para>Field names are not required to be unique (occur once) within a
 comment header.  As an example, assume a track was recorded by three
 well know artists; the following is permissible, and encouraged:
-<programlisting>
+  <programlisting>
               ARTIST=Dizzy Gillespie 
               ARTIST=Sonny Rollins 
               ARTIST=Sonny Stitt 
-</programlisting>
-</para>
-</listitem>
+  </programlisting>
+  </para>
+ </listitem>
 </itemizedlist>
 
 </section>
@@ -229,7 +241,7 @@ The comment header comprises the entirety of the second bitstream
 header packet.  Unlike the first bitstream header packet, it is not
 generally the only packet on the second page and may not be restricted
 to within the second bitstream page.  The length of the comment header
-packet is [practically] unbounded.  The comment header packet is not
+packet is (practically) unbounded.  The comment header packet is not
 optional; it must be present in the bitstream even if it is
 effectively empty.</para>
 
@@ -240,26 +252,24 @@ coded into the least significant available bit of the current
 bitstream octet first):
 
 <orderedlist>
-<listitem>
-<simpara>
-Vendor string length (32 bit unsigned quantity specifying number of octets)
-</simpara></listitem>
-<listitem><simpara>
-Vendor string ([vendor string length] octets coded from beginning of string to end of string, not null terminated)
-</simpara></listitem>
-<listitem><simpara>
-Number of comment fields (32 bit unsigned quantity specifying number of fields)
-</simpara></listitem>
-<listitem><simpara>
-Comment field 0 length (if [Number of comment fields]>0; 32 bit unsigned quantity specifying number of octets)
-</simpara></listitem>
-<listitem><simpara>
-Comment field 0 ([Comment field 0 length] octets coded from beginning of string to end of string, not null terminated)
-</simpara></listitem>
-<listitem><simpara>
-Comment field 1 length (if [Number of comment fields]>1...)...
-</simpara></listitem>
-
+ <listitem><simpara>
+  Vendor string length (32 bit unsigned quantity specifying number of octets)
+ </simpara></listitem>
+ <listitem><simpara>
+  Vendor string ([vendor string length] octets coded from beginning of string to end of string, not null terminated)
+ </simpara></listitem>
+ <listitem><simpara>
+  Number of comment fields (32 bit unsigned quantity specifying number of fields)
+ </simpara></listitem>
+ <listitem><simpara>
+  Comment field 0 length (if [Number of comment fields]>0; 32 bit unsigned quantity specifying number of octets)
+ </simpara></listitem>
+ <listitem><simpara>
+  Comment field 0 ([Comment field 0 length] octets coded from beginning of string to end of string, not null terminated)
+ </simpara></listitem>
+ <listitem><simpara>
+  Comment field 1 length (if [Number of comment fields]>1...)...
+ </simpara></listitem>
 </orderedlist>
 </para>
 

diff --git a/doc/xml/06-floor0.xml b/doc/xml/06-floor0.xml
index 67d3cbc..2740a9a 100644 (file)
--- a/doc/xml/06-floor0.xml
+++ b/doc/xml/06-floor0.xml
@@ -1,7 +1,7 @@
 <section id="vorbis-spec-floor0">
 <sectioninfo>
 <releaseinfo>
-  $Id: 06-floor0.xml,v 1.2 2002/10/13 14:32:16 giles Exp $
+  $Id: 06-floor0.xml,v 1.3 2002/10/13 15:18:46 giles Exp $
   <emphasis>Last update to this document: July 19, 2002</emphasis>
 </releaseinfo>
 </sectioninfo>  
@@ -12,8 +12,8 @@
 <title>Overview</title>
 
 <para>
-Vorbis floor type zero uses Line Spectral Pair [LSP, also alternately
-known as Line Spectral Frequency or LSF] representation to encode a
+Vorbis floor type zero uses Line Spectral Pair (LSP, also alternately
+known as Line Spectral Frequency or LSF) representation to encode a
 smooth spectral envelope curve as the frequency response of the LSP
 filter.  This representation is equivalent to a traditional all-pole
 infinite impulse response filter as would be used in linear predictive
@@ -94,7 +94,7 @@ Packet decode proceeds as follows:</para>
 Take note of the following properties of decode:
 <itemizedlist>
  <listitem><simpara>An <varname>[amplitude]</varname> value of zero must result in a return code that indicates this channel is unused in this frame (the output of the channel will be all-zeroes in synthesis).  Several later stages of decode don't occur for an unused channel.</simpara></listitem>
- <listitem><simpara>>An end-of-packet condition during decode should be considered a
+ <listitem><simpara>An end-of-packet condition during decode should be considered a
 nominal occruence; if end-of-packet is reached during any read
 operation above, floor decode is to return 'unused' status as if the
 <varname>[amplitude]</varname> value had read zero at the beginning of decode.</simpara></listitem>

diff --git a/doc/xml/08-residue.xml b/doc/xml/08-residue.xml
index aa02cad..def2bb8 100644 (file)
--- a/doc/xml/08-residue.xml
+++ b/doc/xml/08-residue.xml
@@ -1,7 +1,7 @@
 <section id="vorbis-spec-residue">
 <sectioninfo>
  <releaseinfo>
-  $Id: 08-residue.xml,v 1.1 2002/10/12 20:37:11 giles Exp $
+  $Id: 08-residue.xml,v 1.2 2002/10/13 15:18:47 giles Exp $
   <emphasis>Last update to this document: July 19, 2002</emphasis>
  </releaseinfo>
 </sectioninfo>
@@ -93,7 +93,7 @@ is coded only in the first pass.</para></listitem>
 <para>
 Residue 0 and 1 differ only in the way the values within a residue
 partition are interleaved during partition encoding (visually treated
-as a black box- or cyan box or brown box- in the above figure).</para>
+as a black box--or cyan box or brown box--in the above figure).</para>
 
 <para>
 Residue encoding 0 interleaves VQ encoding according to the

diff --git a/doc/xml/09-helper.xml b/doc/xml/09-helper.xml
index 1df83fa..be4c343 100644 (file)
--- a/doc/xml/09-helper.xml
+++ b/doc/xml/09-helper.xml
@@ -1,7 +1,7 @@
 <section id="vorbis-spec-helper">
 <sectioninfo>
 <releaseinfo>
- $Id: 09-helper.xml,v 1.1 2002/10/12 20:37:11 giles Exp $
+ $Id: 09-helper.xml,v 1.2 2002/10/13 15:18:47 giles Exp $
  <emphasis>Last update to this document: September 10, 2002</emphasis>
 </releaseinfo>
 </sectioninfo>
@@ -16,6 +16,11 @@ specification.  Rather than cluttering up the main specification
 documents, they are defined here and referenced where appropriate.
 </para>
 
+</section>
+
+<section>
+<title>Functions</title>
+
 <section id="vorbis-spec-ilog">
 <title>ilog</title>
 
@@ -40,13 +45,13 @@ The "ilog(x)" function returns the position number (1 through n) of the highest
 Examples:
 
 <itemizedlist>
- <listitem><simpara> ilog(0) = 0;</simpara></listitem>
- <listitem><simpara> ilog(1) = 1;</simpara></listitem>
- <listitem><simpara> ilog(2) = 2;</simpara></listitem>
- <listitem><simpara> ilog(3) = 2;</simpara></listitem>
- <listitem><simpara> ilog(4) = 3;</simpara></listitem>
- <listitem><simpara> ilog(7) = 3;</simpara></listitem>
- <listitem><simpara> ilog(negative number) = 0;</simpara></listitem>
+ <listitem><simpara>ilog(0) = 0;</simpara></listitem>
+ <listitem><simpara>ilog(1) = 1;</simpara></listitem>
+ <listitem><simpara>ilog(2) = 2;</simpara></listitem>
+ <listitem><simpara>ilog(3) = 2;</simpara></listitem>
+ <listitem><simpara>ilog(4) = 3;</simpara></listitem>
+ <listitem><simpara>ilog(7) = 3;</simpara></listitem>
+ <listitem><simpara>ilog(negative number) = 0;</simpara></listitem>
 </itemizedlist>
 </para>