Cleanup pass on the vorbisenc documentation.

svn path=/trunk/vorbis/; revision=16757

diff --git a/doc/vorbisenc/vorbis_analysis.html b/doc/vorbisenc/vorbis_analysis.html
index 6b91922..e5974cb 100644 (file)
--- a/doc/vorbisenc/vorbis_analysis.html
+++ b/doc/vorbisenc/vorbis_analysis.html
@@ -22,7 +22,7 @@ function is called on each block. It looks up the encoding mode and
 dispatches the block to the forward transform provided by that mode.
 </p>
 <p>When using a basic encoding mode, with no bitrate management,
-an ogg_packet pointer can be given, and an the coded block is returned
+an ogg_packet pointer can be given, and the coded block is returned
 directly through that structure and can be placed in the output stream.
 </p>
 <p>Otherwise, NULL should be passed for the ogg_packet pointer. In
@@ -46,9 +46,9 @@ extern int      vorbis_analysis(vorbis_block *vb,ogg_packet *op);
 <dt><i>vb</i></dt>
 <dd>Pointer to the vorbis_block to be encoded.</dd>
 <dt><i>op</i></dt>
-<dd>Optional pointer to an ogg_packet. This should normally NULL,
-and the final output obtained by passing <i>vb</i> though the
-vorbis_bitrate_*() interface to perform any further refinement.
+<dd>Optional pointer to an ogg_packet. This is normally NULL,
+and the final output is obtained by passing <i>vb</i> though the
+vorbis_bitrate_*() interface to perform further refinement.
 However, when not using a bitrate managed encoding mode, it
 is possible to skip that step by providing an ogg_packet pointer
 here, obtaining the compressed data directly.</dd>

diff --git a/doc/vorbisenc/vorbis_analysis_blockout.html b/doc/vorbisenc/vorbis_analysis_blockout.html
index 9f10243..169df08 100644 (file)
--- a/doc/vorbisenc/vorbis_analysis_blockout.html
+++ b/doc/vorbisenc/vorbis_analysis_blockout.html
@@ -17,9 +17,9 @@
 
 <p><i>declared in "vorbis/codec.h";</i></p>
 
-<p>This fuction examines the available encoder and tries to break it
-into appropriate sized blocks. It should be called in a loop after
-adding new data with vorbis_analysis_buffer()/vorbis_analysis_wrote()
+<p>This fuction examines the available uncompressed data and tries to
+break it into appropriate sized blocks. It should be called in a loop
+after adding new data with vorbis_analysis_buffer()/vorbis_analysis_wrote()
 until it returns zero (need more data) or an negative value (error).
 </p>
 <p>
@@ -42,7 +42,7 @@ extern int      vorbis_analysis_blockout(vorbis_dsp_state *v,vorbis_block *vb);
 <dt><i>v</i></dt>
 <dd>Pointer to the vorbis_dsp_state representing the encoder.</dd>
 <dt><i>vb</i></dt>
-<dd>Pointer to a previously initialize vorbis_block object to store the
+<dd>Pointer to a previously initialized vorbis_block object to hold the
 returned data.
 </dl>
 

diff --git a/doc/vorbisenc/vorbis_analysis_buffer.html b/doc/vorbisenc/vorbis_analysis_buffer.html
index 5ea9b23..5e79068 100644 (file)
--- a/doc/vorbisenc/vorbis_analysis_buffer.html
+++ b/doc/vorbisenc/vorbis_analysis_buffer.html
@@ -47,7 +47,7 @@ extern float  **vorbis_analysis_buffer(vorbis_dsp_state *v,int vals);
 <dt><i>v</i></dt>
 <dd>Pointer to the vorbis_dsp_state representing the encoder.</dd>
 <dt><i>vals</i></dt>
-<dd>Number of samples to provide in the request buffer.</dd>
+<dd>Number of samples to provide space for in the returned buffer. 1024 is a reasonable choice.</dd>
 </dl>
 
 

diff --git a/doc/vorbisenc/vorbis_analysis_headerout.html b/doc/vorbisenc/vorbis_analysis_headerout.html
index 0c10fc5..5c08656 100644 (file)
--- a/doc/vorbisenc/vorbis_analysis_headerout.html
+++ b/doc/vorbisenc/vorbis_analysis_headerout.html
@@ -18,7 +18,7 @@
 <p><i>declared in "vorbis/codec.h";</i></p>
 
 <p>This function creates and returns the three header packets needed
-to configure a decoder to accept subsequent data. I should be called
+to configure a decoder to accept compressed data. I should be called
 after all encoder initialization and configuration is complete. The
 output packets should be placed in order at the start of the compressed
 vorbis stream, prior to the first data packet.

diff --git a/doc/vorbisenc/vorbis_analysis_init.html b/doc/vorbisenc/vorbis_analysis_init.html
index d652cf4..967d13f 100644 (file)
--- a/doc/vorbisenc/vorbis_analysis_init.html
+++ b/doc/vorbisenc/vorbis_analysis_init.html
@@ -37,7 +37,7 @@ extern int      vorbis_analysis_init(vorbis_dsp_state *v,vorbis_info *vi);
 <dt><i>v</i</dt>
 <dd>Pointer to the vorbis_dsp_state structure to be initialized for encoding.</dd>
 <dt><i>vi</i></dt>
-<dd>File pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd>
+<dd>Pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct describing the encoder configuration.</dd>
 </dl>
 
 

diff --git a/doc/vorbisenc/vorbis_analysis_wrote.html b/doc/vorbisenc/vorbis_analysis_wrote.html
index f6e5483..f907eb4 100644 (file)
--- a/doc/vorbisenc/vorbis_analysis_wrote.html
+++ b/doc/vorbisenc/vorbis_analysis_wrote.html
@@ -22,6 +22,11 @@ Call this after writing new audio into the buffer array returned by
 vorbis_analysis_buffer().
 </p>
 
+<p>
+Call with the <i>vals</i> parameter set to zero to signal the end
+of the input data.
+</p>
+
 <table border=0 color=black cellspacing=0 cellpadding=7>
 <tr bgcolor=#cccccc>
        <td>
@@ -38,7 +43,9 @@ extern int      vorbis_analysis_wrote(vorbis_dsp_state *v,int vals);
 <dd>Pointer to the vorbis_dsp_state representing the encoder.</dd>
 <dt><i>vals</i></dt>
 <dd>Number of samples successfully written. This must be less than
-or equal to the value passed to vorbis_analysis_buffer().</dd>
+or equal to the value passed to vorbis_analysis_buffer(). A value
+of zero means all input data has been provided and the compressed
+stream should be finalized.</dd>
 </dl>
 
 

diff --git a/doc/vorbisenc/vorbis_bitrate_addblock.html b/doc/vorbisenc/vorbis_bitrate_addblock.html
index 651751f..bd360d8 100644 (file)
--- a/doc/vorbisenc/vorbis_bitrate_addblock.html
+++ b/doc/vorbisenc/vorbis_bitrate_addblock.html
@@ -18,9 +18,9 @@
 <p><i>declared in "vorbis/codec.h";</i></p>
 
 <p>This fuction submits a transformed block to the bitrate management
-engine for final encoding. Packets are submitted and, depending on the
-encoding mode, buffered and the packet boundaries adjusted and padded
-to meet the target bitrate.</p>
+engine for final encoding. Packets are buffered and the packet boundaries
+adjusted and padded to meet the target bitrate, if any.</p>
+
 <p>After calling vorbis_bitrate_addblock(), the passed vorbis_block
 structure can be reused in another call to vorbis_analysis_blockout().
 Call vorbis_bitrate_flushpacket() to obtain the final compressed data.
@@ -38,7 +38,7 @@ extern int      vorbis_bitrate_addblock(vorbis_block *vb);
 
 <h3>Parameters</h3>
 <dl>
-<dt><i>v</i></dt>
+<dt><i>vb</i></dt>
 <dd>Pointer to the vorbis_block to be submitted.</dd>
 </dl>
 

diff --git a/doc/vorbisenc/vorbis_bitrate_flushpacket.html b/doc/vorbisenc/vorbis_bitrate_flushpacket.html
index d4cccb7..d5467eb 100644 (file)
--- a/doc/vorbisenc/vorbis_bitrate_flushpacket.html
+++ b/doc/vorbisenc/vorbis_bitrate_flushpacket.html
@@ -17,9 +17,9 @@
 
 <p><i>declared in "vorbis/codec.h";</i></p>
 
-<p>This function returns the next available packet from the bitrate
-management engine. It should be called in a loop after any calls to
-vorbis_bitrate_addblock() until it returns either 0 (more data needed)
+<p>This function returns the next available completed packet from the
+bitrate management engine. It should be called in a loop after any call
+to vorbis_bitrate_addblock() until it returns either 0 (more data needed)
 or a negative value (error).
 </p>
 

diff --git a/doc/vorbisenc/vorbis_block_init.html b/doc/vorbisenc/vorbis_block_init.html
index 167d325..4053e01 100644 (file)
--- a/doc/vorbisenc/vorbis_block_init.html
+++ b/doc/vorbisenc/vorbis_block_init.html
@@ -17,9 +17,9 @@
 
 <p><i>declared in "vorbis/codec.h";</i></p>
 
-<p>This function allocates and initializes internal state associated
-with dividing the input into blocks for further analysis, stored inside
-a vorbis_block structure.
+<p>This function initializes a vorbis_block structure and allocates its
+internal storage. A vorbis_block is used to represent a particular block
+of input audio which can be analyzed and coded as a unit.
 </p>
 
 <table border=0 color=black cellspacing=0 cellpadding=7>
@@ -36,7 +36,7 @@ extern int      vorbis_block_init(vorbis_dsp_state *v, vorbis_block *vb);
 <dl>
 <dt><i>v</i</dt>
 <dd>Pointer to an initialized vorbis_dsp_state with which to associate the new block.</dd>
-<dt><i>vi</i></dt>
+<dt><i>vb</i></dt>
 <dd>Pointer to a vorbis_block struct to be initialized.</dd>
 </dl>
 

diff --git a/doc/vorbisenc/vorbis_encode_ctl.html b/doc/vorbisenc/vorbis_encode_ctl.html
index ce4c8eb..48f63a7 100644 (file)
--- a/doc/vorbisenc/vorbis_encode_ctl.html
+++ b/doc/vorbisenc/vorbis_encode_ctl.html
@@ -46,7 +46,7 @@ extern int vorbis_encode_ctl(vorbis_info *vi,int request,void *arg);
 <h3>Parameters</h3>
 <dl>
 <dt><i>vi</i></dt>
-<dd>File pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd><p>
+<dd>Pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd><p>
 <dt><i>request</i></dt>
 <dd>Specifies the desired action; possible request fields are detailed below.</dd><p>
 <dt><i>arg</i></dt>

diff --git a/doc/vorbisenc/vorbis_encode_init.html b/doc/vorbisenc/vorbis_encode_init.html
index 525b546..f279775 100644 (file)
--- a/doc/vorbisenc/vorbis_encode_init.html
+++ b/doc/vorbisenc/vorbis_encode_init.html
@@ -42,7 +42,7 @@ extern int vorbis_encode_init(<a href="vorbis_info.html">vorbis_info</a> *vi,
 <h3>Parameters</h3>
 <dl>
 <dt><i>vi</i></dt>
-<dd>File pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd>
+<dd>Pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd>
 <dt><i>channels</i></dt>
 <dd>The number of channels to be encoded.</dd>
 <dt><i>rate</i></dt>

diff --git a/doc/vorbisenc/vorbis_encode_init_vbr.html b/doc/vorbisenc/vorbis_encode_init_vbr.html
index 2afe8cd..92f9a23 100644 (file)
--- a/doc/vorbisenc/vorbis_encode_init_vbr.html
+++ b/doc/vorbisenc/vorbis_encode_init_vbr.html
@@ -39,7 +39,7 @@ extern int vorbis_encode_init_vbr(<a href="vorbis_info.html">vorbis_info</a> *vi
 <h3>Parameters</h3>
 <dl>
 <dt><i>vi</i></dt>
-<dd>File pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd>
+<dd>Pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd>
 <dt><i>channels</i></dt>
 <dd>The number of channels to be encoded.</dd>
 <dt><i>rate</i></dt>

diff --git a/doc/vorbisenc/vorbis_encode_setup_init.html b/doc/vorbisenc/vorbis_encode_setup_init.html
index 48abca1..7d18655 100644 (file)
--- a/doc/vorbisenc/vorbis_encode_setup_init.html
+++ b/doc/vorbisenc/vorbis_encode_setup_init.html
@@ -48,7 +48,7 @@ extern int vorbis_encode_setup_init(<a href="vorbis_info.html">vorbis_info</a> *
 <h3>Parameters</h3>
 <dl>
 <dt><i>vi</i></dt>
-<dd>File pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd>
+<dd>Pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd>
 </dl>
 
 

diff --git a/doc/vorbisenc/vorbis_encode_setup_managed.html b/doc/vorbisenc/vorbis_encode_setup_managed.html
index c36599d..6e8d8c7 100644 (file)
--- a/doc/vorbisenc/vorbis_encode_setup_managed.html
+++ b/doc/vorbisenc/vorbis_encode_setup_managed.html
@@ -56,7 +56,7 @@ extern int vorbis_encode_init(<a href="vorbis_info.html">vorbis_info</a> *vi,
 <h3>Parameters</h3>
 <dl>
 <dt><i>vi</i></dt>
-<dd>File pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd>
+<dd>Pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd>
 <dt><i>channels</i></dt>
 <dd>The number of channels to be encoded.</dd>
 <dt><i>rate</i></dt>

diff --git a/doc/vorbisenc/vorbis_encode_setup_vbr.html b/doc/vorbisenc/vorbis_encode_setup_vbr.html
index 0e0b16e..6c9a698 100644 (file)
--- a/doc/vorbisenc/vorbis_encode_setup_vbr.html
+++ b/doc/vorbisenc/vorbis_encode_setup_vbr.html
@@ -48,7 +48,7 @@ extern int vorbis_encode_init_vbr(<a href="vorbis_info.html">vorbis_info</a> *vi
 <h3>Parameters</h3>
 <dl>
 <dt><i>vi</i></dt>
-<dd>File pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd>
+<dd>Pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd>
 <dt><i>channels</i></dt>
 <dd>The number of channels to be encoded.</dd>
 <dt><i>rate</i></dt>