Change GStreamer marker prefix in detail string from 'gstreamer.net' to just 'gstreamer'. Document the caps string co...

Original commit message from CVS:
* gst-libs/gst/utils/install-plugins.c:
* gst-libs/gst/utils/missing-plugins.c:
* tests/check/libs/utils.c: (missing_msg_check_getters):
Change GStreamer marker prefix in detail string from 'gstreamer.net'
to just 'gstreamer'. Document the caps string component of the
decoder/encoder detail a bit better, since not everyone will be
familiar with the GStreamer media type/caps system (but they better
enjoy nested itemized lists).

ChangeLog

@@ -1,3 +1,14 @@
+2007-02-23  Tim-Philipp Müller  <tim at centricular dot net>
+
+	* gst-libs/gst/utils/install-plugins.c:
+	* gst-libs/gst/utils/missing-plugins.c:
+	* tests/check/libs/utils.c: (missing_msg_check_getters):
+	  Change GStreamer marker prefix in detail string from 'gstreamer.net'
+	  to just 'gstreamer'. Document the caps string component of the
+	  decoder/encoder detail a bit better, since not everyone will be
+	  familiar with the GStreamer media type/caps system (but they better
+	  enjoy nested itemized lists).
+
 2007-02-22  Tim-Philipp Müller  <tim at centricular dot net>
 
 	* gst-libs/gst/netbuffer/gstnetbuffer.c:

gst-libs/gst/pbutils/install-plugins.c

@@ -169,7 +169,7 @@
  *  </para></listitem>
  *  <listitem><para>
  *    one 'installer detail string' argument for each plugin to be installed;
- *    these strings will have a <literal>gstreamer.net</literal> prefix; the
+ *    these strings will have a <literal>gstreamer</literal> prefix; the
  *    exact format of the detail string is explained below
  *  </para></listitem>
  * </itemizedlist>
@@ -183,7 +183,7 @@
  * The fields are:
  * <itemizedlist>
  *   <listitem><para>
- *    plugin system identifier, ie. "gstreamer.net"
+ *    plugin system identifier, ie. "gstreamer"
  *   </para><para>
  *    This identifier determines the format of the rest of the detail string.
  *    Automatic plugin installers should not process detail strings with
@@ -219,8 +219,13 @@
  *       element-$(ELEMENT_REQUIRED), e.g. element-ffmpegcolorspace
  *     </para></listitem>
  *     <listitem><para>
- *       decoder-$(CAPS_REQUIRED), e.g. decoder-audio/x-vorbis or
+ *       decoder-$(CAPS_REQUIRED), e.g. (do read below for more details!):
- *       decoder-application/ogg
+ *       <itemizedlist>
+ *         <listitem><para>decoder-audio/x-vorbis</para></listitem>
+ *         <listitem><para>decoder-application/ogg</para></listitem>
+ *         <listitem><para>decoder-audio/mpeg, mpegversion=(int)4</para></listitem>
+ *         <listitem><para>decoder-video/mpeg, systemstream=(boolean)true, mpegversion=(int)2</para></listitem>
+         </itemizedlist>
  *     </para></listitem>
  *     <listitem><para>
  *       encoder-$(CAPS_REQUIRED), e.g. encoder-audio/x-vorbis
@@ -235,7 +240,7 @@
  * <para>
  * An entire ID string might then look like this, for example:
  * <literal>
- * gstreamer.net|0.10|totem|Vorbis audio decoder|decoder-audio/x-vorbis
+ * gstreamer|0.10|totem|Vorbis audio decoder|decoder-audio/x-vorbis
  * </literal>
  * </para>
  * <para>
@@ -244,6 +249,37 @@
  * out when encountering them.
  * </para>
  * <para>
+ * Those unfamiliar with the GStreamer 'caps' system should note a few things
+ * about the caps string used in the above decoder/encoder case:
+ *   <itemizedlist>
+ *     <listitem><para>
+ *       the first part ("video/mpeg") of the caps string is a GStreamer media
+ *       type and <emphasis>not</emphasis> a MIME type. Wherever possible, the
+ *       GStreamer media type will be the same as the corresponding MIME type,
+ *       but often it is not.
+ *     </para></listitem>
+ *     <listitem><para>
+ *       a caps string may or may not have additional comma-separated fields
+ *       of various types (as seen in the examples above)
+ *     </para></listitem>
+ *     <listitem><para>
+ *       the caps string of a 'required' component (as above) will always have
+ *       fields with fixed values, whereas an introspected string (see below)
+ *       may have fields with non-fixed values. Compare for example:
+ *       <itemizedlist>
+ *         <listitem><para>
+ *           <literal>audio/mpeg, mpegversion=(int)4</literal> vs.
+ *           <literal>audio/mpeg, mpegversion=(int){2, 4}</literal>
+ *         </para></listitem>
+ *         <listitem><para>
+ *           <literal>video/mpeg, mpegversion=(int)2</literal> vs.
+ *           <literal>video/mpeg, systemstream=(boolean){ true, false}, mpegversion=(int)[1, 2]</literal>
+ *         </para></listitem>
+ *       </itemizedlist>
+ *     </para></listitem>
+ *   </itemizedlist>
+ * </para>
+ * <para>
  * <emphasis>4. Exit codes the installer should return</emphasis>
  * </para>
  * <para>

gst-libs/gst/pbutils/missing-plugins.c

@@ -70,7 +70,7 @@
 
 #include <string.h>
 
-#define GST_DETAIL_STRING_MARKER "gstreamer.net"
+#define GST_DETAIL_STRING_MARKER "gstreamer"
 
 typedef enum
 {

gst-libs/gst/utils/install-plugins.c

@@ -169,7 +169,7 @@
  *  </para></listitem>
  *  <listitem><para>
  *    one 'installer detail string' argument for each plugin to be installed;
- *    these strings will have a <literal>gstreamer.net</literal> prefix; the
+ *    these strings will have a <literal>gstreamer</literal> prefix; the
  *    exact format of the detail string is explained below
  *  </para></listitem>
  * </itemizedlist>
@@ -183,7 +183,7 @@
  * The fields are:
  * <itemizedlist>
  *   <listitem><para>
- *    plugin system identifier, ie. "gstreamer.net"
+ *    plugin system identifier, ie. "gstreamer"
  *   </para><para>
  *    This identifier determines the format of the rest of the detail string.
  *    Automatic plugin installers should not process detail strings with
@@ -219,8 +219,13 @@
  *       element-$(ELEMENT_REQUIRED), e.g. element-ffmpegcolorspace
  *     </para></listitem>
  *     <listitem><para>
- *       decoder-$(CAPS_REQUIRED), e.g. decoder-audio/x-vorbis or
+ *       decoder-$(CAPS_REQUIRED), e.g. (do read below for more details!):
- *       decoder-application/ogg
+ *       <itemizedlist>
+ *         <listitem><para>decoder-audio/x-vorbis</para></listitem>
+ *         <listitem><para>decoder-application/ogg</para></listitem>
+ *         <listitem><para>decoder-audio/mpeg, mpegversion=(int)4</para></listitem>
+ *         <listitem><para>decoder-video/mpeg, systemstream=(boolean)true, mpegversion=(int)2</para></listitem>
+         </itemizedlist>
  *     </para></listitem>
  *     <listitem><para>
  *       encoder-$(CAPS_REQUIRED), e.g. encoder-audio/x-vorbis
@@ -235,7 +240,7 @@
  * <para>
  * An entire ID string might then look like this, for example:
  * <literal>
- * gstreamer.net|0.10|totem|Vorbis audio decoder|decoder-audio/x-vorbis
+ * gstreamer|0.10|totem|Vorbis audio decoder|decoder-audio/x-vorbis
  * </literal>
  * </para>
  * <para>
@@ -244,6 +249,37 @@
  * out when encountering them.
  * </para>
  * <para>
+ * Those unfamiliar with the GStreamer 'caps' system should note a few things
+ * about the caps string used in the above decoder/encoder case:
+ *   <itemizedlist>
+ *     <listitem><para>
+ *       the first part ("video/mpeg") of the caps string is a GStreamer media
+ *       type and <emphasis>not</emphasis> a MIME type. Wherever possible, the
+ *       GStreamer media type will be the same as the corresponding MIME type,
+ *       but often it is not.
+ *     </para></listitem>
+ *     <listitem><para>
+ *       a caps string may or may not have additional comma-separated fields
+ *       of various types (as seen in the examples above)
+ *     </para></listitem>
+ *     <listitem><para>
+ *       the caps string of a 'required' component (as above) will always have
+ *       fields with fixed values, whereas an introspected string (see below)
+ *       may have fields with non-fixed values. Compare for example:
+ *       <itemizedlist>
+ *         <listitem><para>
+ *           <literal>audio/mpeg, mpegversion=(int)4</literal> vs.
+ *           <literal>audio/mpeg, mpegversion=(int){2, 4}</literal>
+ *         </para></listitem>
+ *         <listitem><para>
+ *           <literal>video/mpeg, mpegversion=(int)2</literal> vs.
+ *           <literal>video/mpeg, systemstream=(boolean){ true, false}, mpegversion=(int)[1, 2]</literal>
+ *         </para></listitem>
+ *       </itemizedlist>
+ *     </para></listitem>
+ *   </itemizedlist>
+ * </para>
+ * <para>
  * <emphasis>4. Exit codes the installer should return</emphasis>
  * </para>
  * <para>

gst-libs/gst/utils/missing-plugins.c

@@ -70,7 +70,7 @@
 
 #include <string.h>
 
-#define GST_DETAIL_STRING_MARKER "gstreamer.net"
+#define GST_DETAIL_STRING_MARKER "gstreamer"
 
 typedef enum
 {

tests/check/libs/pbutils.c

@@ -49,7 +49,7 @@ missing_msg_check_getters (GstMessage * msg)
   str = gst_missing_plugin_message_get_installer_detail (msg);
   fail_unless (str != NULL);
   fail_unless (*str != '\0');
-  fail_unless (g_str_has_prefix (str, "gstreamer.net|"));
+  fail_unless (g_str_has_prefix (str, "gstreamer|"));
   g_free (str);
 
   str = gst_missing_plugin_message_get_description (msg);

tests/check/libs/utils.c

@@ -49,7 +49,7 @@ missing_msg_check_getters (GstMessage * msg)
   str = gst_missing_plugin_message_get_installer_detail (msg);
   fail_unless (str != NULL);
   fail_unless (*str != '\0');
-  fail_unless (g_str_has_prefix (str, "gstreamer.net|"));
+  fail_unless (g_str_has_prefix (str, "gstreamer|"));
   g_free (str);
 
   str = gst_missing_plugin_message_get_description (msg);