GNOME.org
 

[rygel] docs: Mention basic usage (headers, cflags/libs, pkg-config)

commit 175cfe6d135e33b6cdccd8ddf460046dddcf6d69
Author: Murray Cumming <murrayc murrayc com>
Date:   Wed Oct 17 09:36:13 2012 +0200

    docs: Mention basic usage (headers, cflags/libs, pkg-config)
    
    Also link to the examples properly.

 doc/reference/doc-build.am                         |    2 +-
 doc/reference/librygel-core/gtkdoc/overview.xml    |   43 ++++++++++++++++-
 doc/reference/librygel-renderer-gst/Makefile.am    |    2 +
 .../librygel-renderer-gst/gtkdoc/example.xml       |   22 +++++++++
 .../gtkdoc/librygel-renderer-gst-docs.xml          |    5 ++
 .../librygel-renderer-gst/gtkdoc/overview.xml      |   50 ++++++++++++++++----
 .../librygel-renderer/gtkdoc/overview.xml          |   44 +++++++++++++++++-
 doc/reference/librygel-server/Makefile.am          |    5 ++
 .../gtkdoc/implementing-servers.xml                |    3 +-
 .../gtkdoc/librygel-server-docs.xml                |   10 ++--
 doc/reference/librygel-server/gtkdoc/overview.xml  |   50 ++++++++++++++++++++
 .../rygel-playbin-renderer.vala                    |    2 +-
 src/librygel-server/rygel-media-server-plugin.vala |    4 +-
 src/librygel-server/rygel-media-server.vala        |    3 +-
 14 files changed, 221 insertions(+), 24 deletions(-)
---
diff --git a/doc/reference/doc-build.am b/doc/reference/doc-build.am
index 5221f4d..6074a76 100644
--- a/doc/reference/doc-build.am
+++ b/doc/reference/doc-build.am
@@ -28,7 +28,7 @@ gtkdoc/html/index.html: gtkdoc-gen
 
 RYGEL_GTKDOC_DOCS_XML = \
 	$(top_srcdir)/doc/reference/lib$(RYGEL_DOCBUILD_MODULE)/gtkdoc/lib$(RYGEL_DOCBUILD_MODULE)-docs.xml \
-	$(top_srcdir)/doc/reference/lib$(RYGEL_DOCBUILD_MODULE)/gtkdoc/overview.xml
+	$(top_srcdir)/doc/reference/lib$(RYGEL_DOCBUILD_MODULE)/gtkdoc/overview.xml $(RYGEL_GTKDOC_DOCS_XML_EXTRA)
 
 gtkdoc-gen: $(VALA_SOURCE_FILES_WITH_PATHS) $(RYGEL_GTKDOC_DOCS_XML)
 	@rm -rf gtkdoc/html
diff --git a/doc/reference/librygel-core/gtkdoc/overview.xml b/doc/reference/librygel-core/gtkdoc/overview.xml
index 2cd26bb..5f0708b 100644
--- a/doc/reference/librygel-core/gtkdoc/overview.xml
+++ b/doc/reference/librygel-core/gtkdoc/overview.xml
@@ -15,7 +15,48 @@ librygel-core is a collection of classes useful to Rygel's <ulink url="http://de
 </para>
 
 <para>
-librygel-renderer-gst is licensed under the GNU Lesser General Public License (LGPL).
+librygel-core is licensed under the GNU Lesser General Public License (LGPL).
 </para>
 
+<sect1>
+<title>Basic Usage</title>
+<para>
+Include the header:
+</para>
+<para>
+<programlisting>
+#include &lt;rygel-core.h&gt;
+</programlisting>
+</para>
+
+<para>
+If your source file is program.c, you can compile it with:
+</para>
+<para>
+<command>
+gcc program.cc -o program `pkg-config --cflags --libs rygel-core-2.0`
+</command>
+</para>
+
+<para>
+Alternatively, if using autoconf, use the following in configure.ac:
+</para>
+<para>
+<programlisting>
+PKG_CHECK_MODULES([DEPS], [rygel-core-2.0])
+</programlisting>
+</para>
+
+<para>
+Then use the generated DEPS_CFLAGS and DEPS_LIBS variables in the project Makefile.am files. For example:
+</para>
+<para>
+<programlisting>
+program_CPPFLAGS = $(DEPS_CFLAGS)
+program_LDADD = $(DEPS_LIBS)
+</programlisting>
+</para>
+
+</sect1>
+
 </section>
diff --git a/doc/reference/librygel-renderer-gst/Makefile.am b/doc/reference/librygel-renderer-gst/Makefile.am
index 772bc1a..9991391 100644
--- a/doc/reference/librygel-renderer-gst/Makefile.am
+++ b/doc/reference/librygel-renderer-gst/Makefile.am
@@ -27,6 +27,8 @@ RYGEL_DOCBUILD_VALADOC_FLAGS = \
 RYGEL_DOCBUILD_MODULE = rygel-renderer-gst
 RYGEL_DOCBUILD_EXTRA_GTKDOC_OPTIONS = -X -l -X $(top_builddir)/src/librygel-core/.libs/librygel-core-2.0.so \
                                       -X -l -X $(top_builddir)/src/librygel-renderer/.libs/librygel-renderer-2.0.so
+RYGEL_GTKDOC_DOCS_XML_EXTRA = $(top_srcdir)/doc/reference/lib$(RYGEL_DOCBUILD_MODULE)/gtkdoc/example.xml
+
 endif
 
 include $(top_srcdir)/doc/reference/doc-build.am
diff --git a/doc/reference/librygel-renderer-gst/gtkdoc/example.xml b/doc/reference/librygel-renderer-gst/gtkdoc/example.xml
new file mode 100644
index 0000000..76295e6
--- /dev/null
+++ b/doc/reference/librygel-renderer-gst/gtkdoc/example.xml
@@ -0,0 +1,22 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"; [
+<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+]>
+
+<section id="example">
+
+<!-- TODO: Find a way to mention this C example code in the RygelPlaybinRenderer valadoc comments instead. -->
+<para>
+This example program shows how to instantiate the renderer then configure its GStreamer playbin element
+and connect it to a network interface.
+</para>
+
+<!-- Do not indent the xi:include node. That puts spaces at the start of the code. -->
+<programlisting role="C">
+<xi:include  href="../../../../examples/standalone-renderer.c"
+    parse="text"
+    xmlns:xi="http://www.w3.org/2001/XInclude"/>
+</programlisting>
+
+</section>
diff --git a/doc/reference/librygel-renderer-gst/gtkdoc/librygel-renderer-gst-docs.xml b/doc/reference/librygel-renderer-gst/gtkdoc/librygel-renderer-gst-docs.xml
index 84eb006..6567937 100644
--- a/doc/reference/librygel-renderer-gst/gtkdoc/librygel-renderer-gst-docs.xml
+++ b/doc/reference/librygel-renderer-gst/gtkdoc/librygel-renderer-gst-docs.xml
@@ -20,6 +20,11 @@
     <xi:include href="overview.xml"/>
   </preface>
 
+  <chapter>
+    <title>Example</title>
+    <xi:include href="example.xml"/>
+  </chapter>
+
     <!-- These are generated: -->
   <chapter>
     <title>librygel-renderer-gst API Reference</title>
diff --git a/doc/reference/librygel-renderer-gst/gtkdoc/overview.xml b/doc/reference/librygel-renderer-gst/gtkdoc/overview.xml
index cabf596..372980b 100644
--- a/doc/reference/librygel-renderer-gst/gtkdoc/overview.xml
+++ b/doc/reference/librygel-renderer-gst/gtkdoc/overview.xml
@@ -13,24 +13,54 @@ librygel-renderer-gst is part of the <ulink url="http://rygel-project.org/";>Ryge
 <para>
 This library may be used to create UPnP or DLNA Renderers using GStreamer.
 The <link linkend="RygelPlaybinRenderer">RygelPlaybinRenderer</link> may
-wrap an existing GStreamer playbin or create its own.
+wrap an existing GStreamer playbin or create its own. See the 
+<link linkend="example">example</link>.
 </para>
 
-<!-- TODO: Find a way to mention this C example code in the RygelPlaybinRenderer valadoc comments instead. -->
 <para>
-This example program shows how to instantiate the renderer then configure its GStreamer playbin element
-and connect it to a network interface.
+librygel-renderer-gst is licensed under the GNU Lesser General Public License (LGPL).
 </para>
 
-<!-- Do not indent the xi:include node. That puts spaces at the start of the code. -->
-<programlisting role="C">
-<xi:include  href="../../../../examples/standalone-renderer.c"
-    parse="text"
-    xmlns:xi="http://www.w3.org/2001/XInclude"/>
+
+<sect1 id="basic-usage">
+<title>Basic Usage</title>
+<para>
+Include the header:
+</para>
+<para>
+<programlisting>
+#include &lt;rygel-renderer-gst.h&gt;
 </programlisting>
+</para>
 
 <para>
-librygel-renderer-gst is licensed under the GNU Lesser General Public License (LGPL).
+If your source file is program.c, you can compile it with:
+</para>
+<para>
+<command>
+gcc program.cc -o program `pkg-config --cflags --libs rygel-renderer-gst-2.0`
+</command>
+</para>
+
+<para>
+Alternatively, if using autoconf, use the following in configure.ac:
+</para>
+<para>
+<programlisting>
+PKG_CHECK_MODULES([DEPS], [rygel-renderer-gst-2.0])
+</programlisting>
 </para>
 
+<para>
+Then use the generated DEPS_CFLAGS and DEPS_LIBS variables in the project Makefile.am files. For example:
+</para>
+<para>
+<programlisting>
+program_CPPFLAGS = $(DEPS_CFLAGS)
+program_LDADD = $(DEPS_LIBS)
+</programlisting>
+</para>
+
+</sect1>
+
 </section>
diff --git a/doc/reference/librygel-renderer/gtkdoc/overview.xml b/doc/reference/librygel-renderer/gtkdoc/overview.xml
index 9ff83d3..0d67dea 100644
--- a/doc/reference/librygel-renderer/gtkdoc/overview.xml
+++ b/doc/reference/librygel-renderer/gtkdoc/overview.xml
@@ -17,7 +17,49 @@ to implement its RygelPlaybinRenderer renderer.
 </para>
 
 <para>
-librygel-renderer-gst is licensed under the GNU Lesser General Public License (LGPL).
+librygel-renderer is licensed under the GNU Lesser General Public License (LGPL).
 </para>
 
+
+<sect1>
+<title>Basic Usage</title>
+<para>
+Include the header:
+</para>
+<para>
+<programlisting>
+#include &lt;rygel-renderer.h&gt;
+</programlisting>
+</para>
+
+<para>
+If your source file is program.c, you can compile it with:
+</para>
+<para>
+<command>
+gcc program.cc -o program `pkg-config --cflags --libs rygel-renderer-2.0`
+</command>
+</para>
+
+<para>
+Alternatively, if using autoconf, use the following in configure.ac:
+</para>
+<para>
+<programlisting>
+PKG_CHECK_MODULES([DEPS], [rygel-renderer-2.0])
+</programlisting>
+</para>
+
+<para>
+Then use the generated DEPS_CFLAGS and DEPS_LIBS variables in the project Makefile.am files. For example:
+</para>
+<para>
+<programlisting>
+program_CPPFLAGS = $(DEPS_CFLAGS)
+program_LDADD = $(DEPS_LIBS)
+</programlisting>
+</para>
+
+</sect1>
+
 </section>
diff --git a/doc/reference/librygel-server/Makefile.am b/doc/reference/librygel-server/Makefile.am
index db8b17e..229c116 100644
--- a/doc/reference/librygel-server/Makefile.am
+++ b/doc/reference/librygel-server/Makefile.am
@@ -23,6 +23,11 @@ RYGEL_DOCBUILD_VALADOC_FLAGS = \
 
 RYGEL_DOCBUILD_MODULE = rygel-server
 RYGEL_DOCBUILD_EXTRA_GTKDOC_OPTIONS = -X -l -X $(top_builddir)/src/librygel-core/.libs/librygel-core-2.0.so
+
+RYGEL_GTKDOC_DOCS_XML_EXTRA = $(top_srcdir)/doc/reference/lib$(RYGEL_DOCBUILD_MODULE)/gtkdoc/implementing-servers.xml \
+		$(top_srcdir)/doc/reference/lib$(RYGEL_DOCBUILD_MODULE)/gtkdoc/implementing-server-plugins.xml \
+		$(top_srcdir)/doc/reference/lib$(RYGEL_DOCBUILD_MODULE)/gtkdoc/implementing-media-engines.xml
+
 endif
 
 include $(top_srcdir)/doc/reference/doc-build.am
diff --git a/doc/reference/librygel-server/gtkdoc/implementing-servers.xml b/doc/reference/librygel-server/gtkdoc/implementing-servers.xml
index 7508f83..a1d86c5 100644
--- a/doc/reference/librygel-server/gtkdoc/implementing-servers.xml
+++ b/doc/reference/librygel-server/gtkdoc/implementing-servers.xml
@@ -7,8 +7,7 @@
 <section id="implementing-servers">
 
 <para>
-This library may be used to create UPnP or DLNA servers via its
-The <link linkend="RygelMediaServer">RygelMediaServer</link>.
+This library may be used to create UPnP or DLNA servers via its <link linkend="RygelMediaServer">RygelMediaServer</link> class.
 </para>
 
 <!-- TODO: Find a way to mention this C example code in the RygelMediaServer valadoc comments instead. -->
diff --git a/doc/reference/librygel-server/gtkdoc/librygel-server-docs.xml b/doc/reference/librygel-server/gtkdoc/librygel-server-docs.xml
index 1a9ccb9..c6d62ca 100644
--- a/doc/reference/librygel-server/gtkdoc/librygel-server-docs.xml
+++ b/doc/reference/librygel-server/gtkdoc/librygel-server-docs.xml
@@ -21,6 +21,11 @@
   </preface>
 
   <chapter>
+    <title>Implementing Servers</title>
+    <xi:include href="implementing-servers.xml"/>
+  </chapter>
+
+  <chapter>
     <title>Implementing Rygel Server Plugins</title>
     <xi:include href="implementing-server-plugins.xml"/>
   </chapter>
@@ -30,11 +35,6 @@
     <xi:include href="implementing-media-engines.xml"/>
   </chapter>
 
-  <chapter>
-    <title>Implementing Servers</title>
-    <xi:include href="implementing-servers.xml"/>
-  </chapter>
-
   <!-- These are generated: -->
   <chapter>
     <title>librygel-server API Reference</title>
diff --git a/doc/reference/librygel-server/gtkdoc/overview.xml b/doc/reference/librygel-server/gtkdoc/overview.xml
index b3de263..c646b40 100644
--- a/doc/reference/librygel-server/gtkdoc/overview.xml
+++ b/doc/reference/librygel-server/gtkdoc/overview.xml
@@ -11,7 +11,57 @@ librygel-server is part of the <ulink url="http://rygel-project.org/";>Rygel</uli
 </para>
 
 <para>
+This library may be used to:
+  <itemizedlist>
+    <listitem><link linkend="implementing-servers">Create UPnP or DLNA servers</link>, such as the Rygel server.</listitem>
+    <listitem><link linkend="implementing-server-plugins">Create Rygel Server plugins</link></listitem>
+    <listitem><link linkend="implementing-media-engines">Create Rygel Media Engines</link></listitem>
+  </itemizedlist>
+</para>
+
+<para>
 librygel-server is licensed under the GNU Lesser General Public License (LGPL).
 </para>
 
+<sect1>
+<title>Basic Usage</title>
+<para>
+Include the header:
+</para>
+<para>
+<programlisting>
+#include &lt;rygel-server.h&gt;
+</programlisting>
+</para>
+
+<para>
+If your source file is program.c, you can compile it with:
+</para>
+<para>
+<command>
+gcc program.cc -o program `pkg-config --cflags --libs ryhttp://git.gnome.org/browse/rygel/commit/doc/reference/librygel-server/gtkdoc/overview.xml?id=b5748f34b25c5fc260d4f21969e2fb2cb8b5a1c2gel-server-2.0`
+</command>
+</para>
+
+<para>
+Alternatively, if using autoconf, use the following in configure.ac:
+</para>
+<para>
+<programlisting>
+PKG_CHECK_MODULES([DEPS], [rygel-server-2.0])
+</programlisting>
+</para>
+
+<para>
+Then use the generated DEPS_CFLAGS and DEPS_LIBS variables in the project Makefile.am files. For example:
+</para>
+<para>http://git.gnome.org/browse/rygel/commit/doc/reference/librygel-server/gtkdoc/overview.xml?id=b5748f34b25c5fc260d4f21969e2fb2cb8b5a1c2
+<programlisting>
+program_CPPFLAGS = $(DEPS_CFLAGS)
+program_LDADD = $(DEPS_LIBS)
+</programlisting>
+</para>
+
+</sect1>
+
 </section>
diff --git a/src/librygel-renderer-gst/rygel-playbin-renderer.vala b/src/librygel-renderer-gst/rygel-playbin-renderer.vala
index 9438a3e..740401c 100644
--- a/src/librygel-renderer-gst/rygel-playbin-renderer.vala
+++ b/src/librygel-renderer-gst/rygel-playbin-renderer.vala
@@ -56,7 +56,7 @@ internal class Rygel.Playbin.WrappingPlugin : Rygel.MediaRendererPlugin {
  * to be controlled by a control point and to retrieve data streams via that
  * network interface.
  *
- * See the example code in the <link linkend="overview">overview</link>.
+ * See the <link linkend="example">example</link>.
  */
 public class Rygel.Playbin.Renderer : Rygel.MediaDevice {
     /**
diff --git a/src/librygel-server/rygel-media-server-plugin.vala b/src/librygel-server/rygel-media-server-plugin.vala
index 19aaf54..cbea507 100644
--- a/src/librygel-server/rygel-media-server-plugin.vala
+++ b/src/librygel-server/rygel-media-server-plugin.vala
@@ -24,8 +24,8 @@
 
 /**
  * This is the base class for every Rygel implementation of a UPnP media
- * server. It should be used either for a real plug-in for the rygel process or used
- * in-process via the librygel-server API (see the standalone-server.c example).
+ * server. It should be used either for a real plug-in for the Rygel process or used
+ * in-process via the librygel-server API.
  */
 public abstract class Rygel.MediaServerPlugin : Rygel.Plugin {
     private static const string MEDIA_SERVER_DESC_PATH =
diff --git a/src/librygel-server/rygel-media-server.vala b/src/librygel-server/rygel-media-server.vala
index afa61f3..eee9018 100644
--- a/src/librygel-server/rygel-media-server.vala
+++ b/src/librygel-server/rygel-media-server.vala
@@ -31,7 +31,8 @@ internal class Plugin : Rygel.MediaServerPlugin {
  * Call rygel_media_device_add_interface() on the RygelMediaServer to allow it
  * to serve media via that network interface.
  *
- * See the example code in the <link linkend="overview">overview</link>.
+ * See the example code in the 
+ * <link linkend="implementing-servers">Implementing Servers</link> section.
  */
 public class Rygel.MediaServer : MediaDevice {
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]