Commit c2b61957 authored by Pierre Wieser's avatar Pierre Wieser

Review reference documentation

parent e8f3d294
......@@ -39,11 +39,11 @@
<chapter>
<title>&prodname; Overview</title>
<xi:include href="fma-about.xml" />
<xi:include href="fma-what-is-it.xml" />
<xi:include href="fma-getting.xml" />
<xi:include href="fma-dist-content.xml" />
<xi:include href="fma-compiling.xml" />
<xi:include href="fma-about.xml" />
</chapter>
<chapter>
......@@ -75,7 +75,7 @@
</chapter>
<chapter>
<title>NAObject Hierarchy</title>
<title>FMAObject Hierarchy</title>
<xi:include href="xml/object.xml"/>
<xi:include href="xml/object-id.xml"/>
<xi:include href="xml/object-item.xml"/>
......
......@@ -27,16 +27,56 @@
<para>
On UNIX, &prodname; uses the standard GNU build system,
using <ulink url="http://www.gnu.org/software/autoconf/">
<application>autoconf</application></ulink> for package
configuration and resolving portability issues,
<ulink url="http://www.gnu.org/software/automake/">
<application>automake</application></ulink> for building makefiles
that comply with the GNU Coding Standards, and
<ulink url="http://www.gnu.org/software/libtool/">
<application>libtool</application></ulink> for building shared
libraries on multiple platforms. The normal sequence for
compiling and installing the &prodname; package is thus:
using
<itemized list>
<listitem>
<para>
<ulink url="http://www.gnu.org/software/autoconf/">
<application>autoconf</application></ulink> for configuring
the package and resolving portability issues,
</para>
</listitem>
<listitem>
<para>
<ulink url="http://www.gnu.org/software/automake/">
<application>automake</application></ulink> for building
makefiles that comply with the GNU Coding Standards;
</para>
</listitem>
<listitem>
<para>
<ulink url="http://www.gnu.org/software/libtool/">
<application>libtool</application></ulink> for building
shared libraries which target multiple platforms;
</para>
</listitem>
<listitem>
<para>
<ulink url="http://www.freedesktop.org/software/pkgconfig/">pkg-config</ulink>
for tracking the compilation flags needed by used libraries
(For each library, a small <literal>.pc</literal> text file is
installed in a standard location that contains the compilation
flags needed for that library along with version number
information);
</para>
</listitem>
<listitem>
<para>
<ulink url="http://www.gnu.org/software/make">GNU make</ulink>
for actually building.
</para>
<para>
The &prodname; makefiles will mostly work with different versions
of <command>make</command>. However, there tends to be
a few incompatibilities, so the &prodname; team recommends
installing <ulink url="http://www.gnu.org/software/make">GNU make</ulink>
if you don't already have it on your system.
</para>
</listitem>
</itemizedlist>
The normal sequence for compiling and installing the &prodname;
package is thus:
<literallayout>
<userinput>./configure</userinput>
......@@ -59,40 +99,6 @@
<refsect1 id="dependencies">
<title>Dependencies</title>
<para>
Before you can compile the &prodname; package, you need to have
various other tools and libraries installed on your
system. The two main tools needed during the build process (as
differentiated from the tools used in when creating &prodname;
mentioned above such as <application>autoconf</application>)
are <command>pkg-config</command> and GNU make.
</para>
<itemizedlist>
<listitem>
<para>
<ulink url="http://www.freedesktop.org/software/pkgconfig/">pkg-config</ulink>
is a tool for tracking the compilation flags needed for
libraries that are used by the &prodname; package.
(For each library, a small <literal>.pc</literal> text file is
installed in a standard location that contains the compilation
flags needed for that library along with version number
information.)
</para>
</listitem>
<listitem>
<para>
The &prodname; makefiles will mostly work with different versions
of <command>make</command>. However, there tends to be
a few incompatibilities, so the &prodname; team recommends
installing <ulink url="http://www.gnu.org/software/make">GNU
make</ulink> if you don't already have it on your system
and using it. (It may be called <command>gmake</command>
rather than <command>make</command>.)
</para>
</listitem>
</itemizedlist>
<para>
&prodname; depends on a number of other libraries.
</para>
......@@ -138,13 +144,13 @@
<listitem>
<para>
<ulink url="http://projects.gnome.org/nautilus/">&nautilus; extension</ulink>
is needed if you want build &nautilus; extension.
is needed if you want build &nautilus; extensions.
</para>
</listitem>
<listitem>
<para>
<ulink url="https://github.com/linuxmint/nemo/">&nemo; extension</ulink>
is needed if you want build &nemo; extension.
is needed if you want build &nemo; extensions.
</para>
</listitem>
</itemizedlist>
......@@ -162,17 +168,13 @@
<command>configure</command>
<group>
<arg>--with-nautilus-extdir=DIR</arg>
</group>
<group>
<arg>--with-nemo-extdir=DIR</arg>
</group>
<group>
<arg>--with-default-io-provider=na-gconf|io-desktop</arg>
</group>
<group>
<!-- pwi 2015- 9-11
this is removed from the documentation
is io-gconf is deprecated
<arg>--with-default-io-provider=io-gconf|io-desktop</arg>
-->
<arg>--enable-html-manuals[=gdt|db2html]</arg>
</group>
<group>
<arg>--enable-pdf-manuals[=dblatex]</arg>
</group>
</cmdsynopsis>
......@@ -180,42 +182,10 @@
<formalpara>
<title><systemitem>--with-nautilus-extdir=DIR</systemitem></title>
<para>
With this option, one may define an alternate directory where
our &nautilus; extensions will be stored.
</para>
<para>
This is most commonly useful:
</para>
<itemizedlist>
<listitem>
<para>
In development mode, we only have to install symlinks
from &nautilus; standard location to our development
tree once. Then, each new version of our libraries
will be automatically considered by &nautilus;.
</para>
</listitem>
<listitem>
<para>
When running <command>make distcheck</command>, so that
compiled libraries do not interfere with installed ones.
</para>
</listitem>
<listitem>
<para>
When &nautilus; is not installed itself in a standard
location.
</para>
</listitem>
</itemizedlist>
</formalpara>
<formalpara>
<title><systemitem>--with-nemo-extdir=DIR</systemitem></title>
<para>
With this option, one may define an alternate directory where
our &nemo; extensions will be stored.
our file manager extensions will be stored.
</para>
<para>
This is most commonly useful:
......@@ -224,9 +194,9 @@
<listitem>
<para>
In development mode, we only have to install symlinks
from &nemo; standard location to our development
from the file manager standard location to our development
tree once. Then, each new version of our libraries
will be automatically considered by &nemo;.
will be automatically considered by the file manager.
</para>
</listitem>
<listitem>
......@@ -237,13 +207,14 @@
</listitem>
<listitem>
<para>
When &nemo; is not installed itself in a standard
When the file manager is not installed itself in its standard
location.
</para>
</listitem>
</itemizedlist>
</formalpara>
<!--
<formalpara>
<title><systemitem>--with-default-io-provider=io-desktop</systemitem></title>
<para>
......@@ -261,6 +232,7 @@
<filename>.desktop</filename> files.
</para>
</formalpara>
-->
<formalpara>
<title><systemitem>--enable-html-manuals[=gdt|db2html]</systemitem></title>
......@@ -276,14 +248,14 @@
realized through <application>gnome-doc-tool</application>
or <application>db2html</application>.
&prodname; defaults to use <application>gnome-doc-tool</application>
as the output format better sticks with those of
as its output format better sticks with those of
<application>Yelp</application>.
</para>
<para>
As this option is always set when running
<command>make distcheck</command>, the packager can be
mostly sure that the distributed manuals are up to date,
and may safely ignore this option.
and may safely ignore it.
</para>
</formalpara>
......@@ -300,7 +272,7 @@
As this option is always set when running
<command>make distcheck</command>, the packager can be
mostly sure that the distributed manuals are up to date,
and may safely ignore this option.
and may safely ignore it.
</para>
</formalpara>
......
......@@ -29,13 +29,13 @@
<itemizedlist>
<listitem>
<para>
Program sources
Some executables
</para>
<itemizedlist>
<listitem>
a file-manager plugin, said <emphasis>menu</emphasis>,
responsible for managing displayed menus and actions
through &nautilus; extension system;
through the file manager extension system;
</listitem>
<listitem>
a file-manager plugin, said <emphasis>tracker</emphasis>,
......@@ -50,16 +50,20 @@
<application>fma-new</application> is a
command-line utility for defining a new action;
</listitem>
<listitem>
<application>fma-print</application> is a
command-line utility for printing an action;
</listitem>
<listitem>
<application>fma-run</application> is a
command-line utility for running an existing action,
taking into account the current file-manager selection;
taking into account the current file-manager selection.
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
Documentation
The documentation
</para>
<itemizedlist>
<listitem>
......@@ -77,7 +81,7 @@
</listitem>
<listitem>
<para>
Samples
Samples from the user's manual
</para>
<itemizedlist>
<listitem>
......
......@@ -42,13 +42,13 @@
*
* <note>
* <para>
* To be really clear, &prodname; relies on &nautilus; in order
* to be able to register its own D-Bus services via the
* To be really clear, &prodname; relies on a running file manager
* in order to be able to register its own D-Bus services via the
* <emphasis>tracker</emphasis> plugin.
* </para>
* <para>
* If &nautilus; does not run, or the <emphasis>tracker</emphasis>
* plugin is not loaded at &nautilus; startup, then these D-Bus
* If the file manager does not run, or the <emphasis>tracker</emphasis>
* plugin is not loaded at file manager startup, then these D-Bus
* services will not be available.
* </para>
* </note>
......
......@@ -85,7 +85,8 @@
* </itemizedlist>
*
* In order to be recognized as a valid &prodname; plugin, the library
* must at least export the functions described in this extension API.
* must at least export the functions described as mandatory in this
* extension API.
*
* <refsect2>
* <title>Developing a &prodname; plugin</title>
......@@ -98,13 +99,13 @@
* <application><ulink url="http://www.gnu.org/software/automake/">automake</ulink></application>
* and
* <application><ulink url="http://www.gnu.org/software/libtool/">libtool</ulink></application>
* GNU applications.
* GNU tools.
* </para>
* <para>
* In this case, it should be enough to use the <option>-module</option>
* option in your <filename>Makefile.am</filename>, as in:
* <programlisting>
* libna_io_desktop_la_LDFLAGS = -module -no-undefined -avoid-version
* libfma_io_desktop_la_LDFLAGS = -module -no-undefined -avoid-version
* </programlisting>
* </para>
* </refsect3>
......@@ -160,8 +161,9 @@ G_BEGIN_DECLS
* advantage of this call by initializing itself, registering its
* internal #GType types, etc.
*
* A FileManager-Actions extension must implement this function in order
* to be considered as a valid candidate to dynamic load.
* This function is mandatory: a FileManager-Actions extension must
* implement this function in order to be considered as a valid candidate
* to dynamic load.
*
* <example>
* <programlisting>
......@@ -235,8 +237,9 @@ guint fma_extension_get_version( void );
* derived object for each returned #GType type, and associate these objects
* to this library.
*
* A FileManager-Actions extension must implement this function in order
* to be considered as a valid candidate to dynamic load.
* This function is mandatory: a FileManager-Actions extension must
* implement this function in order to be considered as a valid candidate
* to dynamic load.
*
* <example>
* <programlisting>
......@@ -245,22 +248,22 @@ guint fma_extension_get_version( void );
* * - be registered in fma_extension_startup()
* * - be addressed in fma_extension_list_types().
* &rcomment;
* #define NADP_TYPES_COUNT 1
* #define TYPES_COUNT 1
*
* guint
* fma_extension_list_types( const GType **types )
* {
* static GType types_list [1+NADP_TYPES_COUNT];
* static GType types_list [1+TYPES_COUNT];
*
* &lcomment; FMA_TYPE_DESKTOP_PROVIDER has been previously
* * registered in fma_extension_startup function
* &rcomment;
* types_list[0] = FMA_TYPE_DESKTOP_PROVIDER;
*
* types_list[NADP_TYPES_COUNT] = 0;
* types_list[TYPES_COUNT] = 0;
* *types = types_list;
*
* return( NADP_TYPES_COUNT );
* return( TYPES_COUNT );
* }
* </programlisting>
* </example>
......@@ -282,8 +285,9 @@ guint fma_extension_list_types ( const GType **types );
* release any resource, handle, and so on, it may have previously
* allocated.
*
* A FileManager-Actions extension must implement this function in order
* to be considered as a valid candidate to dynamic load.
* This function is mandatory: a FileManager-Actions extension must
* implement this function in order to be considered as a valid
* candidate to dynamic load.
*
* Since: 2.30
*/
......
......@@ -54,7 +54,7 @@
* </para>
* <para>
* Below is a list of currently allocated export format identifiers.
* This list has been last updated on 2010, July 28th.
* This list has been last updated on 2015, September 10th.
* </para>
* <table>
* <title>Currently allocated export format identifiers</title>
......@@ -63,12 +63,16 @@
* <colspec colname="label" />
* <colspec colname="holder" />
* <colspec colname="allocated" align="center" />
* <colspec colname="deprecated" />
* <colspec colname="current" />
* <thead>
* <row>
* <entry>Identifier</entry>
* <entry>Name</entry>
* <entry>Holder</entry>
* <entry>Allocated on</entry>
* <entry></entry>
* <entry></entry>
* </row>
* </thead>
* <tbody>
......@@ -77,30 +81,40 @@
* <entry>Reserved for &prodname; internal needs</entry>
* <entry>&prodname;</entry>
* <entry>2010-02-15</entry>
* <entry></entry>
* <entry>current</entry>
* </row>
* <row>
* <entry><literal>Desktop1</literal></entry>
* <entry>FMA Desktop module</entry>
* <entry>&prodname;</entry>
* <entry>2010-07-28</entry>
* <entry></entry>
* <entry>current</entry>
* </row>
* <row>
* <entry><literal>GConfSchemaV1</literal></entry>
* <entry>FMA XML module</entry>
* <entry>&prodname;</entry>
* <entry>2010-02-15</entry>
* <entry>deprecated</entry>
* <entry></entry>
* </row>
* <row>
* <entry><literal>GConfSchemaV2</literal></entry>
* <entry>FMA XML module</entry>
* <entry>&prodname;</entry>
* <entry>2010-02-15</entry>
* <entry>deprecated</entry>
* <entry></entry>
* </row>
* <row>
* <entry><literal>GConfEntry</literal></entry>
* <entry>FMA XML module</entry>
* <entry>&prodname;</entry>
* <entry>2010-02-15</entry>
* <entry>deprecated</entry>
* <entry></entry>
* </row>
* </tbody>
* </tgroup>
......@@ -114,8 +128,8 @@
* <tgroup rowsep="1" colsep="1" align="center" cols="3">
* <colspec colname="fma-version" />
* <colspec colname="api-version" />
* <colspec colname="current" />
* <colspec colname="deprecated" />
* <colspec colname="current" />
* <thead>
* <row>
* <entry>&prodname; version</entry>
......@@ -128,14 +142,14 @@
* <row>
* <entry>from 2.30 to 3.1.5</entry>
* <entry>1</entry>
* <entry></entry>
* <entry>deprecated</entry>
* <entry></entry>
* </row>
* <row>
* <entry>since 3.2</entry>
* <entry>2</entry>
* <entry>current version</entry>
* <entry></entry>
* <entry>current version</entry>
* </row>
* </tbody>
* </tgroup>
......@@ -263,42 +277,11 @@ typedef struct {
*
* This structure describes a supported output format.
* It must be provided by each #FMAIExporter implementation
* (see e.g. <filename>src/io-xml/naxml-formats.c</filename>).
* (see e.g. <filename>src/io-xml/fma-xml-formats.c</filename>).
*
* When listing available export formats, the @provider must return a #GList
* of these structures.
*
* <refsect2>
* <title>Versions historic</title>
* <table>
* <title>Historic of the versions of the #FMAIExporterFormatv2 structure</title>
* <tgroup rowsep="1" colsep="1" align="center" cols="3">
* <colspec colname="fma-version" />
* <colspec colname="api-version" />
* <colspec colname="current" />
* <thead>
* <row>
* <entry>&prodname; version</entry>
* <entry>#FMAIExporterFormatv2 structure version</entry>
* <entry></entry>
* </row>
* </thead>
* <tbody>
* <row>
* <entry>since 2.30</entry>
* <entry>1</entry>
* <entry></entry>
* </row>
* <row>
* <entry>since 3.2</entry>
* <entry>2</entry>
* <entry>current version</entry>
* </row>
* </tbody>
* </tgroup>
* </table>
* </refsect2>
*
* Since: 3.2
*/
typedef struct {
......
......@@ -145,7 +145,8 @@ typedef struct {
*
* Since: 2.30
*/
void ( *copy ) ( FMAIFactoryObject *instance, const FMAIFactoryObject *source );
void ( *copy ) ( FMAIFactoryObject *instance,
const FMAIFactoryObject *source );
/**
* are_equal:
......@@ -159,7 +160,8 @@ typedef struct {
*
* Since: 2.30
*/
gboolean ( *are_equal ) ( const FMAIFactoryObject *a, const FMAIFactoryObject *b );
gboolean ( *are_equal ) ( const FMAIFactoryObject *a,
const FMAIFactoryObject *b );
/**
* is_valid:
......@@ -186,7 +188,10 @@ typedef struct {
*
* Since: 2.30
*/
void ( *read_start ) ( FMAIFactoryObject *instance, const FMAIFactoryProvider *reader, void *reader_data, GSList **messages );
void ( *read_start ) ( FMAIFactoryObject *instance,
const FMAIFactoryProvider *reader,
void *reader_data,
GSList **messages );
/**
* read_done:
......@@ -200,7 +205,10 @@ typedef struct {
*
* Since: 2.30
*/
void ( *read_done ) ( FMAIFactoryObject *instance, const FMAIFactoryProvider *reader, void *reader_data, GSList **messages );
void ( *read_done ) ( FMAIFactoryObject *instance,
const FMAIFactoryProvider *reader,
void *reader_data,
GSList **messages );
/**
* write_start:
......@@ -216,7 +224,10 @@ typedef struct {
*
* Since: 2.30
*/
guint ( *write_start )( FMAIFactoryObject *instance, const FMAIFactoryProvider *writer, void *writer_data, GSList **messages );
guint ( *write_start )( FMAIFactoryObject *instance,
const FMAIFactoryProvider *writer,
void *writer_data,
GSList **messages );
/**
* write_done:
......@@ -232,7 +243,10 @@ typedef struct {
*
* Since: 2.30
*/
guint ( *write_done ) ( FMAIFactoryObject *instance, const FMAIFactoryProvider *writer, void *writer_data, GSList **messages );
guint ( *write_done ) ( FMAIFactoryObject *instance,
const FMAIFactoryProvider *writer,
void *writer_data,
GSList **messages );
}
FMAIFactoryObjectInterface;
......
......@@ -77,7 +77,7 @@
* <para>
* Now that our elementary datas are banalized and de-structured,
* it is simple enough to describe each of these datas with all
* iss properties in one single, centralized, place.
* its properties in one single, centralized, place.
* </para>
* </formalpara>
* </listitem>
......@@ -190,7 +190,10 @@ typedef struct {
*
* Since: 2.30
*/
void ( *read_start ) ( const FMAIFactoryProvider *reader, void *reader_data, const FMAIFactoryObject *object, GSList **messages );
void ( *read_start ) ( const FMAIFactoryProvider *reader,
void *reader_data,
const FMAIFactoryObject *object,
GSList **messages );
/**
* read_data:
......@@ -209,7 +212,11 @@ typedef struct {
*
* Since: 2.30
*/
FMADataBoxed * ( *read_data ) ( const FMAIFactoryProvider *reader, void *reader_data, const FMAIFactoryObject *object, const FMADataDef *def, GSList **messages );
FMADataBoxed * ( *read_data ) ( const FMAIFactoryProvider *reader,
void *reader_data,
const FMAIFactoryObject *object,
const FMADataDef *def,
GSList **messages );
/**
* read_done:
......@@ -225,7 +232,10 @@ typedef struct {
*
* Since: 2.30
*/
void ( *read_done ) ( const FMAIFactoryProvider *reader, void *reader_data, const FMAIFactoryObject *object, GSList **messages );
void ( *read_done ) ( const FMAIFactoryProvider *reader,
void *reader_data,
const FMAIFactoryObject *object,
GSList **messages );
/**
* write_start:
......@@ -241,7 +251,10 @@ typedef struct {
*
* Since: 2.30
*/
guint ( *write_start )( const FMAIFactoryProvider *writer, void *writer_data, const FMAIFactoryObject *object, GSList **messages );
guint ( *write_start )( const FMAIFactoryProvider *writer,
void *writer_data,
const FMAIFactoryObject *object,
GSList **messages );
/**
* write_data:
......@@ -261,7 +274,11 @@ typedef struct {
*
* Since: 2.30
*/
guint ( *write_data ) ( const FMAIFactoryProvider *writer, void *writer_data, const FMAIFactoryObject *object, const FMADataBoxed *boxed, GSList **messages );
guint ( *write_data ) ( const FMAIFactoryProvider *writer,
void *writer_data,
const FMAIFactoryObject *object,
const FMADataBoxed *boxed,
GSList **messages );
/**
* write_done:
......@@ -278,7 +295,10 @@ typedef struct {
*
* Since: 2.30
*/
guint ( *write_done ) ( const FMAIFactoryProvider *writer, void *writer_data, const FMAIFactoryObject *object, GSList **messages );
guint ( *write_done ) ( const FMAIFactoryProvider *writer,
void *writer_data,
const FMAIFactoryObject *object,
GSList **messages );
}
FMAIFactoryProviderInterface;
......
......@@ -154,7 +154,7 @@ typedef struct {
* @parms is supposed to map to FMAIImporterImportFromUriParms structure.
*
* Contrarily, if the provider implements the version 2 of the interface,
* then @parms is supposed to map to a FMAIImporterImportFromUriParmsv2
* then @parms is expected to map to a FMAIImporterImportFromUriParmsv2
* structure.
*
* Return value: the return code of the operation.
......@@ -183,7 +183,7 @@ typedef struct {
* should be systematically regenerated as a unique id, regardless of the
* asked import mode.
*
* Standard N-A callers provide a function which checks for the existance
* Standard FMA callers provide a function which checks for the existance
* of the newly imported item :
* <itemizedlist>
* <listitem>
......
......@@ -41,7 +41,7 @@
* to their own private storage subsystem.
*
* &prodname; core does not provide by itself input/output code. Instead,
* we entirely relies on input/output facilities provided by implementations
* it entirely relies on input/output facilities provided by implementations
* of this interface.
*
* &prodname; is bundled with several I/O providers.
......@@ -58,7 +58,7 @@
* loading items
* </title>
* <para>
* Loading items is used both by the &nautilus; plugin, by the
* Loading items is used both by the file manager plugins, by the
* &fmact; program, and by the command-line utilities.
* </para>
* </formalpara>
......@@ -77,7 +77,7 @@
* <listitem>
* <formalpara>
* <title>
* informing &prodname; of extern modifications
* informing &prodname; of external modifications
* </title>
* <para>
* The I/O provider should inform &prodname; when an item happens to
......@@ -85,13 +85,13 @@
* </para>
* </formalpara>
* <para>
* This feature is only used by the &nautilus; plugin and by the
* This feature is only used by the file manager plugins and by the
* &fmact; program.
* </para>
* <para>
* The #FMAIIOProvider interface does not define specific monitoring
* methods (but you can also take a glance at #FMATimeout object).
* Instead, it is waited that the I/O provider module takes care
* Instead, it is expected that the I/O provider module takes care