[xiph-cvs] cvs commit: vorbis/doc/xml 05-comment.xml
Ralph Giles
giles at xiph.org
Fri Oct 25 07:41:45 PDT 2002
giles 02/10/25 10:41:45
Modified: doc/xml 05-comment.xml
Log:
Some editorial cleanup from proof.
Revision Changes Path
1.3 +48 -53 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.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- 05-comment.xml 13 Oct 2002 15:18:46 -0000 1.2
+++ 05-comment.xml 25 Oct 2002 14:41:44 -0000 1.3
@@ -1,7 +1,7 @@
<section id="vorbis-spec-comment">
<sectioninfo>
<releaseinfo>
- $Id: 05-comment.xml,v 1.2 2002/10/13 15:18:46 giles Exp $
+ $Id: 05-comment.xml,v 1.3 2002/10/25 14:41:44 giles Exp $
<emphasis>Last update to this document: July 16, 2002</emphasis>
</releaseinfo>
</sectioninfo>
@@ -11,7 +11,7 @@
<section><title>Overview</title>
<para>The Vorbis text comment header is the second (of three) header
-packets that begin a Vorbis bitstream. It is meant for short, text
+packets that begin a Vorbis bitstream. It is meant for short text
comments, not arbitrary metadata; arbitrary metadata belongs in a
separate logical bitstream (usually an XML stream type) that provides
greater structure and machine parseability.</para>
@@ -24,8 +24,8 @@
they turn out to be, eg:
<blockquote>
-<simpara>Honest Bob and the Factory-to-Dealer-Incentives, _I'm Still
-Around_, opening for Moxy Fruvous, 1997.</simpara>
+<simpara>Honest Bob and the Factory-to-Dealer-Incentives, <citetitle>I'm Still
+Around</citetitle>, opening for Moxy Früvous, 1997.</simpara>
</blockquote>
</para>
@@ -36,13 +36,13 @@
<section><title>Structure</title>
<para>
-The comment header logically is a list of eight-bit-clean vectors; the
+The comment header is logically a list of eight-bit-clean vectors; the
number of vectors is bounded to 2^32-1 and the length of each vector
is limited to 2^32-1 bytes. The vector length is encoded; the vector
contents themselves are not null terminated. In addition to the vector
list, there is a single vector for vendor name (also 8 bit clean,
-length encoded in 32 bits). Libvorbis currently sets the vendor string
-to "Xiph.Org libVorbis I 20020717".</para>
+length encoded in 32 bits). The 1.0 release of libvorbis sets the
+vendor string to "Xiph.Org libVorbis I 20020717".</para>
<para>The comment header is decoded as follows:
@@ -55,7 +55,7 @@
6) this iteration's user comment = read a UTF-8 vector as [length] octets
}
7) [framing_bit] = read a single bit as boolean
- 8) if ( [framing_bit] unset or end of packet ) then ERROR
+ 8) if ( [framing_bit] unset or end-of-packet ) then ERROR
9) done.
</programlisting>
</para>
@@ -66,30 +66,30 @@
<para>
The comment vectors are structured similarly to a UNIX environment variable.
-That is, comment fields consist of a field name and a field value and
+That is, comment fields consist of a field name and a corresponding value and
look like:</para>
-<programlisting>
+<blockquote><programlisting>
comment[0]="ARTIST=me";
comment[1]="TITLE=the sound of Vorbis";
-</programlisting>
+</programlisting></blockquote>
-<itemizedlist>
- <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>
+<para>
+The field name is case-insensitive and may consist of ASCII 0x20
+through 0x7D, 0x3D ('=') excluded. ASCII 0x41 through 0x5A inclusive
+(characters A-Z) is to be considered equivalent to ASCII 0x61 through
+0x7A inclusive (characters a-z).
+</para>
+
+<para>
+The field name is immediately followed by ASCII 0x3D ('=');
+this equals sign is used to terminate the field name.
+</para>
+
+<para>
+0x3D is followed by 8 bit clean UTF-8 encoded value of the
+field contents to the end of the field.
+</para>
<section><title>Field names</title>
@@ -181,7 +181,7 @@
</varlistentry>
<varlistentry><term>ISRC</term>
-<listitem><simpara>ISRC number for the
+<listitem><simpara>International Standard Recording Code 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.
@@ -194,41 +194,36 @@
<section><title>Implications</title>
-<itemizedlist>
- <listitem>
- <para>Field names should not be 'internationalized'; this is a
+<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
+the world that doesn't speak English. Field <emphasis>contents</emphasis>
+however, use the UTF-8 character encoding to allow easy representation of any
language.</para>
- </listitem>
- <listitem>
- <para>We have the length of the entirety of the field and restrictions on
+
+<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
+
+<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.
+
+<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
+
+<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>
- ARTIST=Dizzy Gillespie
- ARTIST=Sonny Rollins
- ARTIST=Sonny Stitt
- </programlisting>
- </para>
- </listitem>
-</itemizedlist>
+
+<blockquote><programlisting>
+ARTIST=Dizzy Gillespie
+ARTIST=Sonny Rollins
+ARTIST=Sonny Stitt
+</programlisting></blockquote>
+
+</para>
</section>
@@ -274,7 +269,7 @@
</para>
<para>
-This is actually somewhat easier to describe in code; implementation of the above can be found in vorbis/lib/info.c:_vorbis_pack_comment(),_vorbis_unpack_comment()
+This is actually somewhat easier to describe in code; implementation of the above can be found in <filename>vorbis/lib/info.c</filename>, <function>_vorbis_pack_comment()</function> and <function>_vorbis_unpack_comment()</function>.
</para>
</section>
<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