[xiph-cvs] cvs commit: vorbis/doc/xml 01-introduction.xml 02-bitpacking.xml 05-comment.xml 06-floor0.xml 08-residue.xml 09-helper.xml
Ralph Giles
giles at xiph.org
Sun Oct 13 08:18:47 PDT 2002
giles 02/10/13 11:18:47
Modified: doc/xml 01-introduction.xml 02-bitpacking.xml
05-comment.xml 06-floor0.xml 08-residue.xml
09-helper.xml
Log:
Minor markup cleanup. Also normalize some [] to ().
Revision Changes Path
1.2 +9 -8 vorbis/doc/xml/01-introduction.xml
Index: 01-introduction.xml
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/xml/01-introduction.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- 01-introduction.xml 12 Oct 2002 20:37:11 -0000 1.1
+++ 01-introduction.xml 13 Oct 2002 15:18:46 -0000 1.2
@@ -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 @@
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 @@
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 @@
<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 @@
<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 @@
</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
<p><p>1.2 +3 -3 vorbis/doc/xml/02-bitpacking.xml
Index: 02-bitpacking.xml
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/xml/02-bitpacking.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- 02-bitpacking.xml 12 Oct 2002 20:37:11 -0000 1.1
+++ 02-bitpacking.xml 13 Oct 2002 15:18:46 -0000 1.2
@@ -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 @@
</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>
<p><p>1.2 +75 -65 vorbis/doc/xml/05-comment.xml
Index: 05-comment.xml
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/xml/05-comment.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- 05-comment.xml 12 Oct 2002 20:37:11 -0000 1.1
+++ 05-comment.xml 13 Oct 2002 15:18:46 -0000 1.2
@@ -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 @@
</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 @@
</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 @@
</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 @@
<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 @@
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 @@
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>
<p><p>1.3 +4 -4 vorbis/doc/xml/06-floor0.xml
Index: 06-floor0.xml
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/xml/06-floor0.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- 06-floor0.xml 13 Oct 2002 14:32:16 -0000 1.2
+++ 06-floor0.xml 13 Oct 2002 15:18:46 -0000 1.3
@@ -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 @@
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>
<p><p>1.2 +2 -2 vorbis/doc/xml/08-residue.xml
Index: 08-residue.xml
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/xml/08-residue.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- 08-residue.xml 12 Oct 2002 20:37:11 -0000 1.1
+++ 08-residue.xml 13 Oct 2002 15:18:47 -0000 1.2
@@ -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 @@
<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
<p><p>1.2 +13 -8 vorbis/doc/xml/09-helper.xml
Index: 09-helper.xml
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/xml/09-helper.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- 09-helper.xml 12 Oct 2002 20:37:11 -0000 1.1
+++ 09-helper.xml 13 Oct 2002 15:18:47 -0000 1.2
@@ -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 @@
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 @@
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>
<p><p>--- >8 ----
List archives: http://www.xiph.org/archives/
Ogg project homepage: http://www.xiph.org/ogg/
To unsubscribe from this list, send a message to 'cvs-request at xiph.org'
containing only the word 'unsubscribe' in the body. No subject is needed.
Unsubscribe messages sent to the list will be ignored/filtered.
More information about the commits
mailing list