renamed
authorjmvalin <jmvalin@0101bb08-14d6-0310-b084-bc0e0c8e3800>
Tue, 23 Jul 2002 07:45:27 +0000 (07:45 +0000)
committerjmvalin <jmvalin@0101bb08-14d6-0310-b084-bc0e0c8e3800>
Tue, 23 Jul 2002 07:45:27 +0000 (07:45 +0000)
git-svn-id: http://svn.xiph.org/trunk/speex@3711 0101bb08-14d6-0310-b084-bc0e0c8e3800

doc/internals.lyx [deleted file]

diff --git a/doc/internals.lyx b/doc/internals.lyx
deleted file mode 100644 (file)
index 445ad99..0000000
+++ /dev/null
@@ -1,1273 +0,0 @@
-#LyX 1.2 created this file. For more info see http://www.lyx.org/
-\lyxformat 220
-\textclass article
-\language english
-\inputencoding auto
-\fontscheme default
-\graphics default
-\paperfontsize default
-\spacing single 
-\papersize Default
-\paperpackage a4
-\use_geometry 0
-\use_amsmath 0
-\use_natbib 0
-\use_numerical_citations 0
-\paperorientation portrait
-\secnumdepth 3
-\tocdepth 3
-\paragraph_separation indent
-\defskip medskip
-\quotes_language english
-\quotes_times 2
-\papercolumns 1
-\papersides 1
-\paperpagestyle headings
-
-\layout Title
-
-The Speex Codec Manual
-\layout Author
-
-Jean-Marc Valin
-\layout Standard
-\pagebreak_top 
-Copyright (c) 2002 Jean-Marc Valin.
-\layout Standard
-
-Permission is granted to copy, distribute and/or modify this document under
- the terms of the GNU Free Documentation License, Version 1.1 or any later
- version published by the Free Software Foundation; with no Invariant Section,
- with no Front-Cover Texts, and with no Back-Cover.
- A copy of the license is included in the section entitled "GNU Free Documentati
-on License".
-\layout Section*
-
-Disclaimer
-\layout Standard
-
-This document is meant to ease the understanding of the Speex code but makes
- no warranty of being exact.
- Also, some techniques used in Speex are said to be 
-\begin_inset Quotes eld
-\end_inset 
-
-similar
-\begin_inset Quotes erd
-\end_inset 
-
- to techniques used in known codecs.
- This should not be understood as an acknowledgment that Speex is using
- any patented algorithm used in these codecs, but merely that comprehension
- of Speex can be facilitated by thinking that the principles of operation
- are the same or similar.
- Of course, there's also the obligatory 
-\begin_inset Quotes eld
-\end_inset 
-
-all trademarks are property of their respective owner
-\begin_inset Quotes erd
-\end_inset 
-
-.
-\layout Standard
-\pagebreak_top \pagebreak_bottom 
-
-\begin_inset LatexCommand \tableofcontents{}
-
-\end_inset 
-
-
-\layout Section
-
-Introduction to Speex
-\layout Standard
-
-Speex has been designed with the following goals in mind:
-\layout Itemize
-
-No use of patented algorithms (implies that we can't use ACELP or other
- patented algorithms)
-\layout Itemize
-
-Good for Voice over IP (VoIP)
-\layout Itemize
-
-Provide very good quality speech (at least as an option)
-\layout Itemize
-
-Allow a wide range of quality/bit-rate
-\layout Itemize
-
-Integrate both narrowband and wideband coding
-\layout Itemize
-
-Reasonable complexity
-\layout Standard
-
-Throughout the design the following assumptions and constraints were considered
-\layout Itemize
-
-Presence of packet losses
-\layout Itemize
-
-Integrity of received frames (no bit-errors)
-\layout Itemize
-
-Memory footprint is neither critical nor unlimited
-\layout Standard
-
-This led us to choose the CELP technique for Speex.
- Also many design decisions were based on the original goals and assumptions:
-\layout Itemize
-
-Minimizing the amount of information extracted from past frames (for robustness
- to packet loss)
-\layout Itemize
-
-Dynamically-selectable codebooks (LSP, pitch and innovation)
-\layout Itemize
-
-G.728-like fixed codebooks (without backward-adaptive grains) because of
- patent issues
-\layout Section
-
-Introduction to CELP coding
-\layout Standard
-
-Speex is based on the CELP, which stands for Code Excited Linear Prediction.
- This section attempts to introduce the principles behind CELP, so if you
- are already familiar with CELP, you can safely skip to section 
-\begin_inset LatexCommand \ref{sec:Speex-narrowband-mode}
-
-\end_inset 
-
-.
- The CELP technique is based on three ideas:
-\layout Enumerate
-
-The use of a linear prediction (LP) model to model the vocal tract
-\layout Enumerate
-
-The use of (adaptive and fixed) codebook entries as input (excitation) of
- the LP model
-\layout Enumerate
-
-The search performed in closed-loop in a 
-\begin_inset Quotes eld
-\end_inset 
-
-perceptually weighted domain
-\begin_inset Quotes erd
-\end_inset 
-
-
-\layout Subsection
-
-Linear prediction
-\layout Standard
-
-The linear prediction model represents each speech sample as linear combination
- of past samples, plus an error signal called the excitation (or residual).
-\begin_inset Formula \[
-x(n)=\sum _{i=1}^{N}a_{i}x(n-i)+e(n)\]
-
-\end_inset 
-
-
-\layout Standard
-
-
-\begin_inset Formula \[
-x(z)=\frac{1}{A(z)}\: e(z)\]
-
-\end_inset 
-
-
-\layout Standard
-
-
-\begin_inset Formula \[
-A(z)=1-\sum _{i=1}^{N}a_{i}z^{-i}\]
-
-\end_inset 
-
-
-\layout Standard
-
-We usually refer to 
-\begin_inset Formula $A(z)$
-\end_inset 
-
- as the analysis filter and 
-\begin_inset Formula $1/A(z)$
-\end_inset 
-
- as the synthesis filter.
-\layout Standard
-
-The 
-\begin_inset Formula $A(z)$
-\end_inset 
-
- filter is computed using the Levinson-Durbin algorithm, which starts from
- the auto-correlation 
-\begin_inset Formula $R(m)$
-\end_inset 
-
- of the signal 
-\begin_inset Formula $x(n)$
-\end_inset 
-
-.
-\layout Standard
-
-
-\begin_inset Formula \[
-r(m)=\sum _{i=0}^{N-1}x(i)x(i-m)\]
-
-\end_inset 
-
-
-\layout Standard
-
-For an order 
-\begin_inset Formula $N$
-\end_inset 
-
- filter, we have:
-\begin_inset Formula \[
-\mathbf{R}=\left[\begin{array}{cccc}
- r(0) & r(1) & \cdots  & r(N-1)\\
- r(1) & r(0) & \cdots  & r(N-2)\\
- \vdots  & \vdots  & \ddots  & \vdots \\
- r(N-1) & r(N-2) & \cdots  & r(0)\end{array}
-\right]\]
-
-\end_inset 
-
-
-\begin_inset Formula \[
-\mathbf{r}=\left[\begin{array}{c}
- r(1)\\
- r(2)\\
- \vdots \\
- R(N)\end{array}
-\right]\]
-
-\end_inset 
-
-
-\layout Standard
-
-The filter coefficients 
-\begin_inset Formula $a_{i}$
-\end_inset 
-
- are found by solving the system 
-\begin_inset Formula $\mathbf{Ra}=\mathbf{r}$
-\end_inset 
-
-.
- What the Levinson-Durbin algorithm does here is making the solution to
- the problem 
-\begin_inset Formula $\mathcal{O}\left(N^{2}\right)$
-\end_inset 
-
- instead of 
-\begin_inset Formula $\mathcal{O}\left(N^{3}\right)$
-\end_inset 
-
- by exploiting the fact that matrix 
-\begin_inset Formula $\mathbf{R}$
-\end_inset 
-
- is toeplitz hermitian.
-\layout Standard
-
-Lag-windowing, noise floor
-\layout Subsection
-
-Pitch prediction
-\layout Standard
-
-
-\begin_inset Formula \[
-r(n)=\beta r(n-T)+c(n)\]
-
-\end_inset 
-
-
-\layout Standard
-
-
-\begin_inset Formula \[
-r(z)=\frac{1}{1-\beta z^{-T}}\: c(z)\]
-
-\end_inset 
-
-where 
-\begin_inset Formula $c(n)$
-\end_inset 
-
-is taken from the 
-\emph on 
-innovation codebook
-\emph default 
-.
-\layout Subsection
-
-Innovation codebook
-\layout Standard
-
-This is where most of the bits in a CELP codec are allocated.
-\layout Subsection
-
-Analysis-by-synthesis and error weighting
-\layout Standard
-
-Most (if not all) modern audio codecs attempt to 
-\emph on 
-shape
-\emph default 
- the noise so that it is the hardest to detect with the ear.
- That means that more noise can be tolerated in parts of the spectrum that
- are louder and 
-\emph on 
-vice versa
-\emph default 
-.
-\layout Standard
-
-
-\begin_inset Formula \begin{equation}
-W(z)=\frac{A\left(\frac{z}{\gamma _{1}}\right)}{A\left(\frac{z}{\gamma _{2}}\right)}\label{eq:weighting_filter}\end{equation}
-
-\end_inset 
-
-
-\layout Section
-
-Speex narrowband mode
-\begin_inset LatexCommand \label{sec:Speex-narrowband-mode}
-
-\end_inset 
-
-
-\layout Standard
-
-This section looks at how Speex works for narrowband (
-\begin_inset Formula $8\: \mathrm{kHz}$
-\end_inset 
-
- sampling rate) operation.
- The frame size for this mode is 
-\begin_inset Formula $20\: \mathrm{ms}$
-\end_inset 
-
-, corresponding to 160 samples.
- Each frame is also subdivided into 4 sub-frames of 40 samples each.
-\layout Subsection
-
-LPC analysis
-\layout Standard
-
-An LPC analysis is first performed on a (Hamming) window that spans all
- the current frame and half a frame in advance.
- The LPC coefficients are then converted to Line Spectral Pair (LSP), a
- representation that is more robust to quantization.
- The LSP's are quantized using 30 bits for higher quality modes and 18 bits
- for lower quality.
- The quantized LSP's are considered to be associated to the 
-\begin_inset Formula $4^{th}$
-\end_inset 
-
- sub-frames and the LSP's associated to the first 3 sub-frames are linearly
- interpolated using the current and previous LSP's.
-\layout Standard
-
-The perceptual weighting filter 
-\begin_inset Formula $W(z)$
-\end_inset 
-
- used by Speex corresponds to the one described by eq.
-\begin_inset LatexCommand \ref{eq:weighting_filter}
-
-\end_inset 
-
- with 
-\begin_inset Formula $\gamma _{1}=0.9$
-\end_inset 
-
- and 
-\begin_inset Formula $\gamma _{2}=0.6$
-\end_inset 
-
-.
- We can use the unquantized 
-\begin_inset Formula $A(z)$
-\end_inset 
-
- filter since the weighting filter is only used in the encoder.
-\layout Subsection
-
-Pitch prediction (adaptive codebook)
-\layout Standard
-
-Speex uses a 3-tap prediction for pitch.
- That is, 
-\layout Standard
-
-
-\begin_inset Formula \[
-r(n)=\beta _{0}r(n-T-1)+\beta _{1}r(n-T)+\beta _{2}r(n-T+1)+c(n)\]
-
-\end_inset 
-
-
-\layout Standard
-
-where 
-\begin_inset Formula $T$
-\end_inset 
-
- is the pitch period and the 
-\begin_inset Formula $\beta _{i}$
-\end_inset 
-
- are the prediction (filter) taps.
- The period and quantized gains are determined in closed loop.
-\layout Subsection
-
-Innovation codebook
-\layout Standard
-
-In Speex, the innovation signal is quantized using shape-only vector quantizatio
-n (VQ).
- That means that the codebooks that are used represent both the shape and
- the gain at the same time.
- This save many bits that would otherwise be allocated for a separate gain
- at the price of a slight increase in complexity.
- Except for the absence of (backward-adaptive) gain, the technique used
- in Speex is similar to G.728 (LD-CELP).
- However since we do not have a low-delay constraint, the search can be
- made more 
-\begin_inset Quotes eld
-\end_inset 
-
-global
-\begin_inset Quotes erd
-\end_inset 
-
- and make use of the whole information available for a sub-frame.
-\layout Subsection
-
-Perceptual post-filter
-\layout Standard
-
-This part of the codec only applies to the decoder and can even be changed
- without affecting inter-operatability.
-\layout Section
-
-Speex wideband mode (sub-band CELP)
-\layout Standard
-
-For wideband, the Speex approach is similar to the ITU-T G.722 (ADPCM) wideband
- standard in that it uses a 
-\emph on 
-q
-\emph default 
-uadrature 
-\emph on 
-m
-\emph default 
-irror 
-\emph on 
-f
-\emph default 
-ilter (QMF) to split the band in two.
- The 16 kHz signal is thus divided into two 8 kHz signals, one representing
- the low band (0-4 kHz), the other the high band (4-8 kHz).
- The low band is encoded with the narrowband mode described in section 
-\begin_inset LatexCommand \ref{sec:Speex-narrowband-mode}
-
-\end_inset 
-
- in such a way that the resulting 
-\begin_inset Quotes eld
-\end_inset 
-
-embedded narrowband bit-stream
-\begin_inset Quotes erd
-\end_inset 
-
- can also be decoded with the narrowband decoder.
- Since the low band encoding has already been described only the high band
- encoding is described in this section.
-\layout Subsection
-
-Linear prediction
-\layout Standard
-
-The linear prediction part used for the high-band is very similar to what
- is done for narrowband.
- The only difference is that we use only 12 bits to encode the high-band
- LSP's.
-\layout Section
-
-Programming with Speex (the libspeex API)
-\layout Subsection
-
-Encoding 
-\layout Standard
-
-In order to encode speech using Speex, you first need to:
-\layout LyX-Code
-
-#include <speex.h>
-\layout Standard
-
-You then need to declare a Speex bit-packing struct
-\layout LyX-Code
-
-SpeexBits bits;
-\layout Standard
-
-and a Speex encoder state
-\layout LyX-Code
-
-void *enc_state;
-\layout Standard
-
-The two are initialized by:
-\layout LyX-Code
-
-speex_bits_init(&bits);
-\layout LyX-Code
-
-enc_state = speex_encoder_init(&speex_nb_mode);
-\layout Standard
-
-For wideband coding, 
-\emph on 
-speex_nb_mode
-\emph default 
- will be replaced by 
-\emph on 
-speex_wb_mode
-\emph default 
-.
- In most cases, you will need to know the frame size used by the mode you
- are using.
- You can get that value in the 
-\emph on 
-frame_size
-\emph default 
- variable with:
-\layout LyX-Code
-
-speex_encoder_ctl(enc_state,SPEEX_GET_FRAME_SIZE,&frame_size);
-\layout Standard
-
-Once the initialization is done, for every input frame:
-\layout LyX-Code
-
-speex_bits_reset(&bits);
-\layout LyX-Code
-
-speex_encode(enc_state, input_frame, &bits);
-\layout LyX-Code
-
-nbBytes = speex_bits_write(&bits, byte_ptr, MAX_NB_BYTES);
-\layout Standard
-
-where 
-\emph on 
-input_frame
-\emph default 
- is a 
-\emph on 
-(float *)
-\emph default 
- pointing to the beginning of a speech frame, 
-\emph on 
-byte_ptr
-\emph default 
- is a 
-\emph on 
-(char *)
-\emph default 
- where the encoded frame will be written, 
-\emph on 
-MAX_NB_BYTES
-\emph default 
- is the maximum number of bytes that can be written to 
-\emph on 
-byte_ptr
-\emph default 
- without causing an overflow and 
-\emph on 
-nbBytes
-\emph default 
- is the number of bytes actually written to 
-\emph on 
-byte_ptr
-\emph default 
- (the encoded size in bytes).
-\layout Standard
-
-After you're done with the encoding, free all resources with:
-\layout LyX-Code
-
-speex_bits_destroy(&bits);
-\layout LyX-Code
-
-speex_encoder_destroy(&enc_state);
-\layout Standard
-
-That's about it for the encoder.
-\layout Subsection
-
-Decoding 
-\layout Standard
-
-In order to encode speech using Speex, you first need to:
-\layout LyX-Code
-
-#include <speex.h>
-\layout Standard
-
-You then need to declare a Speex bit-packing struct
-\layout LyX-Code
-
-SpeexBits bits;
-\layout Standard
-
-and a Speex encoder state
-\layout LyX-Code
-
-void *dec_state;
-\layout Standard
-
-The two are initialized by:
-\layout LyX-Code
-
-speex_bits_init(&bits);
-\layout LyX-Code
-
-dec_state = speex_decoder_init(&speex_nb_mode);
-\layout Standard
-
-For wideband decoding, 
-\emph on 
-speex_nb_mode
-\emph default 
- will be replaced by 
-\emph on 
-speex_wb_mode
-\emph default 
-.
- You can get that value in the 
-\emph on 
-frame_size
-\emph default 
- variable with:
-\layout LyX-Code
-
-speex_decoder_ctl(dec_state, SPEEX_GET_FRAME_SIZE, &frame_size); 
-\layout Standard
-
-There is also a parameter that can be set for the decoder: whether or not
- to use a perceptual post-filter.
- This can be set by: 
-\layout LyX-Code
-
-speex_decoder_ctl(dec_state, SPEEX_SET_PF, &pf); 
-\layout Standard
-
-where pf is an int that with value 0 to have the post-filter disabled and
- 1 to have it enabled.
-\layout Standard
-
-Again, once the decoder initialization is done, for every input frame:
-\layout LyX-Code
-
-speex_bits_read_from(&bits, input_bytes, nbBytes);
-\layout LyX-Code
-
-speex_decode(st, &bits, output_frame, 0);
-\layout Standard
-
-where input_bytes is a 
-\emph on 
-(char *)
-\emph default 
- containing the bit-stream data received for a frame, 
-\emph on 
-nbBytes
-\emph default 
- is the size (in bytes) of that bit-stream, and 
-\emph on 
-output_frame
-\emph default 
- is a 
-\emph on 
-(float *)
-\emph default 
- and points to the area where the decoded speech frame will be written.
- The last argument indicates whether the frame we'd like to decode was lost.
- A value of 0 indicates the normal case where bits points to the bit of
- the current frame.
- A value of 1 indicates that we don't have the bits for the current frame,
- in which case the bits argument should be the same as the bits for the
- last correctly received frame.
- When a frame is lost, the Speex decoder will do its best to "guess" the
- correct signal.
-\layout Subsection
-
-Codec options (speex_*_ctl)
-\layout Standard
-
-The Speex encoder and decoder support many options and requests that can
- be accessed through the 
-\emph on 
-speex_encoder_ctl
-\emph default 
- and 
-\emph on 
-speex_decoder_ctl
-\emph default 
- functions.
- These functions are similar the the 
-\emph on 
-ioctl
-\emph default 
- system call and their prototypes are:
-\layout LyX-Code
-
-void speex_encoder_ctl(void *encoder, int request, void *ptr);
-\layout LyX-Code
-
-void speex_decoder_ctl(void *encoder, int request, void *ptr);
-\layout Standard
-
-The different values of request allowed are (note that some only apply to
- the encoder or the decoder):
-\layout Description
-
-SPEEX_SET_PF** Set post-filter to on (1) or off (0) (integer)
-\layout Description
-
-SPEEX_GET_PF** Get post-filter status (integer)
-\layout Description
-
-SPEEX_GET_FRAME_SIZE Get the frame size used for the current mode (integer)
-\layout Description
-
-SPEEX_SET_QUALITY* Set the encoder speech quality (integer 0 to 10)
-\layout Description
-
-SPEEX_GET_QUALITY* Get the current encoder speech quality (integer 0 to
- 10)
-\layout Description
-
-SPEEX_SET_MODE*
-\begin_inset Formula $\dagger $
-\end_inset 
-
-
-\layout Description
-
-SPEEX_GET_MODE*
-\begin_inset Formula $\dagger $
-\end_inset 
-
-
-\layout Description
-
-SPEEX_SET_LOW_MODE*
-\begin_inset Formula $\dagger $
-\end_inset 
-
-
-\layout Description
-
-SPEEX_GET_LOW_MODE*
-\begin_inset Formula $\dagger $
-\end_inset 
-
-
-\layout Description
-
-SPEEX_SET_HIGH_MODE*
-\begin_inset Formula $\dagger $
-\end_inset 
-
-
-\layout Description
-
-SPEEX_GET_HIGH_MODE*
-\begin_inset Formula $\dagger $
-\end_inset 
-
-
-\layout Description
-
-SPEEX_SET_VBR* Set variable bit-rate (VBR) to on (1) or off (0) (integer)
-\layout Description
-
-SPEEX_GET_VBR* Get variable bit-rate (VBR) status (integer)
-\layout Description
-
-SPEEX_SET_VBR_QUALITY* Set the encoder VBR speech quality (integer 0 to
- 10)
-\layout Description
-
-SPEEX_GET_VBR_QUALITY* Get the current encoder VBR speech quality (integer
- 0 to 10)
-\layout Description
-
-* applies only to the encoder
-\layout Description
-
-** applies only to the decoder
-\layout Description
-
-
-\begin_inset Formula $\dagger $
-\end_inset 
-
- normally only used internally
-\layout Section
-\pagebreak_top \start_of_appendix 
-GNU Free Documentation License
-\layout Standard
-
-Version 1.1, March 2000
-\layout Standard
-
-Copyright (C) 2000 Free Software Foundation, Inc.
- 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted
- to copy and distribute verbatim copies of this license document, but changing
- it is not allowed.
-\layout Subsection*
-
-0.
- PREAMBLE
-\layout Standard
-
-The purpose of this License is to make a manual, textbook, or other written
- document "free" in the sense of freedom: to assure everyone the effective
- freedom to copy and redistribute it, with or without modifying it, either
- commercially or noncommercially.
- Secondarily, this License preserves for the author and publisher a way
- to get credit for their work, while not being considered responsible for
- modifications made by others.
-\layout Standard
-
-This License is a kind of "copyleft", which means that derivative works
- of the document must themselves be free in the same sense.
- It complements the GNU General Public License, which is a copyleft license
- designed for free software.
-\layout Standard
-
-We have designed this License in order to use it for manuals for free software,
- because free software needs free documentation: a free program should come
- with manuals providing the same freedoms that the software does.
- But this License is not limited to software manuals; it can be used for
- any textual work, regardless of subject matter or whether it is published
- as a printed book.
- We recommend this License principally for works whose purpose is instruction
- or reference.
-\layout Subsection*
-
-1.
- APPLICABILITY AND DEFINITIONS
-\layout Standard
-
-This License applies to any manual or other work that contains a notice
- placed by the copyright holder saying it can be distributed under the terms
- of this License.
- The "Document", below, refers to any such manual or work.
- Any member of the public is a licensee, and is addressed as "you".
-\layout Standard
-
-A "Modified Version" of the Document means any work containing the Document
- or a portion of it, either copied verbatim, or with modifications and/or
- translated into another language.
-\layout Standard
-
-A "Secondary Section" is a named appendix or a front-matter section of the
- Document that deals exclusively with the relationship of the publishers
- or authors of the Document to the Document's overall subject (or to related
- matters) and contains nothing that could fall directly within that overall
- subject.
- (For example, if the Document is in part a textbook of mathematics, a Secondary
- Section may not explain any mathematics.) The relationship could be a matter
- of historical connection with the subject or with related matters, or of
- legal, commercial, philosophical, ethical or political position regarding
- them.
-\layout Standard
-
-The "Invariant Sections" are certain Secondary Sections whose titles are
- designated, as being those of Invariant Sections, in the notice that says
- that the Document is released under this License.
-\layout Standard
-
-The "Cover Texts" are certain short passages of text that are listed, as
- Front-Cover Texts or Back-Cover Texts, in the notice that says that the
- Document is released under this License.
-\layout Standard
-
-A "Transparent" copy of the Document means a machine-readable copy, represented
- in a format whose specification is available to the general public, whose
- contents can be viewed and edited directly and straightforwardly with generic
- text editors or (for images composed of pixels) generic paint programs
- or (for drawings) some widely available drawing editor, and that is suitable
- for input to text formatters or for automatic translation to a variety
- of formats suitable for input to text formatters.
- A copy made in an otherwise Transparent file format whose markup has been
- designed to thwart or discourage subsequent modification by readers is
- not Transparent.
- A copy that is not "Transparent" is called "Opaque".
-\layout Standard
-
-Examples of suitable formats for Transparent copies include plain ASCII
- without markup, Texinfo input format, LaTeX input format, SGML or XML using
- a publicly available DTD, and standard-conforming simple HTML designed
- for human modification.
- Opaque formats include PostScript, PDF, proprietary formats that can be
- read and edited only by proprietary word processors, SGML or XML for which
- the DTD and/or processing tools are not generally available, and the machine-ge
-nerated HTML produced by some word processors for output purposes only.
-\layout Standard
-
-The "Title Page" means, for a printed book, the title page itself, plus
- such following pages as are needed to hold, legibly, the material this
- License requires to appear in the title page.
- For works in formats which do not have any title page as such, "Title Page"
- means the text near the most prominent appearance of the work's title,
- preceding the beginning of the body of the text.
-\layout Subsection*
-
-2.
- VERBATIM COPYING
-\layout Standard
-
-You may copy and distribute the Document in any medium, either commercially
- or noncommercially, provided that this License, the copyright notices,
- and the license notice saying this License applies to the Document are
- reproduced in all copies, and that you add no other conditions whatsoever
- to those of this License.
- You may not use technical measures to obstruct or control the reading or
- further copying of the copies you make or distribute.
- However, you may accept compensation in exchange for copies.
- If you distribute a large enough number of copies you must also follow
- the conditions in section 3.
-\layout Standard
-
-You may also lend copies, under the same conditions stated above, and you
- may publicly display copies.
-\layout Subsection*
-
-3.
- COPYING IN QUANTITY
-\layout Standard
-
-If you publish printed copies of the Document numbering more than 100, and
- the Document's license notice requires Cover Texts, you must enclose the
- copies in covers that carry, clearly and legibly, all these Cover Texts:
- Front-Cover Texts on the front cover, and Back-Cover Texts on the back
- cover.
- Both covers must also clearly and legibly identify you as the publisher
- of these copies.
- The front cover must present the full title with all words of the title
- equally prominent and visible.
- You may add other material on the covers in addition.
- Copying with changes limited to the covers, as long as they preserve the
- title of the Document and satisfy these conditions, can be treated as verbatim
- copying in other respects.
-\layout Standard
-
-If the required texts for either cover are too voluminous to fit legibly,
- you should put the first ones listed (as many as fit reasonably) on the
- actual cover, and continue the rest onto adjacent pages.
-\layout Standard
-
-If you publish or distribute Opaque copies of the Document numbering more
- than 100, you must either include a machine-readable Transparent copy along
- with each Opaque copy, or state in or with each Opaque copy a publicly-accessib
-le computer-network location containing a complete Transparent copy of the
- Document, free of added material, which the general network-using public
- has access to download anonymously at no charge using public-standard network
- protocols.
- If you use the latter option, you must take reasonably prudent steps, when
- you begin distribution of Opaque copies in quantity, to ensure that this
- Transparent copy will remain thus accessible at the stated location until
- at least one year after the last time you distribute an Opaque copy (directly
- or through your agents or retailers) of that edition to the public.
-\layout Standard
-
-It is requested, but not required, that you contact the authors of the Document
- well before redistributing any large number of copies, to give them a chance
- to provide you with an updated version of the Document.
-\layout Subsection*
-
-4.
- MODIFICATIONS
-\layout Standard
-
-You may copy and distribute a Modified Version of the Document under the
- conditions of sections 2 and 3 above, provided that you release the Modified
- Version under precisely this License, with the Modified Version filling
- the role of the Document, thus licensing distribution and modification
- of the Modified Version to whoever possesses a copy of it.
- In addition, you must do these things in the Modified Version: 
-\layout Itemize
-
-A.
- Use in the Title Page (and on the covers, if any) a title distinct from
- that of the Document, and from those of previous versions (which should,
- if there were any, be listed in the History section of the Document).
- You may use the same title as a previous version if the original publisher
- of that version gives permission.
-\layout Itemize
-
-B.
- List on the Title Page, as authors, one or more persons or entities responsible
- for authorship of the modifications in the Modified Version, together with
- at least five of the principal authors of the Document (all of its principal
- authors, if it has less than five).
-\layout Itemize
-
-C.
- State on the Title page the name of the publisher of the Modified Version,
- as the publisher.
-\layout Itemize
-
-D.
- Preserve all the copyright notices of the Document.
-\layout Itemize
-
-E.
- Add an appropriate copyright notice for your modifications adjacent to
- the other copyright notices.
-\layout Itemize
-
-F.
- Include, immediately after the copyright notices, a license notice giving
- the public permission to use the Modified Version under the terms of this
- License, in the form shown in the Addendum below.
-\layout Itemize
-
-G.
- Preserve in that license notice the full lists of Invariant Sections and
- required Cover Texts given in the Document's license notice.
-\layout Itemize
-
-H.
- Include an unaltered copy of this License.
-\layout Itemize
-
-I.
- Preserve the section entitled "History", and its title, and add to it an
- item stating at least the title, year, new authors, and publisher of the
- Modified Version as given on the Title Page.
- If there is no section entitled "History" in the Document, create one stating
- the title, year, authors, and publisher of the Document as given on its
- Title Page, then add an item describing the Modified Version as stated
- in the previous sentence.
-\layout Itemize
-
-J.
- Preserve the network location, if any, given in the Document for public
- access to a Transparent copy of the Document, and likewise the network
- locations given in the Document for previous versions it was based on.
- These may be placed in the "History" section.
- You may omit a network location for a work that was published at least
- four years before the Document itself, or if the original publisher of
- the version it refers to gives permission.
-\layout Itemize
-
-K.
- In any section entitled "Acknowledgements" or "Dedications", preserve the
- section's title, and preserve in the section all the substance and tone
- of each of the contributor acknowledgements and/or dedications given therein.
-\layout Itemize
-
-L.
- Preserve all the Invariant Sections of the Document, unaltered in their
- text and in their titles.
- Section numbers or the equivalent are not considered part of the section
- titles.
-\layout Itemize
-
-M.
- Delete any section entitled "Endorsements".
- Such a section may not be included in the Modified Version.
-\layout Itemize
-
-N.
- Do not retitle any existing section as "Endorsements" or to conflict in
- title with any Invariant Section.
-\layout Standard
-
-If the Modified Version includes new front-matter sections or appendices
- that qualify as Secondary Sections and contain no material copied from
- the Document, you may at your option designate some or all of these sections
- as invariant.
- To do this, add their titles to the list of Invariant Sections in the Modified
- Version's license notice.
- These titles must be distinct from any other section titles.
-\layout Standard
-
-You may add a section entitled "Endorsements", provided it contains nothing
- but endorsements of your Modified Version by various parties--for example,
- statements of peer review or that the text has been approved by an organization
- as the authoritative definition of a standard.
-\layout Standard
-
-You may add a passage of up to five words as a Front-Cover Text, and a passage
- of up to 25 words as a Back-Cover Text, to the end of the list of Cover
- Texts in the Modified Version.
- Only one passage of Front-Cover Text and one of Back-Cover Text may be
- added by (or through arrangements made by) any one entity.
- If the Document already includes a cover text for the same cover, previously
- added by you or by arrangement made by the same entity you are acting on
- behalf of, you may not add another; but you may replace the old one, on
- explicit permission from the previous publisher that added the old one.
-\layout Standard
-
-The author(s) and publisher(s) of the Document do not by this License give
- permission to use their names for publicity for or to assert or imply endorseme
-nt of any Modified Version.
-\layout Subsection*
-
-5.
- COMBINING DOCUMENTS
-\layout Standard
-
-You may combine the Document with other documents released under this License,
- under the terms defined in section 4 above for modified versions, provided
- that you include in the combination all of the Invariant Sections of all
- of the original documents, unmodified, and list them all as Invariant Sections
- of your combined work in its license notice.
-\layout Standard
-
-The combined work need only contain one copy of this License, and multiple
- identical Invariant Sections may be replaced with a single copy.
- If there are multiple Invariant Sections with the same name but different
- contents, make the title of each such section unique by adding at the end
- of it, in parentheses, the name of the original author or publisher of
- that section if known, or else a unique number.
- Make the same adjustment to the section titles in the list of Invariant
- Sections in the license notice of the combined work.
-\layout Standard
-
-In the combination, you must combine any sections entitled "History" in
- the various original documents, forming one section entitled "History";
- likewise combine any sections entitled "Acknowledgements", and any sections
- entitled "Dedications".
- You must delete all sections entitled "Endorsements."
-\layout Subsection*
-
-6.
- COLLECTIONS OF DOCUMENTS
-\layout Standard
-
-You may make a collection consisting of the Document and other documents
- released under this License, and replace the individual copies of this
- License in the various documents with a single copy that is included in
- the collection, provided that you follow the rules of this License for
- verbatim copying of each of the documents in all other respects.
-\layout Standard
-
-You may extract a single document from such a collection, and distribute
- it individually under this License, provided you insert a copy of this
- License into the extracted document, and follow this License in all other
- respects regarding verbatim copying of that document.
-\layout Subsection*
-
-7.
- AGGREGATION WITH INDEPENDENT WORKS
-\layout Standard
-
-A compilation of the Document or its derivatives with other separate and
- independent documents or works, in or on a volume of a storage or distribution
- medium, does not as a whole count as a Modified Version of the Document,
- provided no compilation copyright is claimed for the compilation.
- Such a compilation is called an "aggregate", and this License does not
- apply to the other self-contained works thus compiled with the Document,
- on account of their being thus compiled, if they are not themselves derivative
- works of the Document.
-\layout Standard
-
-If the Cover Text requirement of section 3 is applicable to these copies
- of the Document, then if the Document is less than one quarter of the entire
- aggregate, the Document's Cover Texts may be placed on covers that surround
- only the Document within the aggregate.
- Otherwise they must appear on covers around the whole aggregate.
-\layout Subsection*
-
-8.
- TRANSLATION
-\layout Standard
-
-Translation is considered a kind of modification, so you may distribute
- translations of the Document under the terms of section 4.
- Replacing Invariant Sections with translations requires special permission
- from their copyright holders, but you may include translations of some
- or all Invariant Sections in addition to the original versions of these
- Invariant Sections.
- You may include a translation of this License provided that you also include
- the original English version of this License.
- In case of a disagreement between the translation and the original English
- version of this License, the original English version will prevail.
-\layout Subsection*
-
-9.
- TERMINATION
-\layout Standard
-
-You may not copy, modify, sublicense, or distribute the Document except
- as expressly provided for under this License.
- Any other attempt to copy, modify, sublicense or distribute the Document
- is void, and will automatically terminate your rights under this License.
- However, parties who have received copies, or rights, from you under this
- License will not have their licenses terminated so long as such parties
- remain in full compliance.
-\layout Subsection*
-
-10.
- FUTURE REVISIONS OF THIS LICENSE
-\layout Standard
-
-The Free Software Foundation may publish new, revised versions of the GNU
- Free Documentation License from time to time.
- Such new versions will be similar in spirit to the present version, but
- may differ in detail to address new problems or concerns.
- See http://www.gnu.org/copyleft/.
-\layout Standard
-
-Each version of the License is given a distinguishing version number.
- If the Document specifies that a particular numbered version of this License
- "or any later version" applies to it, you have the option of following
- the terms and conditions either of that specified version or of any later
- version that has been published (not as a draft) by the Free Software Foundatio
-n.
- If the Document does not specify a version number of this License, you
- may choose any version ever published (not as a draft) by the Free Software
- Foundation.
-\the_end