diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/faq/faq.sgml | 120 | ||||
| -rw-r--r-- | doc/hackersguide/hackersguide.sgml | 3 | ||||
| -rw-r--r-- | doc/hackersguide/overview.sgml | 67 |
3 files changed, 94 insertions, 96 deletions
diff --git a/doc/faq/faq.sgml b/doc/faq/faq.sgml index b3490ea2a..2519a8118 100644 --- a/doc/faq/faq.sgml +++ b/doc/faq/faq.sgml @@ -3,15 +3,16 @@ <book> <bookinfo> - <title>The xine engine FAQ</title> - <titleabbrev>xine FAQ</titleabbrev> + <title>The xine engine FAQ list</title> + <titleabbrev>xine FAQs</titleabbrev> <copyright> - <year>2001-2008</year> + <year>2001-2010</year> <holder>the xine project team</holder> </copyright> </bookinfo> - <article> + <article class="faq"> + <sect1 id="general"> <title>General questions about xine and this document</title> @@ -75,7 +76,7 @@ </sect2> <sect2 id="modules"> - <title>What are those xine-lib, xine-ui, gnome-xine, … modules in cvs for?</title> + <title>What are those xine-lib, xine-ui, gxine, … Mercurial repositories for?</title> <para> Some time ago xine just became too complex to be just one big program. Therefore it was split into two major parts. @@ -88,10 +89,10 @@ <para> Then there are frontends – applications that use xine. The most common frontend is that of a media player. There are currently - two frontends being developed in the xine project, xine-ui (skinned - dvd-player style frontend directly based on xlib) and gxine, - a desktop media-player style frontend using the standard gtk widget set - and comes with a mozilla browser plugin. + three frontends being developed in the xine project: xine-ui, a skinned + dvd-player style frontend directly based on xlib; gxine, a desktop + media-player style frontend using the standard GTK widget set; and + xine-plugin, a plugin for browsers such as Firefox. External projects like kaffeine, sinek and totem develop additional frontends. In the future you will likely see more and different types of applications being developed which will use the xine engine for video processing @@ -102,90 +103,47 @@ first and then choose and install a player frontend like xine-ui or gxine. </para> <para> - Other modules in CVS are: <filename>xine-plugin</filename> a mozilla browser plugin - for streaming media playback using xine, - <filename>xine_www</filename> the - xine project website sources. + Other repositories include <filename>xine-project-www</filename>, + which contains the xine project website sources, and various packaging + and development branches. </para> </sect2> - <sect2 id="cvs"> + <sect2 id="hg"> <title>Where and how do I get the latest development version?</title> <para> Be advised that end-users should stick to the official xine releases. - The CVS and Mercurial repositories are only intended for developers and for others who know why they use it. + The Mercurial repositories are only intended for developers and for others who know why they use it. </para> - <sect3> - <title>Checking out xine modules from Mercurial</title> - <para> - The repositories are listed at <ulink url="http://hg.debian.org/hg/">http://hg.debian.org/hg/</ulink>; - however, this is a list of all repositories which are kept there, not just the - xine project's (which are the ones which begin with <filename>xine-lib/</filename>). To check one out: - <screen> <command>hg clone http://hg.debian.org/hg/<filename>repository</filename> <filename>local_copy</filename></command></screen> - e.g. - <screen> <command>hg clone http://hg.debian.org/hg/xine-lib/xine-lib xine-lib</command></screen> - </para> - <para> - Currently, only xine-lib and gxine are present here. - </para> - </sect3> - <sect3> - <title>Checking out xine modules from CVS</title> - <para> - To check out xine modules from CVS, first do this: - <screen> <command>cvs -d :pserver:anonymous@xine.cvs.sourceforge.net:/cvsroot/xine login</command></screen> - The password is empty, just press Enter. - </para> - <para> - Then, to check out individual modules (e.g. <filename>xine-lib</filename> or <filename>xine-ui</filename>): - <screen> <command>cvs -d :pserver:anonymous@xine.cvs.sourceforge.net:/cvsroot/xine co <modulename></command></screen> - </para> - <para> - If you want xine-lib or gxine, you should use Mercurial instead. - The CVS repositories for these are not maintained. - </para> - </sect3> - </sect2> - - <sect2 id="patch"> - <title>How do I submit patches?</title> <para> - First, make sure that you're using a current development version - (see above) or at least the current release version. Then, once you're - ready to send the patch… + The repositories are listed at <ulink url="http://hg.debian.org/hg/">http://hg.debian.org/hg/</ulink>; + however, this is a list of all repositories which are kept there, not just the + xine project's (which are the ones which begin with <filename>xine-lib/</filename>). To check one out: + <screen> <command>hg clone http://hg.debian.org/hg/<filename>repository</filename> <filename>local_copy</filename></command></screen> + e.g. + <screen> <command>hg clone http://hg.debian.org/hg/xine-lib/xine-lib xine-lib</command></screen> </para> <para> - Generate your patch using either <command>cvs diff -u > - my.patch</command> or <command>hg diff > my.patch</command> (as - appropriate). Make sure that your message subject briefly describes the - patch; your message body should contain a longer description of the - patch. Your patch should be applicable using <command>patch -p0 -i - my.patch</command> or, preferably, <command>patch -p1 -i - my.patch</command> from the top-level directory in the source tree - (i.e. where configure.ac is) – this is fairly important for our - Mercurial-based repositories since it makes importing your patch that - much easier (hg import defaults to -p1). - </para> - <para> - Alternatively, if you've been hacking away at a module which is - maintained using mercurial, you can make them available as diffs – use - <command>hg export</command> or, if you have several patches, you could - use <command>hg bundle</command> instead (both require extra - parameters; <command>hg help export</command> and <command>hg help - bundle</command> for more details) – or via HTTP by using <command>hg - serve</command>. In the latter case, you'll need to post a URL from - which a developer can pull the changes. + You can see a full list of repositories by visiting + <ulink url="http://hg.debian.org/hg/xine-lib/">http://hg.debian.org/hg/xine-lib/</ulink>. </para> + </sect2> + + <sect2 id="cvs"> + <title>Don't you use CVS?</title> <para> - Patches should normally be sent to the xine-devel mailing list, - <email>xine-devel@lists.sourceforge.net</email>. + We used to, but there are some significant problems with CVS. Merging + is easier with Mercurial (and, for that matter, git); and we can commit + changes locally, change them if mistakes have been made, then make them + public whenever we're ready. </para> </sect2> - <sect2 id="gnome-xine"> - <title>Why is gxine's CVS module named "gnome-xine"?</title> + <sect2 id="patch"> + <title>How do I submit patches?</title> <para> - Historical reasons: gxine was originally named gnome-xine. + See the xine Hackers' Guide, chapter 3, "How to contribute". + (This is available online at <ulink url="http://www.xine-project.org/hackersguide#contribute">http://www.xine-project.org/hackersguide#contribute</ulink>.) </para> </sect2> @@ -226,7 +184,7 @@ often found in a package called zlib-devel or similar.) </para> <para> - If you want to compile xine from CVS, you'll need to have the autobuild tools + If you want to compile xine from Mercurial, you'll need to have the autobuild tools installed (automake, autoconf and libtool – in recent versions). </para> <para> @@ -304,7 +262,7 @@ Last but not least. Here the build instructions. As stated earlier, those are the same for every xine module. <screen> - <command>./autogen.sh</command> [→ <emphasis>only</emphasis> if you checked your sources out of CVS] + <command>./autogen.sh</command> [→ <emphasis>only</emphasis> if you're building from hg] <command>./configure</command> <command>make</command> <command>make install</command></screen> @@ -328,7 +286,7 @@ (e.g. <filename>/usr/src/RPM/SRPMS</filename>). </para> <para> - In case that you have a fresh CVS checkout, you will need to do the + In case that you have an up-to-date hg repository, you will need to do the following first in order to get a tarball release out of it which you can later use with the <command>rpmbuild -ta</command> command above: <screen> <command>./autogen.sh && make clean && make dist</command></screen> @@ -342,7 +300,7 @@ <sect2 id="debbuild"> <title>Making your own .deb packages (xine-lib, xine-ui, gxine)</title> <para> - You'll need a CVS or HG snapshot tarball or source checked out from the repository. + You'll need an HG snapshot tarball or source checked out from the repository. </para> <para> First, make sure that the "devscripts" package is installed. You'll diff --git a/doc/hackersguide/hackersguide.sgml b/doc/hackersguide/hackersguide.sgml index ebc42d4c7..e33304110 100644 --- a/doc/hackersguide/hackersguide.sgml +++ b/doc/hackersguide/hackersguide.sgml @@ -22,9 +22,10 @@ <author><firstname>Marco</firstname><surname>Zühlke</surname></author> <author><firstname>Mike</firstname><surname>Melanson</surname></author> <author><firstname>Michael</firstname><surname>Roitzsch</surname></author> + <author><firstname>Darren</firstname><surname>Salt</surname></author> </authorgroup> <copyright> - <year>2001-2003</year> + <year>2001-2010</year> <holder>the xine project team</holder> </copyright> <abstract> diff --git a/doc/hackersguide/overview.sgml b/doc/hackersguide/overview.sgml index 18cc40396..bf036edbc 100644 --- a/doc/hackersguide/overview.sgml +++ b/doc/hackersguide/overview.sgml @@ -793,7 +793,7 @@ </sect2> </sect1> - <sect1> + <sect1 id="contribute"> <title>How to contribute</title> <para> Make sure you send your patches in unified diff format to @@ -811,21 +811,60 @@ committable. This normally means that we want your name and email address (we're not keen on pseudonyms), a subject line which provides a convenient summary of your changes, and body text which provides a longer - description (if needed). Patches must be generated using <command>hg - diff</command> or <command>cvs -z9 diff</command>, depending on which is - used for the repository, and always from within the top level of the - checked-out source. + description (if needed). + </para> + <para> + There are a few ways to submit your patches: </para> + <itemizedlist> + <listitem> + <para> + <command>hg diff</command> is probably the easiest. You'll need a + subject line and body text as described above. If you're copying or + renaming files, or a file should be marked as executable, then use + <command>hg diff --git</command>; this will include the necessary + information (if copying or renaming, you need to have used <command>hg + copy</command> or <command>hg rename</command> for this to work). + </para> + <para> + If you're attaching the patch (recommended), then including the + metadata in the patch file is recommended, e.g. + </para> + <screen>From: Fred Patcher <patcher@example.com> +Subject: Properly toggle the randomiser switch + +The randomiser switch was sometimes not being toggled, leading to random +behaviour. + +diff --git a/foo/control.c b/foo/control.c +...</screen> + </listitem> + <listitem> + <para> + <command>diff -u</command> is also acceptable, but we prefer that you + do so from the top-level directory within the source code (prefix the + files' path names with <parameter>./</parameter>) or from the directory + containing the source code directory. Basically, use <command>hg + diff</command> if you can. + </para> + </listitem> + <listitem> + <para> + <command>hg email</command> is preferred. You'll need to commit your + changes locally for this to work, but this is the easiest way of + sending a set of patches for inclusion and review; it'll send the mail + directly. + </para> + </listitem> + <listitem> + <para> + <command>hg export</command> can also be used with specific changeset + identifiers. Again, you'll need to commit your changes locally for + this to work. + </para> + </listitem> + </itemizedlist> <para> - If your patch is intended for a Mercurial-format repository, then - committing it locally and using - <command>hg export <parameter>.</parameter> ><filename>foo.patch</filename></command> - to create the file to be attached is acceptable (but note that the first - line – up to the first line feed – of the commit message is regarded as - the patch summary; if you're not sure, check with - <command>hg log -r<parameter>.</parameter></command>. - Alternatively, use <token>From:</token> and <token>Subject:</token> lines - in the patch file itself; this is useful when forwarding. </para> <para> Patches should normally be included as attachments. Some mail clients and |