From 0885a354f9c48e2cbcc022b1b36a3485b706f495 Mon Sep 17 00:00:00 2001
From: Monty <xiphmont@xiph.org>
Date: Mon, 26 Apr 2010 07:26:57 +0000
Subject: Doc tweaks; clarify/make more consistent the Index reasoning.

git-svn-id: http://svn.xiph.org/trunk/ogg@17175 0101bb08-14d6-0310-b084-bc0e0c8e3800
---
 doc/ogg-multiplex.html | 21 +++++++++++----------
 doc/oggstream.html     | 22 ++++++++++++++--------
 2 files changed, 25 insertions(+), 18 deletions(-)

(limited to 'doc')

diff --git a/doc/ogg-multiplex.html b/doc/ogg-multiplex.html
index 41c1481..bd08e25 100644
--- a/doc/ogg-multiplex.html
+++ b/doc/ogg-multiplex.html
@@ -117,16 +117,17 @@ Streams'.</p>
 
 <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><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>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>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
diff --git a/doc/oggstream.html b/doc/oggstream.html
index bb8d176..71bbce7 100644
--- a/doc/oggstream.html
+++ b/doc/oggstream.html
@@ -206,14 +206,9 @@ is tolerant of gross corruption.  Seek operations are neither 'fuzzy' nor
 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>
-
-<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.
+<ol>
 
 <li>An index is only marginally useful in Ogg for the complexity
 added; it adds no new functionality and seldom improves performance
@@ -227,7 +222,18 @@ only by building an internal index after reading the entire file
 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>
 
-- 
cgit v1.2.1