[Gnash-commit] gnash/doc/C/usermanual glossary.xml bugreport.xml

[Ann Barcomb]

CVSROOT:        /sources/gnash
Module name:    gnash
Changes by:     Ann Barcomb <ann>       07/06/07 14:12:20

Added files:
        doc/C/usermanual: glossary.xml bugreport.xml 

Log message:
        These two files were also added in release-8-0-0; this commit adds them 
to head

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/gnash/doc/C/usermanual/glossary.xml?cvsroot=gnash&rev=1.2
http://cvs.savannah.gnu.org/viewcvs/gnash/doc/C/usermanual/bugreport.xml?cvsroot=gnash&rev=1.2

Patches:
Index: glossary.xml
===================================================================
RCS file: glossary.xml
diff -N glossary.xml
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ glossary.xml        7 Jun 2007 14:12:20 -0000       1.2
@@ -0,0 +1,221 @@
+<sect1 id="glossary">
+  <title>Glossary</title>
+
+  <para><variablelist mark="opencircle">
+    <varlistentry>
+      <term>
+        ActionScript
+      </term>
+      <listitem>
+        <para>
+          <emphasis>ActionScript</emphasis>, or "AS", is the scripting 
+          language for <emphasis>Flash</emphasis>
+          applications.  It is compiled to bytecode, which is a subset of
+          the <emphasis>SWF</emphasis> format.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>
+        AMF
+      </term>
+      <listitem>
+        <para>
+          <emphasis>AMF</emphasis> 
+          is the object format used by <emphasis>Flash</emphasis> 
+          for shared objects and streaming video.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>
+        DocBook
+      </term>
+      <listitem>
+        <para>
+          <emphasis>DocBook</emphasis>
+           is a markup language for presentation-neutral 
+          documentation, such as manuals.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>
+        Doxygen
+      </term>
+      <listitem>
+        <para>
+          <emphasis>Doxygen</emphasis> 
+          is a documentation generator for for multiple languages 
+          which uses comments in the source code to create stand-alone 
+          documentation. 
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>
+        extensions
+      </term>
+      <listitem>
+        <para>
+          A &app; <emphasis>extension</emphasis> is a plugin (not
+          a browser plugin) which
+          implements additional 
+          functionality beyond what is covered by 
+          <emphasis>Flash</emphasis> specification. 
+          These are shared libraries which are loaded at runtime.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>
+        Flash
+      </term>
+      <listitem>
+        <para>
+          The term <emphasis>Flash</emphasis> is used to describe both the 
+          Adobe IDE for creating <emphasis>SWF</emphasis>
+           files, and the technology itself.  
+          &app; documentation uses the latter definition.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>
+        GUI
+      </term>
+      <listitem>
+        <para>
+          A <emphasis>GUI</emphasis> is a 
+          "graphical user interface". In &app;, the GUI 
+          library provides a wrapper for mouse and keyboard events, 
+          menus, windowing (where available) and a drawing area. 
+          You must choose a GUI library during the
+          <link linkend="configure">configuration</link> stage.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>
+        Klash
+      </term>
+      <listitem>
+        <para>
+          <emphasis>Klash</emphasis> was the name given to the stand-alone 
+          instance of &app; which used the KDE GUI.  It has been replaced with 
+          an implementation using Qt.  Some documentation may incorrectly
+          refer to the Konqueror plugin as <emphasis>Klash</emphasis>.
+          The plugin was renamed <emphasis>Kpart</emphasis>.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>
+        Kpart
+      </term>
+      <listitem>
+        <para>
+          <emphasis>Kpart</emphasis> is a plugin for Konqueror which is
+          enabled with the <link linkend="features">configuration option</link>
+          <emphasis>--enable-klash</emphasis>.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>
+        Mesa
+      </term>
+      <listitem>
+        <para>
+          <emphasis>Mesa</emphasis> is the free software OpenGL 
+          implementation.  &app; documentation will sometimes use the
+          terms 'OpenGL' and 'Mesa' interchangeably.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>
+        plugin
+      </term>
+      <listitem>
+        <para>
+          The term <emphasis>plugin</emphasis> is used in &app; to
+          refer to both any &app; browser plugin, as well as the Firefox
+          plugin specifically.  The Konqueror plugin is called
+          <emphasis>Kpart</emphasis>.  Sometimes, the term is used in
+          an even more generic sense to refer to 
+          <emphasis>extensions</emphasis>.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>
+        renderer
+      </term>
+      <listitem>
+        <para>
+          The <emphasis>renderer</emphasis> is the subsystem of &app;
+          which renders content.  Only one renderer may be used; it is
+          chosen during <link linkend="configure">configuration</link>.
+        </para>
+        <para>
+          Available renderers are: AGG, OpenGL, and Cairo. In terms of 
+          feature completeness, AGG comes first; followed by OpenGL and 
+          then Cairo. In most cases, AGG is preferred for performance, 
+          except cases where it is beneficial to have hardware accelerated 
+          rendering (for example, when you have a very slow CPU but a very 
+          fast graphics card). In this case OpenGL should be used.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>
+        sound handler
+      </term>
+      <listitem>
+        <para>
+          The <emphasis>sound handler</emphasis> is the part of &app;
+          which handles both event sounds and streaming sound.  Audio
+          from external sources are also handled through the sound handler
+          when SDL is used.  The sound handler must be selected during
+          <link linkend="configure">configuration</link>.
+        </para>
+        <para>
+          There are currently two sound handlers available in &app;:
+          SDL and Gstreamer.  The SDL sound handler uses ffmpeg or 
+          libmad for decoding mp3-audio, although it can be built without 
+          mp3-support. The Gstreamer-sound handler uses the available 
+          plugins to decode the audio, so it might not work if some 
+          important plugins are missing.  The SDL sound handler is 
+          recommended.  
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>
+        SWF
+      </term>
+      <listitem>
+        <para>
+          <emphasis>SWF</emphasis> is the file format for 
+          <emphasis>Flash</emphasis> movies.
+        </para>
+      </listitem>
+    </varlistentry>
+
+  </variablelist></para>
+</sect1>
+    

Index: bugreport.xml
===================================================================
RCS file: bugreport.xml
diff -N bugreport.xml
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ bugreport.xml       7 Jun 2007 14:12:20 -0000       1.2
@@ -0,0 +1,121 @@
+<sect1 id="bugreport">
+  <title>Reporting Bugs</title>
+
+  <para>
+    The better your bug report is, the easier it will be for the
+    developers to address the issue.
+    Please follow the three steps described below before filing a bug
+    report:
+    <orderedlist>
+      <listitem><para>
+        <link linkend="bugstep_newcheckout">Compile the latest
+        &app; build.</link>
+      </para></listitem>
+      <listitem><para>
+        <link linkend="bugstep_search">Determine if the bug was
+        previously reported.</link>
+      </para></listitem>
+      <listitem><para>
+        <link linkend="bugstep_guidelines">Review the bug writing 
+        guidelines.</link>
+      </para></listitem>
+    </orderedlist>
+  </para>
+
+  <sect2 id="bugstep_newcheckout">
+    <title>Compile the latest &app; build</title>
+    <para>
+      Obtain a copy of the latest <link linkend="sourcerepo">development
+      checkout</link> or <link linkend="sourcesnapshot">development
+      snapshot</link>.  Put the source in an empty directory, then
+      <link linkend="configure">configure</link> and 
+      <link linkend="compile">compile</link> &app;.
+    </para>
+    <para>
+      If you are able to replicate the bug, 
+      <link linkend="bugstep_search">proceed to the next step</link>.
+    </para>
+    <para>
+      If the bug does not persist, the problem may have been solved, or
+      the issue may involve your environment.  By creating a fresh build
+      of your original version and trying to replicate the bug you
+      can determine if it is an environmental issue or a resolved bug.
+      If you are able to replicate the bug, the problem has been fixed
+      and there is no need to file a bug report.
+    </para>
+    <para>
+      If the bug is no longer visible, the problem may be related to
+      your environment.  Try to determine the source of the conflict
+      so that you can include this information in your bug report.
+    </para>
+  </sect2>
+
+  <sect2 id="bugstep_search">
+    <title>Determine if the bug was previously reported</title>
+    <para>
+      Search the <ulink type="https"
+      url="https://savannah.gnu.org/bugs/?group=gnash";>&app;
+      bug tracker</ulink> to see if the bug has already been identified.
+    </para>
+    <para>
+      If the issue has already been reported, you should not file
+      a bug report.  However, you may add some additional information
+      to the ticket if you feel that it will be beneficial to the
+      developers.  For instance, if someone reported a memory issue
+      on Ubuntu GNU/Linux, and you noticed the same problem on OpenBSD,
+      your stacktrace would be useful.  Conversely, adding a "me too"
+      note to a feature request is not helpful.
+    </para>
+  </sect2>
+
+  <sect2 id="bugstep_guidelines">
+    <title>Review the bug writing guidelines</title>
+    <para>
+      A good bug report should be precise, explicit, and discrete.
+      This means that there should be just one bug per ticket, and
+      that a ticket should contain the following information:
+      <itemizedlist mark="opencircle">
+        <listitem>
+          An overview of the problem;
+        </listitem> 
+        <listitem>
+          Instructions on how to replicate the bug;
+        </listitem> 
+        <listitem>
+          A description of what happened when you performed the steps
+          to replicate the bug, and what you expected to happen;
+        </listitem> 
+        <listitem>
+          Your system information: operating system name and version, as
+          well as the versions of major <link 
+          linkend="codedepend">dependencies</link>;
+        </listitem> 
+        <listitem>
+          The release number or checkout timestamp for the version of &app;
+          where you observe the problem;
+        </listitem> 
+        <listitem>
+          The file <filename>config.log</filename>, which should be
+          attached as a file; and
+        </listitem> 
+        <listitem>
+          A descriptive title.
+        </listitem> 
+      </itemizedlist>
+      Include any additional information that you feel might be useful
+      to the developers.
+    </para>
+  </sect2>
+
+  <sect2 id="bugstep_file">
+    <title>Filing a bug report</title>
+    <para>
+      After following the steps described above, you can
+      <ulink type="https"
+      url="https://savannah.gnu.org/bugs/?group=gnash";>file a
+      bug report</ulink>.
+    </para>
+  </sect2>
+
+</sect1>
+