From 66d5e28a5704deb3fd15d2e4d2cb9f1b30f983ba Mon Sep 17 00:00:00 2001 From: David Robillard Date: Fri, 30 Nov 2007 22:00:00 +0000 Subject: Build/install man pages. git-svn-id: http://svn.drobilla.net/lad/slv2@928 a436a847-0d15-0410-975c-d299462d15a1 --- Makefile.am | 8 +++-- doc/Makefile.am | 14 ++++++-- doc/mainpage.dox | 83 +++++++++++++++++++++++++++++++++--------------- doc/reference.doxygen.in | 39 ++++++++++++----------- slv2/plugin.h | 6 ++-- slv2/pluginclass.h | 2 +- slv2/pluginclasses.h | 2 +- slv2/plugininstance.h | 28 ++++++++-------- slv2/plugins.h | 2 +- slv2/pluginui.h | 2 +- slv2/pluginuiinstance.h | 13 +++----- slv2/pluginuis.h | 2 +- slv2/port.h | 2 +- slv2/util.h | 2 +- slv2/value.h | 2 +- slv2/values.h | 2 +- slv2/world.h | 2 +- 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 #include -/** \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 -/** \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 #include -/** \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 #include -/** \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 #include -/** \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 #include -/** \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). -- cgit v1.2.1