Commit 6fb92092 authored by Ralph Giles's avatar Ralph Giles
Browse files

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

svn path=/trunk/vorbis/; revision=4000
parent 65a4ae98
<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
......
<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>
......
<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>
......
<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>
......
<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
......
<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>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment