docs: librygel-server: Add sub-sections.

Move the chapter tags into the implementing-*.xml files,
so we can have multiple sections in them. Give the chapters an ID
so they can have meaningful URLs.
Also link to the (unfinished) full rygel server plugin example.

4 files changed, 56 insertions, 19 deletions

diff --git a/doc/reference/librygel-server/gtkdoc/implementing-media-engines.xml b/doc/reference/librygel-server/gtkdoc/implementing-media-engines.xml
index 109eea39..72649512 100644
--- a/doc/reference/librygel-server/gtkdoc/implementing-media-engines.xml
+++ b/doc/reference/librygel-server/gtkdoc/implementing-media-engines.xml
@@ -4,7 +4,11 @@
 <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
 ]>
 
-<section id="implementing-media-engines">
+<chapter id="implementing-media-engines">
+<title>Implementing Rygel Media Engines</title>
+
+<section id="implementing-media-engines-overview">
+<title>Implementing Media Engines: Overview</title>
 
 <para>
 This library may be used to create Rygel media engines by 
@@ -31,6 +35,14 @@ returning an instance of it from its create_data_source() implementation.</para>
 </orderedlist>
 </para>
 
+</section>
+
+
+<section id="implementing-server-plugins-full-example">
+<title>Implementing Media Engines: Full Example</title>
+
 <para>In addition, the external <ulink url="http://git.gnome.org/browse/rygel-gst-0-10-media-engine">rygel-gst-0-10-media-engine</ulink> project provides a Rygel media engine that uses an older GStreamer version and is an example of an external Rygel media-engine implemented in C.</para>
 
 </section>
+
+</chapter>
diff --git a/doc/reference/librygel-server/gtkdoc/implementing-server-plugins.xml b/doc/reference/librygel-server/gtkdoc/implementing-server-plugins.xml
index ec399bbb..e5fbe53c 100644
--- a/doc/reference/librygel-server/gtkdoc/implementing-server-plugins.xml
+++ b/doc/reference/librygel-server/gtkdoc/implementing-server-plugins.xml
@@ -5,13 +5,25 @@
 <!ENTITY url_git_browse_base_src "http://git.gnome.org/browse/rygel/tree/src/">
 ]>
 
-<section id="implementing-server-plugins">
+<chapter id="implementing-server-plugins">
+<title>Implementing Rygel Server Plugins</title>
+
+<section id="implementing-server-plugins-overview">
+<title>Implementing Server Plugins: Overview</title>
 
 <para>
 This library may be used to create Rygel server plugins by 
-implementing the <link linkend="RygelMediaServerPlugin">RygelMediaServerPlugin</link> class.
+implementing the <link linkend="RygelMediaServerPlugin">RygelMediaServerPlugin</link> class.</para>
+
+<para>The <link linkend="RygelMediaServerPlugin">RygelMediaServerPlugin</link> reference documentation 
+and these examples explain how to implement these plugins.
 </para>
 
+</section>
+
+<section id="implementing-server-plugins-simple-example">
+<title>Implementing Server Plugins: Simple Example</title>
+
 <!-- TODO: Find a way to mention this C example code in the RygelMediaServer valadoc comments instead. -->
 <para>
 This example source code shows how to implement a Rygel Server plugin.</para>
@@ -22,7 +34,8 @@ hard-coded items. A real Rygel server plugin's root container, or its child item
 populate themselves dynamically. For instance, they might add and remove items based on some source
 such as a file system or database. See, for instance, the 
 <ulink url="&url_git_browse_base_src;plugins/tracker">Rygel Tracker Plugin</ulink> or the
-<ulink url="&url_git_browse_base_src;plugins/media-export">Rygel MediaExport Plugin</ulink>.
+<ulink url="&url_git_browse_base_src;plugins/media-export">Rygel MediaExport Plugin</ulink> plugins,
+implemented in Vala.
 </para>
 
 <!-- Do not indent the xi:include node. That puts spaces at the start of the code. -->
@@ -49,3 +62,11 @@ such as a file system or database. See, for instance, the
 
 </section>
 
+<section id="implementing-server-plugins-full-example">
+<title>Implementing Server Plugins: Full Example</title>
+
+<para>In addition, the external <ulink url="http://git.gnome.org/browse/rygel-gst-0-10-plugins">rygel-gst-0-10-plugins</ulink> project provides a Rygel Server plugin that uses an older GStreamer version and is an example of an external Rygel Server plugin implemented in C. Its <ulink url="http://git.gnome.org/browse/rygel-gst-0-10-plugins">media-export</ulink> plugin </para>
+
+</section>
+
+</chapter>
diff --git a/doc/reference/librygel-server/gtkdoc/implementing-servers.xml b/doc/reference/librygel-server/gtkdoc/implementing-servers.xml
index 80ca1b30..ca9171c9 100644
--- a/doc/reference/librygel-server/gtkdoc/implementing-servers.xml
+++ b/doc/reference/librygel-server/gtkdoc/implementing-servers.xml
@@ -4,12 +4,25 @@
 <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
 ]>
 
-<section id="implementing-servers">
+<chapter id="implementing-servers">
+<title>Implementing Servers</title>
+
+<section id="implementing-servers-overview">
+<title>Implementing Servers: Overview</title>
 
 <para>
 This library may be used to create UPnP or DLNA servers via its <link linkend="RygelMediaServer">RygelMediaServer</link> class.
 </para>
 
+<para>The <link linkend="RygelMediaServer">RygelMediaServer</link> reference documentation 
+and this example explains how to implement a server.
+</para>
+
+</section>
+
+<section id="implementing-servers-simple-example">
+<title>Implementing Servers: Simple Example</title>
+
 <!-- TODO: Find a way to mention this C example code in the RygelMediaServer valadoc comments instead. -->
 <para>
 This example program shows how to fill a container with media items and then instantiate a server to serve 
@@ -24,3 +37,5 @@ them.
 </programlisting>
 
 </section>
+
+</chapter>
diff --git a/doc/reference/librygel-server/gtkdoc/librygel-server-docs.xml b/doc/reference/librygel-server/gtkdoc/librygel-server-docs.xml
index c6d62ca2..503a0488 100644
--- a/doc/reference/librygel-server/gtkdoc/librygel-server-docs.xml
+++ b/doc/reference/librygel-server/gtkdoc/librygel-server-docs.xml
@@ -20,20 +20,9 @@
     <xi:include href="overview.xml"/>
   </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>
-
-  <chapter>
-    <title>Implementing Rygel Media Engines</title>
-    <xi:include href="implementing-media-engines.xml"/>
-  </chapter>
+  <xi:include href="implementing-servers.xml"/>
+  <xi:include href="implementing-server-plugins.xml"/>
+  <xi:include href="implementing-media-engines.xml"/>
 
   <!-- These are generated: -->
   <chapter>