README: Add simple usage explanation and make it look like the other READMEs.

Original commit message from CVS:
* README:
Add simple usage explanation and make it look like the other READMEs.
* src/gstplugin.c:
* src/gstplugin.h:
* src/gsttransform.c:
* src/gsttransform.h:
* tools/make_element:
Add year, username and email fields. Update the templates here and
there a bit. Add more comments.

7 files changed, 112 insertions, 39 deletions

diff --git a/gst-plugin/ChangeLog b/gst-plugin/ChangeLog
index 832f699..059a6b0 100644
--- a/gst-plugin/ChangeLog
+++ b/gst-plugin/ChangeLog
@@ -1,3 +1,16 @@
+2008-05-08  Stefan Kost  <ensonic@users.sf.net>
+
+	* README:
+	  Add simple usage explanation and make it look like the other READMEs.
+
+	* src/gstplugin.c:
+	* src/gstplugin.h:
+	* src/gsttransform.c:
+	* src/gsttransform.h:
+	* tools/make_element:
+	  Add year, username and email fields. Update the templates here and
+	  there a bit. Add more comments.
+
 2007-08-01  Tim-Philipp Müller  <tim at centricular dot net>
 
 	* src/gsttransform.c:
diff --git a/gst-plugin/README b/gst-plugin/README
index e800f09..1acafff 100644
--- a/gst-plugin/README
+++ b/gst-plugin/README
@@ -1,3 +1,6 @@
+WHAT IT IS
+----------
+
 gst-plugin is a template for writing your own GStreamer plug-in.
 
 The code is deliberately kept simple so that you quickly understand the basics
@@ -9,4 +12,22 @@ This template demonstrates :
 - how to setup your source dir 
 - what to put in Makefile.am
 
-More features might get added to this template later on.
+More features and templates might get added later on.
+
+HOW TO USE IT
+-------------
+
+To use it, either make a copy for yourself and rename the parts or use the
+make_element script in tools. To create sources for "myfilter" based on the
+"gsttransform" template run:
+
+cd src;
+../tools/make_element myfilter gsttransform
+
+This will create gstmyfilter.c and gstmyfilter.h. Open them in an editor and
+start editing. There are several occurances of the string "template", update
+those with real values. The plugin will be called 'myfilter' and it will have
+one element called 'myfilter' too.
+
+You still need to adjust the Makefile.am.
+
diff --git a/gst-plugin/src/gstplugin.c b/gst-plugin/src/gstplugin.c
index 9bc4e07..1443020 100644
--- a/gst-plugin/src/gstplugin.c
+++ b/gst-plugin/src/gstplugin.c
@@ -1,7 +1,8 @@
 /*
  * GStreamer
- * Copyright 2005 Thomas Vander Stichele <thomas@apestaart.org>
- * Copyright 2005 Ronald S. Bultje <rbultje@ronald.bitfreak.net>
+ * Copyright (C) 2005 Thomas Vander Stichele <thomas@apestaart.org>
+ * Copyright (C) 2005 Ronald S. Bultje <rbultje@ronald.bitfreak.net>
+ * Copyright (C) YEAR AUTHOR_NAME AUTHOR_EMAIL
  * 
  * Permission is hereby granted, free of charge, to any person obtaining a
  * copy of this software and associated documentation files (the "Software"),
@@ -75,10 +76,14 @@ enum
 
 enum
 {
-  ARG_0,
-  ARG_SILENT
+  PROP_0,
+  PROP_SILENT
 };
 
+/* the capabilities of the inputs and outputs.
+ *
+ * describe the real formats here.
+ */
 static GstStaticPadTemplate sink_factory = GST_STATIC_PAD_TEMPLATE ("sink",
     GST_PAD_SINK,
     GST_PAD_ALWAYS,
@@ -102,6 +107,8 @@ static void gst_plugin_template_get_property (GObject * object, guint prop_id,
 static gboolean gst_plugin_template_set_caps (GstPad * pad, GstCaps * caps);
 static GstFlowReturn gst_plugin_template_chain (GstPad * pad, GstBuffer * buf);
 
+/* GObject vmethod implementations */
+
 static void
 gst_plugin_template_base_init (gpointer gclass)
 {
@@ -109,7 +116,7 @@ gst_plugin_template_base_init (gpointer gclass)
     "PluginTemplate",
     "Generic/PluginTemplate",
     "Generic Template Element",
-    "Thomas Vander Stichele <thomas@apestaart.org>"
+    "AUTHOR_NAME AUTHOR_EMAIL"
   };
   GstElementClass *element_class = GST_ELEMENT_CLASS (gclass);
 
@@ -133,15 +140,15 @@ gst_plugin_template_class_init (GstPluginTemplateClass * klass)
   gobject_class->set_property = gst_plugin_template_set_property;
   gobject_class->get_property = gst_plugin_template_get_property;
 
-  g_object_class_install_property (gobject_class, ARG_SILENT,
+  g_object_class_install_property (gobject_class, PROP_SILENT,
       g_param_spec_boolean ("silent", "Silent", "Produce verbose output ?",
           FALSE, G_PARAM_READWRITE));
 }
 
 /* initialize the new element
  * instantiate pads and add them to element
- * set functions
- * initialize structure
+ * set pad calback functions
+ * initialize instance structure
  */
 static void
 gst_plugin_template_init (GstPluginTemplate * filter,
@@ -177,7 +184,7 @@ gst_plugin_template_set_property (GObject * object, guint prop_id,
   GstPluginTemplate *filter = GST_PLUGIN_TEMPLATE (object);
 
   switch (prop_id) {
-    case ARG_SILENT:
+    case PROP_SILENT:
       filter->silent = g_value_get_boolean (value);
       break;
     default:
@@ -193,7 +200,7 @@ gst_plugin_template_get_property (GObject * object, guint prop_id,
   GstPluginTemplate *filter = GST_PLUGIN_TEMPLATE (object);
 
   switch (prop_id) {
-    case ARG_SILENT:
+    case PROP_SILENT:
       g_value_set_boolean (value, filter->silent);
       break;
     default:
@@ -220,7 +227,6 @@ gst_plugin_template_set_caps (GstPad * pad, GstCaps * caps)
 /* chain function
  * this function does the actual processing
  */
-
 static GstFlowReturn
 gst_plugin_template_chain (GstPad * pad, GstBuffer * buf)
 {
@@ -238,30 +244,34 @@ gst_plugin_template_chain (GstPad * pad, GstBuffer * buf)
 
 /* entry point to initialize the plug-in
  * initialize the plug-in itself
- * register the element factories and pad templates
- * register the features
- *
- * exchange the string 'plugin' with your elemnt name
+ * register the element factories and other features
  */
 static gboolean
 plugin_init (GstPlugin * plugin)
 {
-  /* exchange the strings 'plugin' and 'Template plugin' with your
-   * plugin name and description */
+  /* debug category for fltering log messages
+   *
+   * exchange the string 'Template plugin' with your description
+   */
   GST_DEBUG_CATEGORY_INIT (gst_plugin_template_debug, "plugin",
       0, "Template plugin");
 
-  return gst_element_register (plugin, "myelement",
-      GST_RANK_NONE, GST_TYPE_PLUGIN_TEMPLATE);
+  return gst_element_register (plugin, "plugin", GST_RANK_NONE,
+      GST_TYPE_PLUGIN_TEMPLATE);
 }
 
-/* this is the structure that gstreamer looks for to register plugins
+/* gstreamer looks for this structure to register plugins
  *
- * exchange the strings 'plugin' and 'Template plugin' with you plugin name and
- * description
+ * exchange the string 'Template plugin' with your plugin description
  */
-GST_PLUGIN_DEFINE (GST_VERSION_MAJOR,
+GST_PLUGIN_DEFINE (
+    GST_VERSION_MAJOR,
     GST_VERSION_MINOR,
     "plugin",
     "Template plugin",
-    plugin_init, VERSION, "LGPL", "GStreamer", "http://gstreamer.net/")
+    plugin_init,
+    VERSION,
+    "LGPL",
+    "GStreamer",
+    "http://gstreamer.net/"
+)
diff --git a/gst-plugin/src/gstplugin.h b/gst-plugin/src/gstplugin.h
index 1bcdb90..f1fe4ed 100644
--- a/gst-plugin/src/gstplugin.h
+++ b/gst-plugin/src/gstplugin.h
@@ -1,7 +1,8 @@
 /*
  * GStreamer
- * Copyright 2005 Thomas Vander Stichele <thomas@apestaart.org>
- * Copyright 2005 Ronald S. Bultje <rbultje@ronald.bitfreak.net>
+ * Copyright (C) 2005 Thomas Vander Stichele <thomas@apestaart.org>
+ * Copyright (C) 2005 Ronald S. Bultje <rbultje@ronald.bitfreak.net>
+ * Copyright (C) YEAR AUTHOR_NAME AUTHOR_EMAIL
  * 
  * Permission is hereby granted, free of charge, to any person obtaining a
  * copy of this software and associated documentation files (the "Software"),
diff --git a/gst-plugin/src/gsttransform.c b/gst-plugin/src/gsttransform.c
index 4cfcb8d..b3afd87 100644
--- a/gst-plugin/src/gsttransform.c
+++ b/gst-plugin/src/gsttransform.c
@@ -1,6 +1,7 @@
 /*
  * GStreamer
  * Copyright (C) 2006 Stefan Kost <ensonic@users.sf.net>
+ * Copyright (C) YEAR AUTHOR_NAME AUTHOR_EMAIL
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Library General Public
@@ -45,16 +46,22 @@ GST_DEBUG_CATEGORY_STATIC (gst_plugin_template_debug);
 #define GST_CAT_DEFAULT gst_plugin_template_debug
 
 /* Filter signals and args */
-enum {
+enum
+{
   /* FILL ME */
   LAST_SIGNAL
 };
 
-enum {
+enum
+{
   PROP_0,
   PROP_SILENT,
 };
 
+/* the capabilities of the inputs and outputs.
+ *
+ * describe the real formats here.
+ */
 static GstStaticPadTemplate sink_template =
 GST_STATIC_PAD_TEMPLATE (
   "sink",
@@ -71,8 +78,12 @@ GST_STATIC_PAD_TEMPLATE (
   GST_STATIC_CAPS ("ANY")
 );
 
+/* debug category for fltering log messages
+ *
+ * exchange the string 'Template plugin' with your description
+ */
 #define DEBUG_INIT(bla) \
-  GST_DEBUG_CATEGORY_INIT (gst_plugin_template_debug, "plugin_template", 0, "transformer template plugin");
+  GST_DEBUG_CATEGORY_INIT (gst_plugin_template_debug, "plugin", 0, "Template plugin");
 
 GST_BOILERPLATE_FULL (GstPluginTemplate, gst_plugin_template, GstBaseTransform,
     GST_TYPE_BASE_TRANSFORM, DEBUG_INIT);
@@ -94,7 +105,7 @@ gst_plugin_template_base_init (gpointer klass)
     "PluginTemplate",
     "Generic/PluginTemplate",
     "Generic Template Element",
-    "Stefan Kost <ensonic@users.sf.net>"
+    "AUTHOR_NAME AUTHOR_EMAIL"
   };
   GstElementClass *element_class = GST_ELEMENT_CLASS (klass);
 
@@ -105,6 +116,7 @@ gst_plugin_template_base_init (gpointer klass)
   gst_element_class_set_details (element_class, &element_details);
 }
 
+/* initialize the plugin's class */
 static void
 gst_plugin_template_class_init (GstPluginTemplateClass * klass)
 {
@@ -122,6 +134,9 @@ gst_plugin_template_class_init (GstPluginTemplateClass * klass)
       GST_DEBUG_FUNCPTR (gst_plugin_template_transform_ip);
 }
 
+/* initialize the new element
+ * initialize instance structure
+ */
 static void
 gst_plugin_template_init (GstPluginTemplate *filter, GstPluginTemplateClass * klass)
 {
@@ -181,10 +196,7 @@ gst_plugin_template_transform_ip (GstBaseTransform * base, GstBuffer * outbuf)
 
 /* entry point to initialize the plug-in
  * initialize the plug-in itself
- * register the element factories and pad templates
- * register the features
- *
- * exchange the string 'plugin' with your elemnt name
+ * register the element factories and other features
  */
 static gboolean
 plugin_init (GstPlugin * plugin)
@@ -196,16 +208,15 @@ plugin_init (GstPlugin * plugin)
       GST_TYPE_PLUGIN_TEMPLATE);
 }
 
-/* this is the structure that gstreamer looks for to register plugins
+/* gstreamer looks for this structure to register plugins
  *
- * exchange the strings 'plugin' and 'Template plugin' with you plugin name and
- * description
+ * exchange the string 'Template plugin' with you plugin description
  */
 GST_PLUGIN_DEFINE (
     GST_VERSION_MAJOR,
     GST_VERSION_MINOR,
     "plugin",
-    "Generic Template Plugin",
+    "Template plugin",
     plugin_init,
     VERSION,
     "LGPL",
diff --git a/gst-plugin/src/gsttransform.h b/gst-plugin/src/gsttransform.h
index cdbfbf7..be9ce86 100644
--- a/gst-plugin/src/gsttransform.h
+++ b/gst-plugin/src/gsttransform.h
@@ -1,6 +1,7 @@
 /* 
  * GStreamer
  * Copyright (C) 2006 Stefan Kost <ensonic@users.sf.net>
+ * Copyright (C) YEAR AUTHOR_NAME AUTHOR_EMAIL
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Library General Public
diff --git a/gst-plugin/tools/make_element b/gst-plugin/tools/make_element
index cdfedd2..5d59ffc 100755
--- a/gst-plugin/tools/make_element
+++ b/gst-plugin/tools/make_element
@@ -24,6 +24,14 @@ template=$(echo $Template | tr A-Z a-z)
 filename=$(echo $template | tr -d _)
 Template=$(echo $Template | tr -d _)
 
+YEAR=`date "+%Y"`
+if [ -z "$REAL_NAME" ]; then
+  REAL_NAME=`grep `id -u` /etc/passwd | awk -F":" '{ print $5 }' | awk -F"," '{ print $1 }'`
+fi
+if [ -z "$EMAIL_ADDRESS" ]; then
+  EMAIL_ADDRESS="<user@hostname.org>"
+fi
+
 # remember to break up the Id: in the line below
 sed \
 	-e 's/gstplugin\.c/SOURCEFILE/g' \
@@ -36,6 +44,10 @@ sed \
 	-e 's/\$I[d]: \([^$]*\)\$/\1/g' \
 	-e 's/SOURCEFILE/gstobject\.c/g' \
 	-e "s%MAKEFILTERVERSION%$id%g" \
+	-e "s/plugin/$Template/g" \
+	-e "s/YEAR/$YEAR/g" \
+	-e "s/AUTHOR_NAME/$REAL_NAME/g" \
+	-e "s/AUTHOR_EMAIL/<$EMAIL_ADDRESS>/g" \
 	$srcfile >gst$filename.c.tmp && mv gst$filename.c.tmp gst$filename.c
 
 sed \
@@ -49,5 +61,9 @@ sed \
 	-e 's/\$I[d]: \([^$]*\)\$/\1/g' \
 	-e 's/SOURCEFILE/gstobject\.c/g' \
 	-e "s%MAKEFILTERVERSION%$id%g" \
+	-e "s/plugin/$Template/g" \
+	-e "s/YEAR/$YEAR/g" \
+	-e "s/AUTHOR_NAME/$REAL_NAME/g" \
+	-e "s/AUTHOR_EMAIL/<$EMAIL_ADDRESS>/g" \
 	$srcfile_h >gst$filename.h.tmp && mv gst$filename.h.tmp gst$filename.h