[tracker/merge-control-status] docs: Update tracker-control manpage with all new options merged from tracker-status

[Aleksander Morgado <aleksm src gnome org>]

commit 05e586c2439bba58a0e21de90e108ac0091abec6
Author: Aleksander Morgado <aleksander lanedo com>
Date:   Wed Feb 2 18:13:12 2011 +0100

    docs: Update tracker-control manpage with all new options merged from tracker-status

 docs/manpages/tracker-control.1 |  108 +++++++++++++++++++++++++++++++++++----
 1 files changed, 97 insertions(+), 11 deletions(-)
---
diff --git a/docs/manpages/tracker-control.1 b/docs/manpages/tracker-control.1
index 97a23b2..4e2fbfe 100644
--- a/docs/manpages/tracker-control.1
+++ b/docs/manpages/tracker-control.1
@@ -8,21 +8,41 @@ tracker-control \- Manage Tracker processes and data
 
 .SH DESCRIPTION
 .B tracker-control
-lists all tracker related processes when no
-\fIOPTION\fRs are specified.
+manages and checks status of all Tracker processes and data.
 
-To see the status of the miners and the store, use 
-.B tracker-status.
-You can pause or resume miners and also see which ones
-are running and which ones are installed.
+Controls Tracker both at process level, and at entity level (store, miners).
 
-.SH OPTIONS
+To start or stop miners, you can use
+.B \-\-start.
+The store is started automatically by the D-Bus calls from the miners.
+
+It also allows checking the status of the Tracker store and all data miners.
+For
+.B tracker-store
+, the status is always
+.B Idle
+unless it is restoring a backup and/or replaying a journal (regardless of
+load from applications or miners). For a list of common statuses, see
+.B \-\-list\-common\-statuses.
+
+The miners can be paused or resumed using this command and you can
+also list miners running and available.
+
+.SH COMMON OPTIONS
 .TP
 .B \-?, \-\-help
-Show summary of options.
+Show summary of options by group.
+.TP
+.B \-?, \-\-help-all
+Show all groups and options.
 .TP
 .B \-V, \-\-version
-Returns the version of this binary.
+Returns the version of this program.
+
+.SH GENERAL OPTIONS
+.TP
+.B \-p, \-\-list\-processes
+This lists all Tracker processes in the system.
 .TP
 .B \-k, \-\-kill=[all|store|miners]
 This uses SIGKILL to stop all Tracker processes found matching the
@@ -64,18 +84,84 @@ configuration files.
 .B \-s, \-\-start
 Starts all miners. This indirectly starts tracker-store too because it
 is needed for miners to operate properly.
+
+.SH STATUS OPTIONS
+.TP
+.B \-S, \-\-status
+Show the current status of all Tracker entities (store and all available
+miners).
+.TP
+.B \-F, \-\-follow
+Follow status changes as they happen. This requires Ctrl+C to stop and
+return to the command line. Each new status is put on a new line. To
+get more information, you can use
+.B \-\-detailed
+with this.
+.TP
+.B \-D, \-\-detailed
+For the most part, this purely provides a timestamp with each status
+update to follow WHEN changes happened.
+.TP
+.B \-C, \-\-list-common-statuses
+This will list statuses most commonly produced by miners and the
+store. These statuses are not translated when sent over D-Bus and
+should be translated by each application. These are not considered
+static and are subject to change at any point.
+
+Additionally, these statuses are not the only ones which may be
+reported by a miner. There may be other states pertaining to the
+specific roles of the miner in question.
+
+.SH MINER OPTIONS
 .TP
 .B \-m, \-\-reindex-mime-type=MIME
 Re-index files which match the \fIMIME\fR type supplied. This is
 usually used when installing new extractors which support \fIMIME\fR
 types previously unsupported. This forces Tracker to re-index those
-files. You can use 
+files. You can use
 .B \-\-reindex-mime-type
 more than once per \fIMIME\fR type.
 .TP
 .B \-f, \-\-index-file=FILE
 (Re)index a file matching the \fIFILE\fR type supplied.
+.TP
+.B \-l, \-\-list-miners-running
+This will list all miners which have responded to a D-Bus call.
+Sometimes it is helpfult to use this command with
+.B \-\-list-miners-available.
+.TP
+.B \-a, \-\-list-miners-available
+This will list all miners which are available even if they are not
+running at the moment.
+.TP
+.B \-i, \-\-pause-details
+For listing all miners which are paused and the reasons for being
+paused, you can use this. It will also display the application that
+requested the pause too.
+.TP
+.B \-\-miner=MINER
+This argument is used with
+.B \-\-pause
+or
+.B \-\-resume
+to say which miner you want to pause or resume. You can use the full
+D-Bus name, e.g.
+.B org.freedesktop.Tracker1.Miner.Files
+OR you can use the suffix, e.g.
+.B Files
+.TP
+.B \-\-pause=REASON
+The REASON here is useful to know WHY the miner should be paused. A
+miner can be paused many times by multiple applications. Only when all
+pauses have been resumed will it continue. If successful, a cookie
+will be given to uniquely identify the request. This cookie is used to
+resume the pause at a later stage.
+.TP
+.B \-\-resume=COOKIE
+The COOKIE is given by a successful
+.B \-\-pause
+command. It is a number which identifies each pause request. When all
+pauses have been resumed, the miner will resume working.
 
 .SH SEE ALSO
-.BR tracker-status (1),
 .BR tracker-store (1).