Beginning of un updated developer documentation and beginning of playlist documentation

doc/developer2/Makefile

+XSLTPROC=xsltproc
+DOC := vlc-dev-doc
+
+XML_DECL1 = /usr/lib/sgml/declaration/xml.decl
+XML_DECL2 = /usr/share/sgml/declaration/xml.decl
+XML_DECL = `test -f $(XML_DECL1) && echo $(XML_DECL1) || echo $(XML_DECL2)`
+
+XSL= videolan-doc.xsl
+
+all: en/$(DOC).html
+
+init:
+	mkdir -p en
+	cp screen.css en
+
+en/$(DOC).html : init
+	xsltproc $(XSL)	$(DOC).xml > en/$(DOC).html
+	mv *.html en
+
+clean:
+	rm -rf en

doc/developer2/build.xml

+<chapter><title>The build system</title>
+
+<sect1><title>Modules.am files</title>
+</sect1>
+
+<sect1><title>Bootstrap sequence</title>
+</sect1>
+
+<sect1><title>vlc-config</title>
+</sect1>
+
+<sect1><title>The toolbox</title>
+</sect1>
+
+</chapter>

doc/developer2/coding.xml

+<chapter><title>Coding rules</title>
+
+<sect1><title>Naming conventions</title>
+
+<sect2><title>Functions</title>
+
+      <para>
+All functions are named accordingly : module name (in lower case) + _ +
+function name (in mixed case, <emphasis> without underscores</emphasis>).
+For instance : <function>intf_FooFunction</function>. Static functions
+don't need usage of the module name.
+      </para>
+
+</sect2>
+
+<sect2><title>Variables</title>
+
+      <para>
+Hungarian notations are used, that means we have the following prefixes :
+      </para>
+
+      <itemizedlist>
+        <listitem> <para> i_ for integers (sometimes l_ for long integers) ;
+        </para> </listitem>
+        <listitem> <para> b_ for booleans ; </para> </listitem>
+        <listitem> <para> d_ for doubles (sometimes f_ for floats) ;
+        </para> </listitem>
+        <listitem> <para> pf_ for function pointers ; </para> </listitem>
+        <listitem> <para> psz_ for a Pointer to a String terminated by a
+        Zero (C-string) ;
+        </para> </listitem>
+        <listitem> <para> More generally, we add a p when the variable is
+        a pointer to a type. </para> </listitem>
+      </itemizedlist>
+    
+      <para>
+If one variable has no basic type (for instance a complex structure), don't
+put any prefix (except p_* if it's a pointer). After one prefix, put
+an <emphasis> explicit </emphasis> variable name <emphasis> in lower
+case</emphasis>. If several words are required, join them with an
+underscore (no mixed case). Examples :
+      </para>
+
+      <itemizedlist>
+        <listitem> <para>
+        <type> data_packet_t * </type> <varname> p_buffer; </varname>
+        </para> </listitem> <listitem> <para>
+        <type> char </type> <varname> psz_msg_date[42]; </varname>
+        </para> </listitem> <listitem> <para>
+        <type> int </type> <varname> pi_es_refcount[MAX_ES]; </varname>
+        </para> </listitem> <listitem> <para>
+        <type> void </type> <varname> (* pf_next_data_packet)( int * ); </varname>
+        </para> </listitem>
+      </itemizedlist>
+
+    </sect2>
+
+
+
+</sect1>
+
+<sect1><title>Code indentation</title>
+
+<para>Code is indented with 4 spaces. Never use tabs in the source
+code. If you are using Vim as your editor, you can use <command>set
+expandtab</command>.</para>
+
+<para>Please put spaces <emphasis> before and after </emphasis> operators, and
+inside brackets. For instance :
+<programlisting> for( i = 0; i &lt; 12; i++, j += 42 ); </programlisting>
+      </para>
+
+      <para>
+Third, leave braces alone on their lines (GNU style). For instance :
+        <programlisting>
+if( i_es == 42 )
+{
+   p_buffer[0] = 0x12;
+}
+        </programlisting>
+      </para>
+
+      <para>
+We write C, so use C-style comments /* ... */.
+      </para>
+
+</sect1>
+
+</chapter>

doc/developer2/cpumisc.xml

+<chapter><title>CPU and misc stuff</title>
+
+<sect1><title>CPU detection</title>
+</sect1>
+
+<sect1><title>Misc general stuff</title>
+
+<sect2><title>VLC_EXPORT</title>
+
+</sect2>
+
+</sect1>
+
+</chapter>

doc/developer2/debugging.xml

+<chapter><title>Debugging VLC</title>
+
+  <para>
+We never debug our code, because we don't put bugs in. Okay, you want
+some real stuff. Sam still uses <function> printf() </function> to
+find out where it crashes. For real programmers, here is a summary
+of what you can do if you have problems.
+  </para>
+
+  <sect1> <title> Where does it crash ? </title>
+
+    <para>
+The best way to know that is to use gdb. You can start using it with
+good chances by configuring with <parameter> --enable-debug </parameter>.
+It will add <parameter> -g </parameter> to the compiler <parameter>
+CFLAGS</parameter>, and activate some additional safety checks. Just
+run <command> gdb vlc</command>, type <command> run myfile.vob</command>,
+and wait until it crashes. You can view where it stopped with
+<command>bt</command>, and print variables with <command>print
+&lt;C-style&gt;</command>.
+    </para>
+
+    <para>
+If you run into troubles, you may want to turn the optimizations off.
+Optimizations (especially inline functions) may confuse the debugger.
+Use <parameter> --disable-optimizations </parameter> in that case.
+    </para>
+
+  </sect1>
+
+  <sect1> <title> Other problems </title>
+
+    <para>
+It may be more complicated than that, for instance unpredictable
+behaviour, random bug or performance issue. You have several options
+to deal with this. If you experience unpredictable behaviour, I hope
+you don't have a heap or stack corruption (eg. writing in an unallocated
+space), because they are hard to find. If you are really desperate, have
+a look at something like ElectricFence or dmalloc. Under GNU/Linux, an
+easy check is to type <command> export MALLOC_CHECK_=2 </command> before
+launching vlc (see <command> malloc(3) </command> for more information).
+    </para>
+
+    <para>
+VLC offers a "trace-mode". It can create a log file with very accurate dates
+and messages of what it does, so it is useful to detect performance
+issues or lock-ups. Compile with <parameter> --enable-trace </parameter>
+and tune the <parameter> TRACE_* </parameter> flags in <filename>
+include/config.h </filename> to enable certain types of messages (log
+file writing can take up a lot of time, and will have side effects).
+    </para>
+
+  </sect1>
+
+</chapter>

doc/developer2/glossary.xml

+    <glossary>
+
+      <warning> <para>
+        Please note that this book is in no way a reference documentation
+        on how DVDs work. Its only purpose is to describe the API
+        available for programmers in VLC media player. It is assumed that
+        you have basic knowledge of what MPEG is. The following paragraph
+        is just here as a reminder :
+      </para> </warning>
+
+      <glossentry>
+        <glossterm> <acronym> AC3 </acronym> :
+        Digital Audio Compression Standard </glossterm>
+        <glossdef> <para> Specification for coding audio data, used in DVD.
+        The documentation is
+        <ulink url="http://www.linuxvideo.org/devel/library/ac3-standard_a_52.pdf">
+        freely available </ulink>.
+        </para> </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm> <acronym> B </acronym> (bi-directional) picture </glossterm>
+        <glossdef> <para> Picture decoded from its own data, <emphasis>
+        and </emphasis> from the data of the previous and next (that
+        means <emphasis>in the future</emphasis>) reference
+        pictures (I or P pictures). It is the most compressed picture
+        format, but it is less fault-tolerant.
+        </para> </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm> <acronym> DVD </acronym> :
+        Digital Versatile Disc </glossterm>
+        <glossdef> <para> Disc hardware format, using the UDF file system,
+        an extension of the ISO 9660 file system format and a video format
+        which is an extension of the MPEG-2 specification.
+        It basically uses MPEG-2 PS files, with subtitles and sound
+        tracks encoded as private data and fed into non-MPEG decoders, 
+        along with .ifo files describing the contents of the DVD. DVD
+        specifications are very hard to get, and it takes some
+        time to reverse-engineer it. Sometimes DVD are zoned and
+        scrambled, so we use a brute-force algorithm to find the key.
+        </para> </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm> <acronym> ES </acronym> : Elementary Stream </glossterm>
+        <glossdef> <para> Continuous stream of data fed into a decoder,
+        without any multiplexing layer. ES streams can be MPEG video
+        MPEG audio, AC3 audio, LPCM audio, SPU subpictures...
+        </para> </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm> Field picture </glossterm>
+        <glossdef> <para> Picture split in two fields, even and odd, like
+        television does. DVDs coming from TV shows typically use field
+        pictures.
+        </para> </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm> Frame picture </glossterm>
+        <glossdef> <para> Picture without even/odd discontinuities, unlike
+        field pictures. DVDs coming from movies typically use frame
+        pictures.
+        </para> </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm> <acronym>I</acronym> (intra) picture </glossterm>
+        <glossdef> <para> Picture independantly coded. It can be
+        decoded without any other reference frame. It is regularly
+        sent (like twice a second) for resynchronization purposes.
+        </para> </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm> <acronym> IDCT </acronym> : Inverse Discrete
+        Cosinus Transform </glossterm>
+        <glossdef> <para> IDCT is a classical mathematical algorithm
+        to convert from a space domain to a frequency domain. In a
+        nutshell, it codes differences instead of coding all absolute
+        pixels. MPEG uses an 2-D IDCT in the video decoder, and a 1-D
+        IDCT in the audio decoder.
+        </para> </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm> <acronym> LPCM </acronym> :
+        Linear Pulse Code Modulation </glossterm>
+        <glossdef> <para> LPCM is a non-compressed audio encoding,
+        available in DVDs.
+        </para> </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm> <acronym> MPEG </acronym> :
+        Motion Picture Expert Group </glossterm>
+        <glossdef> <para> Specification describing a standard syntax of files
+        and streams for carrying motion pictures and sound. MPEG-1 is
+        ISO/IEC 11172 (three books), MPEG-2 is ISO/IEC 13818. MPEG-4
+        version 1 is out, but this player doesn't support it. It is
+        relatively easy to get an MPEG specification from ISO or
+        equivalent, drafts are even freely available on the Internet.
+        </para> </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm> <acronym> P </acronym> (predictive) picture </glossterm>
+        <glossdef> <para> Picture decoded from its own data <emphasis>
+        and </emphasis> data from a reference picture, which is the
+        last I or P picture received.
+        </para> </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm> <acronym> PES </acronym> :
+        Packetized Elementary Stream </glossterm>
+        <glossdef> <para> A chunk of elementary stream. It often corresponds
+        to a logical boundary of the stream (for instance a picture
+        change), but it is not mandatory. PES carry the synchronization
+        information.
+        </para> </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm> <acronym> PTS </acronym> :
+        Presentation Time Stamp </glossterm>
+        <glossdef> <para> Time at which the content of a PES packet is supposed
+        to be played. It is used for A/V synchronization.
+        </para> </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm> <acronym> PS </acronym> : Program Stream </glossterm>
+        <glossdef> <para> File format obtained by concatenating PES packets
+        and inserting Pack headers and System headers (for timing
+        information). It is the only format described in MPEG-1, and
+        the most used format in MPEG-2.
+        </para></glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm> <acronym> RGB </acronym> : Red Green Blue </glossterm>
+        <glossdef> <para> Picture format where every pixel is calculated in a
+        vector space whose coordinates are red, green, and blue. This
+        is natively used by monitors and TV sets.
+        </para> </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm> <acronym> SPU </acronym> : Sub Picture Unit </glossterm>
+        <glossdef> <para> Picture format allowing to do overlays, such
+        as subtitles or DVD menus.
+        </para> </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm> <acronym> SCR </acronym> :
+        System Clock Reference </glossterm>
+        <glossdef> <para> Time at which the first byte of a particular pack
+        is supposed to be fed to the decoder. VLC uses it to read the
+        stream at the right pace.
+        </para> </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm> <acronym> SDL </acronym> :
+        Simple DirectMedia Layer </glossterm>
+        <glossdef> <para> <ulink url="http://www.libsdl.org/"> SDL </ulink>
+        is a cross-platform multimedia library
+        designed to provide fast access to the video framebuffer and
+        the audio device. Since version 1.1, it features YUV overlay
+        support, which reduces decoding times by a third.
+        </para> </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm> <acronym> TS </acronym> : Transport Stream </glossterm>
+        <glossdef> <para> Stream format constituted of fixed size packets
+        (188 bytes), defined by ISO/IEC 13818-1. PES packets are
+        split among several TS packets.
+        A TS stream can contain several programs. It is used in
+        streaming applications, in particular for satellite or cable
+        broadcasting.
+        </para> </glossdef>
+      </glossentry>
+
+      <glossentry>
+        <glossterm> <acronym> YUV </acronym> :
+        Luminance/Chrominance </glossterm>
+        <glossdef> <para> Picture format with 1 coordinate of luminance (black
+        and white) and 2 coordinates of chrominance (red and blue).
+        This is natively used by PAL video system, for backward
+        compatibility with older black and white TV sets. Your eyes
+        distinguish luminance variations much better than chrominance
+        variations, so you can compress them more. It is therefore
+        well suited for image compression, and is used by the MPEG
+        specification. The RGB picture can be obtained from the YUV one
+        via a costly matrix multiply operation, which can be done in
+        hardware by most modern video cards ("YUV acceleration").
+        </para> </glossdef>
+      </glossentry>
+    </glossary>

doc/developer2/history.xml

+<?xml version="1.0" encoding="iso-8859-15" ?>
+<appendix> <title> Project history </title>
+
+  <sect1> <title> VIA and the Network2000 project </title>
+
+    <para>
+The whole project started back in 1995. At that time, students of the
+<ulink url="http://www.ecp.fr/"> &Eacute;cole Centrale de Paris </ulink>
+enjoyed a TokenRing network, managed by the <ulink
+url="http://www.via.ecp.fr/"> VIA Centrale R&eacute;seaux
+association</ulink>, and were looking
+for a solution to upgrade to a modern network. So the idea behind
+Network2000 was to find a project students would realize that would
+be interesting, would require a high-quality network, and could
+provide enough fame so that sponsors would be interested.
+    </para>
+
+    <para>
+Someone came up with the idea of doing television broadcast on the
+network, so that students could watch TV in their room. This was
+interesting, mixed a lot of cool technologies, and provided fame
+because no one had written a free MPEG-2 decoder so far.
+    </para>
+
+  </sect1>
+
+  <sect1> <title> Foundation of the VideoLAN project </title>
+
+    <para>
+<ulink url="http://www.3com.com/"> 3Com</ulink>,
+<ulink url="http://www.bouygues.com/"> Bouygues </ulink> and
+la Soci&eacute;t&eacute; des Amis were
+interested and financed the project, which was then known after
+the name of VideoLAN.
+    </para>
+
+    <para>
+The VideoLAN team, in particular <ulink url="mailto:walken@via.ecp.fr">
+Michel Lespinasse </ulink> (current maintainer of <ulink
+url="http://www.linuxvideo.org/">LiViD</ulink>'s mpeg2dec)
+and <ulink url="mailto:hpreg@via.ecp.fr"> R&eacute;gis
+Duchesne</ulink>, started writing code in 1996. By the end of 1997 they had
+a working client-server solution, but it would crash a lot and was
+hard to extend.
+    </para>
+
+    <para>
+At that time it was still closed-source and only-for-demo code.
+    </para>
+
+  </sect1>
+
+  <sect1> <title> VLC media player design </title>
+
+    <para>
+In 1998, <ulink url="mailto:seguin@via.ecp.fr"> Vincent Seguin</ulink>
+(structure, interface and video output),
+<ulink url="mailto:massiot@via.ecp.fr"> Christophe Massiot</ulink>
+(input and video decoder),
+<ulink url="mailto:maxx@via.ecp.fr"> Michel Kaempf</ulink>
+(audio decoder and audio output) and
+<ulink url="mailto:polux@via.ecp.fr"> Jean-Marc Dressler</ulink>
+(synchronization) decided to write a brand new player from scratch,
+called VideoLAN Client (VLC), so that it could be easily open sourced.
+Of course we based it on code written by our predecessors, but in
+an advanced structure, described in the first chapter (it hasn't been
+necessary to change it a lot).
+    </para>
+
+    <para>
+At the same time, <ulink url="mailto:benny@via.ecp.fr"> Beno&icirc;t
+Steiner </ulink> started the writing of an advanced stream server, called
+VideoLAN Server (VLS).
+    </para>
+
+    <para>
+Functional test seeds have been released internally in June 1999
+(vlc-DR1) and November 1999 (vlc-DR2), and we started large scale tests
+and presentations. The French audience discovered us at Linux Expo
+in June 1999, presenting our 20 minutes of Golden Eye (which is now
+a legend among developers :-).  At that time only a network input was
+possible, file input was added later, but it remained kludgy for a while.
+    </para>
+
+    <para>
+In early 2000, we (especially <ulink url="mailto:sam@via.ecp.fr"> Samuel
+Hocevar</ulink>, who is still a major contributor) started working
+on DVDs (PS files, AC3, SPU). In the summer 2000, pre-release builds
+have been seeded (0.2.0 versions), but they still lacked essential
+features.
+    </para>
+
+    <para>
+In late 2000, <ulink url="mailto:massiot@via.ecp.fr"> Christophe Massiot
+</ulink> with the support of his company,
+<ulink url="http://www.idealx.com/"> IDEALX</ulink>, rewrote major
+parts of the input to allow modularization and advanced navigation, and <ulink
+url="mailto:stef@via.ecp.fr"> Stéphane Borel </ulink> worked on a
+fully-featured DVD plug-in for VLC.
+    </para>
+
+  </sect1>
+
+  <sect1> <title> The Opening </title>
+
+    <para>
+For Linux Expo in February 2001, the <ulink url="http://www.gnu.org/">
+Free Software Foundation </ulink> and <ulink url="http://www.idealx.com/">
+IDEALX </ulink> wanted to make live streaming of the 2001 FSF awards
+from Paris to New York. VideoLAN was the chosen solution. Finally
+it couldn't be done live because of bandwidth considerations, but a
+<ulink url="http://www.via.ecp.fr/~massiot/encoding.html"> chain of 
+fully open-source solutions </ulink> made it possible to record it.
+    </para>
+
+    <para>
+At the same time, the president of the <ulink url="http://www.ecp.fr/">
+&Eacute;cole Centrale Paris</ulink> officially decided to place the software
+under GNU General Public Licence, thanks to <ulink
+url="mailto:henri@via.ecp.fr"> Henri Fallon</ulink>, <ulink
+url="mailto:jprey@ads.ecp.fr"> Jean-Philippe Rey</ulink>, and the IDEALX team.
+    </para>
+
+    <para>
+VideoLAN software is now one of the most popular open source DVD
+players available, and has contributors all around the world. The
+last chapter of this appendix is not written yet :-).
+    </para>
+
+  </sect1>
+
+</appendix>

doc/developer2/i18n.xml

+<chapter><title>Internationalization</title>
+
+</chapter>

doc/developer2/input.xml

+<chapter><title>Input</title>
+
+
+</chapter>

doc/developer2/interface.xml

+<chapter><title>Interface modules</title>
+
+</chapter>

doc/developer2/libvlc.xml

+<chapter><title>LibVLC</title>
+
+<sect1><title>LibVLC</title>
+</sect1>
+
+<sect1><title>VLC</title>
+</sect1>
+
+<sect1><title>The Mozilla plugin</title>
+</sect1>
+
+</chapter>

doc/developer2/messages.xml

+<chapter><title>Messages queue</title>
+
+</chapter>

doc/developer2/modulesobjects.xml

+<chapter><title>Modules and objects</title>
+
+<sect1><title>Modules</title>
+
+<sect2><title>What is a module ?</title>
+</sect2>
+
+<sect2><title>Modules declarators</title>
+</sect2>
+
+<sect2><title>Calling a module</title>
+</sect2>
+
+<sect2><title>The module bank</title>
+</sect2>
+
+</sect1>
+
+<sect1><title>Objects</title>
+
+<sect2><title>The vlc_object_t structure</title>
+</sect2>
+
+<sect2><title>Operations on objects</title>
+
+<sect3><title>Creating an object</title>
+</sect3>
+
+<sect3><title>Destroying an object</title>
+</sect3>
+
+<sect3><title>Finding an object</title>
+</sect3>
+
+</sect2>
+
+<sect2><title>Parents, children, refcount</title>
+</sect2>
+
+</sect1>
+
+</chapter>

doc/developer2/playlist.xml

+<chapter><title>Playlist core</title>
+
+<sect1><title>Concepts</title>
+
+<sect2><title>Overview</title>
+
+VLC's playlist now features a tree system, with a notion of several
+views. Each view comes with a new tree. Items can be shared between
+views. Items can become internal nodes.
+
+</sect2>
+
+<sect2><title>Views</title>
+
+The predefined views are :
+
+<itemizedlist>
+
+<listitem><para>The "simple" view which only contains the "manually
+added" items (either added through command line, either through command
+line). It can contain a hierarchy.</para></listitem>
+
+<listitem><para>The "category" view contains a "General" node that is
+exactly like the "simple" view. It can also contains several types of
+items (generally, "autodiscovered". Examples are:</para>
+
+<itemizedlist>
+
+<listitem><para>SAP items</para></listitem>
+<listitem><para>Audio CD if detected</para></listitem>
+<listitem><para>imported playlists</para></listitem>
+
+</itemizedlist>
+</listitem>
+
+<listitem><para>The "all items" flat view contains all items without any hierarchy</para></listitem>
+
+<listitem><para>Sorted views (Sorted by author, with a node per author, ...)</para></listitem>
+
+</itemizedlist>
+
+</sect2>
+
+<sect2><title>Who uses this ?</title>
+
+<sect3><title>Services discovery modules</title>
+
+A new type of modules has been created, the services_discovery modules.
+Their goal is to add items to the playlist (SAP listener, HAL (Hardware
+Abstraction Layer), ...).
+
+</sect3>
+
+</sect2>
+
+</sect1>
+
+<sect1><title>How does the playlist work</title>
+
+<sect2><title>Process overview</title>
+
+<para>On startup, a playlist thread is started. It starts an infinite
+loop, always searching for something to do.</para>
+
+<itemizedlist>
+
+<listitem><para>If a request is triggered by an action on the playlist,
+stop the current item and process the request</para></listitem>
+
+<listitem><para>If the current item has finished, stop it and go to next
+item</para></listitem>
+
+</itemizedlist>
+
+</sect2>
+
+<sect2><title>Data structures</title>
+
+<sect3><title>View</title>
+
+<para>Each view is identified by an identifier. It also contains a
+pointer to the root item.</para>
+
+</sect3>
+
+<sect3><title>Item</title>
+
+<para>An item can be either a leaf node (which can be played) or an
+internal node of the tree (can not be played directly, but contains
+children).</para>
+
+<para>You can know if an item is a leaf or internal node by looking
+at i_children. If i_children is -1, then it is a leaf node, else it
+contains the number of children, available in pp_children.</para>
+
+
+<para>As items can be common to several views, we need to remember
+for each the parent in each view. That's why each item includes the
+pp_parents array. Each one is an <code>item_parent_t</code> structure
+that contains the view identifier, and the parent _in this view_.</para>
+
+<para>The <code>i_flags</code> is a bit array used to know whether an
+item is to be saved, whether the playlist can continue after playing
+this item (which is generally not the desired behaviour for SAP items,
+fe), whether it is enabled, and whether it must be deleted after being
+played.</para>
+
+<para>The <code>i_serial</code> field is increased on each change of
+the children, if the item is an internal node. The goal is to allow
+interfaces to update in a clever way, by only rebuilding nodes that have
+changed.</para>
+
+</sect3>
+
+</sect2>
+
+<sect2><title>Controlling the playlist</title>
+
+<para>The playlist can be controlled using playlist_Control. It takes a
+query identifier, and a variable number of arguments.</para>
+
+<para>When a control is made, the "request" field of the playlist is set
+to true, which causes the current item to be stopped. If needed, a new
+item is then selected.</para>
+
+</sect2>
+
+<sect2><title>Selecting an item</title>
+
+<para>Different rules apply for selection of items, if a request
+has been made or if it is an "automatic" change, after an item has
+finished.</para>
+
+<para>If there a request, the item is always selected if possible (if
+you selected a node, it will play the first available child), else, some
+more rules will apply (play-and-stop, random, repeat, ...).</para>
+
+<para>All item selection is made in
+<code>src/playlist/playlist.c</code>, function NextItem.</para>
+
+<para>The playlist object contains two fields dedicated to this, status
+and request.</para>
+
+<para>This process uses tree walking functions in
+<code>src/playlist/view.c</code>.</para>
+
+</sect2>
+
+</sect1>
+
+</chapter>

doc/developer2/porting.xml

+<chapter><title>Porting VLC</title>
+
+  <sect1> <title> Port steps </title>
+
+    <para>
+Basically, porting to a new architecture boils down to follow the
+following steps :
+    </para>
+
+    <orderedlist>
+
+      <listitem> <para> <emphasis> Building the VLC : </emphasis>
+      That may be the most difficult part, depending on how POSIX
+      the architecture is. You have to produce valid C.
+      </para> </listitem>
+
+      <listitem> <para> <emphasis> Having video : </emphasis>
+      If your architecture features an X server, it should be
+      straightforward, though you might have problems with xvideo
+      or xshm. Otherwise you can try to use SDL if it is supported,
+      or end up writing your own video output plugin.
+      </para> </listitem>
+
+      <listitem> <para> <emphasis> Having audio : </emphasis>
+      If your architecture features an OSS compatible DSP or ALSA, you
+      can reuse an existing plugin. Otherwise you will have to write
+      your own audio output plugin.
+      </para> </listitem>
+
+      <listitem> <para> <emphasis> Accessing DVDs : </emphasis>
+      You are going to need a write access to the DVD device.
+      Every system has specific ioctl() for key negociation with
+      the DVD drive, so we have set up an abstration layer in
+      <filename> plugins/dvd/dvd_ioctl.c</filename>. You might
+      need to add stuff here. Some operating systems won't give
+      you access to the key negociation (MacOS X), so you will
+      have to write a kernel extension or you will only be able to read
+      unencrypted DVDs. Other operating systems might only give
+      you read access to the DVD device if you are root. Your mileage
+      may vary.
+      </para> </listitem>
+
+      <listitem> <para> <emphasis> Writing a native interface : </emphasis>
+      If your system doesn't support GTK or Qt, you will have to
+      write a native interface plugin (for instance Aqua or Win32).
+      You may also need to rewrite the video output plugin if
+      you're currently using a slow compatibility layer.
+      </para> </listitem>
+
+      <listitem> <para> <emphasis> Optimizing : </emphasis>
+      If your architecture features a special set of multimedia
+      instructions (such as MMX) that is not supported by VLC, you
+      may want to write specific optimizations. Heavy calculation
+      parts are : IDCT (see idct plugin), motion compensation
+      (see motion plugin), and YUV (see video output) if you don't
+      use the YUV overlay support of your video board (SDL or
+      XVideo extension).
+      </para> </listitem>
+
+    </orderedlist>
+
+  </sect1>
+
+  <sect1> <title> Building </title>
+
+    <para>
+This is probably the most complicated part. If your platform is fully
+POSIX-compliant (such as GNU/Linux), it should be quick, otherwise
+expect troubles. Known issues are :
+    </para>
+
+    <itemizedlist>
+
+      <listitem> <para> Finding a compiler : We use <application> gcc
+      </application> on all platforms, and <application> mingw32
+      </application> to cross-compile the win32 port. If you don't you're
+      probably in <emphasis> very big </emphasis> trouble. Good luck.
+      </para> </listitem>
+
+      <listitem> <para> Finding <application> GNU make </application> : Our
+      <filename>Makefile</filename> is heavily <application>GNU make
+      </application> specific, so I suggest you install it.
+      </para> </listitem>
+
+      <listitem> <para> Running the <filename> configure </filename>
+      script : This is basically a shell script, so if you have a UNIX
+      shell on your platform it shouldn't be a problem. It will probe
+      your system for headers and libraries needed. It needs
+      adequate <filename> config.sub </filename> and <filename>
+      config.guess</filename>, so if your platform is young your
+      provider may have supplied customized versions. Check with it.
+      </para> </listitem>
+
+      <listitem> <para> Compiling the VLC binary : This is the most
+      difficult. Type <command> make </command> or <command> gmake
+      </command> and watch the results. It will probably break soon
+      on a parse error. Add the headers missing, fix mistakes. If
+      you cannot make it to also compiles on other platforms, use
+      #ifdef directives. Add tests for functions or libraries in
+      <filename> configure.in </filename> and run <command> autoheader
+      </command> and <command> autoconf</command>. Always prefer
+      tests on <property> #ifdef HAVE_MY_HEADER_T</property>,
+      instead of <property> #ifdef SYS_MYOPERATINGSYSTEM</property>.
+      You may especially experience problems with the network code
+      in <filename> src/input/input.c</filename>.
+      </para> </listitem>
+
+      <listitem> <para> Threads : If your system has an exotic thread
+      implementation, you will probably need to fill the wrappers in
+      <filename> include/threads.h </filename> for your system.
+      Currently supported implementations include the POSIX pthreads,
+      the BeOS threads, and the Mach cthreads.
+      </para> </listitem>
+
+      <listitem> <para> Linking : You will need special flags to the
+      compiler, to allow symbol exports (otherwise plug-ins won't
+      work). For instance under GNU/Linux you need <parameter>
+      -rdynamic</parameter>.
+      </para> </listitem>
+
+      <listitem> <para> Compiling plug-ins : You do not need external
+      plug-ins at first, you can build all you need in (see <filename>
+      Makefile.opts</filename>). In the long run though, it is a
+      good idea to change <parameter> PCFLAGS</parameter> and <parameter>
+      PLCFLAGS</parameter> to allow run-time loading of libraries.
+      You are going to need <application> libdl</application>, or a
+      similar dynamic loader. To add support for an exotic dynamic
+      loader, have a look at <filename> include/modules_core.h
+      </filename>. Currently supported implementations include the
+      UNIX dynamic loader and the BeOS image loader.
+      </para> </listitem>
+
+      <listitem> <para> Assembling : If you use specific optimizations
+      (such as MMX), you may have problem assembling files, because
+      the assembler syntax may be different on your platform. Try
+      without it at first. Pay attention to the optimization flags
+      too, you may see a <emphasis>huge</emphasis> difference.
+      </para> </listitem>
+
+    </itemizedlist>
+
+    <para>
+VLC should work both on little endian and big endian systems. All
+load operations should be aligned on the native size of the type, so
+that it works on exotic processors like Sparc or Alpha. It should
+work on 64-bit platforms, though it has not been optimized for it.
+A big boost for them would be to have a WORD_TYPE = u64 in <filename>
+include/input_ext-dec.h</filename>, but it is currently broken for
+unknown reasons.
+    </para>
+
+    <para>
+If you experience run-time problems, see the following appendix and
+pray for you to have <command> gdb</command>...
+    </para>
+
+  </sect1>
+
+
+</chapter>

doc/developer2/screen.css

+/*
+ * screen.css
+ */
+
+a:link          {color: blue; 
+                 text-decoration: underline}
+
+a:active        {color: red;
+                 text-decoration: underline}
+
+a:visited       {color: #0005cf;
+                 text-decoration: underline}
+
+a:hover         {color: red; 
+                 text-decoration: underline}
+
+body            {font-family: "Times New Roman", Georgia, Times; 
+                 font-size: 1em; 
+                 color: #000000; 
+                 background-color: #FFFFFF; 
+                 margin: 1em 1em 1em 1em;}
+
+h1               {font-size: 2.4em;
+                 font-family: Verdana, Arial, Helvetica, Sans-Serif;
+                 margin-top: 0em;
+                 margin-bottom: 0.5em;
+                 margin-left: 0.5in;
+                 margin-right: 0.5in;}
+
+h1.div           {font-size: 1.5em;
+                 font-family: Verdana, Arial, Helvetica, Sans-Serif;
+                 margin-top: 0em;
+                 margin-bottom: 0.5em;
+                 margin-left: 0.5in;
+                 margin-right: 0.5in;}
+
+
+h2
+{
+    font-family: Verdana, Arial, Helvetica, Sans-Serif;
+    margin: 0.7em 0 0.7em 0;
+    padding: 0.5em 0.7em 0.5em 0.7em;
+    font-size: 1.9em;
+    text-decoration: none;
+    border-bottom: solid #00A 2px;
+}
+
+/*
+ * Ici on distingue les chapitres des sections
+ */
+
+div.sect1 h2
+{
+    font-family: Verdana, Arial, Helvetica, Sans-Serif;
+    font-size: 1.3em;
+    text-decoration: none;
+    border-bottom: solid #00A 2px;
+    padding: 0 0 0 0.7em;
+}
+
+
+
+div.sect2 h3
+{
+    font-family: Verdana, Arial, Helvetica, Sans-Serif;
+    font-size: 1.2em;
+    text-decoration: none;
+    border-bottom: solid #00A 1px;
+    padding: 0 0 0 0.7em;
+}
+
+div.note h3
+{
+    font-family: Verdana, Arial, Helvetica, Sans-Serif;
+    font-size: 1.2em;
+    text-decoration: none;
+    border-bottom: none;
+    padding: 0 0 0 0.7em;
+}
+
+h3
+{
+    font-family: Verdana, Arial, Helvetica, Sans-Serif;
+    font-size: 1.2em;
+    text-decoration: none;
+    border-bottom: none;
+    padding: 0 0 0 0.7em;
+}
+
+h4
+{
+    font-family: Verdana, Arial, Helvetica, Sans-Serif;
+    font-size: 1.1em;
+    text-decoration: none ;
+    padding: 0 0 0 0.7em;
+}
+
+h5
+{
+    font-family: Verdana, Arial, Helvetica, Sans-Serif;
+    font-size: 1em;
+    text-decoration: none  ;
+    padding: 0 0 0 0.7em;
+}
+
+
+p               {font-size: 1em; 
+                 margin: 0em 0em 0.5em 0em;}
+
+p.validator     { text-align: right; }
+
+tt              {font-family: "Courier New";
+                 font-size: 0.95em;}
+/*                 font-weight: bold;}
+*/
+
+hr		{height: 1px;}
+
+.titre          {font-size: 3em;
+                 text-align: center;}
+.navheader      {}
+
+/* .navfooter      {} */
+
+.revhistory table { border: none; padding: 0px 0px 0px 0px; margin: 1em 0em 1em 0em;}
+
+.revhistory th { border: none; padding: 0px 0px 0px 0px	;}
+
+.revhistory td { border: none; padding: 0px 0px 0px 0px	;}
+
+.highlights { font-style: italic;}
+
+.note { border: 1px solid #CCCC99; 
+        background-color: #F5F5E7; 
+        padding: 0.5em 0.5em 0.5em 0.5em; 
+        margin: 1em 0em 1em 0em; }
+
+.caution { border: 1px solid #F6EA00; 
+           background-color: #FFFFC9; 
+           padding: 0.5em 0.5em 0.5em 0.5em;  
+             margin-top: 1em;
+             margin-bottom: 1em;
+             margin-left: 0.5in;
+             margin-right: 0.5in;}
+
+.tipp { background-color: #F5F5DC }
+
+.important { font-family: "Courier New";
+             font-size: 0.8em;
+             border: 1px solid #F95E00; 
+             background-color: #F9CDB3;
+             padding: 0.5em 0.5em 0.5em 0.5em;
+             margin-top: 1em;
+             margin-bottom: 1em;
+             margin-left: 0.5in;
+             margin-right: 0.5in;}
+
+
+.screen { font-family: "Courier New"; 
+          font-size: 0.8em; 
+          border: 1px solid #999999; 
+          background-color: #EBEBEB; 
+          padding: 0.5em 0.5em 0.5em 0.5em; 
+          margin: 2em 0em 2em 0em;}
+
+.programlisting { font-family: "Courier New";
+                  font-size: 0.8em; 
+                  border: 1px solid #B2DBFF; 
+                  background-color: #F0F8FF; 
+                  padding: 0.5em 0.5em 0.5em 0.5em; 
+                  margin: 2em 0em 2em 0em;}
+
+.funcsynopsis {
+                  border: 1px solid #B2DBFF; 
+                  background-color: #F0F8FF; 
+                  padding: 0.5em 0.5em 0.5em 0.5em; 
+                  margin: 2em 0em 2em 0em;}
+
+tt.prompt { color: #000080; }
+tt.function { font-weight: bold; }
+tt.userinput { font-weight: bold; }
+
+.important .programlisting { font-family: "Courier New"; font-size: 1em; border: 1px solid #B2DBFF; background-color: #F0F8FF; padding: 0.5em 0.5em 0.5em 0.5em; margin: 2em 0em 2em 0em;}
+
+.important .screen { font-family: "Courier New"; font-size: 1em; border: 1px solid #999999; background-color: #EBEBEB; padding: 0.5em 0.5em 0.5em 0.5em; margin: 2em 0em 2em 0em;}
+
+.informalexample { font-family: "Courier New"; font-size: 0.8em; border: 1px solid #B2DBFF; background-color: #F0F8FF; padding: 0.5em 0.5em 0.5em 0.5em; margin: 2em 0em 2em 0em;}
+
+p.validator     { text-align: right; }

doc/developer2/sout.xml

+<chapter><title>Stream output</title>
+
+</chapter>

doc/developer2/synopsys.txt

+Structure for the new vlc developer documentation
+
+* Coding rules
+	- Hungarian notation
+	- Code indentation
+
+* LibVLC, VLC, and Mozilla plugin
+	- Libvlc structure
+
+* Build system
+        - Modules.am
+	- bootstrap sequence
+	- vlc-config
+	- config.h
+	- toolbox
+
+* i18n
+	- Gettext
+
+* Modules
+	- Calling a module
+	- Writing a module descriptor (do not forget E_ & N_ ) 
+	- The module bank
+
+* Objects
+	- vlc_object_t
+	- Creating, deleting objects
+	- parents and children
+	- Refcounts
+
+* CPU stuff
+	
+* Misc stuff
+	- VLC_EXPORT
+	- MODULE_NAME_is
+	- more ?
+
+* Variables, callbacks, and configuration
+	- Variable management
+	- adding configuration to modules
+
+* Thread management
+        - thread 
+	- mutexes
+	- condition variables
+
+* Playlist management
+	- The playlist object
+	- Items / Options
+	- Playlist infos
+
+* Message queue
+
+* Interface modules
+
+* Input layer
+	- Access / stream 
+	- Demuxers / ES
+	- PCR / PTS / DTS
+	- Input, access and demux control
+
+* Packetizers
+
+* Decoders
+
+* Vout
+	- Subpictures
+	- Text rendering
+	- Filters
+
+* Aout
+	- Mixers
+	- Filters (converters, resamplers, downmixers)
+	- Output
+
+* Sout
+	- stream chain
+	- packetizer
+	- encoder
+	- muxer
+	- access output
+
+* Porting
+	- port specific stuff
+
+* Debugging
+	- Compile flags
+	- Valgrind / eFence / ...

doc/developer2/threads.xml

+<chapter><title>Threading with VLC</title>
+
+<para>VLC is a multi-thread application. We chose against a single-thread
+    approach because decoder preemptibility and scheduling would be a
+    mastermind (for instance decoders and outputs have to be separated,
+    otherwise it cannot be warrantied that a frame will be played at the
+    exact presentation time), and we currently have no plan to support a
+    single-threaded client. Multi-process decoders usually imply more overhead
+    (problems of shared memory) and communication between processes is harder.
+    </para>
+
+
+<sect1><title>VLC's threading API</title>
+
+<para>For portability, VLC provides a wrapper for native threading API.
+It is modelled on the pthread library.</para>
+
+<para>Our wrapper consists of the following functions:</para>
+
+<itemizedlist>
+<listitem><para><function>vlc_thread_create</function></para></listitem>
+<listitem><para>    <function>vlc_thread_exit</function></para></listitem>
+<listitem><para>    <function>vlc_thread_join</function></para></listitem>
+<listitem><para>    <function>vlc_mutex_init</function></para></listitem>
+<listitem><para> <function>vlc_mutex_lock</function></para></listitem>
+<listitem><para>    <function>vlc_mutex_unlock</function></para></listitem>
+<listitem><para>    <function>vlc_mutex_destroy</function></para></listitem>
+<listitem><para>    <function>vlc_cond_init</function></para></listitem>
+<listitem><para> <function>vlc_cond_signal</function></para></listitem>
+<listitem><para>    <function>vlc_cond_broadcast</function></para></listitem>
+<listitem><para>    <function>vlc_cond_wait</function></para></listitem>
+<listitem><para> <function>vlc_cond_destroy</function></para></listitem>
+</itemizedlist>
+
+<para>Corresponding data structures are <type>vlc_thread_t</type>,
+<type>vlc_mutex_t</type>, and <type>vlc_cond_t</type>. </para>
+
+</sect1>
+
+</chapter>

doc/developer2/variables.xml

+<chapter><title>Variables and configuration</title>
+
+<sect1><title>Variables management</title>
+</sect1>
+
+<sect1><title>Configuration</title>
+</sect1>
+
+</chapter>

doc/developer2/videolan-doc.xsl

+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0' xmlns="http://www.w3.org/TR/xhtml1/transitional" exclude-result-prefixes="#default">
+
+<xsl:import href="/usr/share/sgml/docbook/stylesheet/xsl/nwalsh/xhtml/chunk.xsl"/>
+
+<xsl:variable name="toc.section.depth">1</xsl:variable>
+<xsl:param name="chunker.output.encoding" select="'iso-8859-15'"/>
+<xsl:param name="chunk.section.depth" select="0"/>
+<xsl:param name="html.stylesheet" select="'screen.css'"/>
+
+
+</xsl:stylesheet>
+

doc/developer2/vlc-dev-doc.xml

+<?xml version="1.0" encoding="iso-8859-1"?>
+
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "/sw/share/xml/dtd/docbookx/4.1.2/docbookx.dtd"
+[
+    <!ENTITY coding SYSTEM "coding.xml">
+    <!ENTITY libvlc SYSTEM "libvlc.xml">
+    <!ENTITY build SYSTEM "build.xml">
+    <!ENTITY i18n SYSTEM "i18n.xml">
+    <!ENTITY modulesobjects SYSTEM "modulesobjects.xml">
+    <!ENTITY cpumisc SYSTEM "cpumisc.xml">
+    <!ENTITY variables SYSTEM "variables.xml">
+    <!ENTITY threads SYSTEM "threads.xml">
+    <!ENTITY messages SYSTEM "messages.xml">
+    <!ENTITY playlist SYSTEM "playlist.xml">
+    <!ENTITY interface SYSTEM "interface.xml">
+    <!ENTITY input SYSTEM "input.xml">
+    <!ENTITY vout SYSTEM "vout.xml">
+    <!ENTITY aout SYSTEM "aout.xml">
+    <!ENTITY sout SYSTEM "sout.xml">
+    <!ENTITY porting SYSTEM "porting.xml">
+    <!ENTITY debugging SYSTEM "debugging.xml">
+    <!ENTITY history SYSTEM "history.xml">
+    <!ENTITY glossary SYSTEM "glossary.xml">
+    <!ENTITY gpl SYSTEM "gpl.xml">
+]>
+
+<book>
+
+<title> VLC media player API Documentation </title>
+
+<bookinfo>
+
+
+ <author>
+    <firstname> Christophe </firstname>
+    <surname> Massiot </surname>
+    <affiliation>
+      <jobtitle> <ulink url="mailto:christophe.massiot@idealx.com">
+      Developer </ulink> </jobtitle>
+      <orgname> <ulink url="http://www.idealx.com/"> IDEALX
+      S.A.S. </ulink> </orgname>
+      <orgdiv> Industrial Computing </orgdiv>
+    </affiliation>
+  </author>
+  <collab>
+    <collabname> <ulink url="mailto:sam@zoy.org"> Samuel Hocevar
+    </ulink> </collabname>
+    <affiliation>
+      <jobtitle> Developer </jobtitle>
+      <orgname> VideoLAN project </orgname>
+    </affiliation>
+  </collab>
+  <collab>
+    <collabname> Jean-Fran&ccedil;ois Lecomte </collabname>
+    <affiliation>
+      <jobtitle> <ulink url="mailto:jean-francois.lecomte@idealx.com">
+      Developer </ulink> </jobtitle>
+      <orgname> <ulink url="http://www.idealx.com/"> IDEALX
+      S.A.S. </ulink> </orgname>
+    </affiliation>
+  </collab>
+  <collab>
+    <collabname> <ulink url="mailto:henri@via.ecp.fr">Henri Fallon
+    </ulink> </collabname>
+    <affiliation>
+      <jobtitle> Developer </jobtitle>
+      <orgname> VideoLAN project </orgname>
+    </affiliation>
+  </collab>
+  <pubdate> $Id: manual.xml 7937 2004-06-07 19:13:05Z zorglub $ </pubdate>
+  <copyright> <year> 2001 </year>
+      <holder> Christophe Massiot, for IDEALX S.A.S. </holder>
+  </copyright>
+
+    <legalnotice> <para>
+      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;
+      A copy of the license is included in the section entitled "GNU
+      Free Documentation License".
+  </para> </legalnotice>
+</bookinfo>
+
+<toc />
+
+<!-- Coding rules -->
+&coding;
+&libvlc;
+&build;
+&i18n;
+&modulesobjects;
+&cpumisc;
+&variables;
+&threads;
+&messages;
+&playlist;
+&interface;
+&input;
+&vout;
+&aout;
+&sout;
+&porting;
+&debugging;
+
+&history;
+&glossary;
+
+
+<!-- GNU Free Documentation License -->
+<!--&gpl;-->
+
+</book>

doc/developer2/vout.xml

+<chapter><title>Video output</title>
+
+</chapter>