Build/install man pages.

git-svn-id: http://svn.drobilla.net/lad/slv2@928 a436a847-0d15-0410-975c-d299462d15a1

17 files changed, 126 insertions, 85 deletions

diff --git a/Makefile.am b/Makefile.am
index 7a4fdab..24a7967 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -13,8 +13,9 @@ dist-check-doxygen:
 	@false
 endif
 
-SUBDIRS      = src slv2 utils hosts data $(DOC_DIR) swig debian
-DIST_SUBDIRS = src slv2 utils hosts data doc swig debian
+#SUBDIRS      = src slv2 utils hosts data $(DOC_DIR) swig debian
+#DIST_SUBDIRS = src slv2 utils hosts data doc swig debian
+SUBDIRS = src slv2 utils hosts data doc swig debian
 
 pkgconfigdir = $(libdir)/pkgconfig
 pkgconfig_DATA = slv2.pc
@@ -25,5 +26,8 @@ distclean-local:
 	rm -rf doc/slv2
 	rm -rf doc/reference.doxygen
 
+docs:
+	cd doc && make docs
+
 deb:
 	debuild -i --lintian-opts -i
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 8b64001..50532ed 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,7 +1,15 @@
-EXTRA_DIST = mainpage.dox reference.doxygen
+EXTRA_DIST = mainpage.dox man.dox html.dox reference.doxygen
 
-all-local: doc
+man_MANS = \
+	@abs_top_builddir@/doc/slv2/man/man3/slv2.3 \
+	@abs_top_builddir@/doc/slv2/man/man3/slv2_collections.3 \
+	@abs_top_builddir@/doc/slv2/man/man3/slv2_data.3 \
+	@abs_top_builddir@/doc/slv2/man/man3/slv2_library.3 \
+	@abs_top_builddir@/doc/slv2/man/man3/slv2_util.3 \
+	@abs_top_builddir@/doc/slv2/man/man3/slv2_world.3
 
-doc: $(srcdir)/reference.doxygen.in reference.doxygen $(srcdir)/../slv2/*.h
+all-local: docs
+
+docs: $(srcdir)/reference.doxygen.in reference.doxygen $(srcdir)/../slv2/*.h
 	mkdir -p @abs_top_builddir@/doc/slv2
 	doxygen reference.doxygen
diff --git a/doc/mainpage.dox b/doc/mainpage.dox
index dd5b986..6f0a37a 100644
--- a/doc/mainpage.dox
+++ b/doc/mainpage.dox
@@ -1,27 +1,60 @@
-/** @mainpage
-
-@section Overview
-
-SLV2 is a host library to simplify the discovery, loading, and use of LV2
-plugins (http://lv2plug.in).
-
-SLV2 is written in standard C99, and depends only on the Redland RDF library
-(http://librdf.org).  It should be portable to any system, and is tested on various
-GNU/Linux distributions (often), and Mac OSX (occasionally).
-
-The public interface of SLV2 is documented in several sections.  The RDF and shared
-library functionality is strictly divided so it is simple to understand when each is
-being used (e.g. it is possible to discover/investigate plugins and related data
-without loading any shared libraries, avoiding the associated risks).
+/* This duplication sucks :( */
 
-\li \link world World \endlink - Global library initialisation, state, plugin discovery, etc.
+/* HTML */
 
-\li \link util Util \endlink - Generally useful utility functions
-
-\li \link collections Collections \endlink - Collections of values (literals and URIs) and objects
-
-\li \link data Data \endlink - Access to plugin RDF data
-
-\li \link lib Library \endlink - Access to plugin shared libraries
-
-*/
+/** @mainpage
+ * @section Overview
+ * 
+ * SLV2 is a host library to simplify the discovery, loading, and use of LV2
+ * plugins (http://lv2plug.in).
+ * 
+ * SLV2 is written in standard C99, and depends only on the Redland RDF library
+ * (http://librdf.org).  It should be portable to any system with Redland, and
+ * is tested on various GNU/Linux distributions (often), and MacOS X (occasionally).
+ * 
+ * The Data (RDF) and code (shared library) functionality in SLV2 is strictly
+ * separated so it is simple to control where each is used (e.g. it is
+ * possible to discover/investigate plugins and related data without loading
+ * any shared libraries, avoiding the associated risks).
+ * 
+ * The SLV2 documentation is broken into several pages:
+ * 
+ * \li \link slv2_world slv2_world \endlink - Global library initialisation, state, plugin discovery, etc.
+ * 
+ * \li \link slv2_util slv2_util \endlink - Generally useful utility functions
+ * 
+ * \li \link slv2_collections slv2_collections \endlink - Collections of values (literals and URIs) and objects
+ * 
+ * \li \link slv2_data slv2_data \endlink - Access to plugin RDF data
+ * 
+ * \li \link slv2_library slv2_library \endlink - Access to plugin shared libraries
+ */
+
+
+/* man page */
+
+/** @defgroup slv2 SLV2
+ * SLV2 is a host library to simplify the discovery, loading, and use of LV2
+ * plugins (http://lv2plug.in).
+ * 
+ * SLV2 is written in standard C99, and depends only on the Redland RDF library
+ * (http://librdf.org).  It should be portable to any system with Redland, and
+ * is tested on various GNU/Linux distributions (often), and MacOS X (occasionally).
+ * 
+ * The Data (RDF) and code (shared library) functionality in SLV2 is strictly
+ * separated so it is simple to control where each is used (e.g. it is
+ * possible to discover/investigate plugins and related data without loading
+ * any shared libraries, avoiding the associated risks).
+ * 
+ * The SLV2 documentation is broken into several pages:
+ * 
+ * \li \link slv2_world slv2_world \endlink - Global library initialisation, state, plugin discovery, etc.
+ * 
+ * \li \link slv2_util slv2_util \endlink - Generally useful utility functions
+ * 
+ * \li \link slv2_collections slv2_collections \endlink - Collections of values (literals and URIs) and objects
+ * 
+ * \li \link slv2_data slv2_data \endlink - Access to plugin RDF data
+ * 
+ * \li \link slv2_library slv2_library \endlink - Access to plugin shared libraries
+ */
diff --git a/doc/reference.doxygen.in b/doc/reference.doxygen.in
index 34fa7ca..b7fbe90 100644
--- a/doc/reference.doxygen.in
+++ b/doc/reference.doxygen.in
@@ -38,7 +38,7 @@ PROJECT_NUMBER         = @PACKAGE_VERSION@
 # If a relative path is entered, it will be relative to the location 
 # where doxygen was started. If left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = @abs_top_builddir@/doc/slv2
+OUTPUT_DIRECTORY       = @top_builddir@/doc/slv2
 
 # If the CREATE_SUBDIRS tag is set to YES, then doxygen will create 
 # 4096 sub-directories (in 2 levels) under the output directory of each output 
@@ -66,14 +66,14 @@ OUTPUT_LANGUAGE        = English
 # the file and class documentation (similar to JavaDoc). 
 # Set to NO to disable this.
 
-BRIEF_MEMBER_DESC      = YES
+BRIEF_MEMBER_DESC      = NO
 
 # If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend 
 # the brief description of a member or function before the detailed description. 
 # Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the 
 # brief descriptions will be completely suppressed.
 
-REPEAT_BRIEF           = YES
+REPEAT_BRIEF           = NO
 
 # This tag implements a quasi-intelligent brief description abbreviator 
 # that is used to form the text in various listings. Each string 
@@ -462,22 +462,23 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.
 
-INPUT                  = @abs_srcdir@/../doc/mainpage.dox \
-                         @abs_srcdir@/../slv2/lv2.h \
-                         @abs_srcdir@/../slv2/types.h \
-                         @abs_srcdir@/../slv2/util.h \
-                         @abs_srcdir@/../slv2/value.h \
-                         @abs_srcdir@/../slv2/values.h \
-                         @abs_srcdir@/../slv2/world.h \
-                         @abs_srcdir@/../slv2/plugin.h \
-                         @abs_srcdir@/../slv2/pluginclass.h \
-                         @abs_srcdir@/../slv2/pluginclasses.h \
-                         @abs_srcdir@/../slv2/plugininstance.h \
-                         @abs_srcdir@/../slv2/plugins.h \
-                         @abs_srcdir@/../slv2/port.h \
-                         @abs_srcdir@/../slv2/pluginui.h \
-                         @abs_srcdir@/../slv2/pluginuis.h \
-                         @abs_srcdir@/../slv2/pluginuiinstance.h
+INPUT                  = @SLV2_SRCDIR@/doc/mainpage.dox \
+                         @SLV2_SRCDIR@/slv2/types.h \
+                         @SLV2_SRCDIR@/slv2/util.h \
+                         @SLV2_SRCDIR@/slv2/value.h \
+                         @SLV2_SRCDIR@/slv2/values.h \
+                         @SLV2_SRCDIR@/slv2/world.h \
+                         @SLV2_SRCDIR@/slv2/plugin.h \
+                         @SLV2_SRCDIR@/slv2/pluginclass.h \
+                         @SLV2_SRCDIR@/slv2/pluginclasses.h \
+                         @SLV2_SRCDIR@/slv2/plugininstance.h \
+                         @SLV2_SRCDIR@/slv2/plugins.h \
+                         @SLV2_SRCDIR@/slv2/port.h \
+                         @SLV2_SRCDIR@/slv2/pluginui.h \
+                         @SLV2_SRCDIR@/slv2/pluginuis.h \
+                         @SLV2_SRCDIR@/slv2/pluginuiinstance.h
+                         
+						 #@SLV2_SRCDIR@/slv2/lv2.h \
 
 # This tag can be used to specify the character encoding of the source files that 
 # doxygen parses. Internally doxygen uses the UTF-8 encoding, which is also the default 
diff --git a/slv2/plugin.h b/slv2/plugin.h
index c22fda5..b7a436e 100644
--- a/slv2/plugin.h
+++ b/slv2/plugin.h
@@ -29,10 +29,10 @@ extern "C" {
 #include <slv2/port.h>
 #include <slv2/values.h>
 
-/** \defgroup data Plugin data access
+/** \defgroup slv2_data Plugin data access
  *
- * These functions work exclusively with the plugin's RDF data.
- * They do not load or access the plugin dynamic library in any way.
+ * These functions work exclusively with the plugin's RDF data,
+ * they do not access the plugin's shared library in any way.
  *
  * An SLV2Plugin contains an in-memory cache of the plugin data, loaded
  * on demand.  Duplicating plugins should be avoided when possible for
diff --git a/slv2/pluginclass.h b/slv2/pluginclass.h
index 3dacfd7..14449ab 100644
--- a/slv2/pluginclass.h
+++ b/slv2/pluginclass.h
@@ -25,7 +25,7 @@ extern "C" {
 
 #include <slv2/types.h>
 
-/** \addtogroup data
+/** \addtogroup slv2_data
  * @{
  */
 
diff --git a/slv2/pluginclasses.h b/slv2/pluginclasses.h
index e95710b..b4cd08d 100644
--- a/slv2/pluginclasses.h
+++ b/slv2/pluginclasses.h
@@ -25,7 +25,7 @@
 extern "C" {
 #endif
 
-/** \addtogroup collections
+/** \addtogroup slv2_collections
  * @{
  */
 
diff --git a/slv2/plugininstance.h b/slv2/plugininstance.h
index a78b644..c960e86 100644
--- a/slv2/plugininstance.h
+++ b/slv2/plugininstance.h
@@ -28,33 +28,31 @@ extern "C" {
 #include <slv2/plugin.h>
 #include <slv2/port.h>
 
-/** \defgroup lib Plugin library access
- *
- * An SLV2Instance is an instantiated SLV2Plugin (ie a loaded dynamic
- * library).  These functions interact with the binary library code only,
- * they do not read data files in any way.
- * 
- * @{
- */
-
-
 typedef struct _InstanceImpl* SLV2InstanceImpl;
 
-
-/** Instance of a plugin.
+/* Instance of a plugin.
  *
  * The LV2 descriptor and handle of this are exposed to allow inlining of
  * performance critical functions like slv2_instance_run (which are exposed
- * in lv2.h anyway).  The remaining implementation details are
- * in the opaque pimpl member.
+ * in lv2.h anyway).  This is for performance only, this struct is not
+ * documented and should not be used directly.  The remaining implementation
+ * details are in the opaque pimpl member.
  */
-typedef struct _Instance {
+typedef struct {
 	const LV2_Descriptor* lv2_descriptor;
 	LV2_Handle            lv2_handle;
 	SLV2InstanceImpl      pimpl; ///< Private implementation
 }* SLV2Instance;
 
 
+/** \defgroup slv2_library Plugin library access
+ *
+ * An SLV2Instance is an instantiated SLV2Plugin (ie a loaded dynamic
+ * library).  These functions interact with the binary library code only,
+ * they do not read data files in any way.
+ * 
+ * @{
+ */
 
 /** Instantiate a plugin.
  *
diff --git a/slv2/plugins.h b/slv2/plugins.h
index 1ca4cc7..6b8eead 100644
--- a/slv2/plugins.h
+++ b/slv2/plugins.h
@@ -26,7 +26,7 @@
 extern "C" {
 #endif
 
-/** \addtogroup collections
+/** \addtogroup slv2_collections
  * @{
  */
 
diff --git a/slv2/pluginui.h b/slv2/pluginui.h
index cd5fd3a..7de54aa 100644
--- a/slv2/pluginui.h
+++ b/slv2/pluginui.h
@@ -23,7 +23,7 @@
 extern "C" {
 #endif
 
-/** \addtogroup data
+/** \addtogroup slv2_data
  * @{
  */
 
diff --git a/slv2/pluginuiinstance.h b/slv2/pluginuiinstance.h
index ba2ada6..2723585 100644
--- a/slv2/pluginuiinstance.h
+++ b/slv2/pluginuiinstance.h
@@ -28,16 +28,9 @@ extern "C" {
 #include <slv2/lv2_gui.h>
 #include <slv2/plugin.h>
 
-/** \addtogroup lib
- * @{
- */
-
-
 typedef struct _SLV2UIInstanceImpl* SLV2UIInstanceImpl;
 
-  
-
-/** Instance of a plugin UI.
+/* Instance of a plugin UI.
  *
  * All details are in hidden in the pimpl member to avoid making the
  * implementation a part of the ABI.
@@ -47,6 +40,10 @@ typedef struct _SLV2UIInstance {
 }* SLV2UIInstance;
 
 
+/** \addtogroup slv2_library
+ * @{
+ */
+
 
 /** Instantiate a plugin UI.
  *
diff --git a/slv2/pluginuis.h b/slv2/pluginuis.h
index f3eb699..b14e61a 100644
--- a/slv2/pluginuis.h
+++ b/slv2/pluginuis.h
@@ -26,7 +26,7 @@
 extern "C" {
 #endif
 
-/** \addtogroup collections
+/** \addtogroup slv2_collections
  *
  * @{
  */
diff --git a/slv2/port.h b/slv2/port.h
index dc477cd..2cf0e30 100644
--- a/slv2/port.h
+++ b/slv2/port.h
@@ -28,7 +28,7 @@ extern "C" {
 #include <slv2/port.h>
 #include <slv2/values.h>
 
-/** \addtogroup data
+/** \addtogroup slv2_data
  * @{
  */
 
diff --git a/slv2/util.h b/slv2/util.h
index 1bd2847..0313f6e 100644
--- a/slv2/util.h
+++ b/slv2/util.h
@@ -25,7 +25,7 @@
 extern "C" {
 #endif
 
-/** \defgroup util Utility functions
+/** \defgroup slv2_util Utility functions
  *
  * @{
  */
diff --git a/slv2/value.h b/slv2/value.h
index 0d8f9dc..00cd39a 100644
--- a/slv2/value.h
+++ b/slv2/value.h
@@ -26,7 +26,7 @@ extern "C" {
 #include <stdbool.h>
 #include <slv2/types.h>
 
-/** \addtogroup data
+/** \addtogroup slv2_data
  * @{
  */
 
diff --git a/slv2/values.h b/slv2/values.h
index 2535bdd..9d6c717 100644
--- a/slv2/values.h
+++ b/slv2/values.h
@@ -26,7 +26,7 @@
 extern "C" {
 #endif
 
-/** \defgroup collections Collections of values/objects
+/** \defgroup slv2_collections Collections of values/objects
  *
  * Ordered collections of typed values which are fast for random
  * access by index (i.e. a fancy array).
diff --git a/slv2/world.h b/slv2/world.h
index 01e671c..610d830 100644
--- a/slv2/world.h
+++ b/slv2/world.h
@@ -27,7 +27,7 @@
 extern "C" {
 #endif
 
-/** \defgroup world Global library state
+/** \defgroup slv2_world Global library state
  * 
  * The "world" represents all library state, and the data found in bundles'
  * manifest.ttl (ie it is an in-memory index of all things LV2 found).