diff --git a/doc/build-howto.xml b/doc/build-howto.xml deleted file mode 100644 index c22c78a..0000000 --- a/doc/build-howto.xml +++ /dev/null @@ -1,89 +0,0 @@ - - - - %gtkdocentities; -]> - - - - Compiling with &package_string; - 3 - - - - Compiling with &package_string;Notes on compiling - - - - Using pkg-config - - Like other GNOME libraries, - &package_string; uses - pkg-config to provide compiler options. The - package name is - "&package_ver_str;". So in - your configure.ac script, you might specify something - like: - - - PKG_CHECK_MODULES(LIBFEEDBACK, [&package_string;-&package_api_version;]) - AC_SUBST(LIBFEEDBACK_CFLAGS) - AC_SUBST(LIBFEEDBACK_LIBS) - - - - Or if using Meson/Ninja use a dependency('&package_string;-&package_api_version;') - dependency. - - - - The "&package_api_version;" in the package name is the "API version" - (indicating "the version of the &package_string; API - that first appeared in version &package_api_version;") and is essentially just part of - the package name. - - - - When using the Meson build system you can declare a dependency like - - - dependency(libfeedback-0.0') - - - - - - Acknowledge the Instability - - - Since the library is young and is still changing a lot, in order to use it you are required to acknowledge that your are using an unstable API. - To do so, LIBFEEDBACK_USE_UNSTABLE_API must be defined for compilation to succeed. - - - - From C code or any compatible language, you can prefix your inclusion of the &package_string; header like so: - - - - #define LIBFEEDBACK_USE_UNSTABLE_API - #include <libfeedback.h> - - - - Including individual headers rather than libfeedback.h is not - recommended. - - - You can also acknoledge this with the definition option of your C compiler, like -DFEEDBACK_USE_UNSTABLE_API. - This is required from Vala. - - - - To use &package_name; from Vala, you must define the acknowledgment in C via -X -DFEEDBACK_USE_UNSTABLE_API. - If your build system uses a two pass compilation and hence your Vala compiler outputs C (Meson, Automake, or using the --ccode Vala compiler option trigger that) then you must add -DLIBFEEDBACK_USE_UNSTABLE_API to your C compiler argments instead. - - - - diff --git a/doc/libfeedback-docs.xml b/doc/libfeedback-docs.xml index ae2460e..5a9f5ad 100644 --- a/doc/libfeedback-docs.xml +++ b/doc/libfeedback-docs.xml @@ -27,16 +27,10 @@ - - Introduction + - - The purpose of libfeedback is to trigger audible, haptic and visual feedback based on - events. Events are identified by strings. - - - - + + API Reference Core API @@ -54,7 +48,8 @@ DBus Interface - + + Object Hierarchy diff --git a/doc/meson.build b/doc/meson.build index 5fc9fd5..1bc5648 100644 --- a/doc/meson.build +++ b/doc/meson.build @@ -6,7 +6,7 @@ private_headers = [ ] content_files = [ - 'build-howto.xml', + 'overview.xml', ] glib_prefix = dependency('glib-2.0').get_pkgconfig_variable('prefix') diff --git a/doc/overview.xml b/doc/overview.xml new file mode 100644 index 0000000..7f88681 --- /dev/null +++ b/doc/overview.xml @@ -0,0 +1,111 @@ + + + + %gtkdocentities; +]> + + + Libfeedback Overview + + + Introduction + + + The purpose of libfeedback is to make it simple to supply + audible, haptic and visual feedback to the user. This is done + by notifying a &feedback_daemon; over DBus that a certain event + happened and the daemon selects the appropriate feedbacks (such as + a buzzing haptic motor or playing an audio file) based + on the user session's current feedback profile, feedback theme and available + hardware. Events are identified by strings like + message-new-sms or + message-new-sms. The available event names are + described in the &event_naming_spec;. + + + &package; provides synchronous and asynchronous APIs to trigger + and stop feedback for these events and is usable from other languages + than C by GObject introspection. + + + + + Compiling libfeedback applications + + Using pkg-config + + Like other GNOME libraries, + &package_string; uses + pkg-config to provide compiler options. The + package name is + "&package_ver_str;". So in + your configure.ac script, you might specify something + like: + + + PKG_CHECK_MODULES(LIBFEEDBACK, [&package_string;-&package_api_version;]) + AC_SUBST(LIBFEEDBACK_CFLAGS) + AC_SUBST(LIBFEEDBACK_LIBS) + + + + + Using Meson/Ninja + + If using Meson/Ninja use a dependency('&package_string;-&package_api_version;') + dependency. + + + + The "&package_api_version;" in the package name is the "API version" + (indicating "the version of the &package_string; API + that first appeared in version &package_api_version;") and is essentially just part of + the package name. + + + + When using the Meson build system you can declare a dependency like + + + dependency(libfeedback-0.0') + + + + + + Acknowledge the Instability + + + Since the library is young and is still changing a lot, in order to use it you are required to acknowledge that your are using an unstable API. + To do so, LIBFEEDBACK_USE_UNSTABLE_API must be defined for compilation to succeed. + + + + From C code or any compatible language, you can prefix your inclusion of the &package_string; header like so: + + + + #define LIBFEEDBACK_USE_UNSTABLE_API + #include <libfeedback.h> + + + + Including individual headers rather than libfeedback.h is not + recommended. + + + You can also acknoledge this with the definition option of your C compiler, like -DFEEDBACK_USE_UNSTABLE_API. + This is required from Vala. + + + + To use &package_name; from Vala, you must define the acknowledgment in C via -X -DFEEDBACK_USE_UNSTABLE_API. + If your build system uses a two pass compilation and hence your Vala compiler outputs C (Meson, Automake, or using the --ccode Vala compiler option trigger that) then you must add -DLIBFEEDBACK_USE_UNSTABLE_API to your C compiler argments instead. + + + + + + diff --git a/doc/xml/gtkdocentities.ent.in b/doc/xml/gtkdocentities.ent.in index db8f29d..52726f3 100644 --- a/doc/xml/gtkdocentities.ent.in +++ b/doc/xml/gtkdocentities.ent.in @@ -7,3 +7,5 @@ +Event naming specification draft"> +Feedback Daemon">