[xiph-commits] r17175 - trunk/ogg/doc

[xiphmont at svn.xiph.org]

Author: xiphmont
Date: 2010-04-26 00:26:57 -0700 (Mon, 26 Apr 2010)
New Revision: 17175

Modified:
   trunk/ogg/doc/ogg-multiplex.html
   trunk/ogg/doc/oggstream.html
Log:
Doc tweaks; clarify/make more consistent the Index reasoning.



Modified: trunk/ogg/doc/ogg-multiplex.html
===================================================================
--- trunk/ogg/doc/ogg-multiplex.html	2010-04-25 19:46:23 UTC (rev 17174)
+++ trunk/ogg/doc/ogg-multiplex.html	2010-04-26 07:26:57 UTC (rev 17175)
@@ -117,16 +117,17 @@
 
 <h3>Seeking</h3> 
 
-<p>Ogg is designed to use a bisection search to implement exact
-positional seeking rather than building an index; an index requires
-two-pass encoding and as such is not acceptable given the requirement
-for full-featured linear encoding.</p>
+<p>Ogg is designed to use an interpolated bisection search to
+implement exact positional seeking.  Interpolated bisection search is
+a spec-mandated mechanism.</p>
 
-<p><i>Even making an index optional then requires an
-application to support multiple methods (bisection search for a
-one-pass stream, indexing for a two-pass stream), which adds no
-additional functionality as bisection search delivers the same
-functionality for both stream types.</i></p>
+<p><i>An index may improve objective performance, but it seldom
+improves subjective performance outside of a few high-latency use
+cases and adds no additional functionality as bisection search
+delivers the same functionality for both one- and two-pass stream
+types.  For these reasons, use of indexes is discouraged, except in
+cases where an index provides demonstrable and noticable performance
+improvement.</i></p>
 
 <p>Seek operations are by absolute time; a direct bisection search must
 find the exact time position requested. Information in the Ogg

Modified: trunk/ogg/doc/oggstream.html
===================================================================
--- trunk/ogg/doc/oggstream.html	2010-04-25 19:46:23 UTC (rev 17174)
+++ trunk/ogg/doc/oggstream.html	2010-04-26 07:26:57 UTC (rev 17175)
@@ -206,15 +206,10 @@
 heuristic.
 
 <p>Seeking without use of an index is a major point of the Ogg
-design. There are several reasons why Ogg forgoes an index:
+design. There two primary reasons why Ogg transport forgoes an index:
 			  
-<ul>
+<ol>
 
-<li>It must be possible to create an Ogg stream in a single pass, and
-an index requires either two passes to create, or the index must be
-tacked onto the end of a live stream after the stream is finished.
-Both methods run afoul of other design constraints.
-
 <li>An index is only marginally useful in Ogg for the complexity
 added; it adds no new functionality and seldom improves performance
 noticeably.  Empirical testing shows that indexless interpolation
@@ -227,8 +222,19 @@
 beginning to end.  This has been the fate of other containers that
 specify optional indexing.
 
-</ul>
+</ol>
 
+<p>In addition, it must be possible to create an Ogg stream in a
+single pass. Although an optional index can simply be tacked on the
+end of the created stream, some software groups object to
+end-positioned indexes and claim to be unwilling to support indexes
+not located at the stream beginning.
+
+<p><i>All this said, it's become clear that an optional index is a
+demanded feature.  For this reason, the <a
+href="http://wiki.xiph.org/Ogg_Index">OggSkeleton now defines a
+proposed index.</a></i>
+
 <h3>Simple multiplexing</h3>
 
 <p>Ogg multiplexes streams by interleaving pages from multiple elementary streams into a