Index: pads-api.xml
===================================================================
RCS file: /cvs/gstreamer/gstreamer/docs/manual/pads-api.xml,v
retrieving revision 1.2
diff -u -r1.2 pads-api.xml
--- pads-api.xml	28 Jan 2004 15:08:17 -0000	1.2
+++ pads-api.xml	13 Mar 2004 18:12:58 -0000
@@ -140,41 +140,38 @@
         what type of media the pad can handle.
       </para>
       <para>
-	Its structure is:
+        The <classname>GstCaps</classname> structure is opaque and should only be accessed via
+        the provided functions.
       </para>
-      <programlisting>
-struct _GstCaps {
-  gchar *name;                  /* the name of this caps */
-  guint16 id;                   /* type id (major type) */
-
-  guint refcount; 		/* caps are refcounted */
-
-  GstProps *properties;         /* properties for this capability */
-
-  GstCaps *next;		/* caps can be chained together */
-};
-      </programlisting>
     </sect2>
 
     <sect2 id="section-pads-api-caps-get">
       <title>Getting the capabilities of a pad</title>
       <para> 
         A pad can have a chain of capabilities attached to it. You can get the capabilities chain
-	with:
+        with:
       </para>
     <programlisting>
- GstCaps *caps;
+ GstCaps  *caps;
     ...
- caps = gst_pad_get_caps (pad);
-
  g_print ("pad name %s\n", gst_pad_get_name (pad));
  
- while (caps) {
-   g_print (" Capability name %s, MIME type %s\n", 
-   				gst_caps_get_name (cap), 
-                                gst_caps_get_mime (cap));
-   
-   caps = caps-&gt;next;
+ caps = gst_pad_get_caps (pad);
+ 
+ if (caps != NULL)
+ {
+   gint size, i;
+    
+   size = gst_caps_get_size(caps);
+   for (i = 0; i &lt; size; ++i)
+   {
+      GstStructure *st;
+
+      st = gst_caps_get_structure(caps, i);
+      
+      g_print (" Capability MIME type %s\n", 
+               gst_structure_get_name(st));
+   }
  }
     ...
     </programlisting>
@@ -193,108 +190,37 @@
         <classname>GstCaps</classname> structure is:
 
     <programlisting>
-GstCaps*    gst_caps_new (const gchar *name, const gchar *mime, GstProps *props);
+GstCaps*    gst_caps_new (const gchar *mimetype, ...);
     </programlisting>
       </para>
       <para>
-        You can therefore create a new capability with no properties like this:
+        The function takes a mime type, and is followed by a list of 
+        field arguments in sets of 3, which has to be terminated by
+        a NULL. You can therefore create a new capability with no 
+        properties like this:
     <programlisting>
   GstCaps *newcaps;
   
-  newcaps = gst_caps_new ("my_caps", "audio/wav", NULL);
+  newcaps = gst_caps_new ("audio/wav", NULL);
     </programlisting>
       </para>
       <para>
-        <classname>GstProps</classname> basically consist of a set of key-value pairs
-	and are created with a function with this signature:
+        A new capability with a set of additional properties is created like this:
     <programlisting>
-GstProps*     gst_props_new   (const gchar *firstname, ...);
+  GstCaps *newcaps;
+  
+  newcaps = gst_caps_new ("audio/x-raw-int", 
+                          "channels", G_TYPE_INT, 5,
+                          NULL);
     </programlisting>
       </para>
       <para>
-        The keys are given as strings and the values are given with a set of macros:
-        <itemizedlist>
-          <listitem>
-            <para>
-              GST_PROPS_INT(a): An integer value
-            </para>
-          </listitem>
-          <listitem>
-            <para>
-              GST_PROPS_FLOAT(a): A floating point value
-            </para>
-          </listitem>
-          <listitem>
-            <para>
-              GST_PROPS_FOURCC(a): A fourcc value
-            </para>
-          </listitem>
-          <listitem>
-            <para>
-              GST_PROPS_BOOLEAN(a): A boolean value
-            </para>
-          </listitem>
-          <listitem>
-            <para>
-              GST_PROPS_STRING(a): A string value
-            </para>
-          </listitem>
-        </itemizedlist>
-        The values can also be specified as ranges with:
-        <itemizedlist>
-          <listitem>
-            <para>
-              GST_PROPS_INT_RANGE(a,b): An integer range from a to b
-            </para>
-          </listitem>
-          <listitem>
-            <para>
-              GST_PROPS_FLOAT_RANGE(a,b): A float ragne from a to b
-            </para>
-          </listitem>
-        </itemizedlist>
-        All of the above values can be given with a list too, using:
-        <itemizedlist>
-          <listitem>
-            <para>
-              GST_PROPS_LIST(a,...): A list of property values.
-            </para>
-          </listitem>
-        </itemizedlist>
-      </para>
+       See the API reference manual for more details.
+      </para>    
       <para>
-        A more complex capability with properties is created like this:
-        <programlisting>
-  GstCaps *newcaps;
-  
-  newcaps = gst_caps_new ("my_caps", 
-                          "audio/wav", 
-  			  gst_props_new (
-			    "bitrate", GST_PROPS_INT_RANGE (11025,22050),
-			    "depth",   GST_PROPS_INT (16),
-			    "signed",  GST_PROPS_LIST (
-			     		 GST_PROPS_BOOLEAN (TRUE),
-			     		 GST_PROPS_BOOLEAN (FALSE)
-				       ),
-			    NULL
-			  );
-        </programlisting>
-	Optionally, the convenient shortcut macro can be used. The above complex
-	capability can be created with:
-        <programlisting>
-  GstCaps *newcaps;
-  
-  newcaps = GST_CAPS_NEW ("my_caps", 
-                          "audio/wav", 
-			    "bitrate", GST_PROPS_INT_RANGE (11025,22050),
-			    "depth",   GST_PROPS_INT (16),
-			    "signed",  GST_PROPS_LIST (
-			     		 GST_PROPS_BOOLEAN (TRUE),
-			     		 GST_PROPS_BOOLEAN (FALSE)
-				       )
-			  );
-        </programlisting>
-      </para>
+       TODO: show how to create more complext caps, e.g. with range values 
+             for fields, or from a string. Also show how to use static caps.
+      </para>    
     </sect2>
 
   </sect1>
