From 2bc69c3e81d3cc7da896bfd21ffff986b004a30a Mon Sep 17 00:00:00 2001 From: Pierre Wieser Date: Mon, 6 Dec 2010 23:33:56 +0100 Subject: [PATCH] Reference manual: overview --- ChangeLog | 7 + docs/README | 6 +- docs/reference/Makefile.am | 24 ++- docs/reference/na-compiling.xml | 270 +++++++++++++++++++++++++++++++ docs/reference/na-dist-content.xml | 98 +++++++++++ docs/reference/na-getting.xml | 50 ++++++ docs/reference/na-plugin.xml | 76 +++++++++ docs/reference/na-what-is-it.xml | 39 +++++ docs/reference/nautilus-actions-docs.xml | 30 ++-- docs/reference/version_dir.xml | 1 + 10 files changed, 580 insertions(+), 21 deletions(-) create mode 100644 docs/reference/na-compiling.xml create mode 100644 docs/reference/na-dist-content.xml create mode 100644 docs/reference/na-getting.xml create mode 100644 docs/reference/na-plugin.xml create mode 100644 docs/reference/na-what-is-it.xml create mode 100644 docs/reference/version_dir.xml diff --git a/ChangeLog b/ChangeLog index 8c4f4a0a..dcd37e23 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,12 @@ 2010-12-06 Pierre Wieser + * docs/reference/na-compiling.xml: + * docs/reference/na-dist-content.xml: + * docs/reference/na-getting.xml: + * docs/reference/na-plugin.xml: + * docs/reference/na-what-is-it.xml: + * docs/reference/version_dir.xml: New files. + * data/actions/my-first-na-action.desktop: * data/actions/my-first-na-menu.desktop: * data/actions/open-terminal-here.desktop: diff --git a/docs/README b/docs/README index cec15c60..c116d602 100644 --- a/docs/README +++ b/docs/README @@ -2,10 +2,8 @@ docs ---- As of Nautilus-Actions 3.0, the documentation is composed of two main parts: - -- the Reference Manual describes all features of the product, and - rather targets developers and packagers; - +- the Reference Manual describes all features of the product, rather + targeting developers and packagers; - the Nautilus-Actions Configuration Tool User's Manual. P. Wieser, Dec. 2010 diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am index c6145d6b..c5fd68cd 100644 --- a/docs/reference/Makefile.am +++ b/docs/reference/Makefile.am @@ -44,6 +44,10 @@ DOC_MAIN_SGML_FILE = $(DOC_MODULE)-docs.xml # that is, only consider in src/core .c sources whose header is in src/api core_headers = $(patsubst $(top_srcdir)/src/core/%,%,$(shell \ls -1 $(top_srcdir)/src/core/*.h)) +written_xmls_regexp = $(shell echo "$(DOC_MAIN_SGML_FILE) $(content_files)" | $(SED) 's/[[:space:]]\+/|/g') + +written_xmls = $(shell \ls -1 *.xml | $(EGREP) -v "$(written_xmls_regexp)") + # Extra options to supply to gtkdoc-scan # --ignore-headers="config.h devkit-disks-daemon-glue.h" # --rebuild-sections @@ -101,9 +105,11 @@ MKTMPL_OPTIONS = \ $(NULL) # Non-autogenerated SGML files to be included in $(DOC_MAIN_SGML_FILE) +# nb: unable to subst/strip/sed a last $(null) terminating character! +# so keep it out of there content_files = \ $(xml_files) \ - $(NULL) + version_dir.xml # Images to copy into HTML directory HTML_IMAGES = \ @@ -124,22 +130,24 @@ xml_in_files = \ xml_files = $(xml_in_files:.xml.in=.xml) -#CLEANFILES += \ -# *~ \ -# gnome-disk-utility-scan* \ -# gnome-disk-utility-sections.txt \ -# *.stamp \ -# -rf html xml tmpl \ -# $(NULL) +version_dir.xml: version.xml + cat version.xml | $(SED) 's?^\([[:alnum:]]\.[[:alnum:]]\).*?\1?' > version_dir.xml + +CLEANFILES += \ + version_dir.xml \ + $(NULL) # Version information for marking the documentation EXTRA_DIST += \ $(xml_in_files) \ + $(written_xmls) \ $(NULL) install-data-local: install-data-local-hook install-data-local-hook: echo "core_headers=$(core_headers)" + echo "written_xmls_regexp=$(written_xmls_regexp)" + echo "written_xmls=$(written_xmls)" #TESTS = $(GTKDOC_CHECK) diff --git a/docs/reference/na-compiling.xml b/docs/reference/na-compiling.xml new file mode 100644 index 00000000..fc63c3ba --- /dev/null +++ b/docs/reference/na-compiling.xml @@ -0,0 +1,270 @@ + +Nautilus-Actions"> + Nautilus"> +]> + + + + + Compiling the Nautilus-Actions package + 3 + Nautilus-Actions + + + + Compiling the Nautilus-Actions Package + + How to compile Nautilus-Actions + + + + + Building &prodname; on UNIX + + + On UNIX, &prodname; uses the standard GNU build system, + using autoconf for package + configuration and resolving portability issues, + automake for building makefiles + that comply with the GNU Coding Standards, and + libtool for building shared + libraries on multiple platforms. The normal sequence for + compiling and installing the &prodname; package is thus: + + + ./configure + make + make install + + + + + The standard options provided by GNU + autoconf may be passed to the + configure script. Please see the + autoconf documentation or run + ./configure --help for information about + the standard options. + + + + + Dependencies + + + Before you can compile the &prodname; package, you need to have + various other tools and libraries installed on your + system. The two tools needed during the build process (as + differentiated from the tools used in when creating &prodname; + mentioned above such as autoconf) + are pkg-config and GNU make. + + + + + + pkg-config + is a tool for tracking the compilation flags needed for + libraries that are used by the &prodname; package. + (For each library, a small .pc text file is + installed in a standard location that contains the compilation + flags needed for that library along with version number + information.) + + + + + The &prodname; makefiles will mostly work with different versions + of make. However, there tends to be + a few incompatibilities, so the &prodname; team recommends + installing GNU + make if you don't already have it on your system + and using it. (It may be called gmake + rather than make.) + + + + + + &prodname; depends on a number of other libraries. + + + + + + GLib + and Gtk+ are fondamental + libraries, both for user interface and for portability and + internationalization management. + + + + + libxml2 is used to + manage XML imports and exports. + + + + + libgtop2 + is used to detect and identify running processes as part of the validation + process of a candidate context. + + + + + libSM + is used as a session management library, in order to be sure the session + will not terminate without at least proposing the user to save his + modifications. + + + + + libUUID + is the universally unique ID library used to automatically generate a + unique identifiant at item creation. + + + + + libunique + is required so that the Nautilus-Actions Configuration Tool only + executes one instance. + + + + + And, of course, + &nautilus; extension + is required because &prodname; is first a &nautilus; extension. + + + + + + + Extra Configuration Options + + + In addition to the normal options, the + configure script in the &prodname; package + supports these additional arguments: + + + configure + + --with-nautilus-extdir=DIR + + + --with-default-io-provider=na-gconf|na-desktop + + + --enable-html-manuals[=gdt|db2html] + + + --enable-pdf-manuals[=dblatex] + + + + + + <systemitem>--with-nautilus-extdir=DIR</systemitem> + + With this option, one may define an alternate directory where + our &nautilus; extensions will be stored. + + + This is most commonly useful: + + + + + 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;. + + + + + When running make distcheck, so that + compiled libraries do not interfere with installed ones. + + + + + When &nautilus; is not installed itself in a standard + location. + + + + + + + <systemitem>--with-default-io-provider=na-gconf|na-desktop</systemitem> + + As of version 3.0, &prodname; may store menus and actions + both in GConf, which is the historical behavior, or as + .desktop files. + + + This option lets the packager define which will be the + default destination when a new menu or action will be + created. + + + This defaults to "na-desktop" which is the internal + identifiant of the I/O provider which manages + .desktop files. + + + + + <systemitem>--enable-html-manuals[=gdt|db2html]</systemitem> + + This option lets the packager regenerate user's manuals + from the DocBook sources as HTML documents. + + + All available translations are generated. + + + Building HTML documents from DocBook source can be + realized through gnome-doc-tool + or db2html. + &prodname; defaults to use gnome-doc-tool + as the output format better sticks with those of + Yelp. + + + As this option is always set when running + make distcheck, the packager can be + mostly sure that the distributed manuals are up to date, + and may safely ignore this option. + + + + + <systemitem>--enable-pdf-manuals[=dblatex]</systemitem> + + This option lets the packager regenerate user's manuals + from the DocBook sources as PDF documents. + + + All available translations are generated. + + + As this option is always set when running + make distcheck, the packager can be + mostly sure that the distributed manuals are up to date, + and may safely ignore this option. + + + + + + \ No newline at end of file diff --git a/docs/reference/na-dist-content.xml b/docs/reference/na-dist-content.xml new file mode 100644 index 00000000..72e8b952 --- /dev/null +++ b/docs/reference/na-dist-content.xml @@ -0,0 +1,98 @@ + +Nautilus-Actions"> + Nautilus"> +]> + + + + + Distribution content + 3 + Nautilus-Actions + + + + Distribution content + + What is distributed ? + + + + + What does content the distribution ? + + &prodname; distribution contains the following components: + + + + + Programs + + + + a &nautilus; plugin, said menu, + responsible for managing displayed menus and actions + through &nautilus; extensions; + + + a &nautilus; plugin, said tracker, + which manages DBus services; + + + Nautilus-Actions Configuration Tool + is the user interface application which lets the user edit, + create, delete and organize his collection of menus and actions; + + + nautilus-actions-new is a + command-line utility for defining a new action; + + + nautilus-actions-run is a + command-line utility for running an existing action, + taking into account the current &nautilus; selection; + + + nautilus-actions-schemas + is a command-line utility which outputs + to stdout the GConf schemas of the + Nautilus-Actions Configuration Tool; + it rather targets packagers. + + + + + + Documentation + + + + the &prodname; Reference Manual (this document) rather + targets developers and packagers; + + + the &prodname; Configuration Tool User's Manual is the user's + manual of the + Nautilus-Actions Configuration Tool + management user interface. The distribution contains all + available translations, both as HTML and PDF documents. + + + + + + Samples + + + The sample menus and actions described in the + &prodname; Configuration Tool User's Manual + are included in the standard distribution. + + + + + + \ No newline at end of file diff --git a/docs/reference/na-getting.xml b/docs/reference/na-getting.xml new file mode 100644 index 00000000..b4e20f29 --- /dev/null +++ b/docs/reference/na-getting.xml @@ -0,0 +1,50 @@ + + + Nautilus-Actions"> + Nautilus"> +]> + + + + + Getting Nautilus-Actions + Nautilus-Actions + + + + Getting Nautilus-Actions + + Where to find it ? + + + + + Getting Nautilus-Actions + + The latest release may always be found in + + + + + http://www.nautilus-actions.org/downloads/ + + + + + http://ftp.gnome.org/nautilus-actions/&version_dir;/ + + + + + + ftp://ftp.trychlos.org/pub/tarballs/nautilus-actions/ + + + + + + \ No newline at end of file diff --git a/docs/reference/na-plugin.xml b/docs/reference/na-plugin.xml new file mode 100644 index 00000000..4c604426 --- /dev/null +++ b/docs/reference/na-plugin.xml @@ -0,0 +1,76 @@ + +Nautilus-Actions"> + Nautilus"> +]> + + + + + Extending Nautilus-Actions + Nautilus-Actions + + + + Plugin development + + How to extend Nautilus-Actions and develop new plugins ? + + + + + Plugin Overview + + &prodname; may be extended by developing new extensions + which will be dynamically taken into account at runtime. + These are plugins. + + + As of today, &prodname; may be extended in the following + areas: + + + + + + Storing menus and actions in a specific storage subsystem + + + This extension is provided via the public NAIIOProvider + interface; it takes care of reading and writing menus + and actions to a specific storage subsystem. + + + + + + + Exporting menus and actions + + + This extension is provided via the public NAIExporter + interface; it takes care of exporting menus and actions + to the filesystem from the &prodname; Configuration Tool + user interface. + + + + + + + Importing menus and actions + + + This extension is provided via the public NAIImporter + interface; it takes care of importing menus and actions + from the filesystem into the &prodname; Configuration Tool + user interface. + + + + + + + \ No newline at end of file diff --git a/docs/reference/na-what-is-it.xml b/docs/reference/na-what-is-it.xml new file mode 100644 index 00000000..7f2714fe --- /dev/null +++ b/docs/reference/na-what-is-it.xml @@ -0,0 +1,39 @@ + +Nautilus-Actions"> + Nautilus"> +]> + + + + + What is it ? + Nautilus-Actions + + + + What is it ? + + What is Nautilus-Actions ? + + + + + What is Nautilus-Actions ? + + &prodname; is a &nautilus; extension whose principal function + is to allow the user to add arbitrary actions to the file manager + context menus. These actions may be organized in menus and submenus, + exported and shared with other desktop environments. + + + &prodname; is compliant with + DES-EMA + specification. This means that actions and menus defined in &prodname; + will be shareable with the compliant desktop environments. + + + + \ No newline at end of file diff --git a/docs/reference/nautilus-actions-docs.xml b/docs/reference/nautilus-actions-docs.xml index 9db6e807..fc3c3e92 100644 --- a/docs/reference/nautilus-actions-docs.xml +++ b/docs/reference/nautilus-actions-docs.xml @@ -2,36 +2,48 @@ + Nautilus-Actions"> Nautilus"> ]> + &prodname; Reference Manual For Nautilus-Actions &version; - The latest version of this documentation can be found on-line at - http://[SERVER]/nautilus-actions/. - --> + http://www.nautilus-actions.org/docs/reference. + + 2010 + Pierre Wieser + &prodname; Overview - - - + + + + - &prodname; Overview + Extending &prodname; + - Available interfaces + Public extension interfaces diff --git a/docs/reference/version_dir.xml b/docs/reference/version_dir.xml new file mode 100644 index 00000000..8c50098d --- /dev/null +++ b/docs/reference/version_dir.xml @@ -0,0 +1 @@ +3.1 -- 2.11.4.GIT