docs: fix some typos and add some missing links in the app dev manual

[platform/upstream/gstreamer.git] / docs / manual / intro-basics.xml

diff --git a/docs/manual/intro-basics.xml b/docs/manual/intro-basics.xml
index 1ab1940..b0c2806 100644 (file)
--- a/docs/manual/intro-basics.xml
+++ b/docs/manual/intro-basics.xml
@@ -34,7 +34,7 @@
       <quote>plug</quote> or <quote>port</quote> on an element where
       links may be made with other elements, and through which data can
       flow to or from those elements. Pads have specific data handling
-      capabilities: A pad can restrict the type of data that flows
+      capabilities: a pad can restrict the type of data that flows
       through it. Links are only allowed between two pads when the
       allowed data types of the two pads are compatible. Data types are
       negotiated between pads using a process called <emphasis>caps
@@ -59,9 +59,9 @@
       through one or more <emphasis>sink pads</emphasis>. Source and sink
       elements have only source and sink pads, respectively. Data usually
       means buffers (described by the <ulink type="http"
-      url="&URLAPI;/gstreamer-GstBuffer.html"><classname>GstBuffer
+      url="&URLAPI;gstreamer-GstBuffer.html"><classname>GstBuffer
       </classname></ulink> object) and events (described by the <ulink
-      type="http" url="&URLAPI;/gstreamer-GstEvent.html"><classname>
+      type="http" url="&URLAPI;gstreamer-GstEvent.html"><classname>
       GstEvent</classname></ulink> object).
     </para>
   </sect1>
@@ -108,32 +108,38 @@
     <itemizedlist>
       <listitem>
         <para>
-          <emphasis>buffers</emphasis>: are objects for passing streaming data
+          <emphasis>buffers</emphasis> are objects for passing streaming data
           between elements in the pipeline. Buffers always travel from sources
           to sinks (downstream).
         </para>
       </listitem>
       <listitem>
         <para>
-          <emphasis>events</emphasis>: are objects send between elements or from
+          <emphasis>events</emphasis> are objects sent between elements or from
           the application to elements. Events can travel upstream and downstream.
           Downstream events can be synchronised to the data flow.
         </para>
       </listitem>
       <listitem>
         <para>
-          <emphasis>messages</emphasis>: are object send from elements over the
-          bus to the application. Messages can be received synchronously, but
-          then from the streaming thread context of the sender or asynchronously
-          marshalled to the main thread of the application.
+          <emphasis>messages</emphasis> are objects posted by elements on
+          the pipeline's message bus, where they will be held for collection
+          by the application. Messages can be intercepted synchronously from
+          the streaming thread context of the element posting the message, but
+          are usually handled asynchronously by the application from the
+          application's main thread. Messages are used to transmit information
+          such as errors, tags, state changes, buffering state, redirects etc.
+          from elements to the application in a thread-safe way.
         </para>
       </listitem>
       <listitem>
         <para>
-          <emphasis>queries</emphasis>: allow application to request information
-          from the pipeline. Queries are answered synchronously. Also elements
-          can use queries. They can be used both ways, but most common are
-          downstream queries.
+          <emphasis>queries</emphasis> allow applications to request information
+          such as duration or current playback position from the pipeline.
+          Queries are always answered synchronously. Elements can also use
+          queries to request information from their peer elements (such as the
+          file size or duration). They can be used both ways within a pipeline,
+          but upstream queries are more common.
         </para>
       </listitem>
     </itemizedlist>