Small changes to the English in the introduction -- only tiny 'native-speaker' issues.

CVS patchset: 1489
CVS date: 2002/02/09 13:43:11

2 files changed, 40 insertions, 31 deletions

diff --git a/doc/hackersguide/hackersguide.sgml b/doc/hackersguide/hackersguide.sgml
index b0ae908e0..632e883d5 100644
--- a/doc/hackersguide/hackersguide.sgml
+++ b/doc/hackersguide/hackersguide.sgml
@@ -309,42 +309,52 @@
     </para>
   </sect1>
   <sect1>
-    <title>xine engine from inside</title>
+    <title>The xine engine from the inside</title>
     <para></para>
   </sect1>
   <sect1>
     <title>Plugin architecture</title>
     <para>
-    xine plugins are basically shared libraries that export one
-    public function init_*_plugin (exact function name depends on plugin type).
-    This function returns a pointer to freshly malloced
-    struct containing mainly
-    function pointers, the "methods" of the plugin. 
-    If you think this is pretty much an object-oriented aproach, you're right.
+    xine plugins are built as shared libraries that export at least one
+    public function named <function>init_type_plugin</function>, where
+    <function>type</function> reflects the function of the plugin (video,
+    audio, etc). This function returns a pointer to freshly allocated (typically
+    via <function>malloc()</function>) structure containing mainly
+    function pointers; these are the "methods" of the plugin. 
+    If you think this is pretty much an object-oriented aproach, 
+    then you're right.
+    </para>
+    <para>
+    All plugins are installed in a special xine plugins directory
+    which can be found using the  <command>xine-config --plugindir</command>
+    command.
     </para>
     <para>
     You'll find exact definitions of public functions and plugin structs
-    in the appropriate header files (e.g. demux/demux.h, input/input_plugin.h,
-    xine-engine/video_out.h,...).
+    in the appropriate header files for each plugin type
+    (e.g. <filename>demux/demux.h</filename>, <filename>input/input_plugin.h</filename>,
+    <filename>xine-engine/video_out.h</filename>, etc) within the xine source-code.
     </para>
     <para>
-    Most plugins will need some additional "private" data fields.
-    These should be simply added at the end of the plugin struct,
-    e.g. a demuxer plugin called "foo" with two private 
-    fields "xine" and "count"
-    would have a plugin struct like
+    Many plugins will need some additional "private" data fields.
+    These should be simply added at the end of the plugin structure.
+    For example a demuxer plugin called "foo" with two private 
+    fields "xine" and "count" may have a plugin structure declared in
+    the following way:
     <programlisting>
     typedef struct {
        /* public fields "inherited" from demux.h */
 
        demux_plugin_t    demux_plugin;
-
        xine_t           *xine;
-
        int               count;
     } demux_foo_t;
     </programlisting>
     </para>
+    <para>
+      The plugin would then access public fields via the 
+      <varname>demux_plugin</varname> field and private fields directly.
+    </para>
   </sect1>
 </chapter>
 
@@ -465,16 +475,8 @@ struct demux_plugin_s
     <title>Adding support for a new type of video output
            (e.g. framebuffer device)</title>
     <para>
-      The xine plugin system makes it easy to create a new video
-      output target for xine. Video output plugins, like all
-      plugins are installed in a special xine plugins directory
-      which can be found using the 
-      <command>xine-config --plugindir</command>
-      command.
-    </para>
-    <para>
       In order to allow for device-dependant acceleration features, xine
-      calls on the video output plugin for more than just displaying
+      calls upon the video output plugin for more than just displaying
       images. The tasks performed by the video plugins are:
     </para>
     <para>
diff --git a/doc/hackersguide/intro.sgml b/doc/hackersguide/intro.sgml
index de9df59c2..b2bcfa909 100644
--- a/doc/hackersguide/intro.sgml
+++ b/doc/hackersguide/intro.sgml
@@ -1,9 +1,10 @@
 <sect1>
 <title>Where am I ?</title>
 <para>
-You are currently looking at a piece of documentation for xine.
+You are currently looking at a piece of documentation for xine. 
 xine is a free video player. It lives on
-<ulink url="http://xine.sf.net">http://xine.sf.net</ulink>.
+<ulink url="http://xine.sf.net">http://xine.sf.net</ulink>. Specifically
+this document goes under the moniker of the 'xine Hackers' Guide'.
 </para>
 </sect1>
 
@@ -13,12 +14,18 @@ xine is a free video player. It lives on
 This document should help xine hackers to find their way through
 xine's architecture and source code. It's a pretty free-form document
 containing a loose collection of articles describing various aspects
-of xine's internals.
+of xine's internals. It has been written by a number of people who work
+on xine themselves and is intended to provide the important concepts and
+methods used within xine. Readers should not consider this document to be
+an exhausative description of the internals of xine. As with all projects
+which provide access, the source-code should be considered the definative source
+of information.
 </para>
 
 <para>
-This document has no intention to and therefore will never be complete or
-current in any way.
+This document has no intention to be, and therefore never will be, complete or
+current in any way. Instead it should be considered a read-map pointing the
+casual hacker to the correct location in the xine source.
 </para>
 </sect1>
 
@@ -45,4 +52,4 @@ All comments, error reports, additional information and criticism of
 all sorts should be directed to the xine developer mailing list
 <email>xine-devel@lists.sourceforge.net</email>.
 </para>
-</sect1>
\ No newline at end of file
+</sect1>