[tracker-miners/sam/website-manpages: 44/44] Use asciidoc to generate manpages

From: Sam Thursfield <sthursfield src gnome org>
To: commits-list gnome org
Cc:
Subject: [tracker-miners/sam/website-manpages: 44/44] Use asciidoc to generate manpages
Date: Sun, 12 Apr 2020 14:46:08 +0000 (UTC)
commit 55c8b12ffc53f7c929b20a1c9386b48ae9236428
Author: Sam Thursfield <sam afuera me uk>
Date:   Sun Mar 29 01:06:11 2020 +0100

    Use asciidoc to generate manpages
    
    Previously we wrote the man pages directly in ROFF format. The
    asciidoc format is easier to read, and also we can convert it to
    HTML easily to publish the man pages online.

 docs/manpages/meson.build             |  57 ++++----
 docs/manpages/tracker-daemon.1        | 239 ----------------------------------
 docs/manpages/tracker-daemon.1.txt    | 174 +++++++++++++++++++++++++
 docs/manpages/tracker-extract.1       | 110 ----------------
 docs/manpages/tracker-extract.1.txt   |  76 +++++++++++
 docs/manpages/tracker-index.1         |  63 ---------
 docs/manpages/tracker-index.1.txt     |  62 +++++++++
 docs/manpages/tracker-miner-fs.1      |  72 ----------
 docs/manpages/tracker-miner-fs.1.txt  |  59 +++++++++
 docs/manpages/tracker-miner-rss.1     |  54 --------
 docs/manpages/tracker-miner-rss.1.txt |  46 +++++++
 docs/manpages/tracker-reset.1         |  46 -------
 docs/manpages/tracker-reset.1.txt     |  48 +++++++
 docs/manpages/tracker-search.1        | 117 -----------------
 docs/manpages/tracker-search.1.txt    |  98 ++++++++++++++
 docs/manpages/tracker-status.1        |  64 ---------
 docs/manpages/tracker-status.1.txt    |  65 +++++++++
 docs/manpages/tracker-tag.1           |  85 ------------
 docs/manpages/tracker-tag.1.txt       |  75 +++++++++++
 docs/manpages/tracker-writeback.1     |  44 -------
 docs/manpages/tracker-writeback.1.txt |  42 ++++++
 meson.build                           |   5 +
 meson_options.txt                     |   2 +
 23 files changed, 786 insertions(+), 917 deletions(-)
---
diff --git a/docs/manpages/meson.build b/docs/manpages/meson.build
index 99094813c..e69124010 100644
--- a/docs/manpages/meson.build
+++ b/docs/manpages/meson.build
@@ -7,30 +7,41 @@ if have_tracker_miner_rss
   daemon_manpages += 'miner-rss'
 endif
 
-foreach m: daemon_manpages
-    manpage = configure_file(
-        input: 'tracker-@0@.1'.format(m),
-        output: 'tracker-@0@-@1@.1'.format(m, tracker_api_major),
-        copy: true,
-        install: false)
-    install_man(manpage)
-endforeach
-
 cli_manpages = [
-    'daemon',
-    'extract',
-    'index',
-    'reset',
-    'search',
-    'status',
-    'tag',
+  'daemon',
+  'extract',
+  'index',
+  'reset',
+  'search',
+  'status',
+  'tag',
 ]
 
-foreach m: cli_manpages
-    manpage = configure_file(
-        input: 'tracker-@0@.1'.format(m),
-        output: 'tracker@0@-@1@.1'.format(tracker_api_major, m),
-        copy: true,
-        install: false)
-    install_man(manpage)
+foreach m : daemon_manpages + cli_manpages
+  manpage_src = 'tracker-@0  1 txt'.format(m)
+  manpage_xml = 'tracker-@0  1 xml'.format(m)
+  manpage = 'tracker@0@-@1@.1'.format(tracker_api_major, m)
+
+  xml = custom_target(manpage_xml,
+    command: [asciidoc,
+              '--attribute=author=The Tracker developers',
+              '--attribute=manversion=@0@'.format(meson.project_version()),
+              '--attribute=manmanual=Tracker manual',
+              '--backend', 'docbook',
+              '--doctype', 'manpage',
+              '--out-file', '@OUTPUT@', '@INPUT@'],
+    input: manpage_src,
+    output: manpage_xml
+  )
+
+  custom_target(manpage,
+    command: [xsltproc,
+              '--stringparam', 'man.authors.section.enabled', '0',
+              '/etc/asciidoc/docbook-xsl/manpage.xsl', '@INPUT@'],
+    capture: true,
+    input: xml,
+    output: manpage,
+    install: true,
+    install_dir: get_option('mandir')
+  )
 endforeach
diff --git a/docs/manpages/tracker-daemon.1.txt b/docs/manpages/tracker-daemon.1.txt
new file mode 100644
index 000000000..808d86a2c
--- /dev/null
+++ b/docs/manpages/tracker-daemon.1.txt
@@ -0,0 +1,174 @@
+tracker-daemon(1)
+=================
+
+== NAME
+
+tracker-daemon - Start, stop, restart and list daemons responsible for
+indexing content
+
+== SYNOPSIS
+
+....
+tracker daemon [options...]
+tracker daemon -s | -t [daemons] | -k [daemons] | -l
+tracker daemon -f | -w [ontology]
+tracker daemon --miner <miner> --pause[-for-process] <reason>
+tracker daemon --miner <miner> --resume <cookie> 
+....
+
+== DESCRIPTION
+
+Tracker has many components to it including a "store" for handling data
+set updates and "miners" for handling data mining in their respective
+areas.
+
+The *tracker daemon* command allows for control of these components.
+This ranges from starting, stopping and killing processes to pausing and
+resuming them.
+
+In addition to all this, there are ways to change the log verbsity for
+all processes that generate logs and to follow or watch what is
+happening in real time from a top level and right down where the SPARQL
+commits are happening too.
+
+If no arguments are provided this command will show the current status
+of all Tracker entities (store and all available data miners).
+
+For *tracker-store*, the status is always "Idle" unless it is restoring
+a backup and/or replaying a journal (see also *tracker reset* --soft).
+For a list of common statuses, see *--list-common-statuses*.
+
+The data miners can be paused or resumed using this command and you can
+also list miners running and available.
+
+== OPTIONS
+
+*-p, --list-processes*::
+  This lists all Tracker processes in the system.
+*-k, --kill=[_daemons_]*::
+  This uses SIGKILL to stop all Tracker processes found matching the
+  parameter, if no extra parameter is passed, "all" will be assumed.
+  This is not advised unless you are having problems stopping Tracker in
+  the first place. This *GUARANTEES* death.
+
+The possible _daemons_ options are:
+
+_____________________________________
+· _all_ - All daemons.
+
+· _store_ - Only the *tracker-store*.
+
+· _miners_ - Only data miners.
+_____________________________________
+
+*-t, --terminate=[daemons]*::
+  This uses SIGTERM to stop all Tracker processes found matching the
+  parameter, if no extra parameter is passed, "all" will be assumed.
+  This is recommended over --kill because it gives the processes time to
+  shutdown cleanly.
+
+For a list of possible _daemons_, see --kill.
+
+*-s, --start*::
+  Starts all miners. This indirectly starts *tracker-store* too because
+  it is needed for miners to operate properly. The store is started from
+  D-Bus.
+*--get-log-verbosity*::
+  This displays the log verbosity for ALL components using GSettings for
+  this configuration. For possible values, see *--set-log-verbosity.*
+*--set-log-verbosity=<__verbosity__>*::
+  This sets the log verbosity for ALL daemons using GSettings to store
+  their "verbosity" configuration.
+
+The possible _verbosity_ options are:
+
+__________________________________________________________________________________________________________
+· _debug_ - Show EVERYTHING, from debug messages to errors. This often
+includes actual SQL being executed.
+
+· _detailed_ - Show enough detail to understand what is happening.
+
+· _minimal_ - Show an overview of what is going on, e.g. stats and when
+things start or stop.
+
+· _errors_ - Show only warnings, criticals, errors or fatal events.
+__________________________________________________________________________________________________________
+
+*-f, --follow*::
+  Follow status changes to daemons as they happen. This is a top level
+  view of what is happening. You will see the name for each daemon and a
+  state with the progress in that state.
+
+This requires Ctrl+C to stop and return to the command line. Each new
+status is put on a new line.
+
+*-w, --watch=[_ontology_]*::
+  Watch changes that happen to the database in real time. This requires
+  Ctrl+C to stop and return to the command line.
+
+If _ontology_ is unspecified, all updates are shown. The _ontology_ can
+be a comma separated list of shorthand or long hand ontology properties.
+For example:
+
+....
+    $ tracker-control -w nie:url,nie:mimeType,nfo:fileSize,nie:dataSource
+    Now listening for resource updates to the database
+    All nie:plainTextContent properties are omitted
+
+    Press Ctrl+C to stop
+
+    'nfo:Document'
+       'nfo:fileSize' = '1770'
+       'nie:dataSource' = 'http://www.tracker-project.org/ontologies/tracker#extractor-data-source'
+       'nie:mimeType' = 'text/plain'
+       'nie:url' = 'file:///home/martyn/.bash_aliases'
+    'nfo:Document'
+       'nie:dataSource' = 'http://www.tracker-project.org/ontologies/tracker#extractor-data-source'
+
+    ...
+....
+
+*--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.
+
+*--list-miners-running*::
+  This will list all miners which have responded to a D-Bus call.
+  Sometimes it is helpful to use this command with
+  *--list-miners-available.*
+*--list-miners-available*::
+  This will list all miners which are available even if they are not
+  running at the moment.
+*--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.
+*--miner=<__miner__>*::
+  This argument is used with *--pause* or *--resume* to say which miner
+  you want to pause or resume. You can use the full D-Bus name, e.g.
+  "org.freedesktop.Tracker3.Miner.Files" OR you can use the suffix, e.g.
+  "Files".
+*--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.
+*--pause-for-process=<__reason__>*::
+  This works exactly the same way as *--pause* with the exception that
+  it only keeps the pause active while the calling process is alive. As
+  soon as you press Ctrl+C the pause is resumed automatically.
+*--resume=<__cookie__>*::
+  The _cookie_ is given by a successful *--pause* command. It is a
+  number which identifies each pause request. When all pauses have been
+  resumed, the miner will resume working.
+
+== SEE ALSO
+
+*tracker-store*(1).
diff --git a/docs/manpages/tracker-extract.1.txt b/docs/manpages/tracker-extract.1.txt
new file mode 100644
index 000000000..ed081fda4
--- /dev/null
+++ b/docs/manpages/tracker-extract.1.txt
@@ -0,0 +1,76 @@
+tracker-extract(1)
+==================
+
+== NAME
+
+tracker-extract - Extract metadata from a file.
+
+== SYNOPSYS
+
+*tracker extract* _FILE_
+
+== DESCRIPTION
+
+*tracker extract* reads the file provided and extracts any metadata it
+can from this file, then displays the metadata on standard output.
+
+The metadata is displayed as a SPARQL update command, that can be run
+against a SPARQL endpoint to update its copy of the metadata.
+
+The actual extraction is done by a separate process. This is done to
+isolate the calling process from any memory leaks or crashes in the
+libraries Tracker uses to extract metadata.
+
+For more information see the libtracker-extract reference documentation.
+
+== OPTIONS
+
+*-v, --verbosity=<__LEVEL__>*::
+  This sets the log verbosity for the extractor process.
+
+The possible _LEVEL_ options are:
+
+___________________________________________________________________
+· _debug_ - Show EVERYTHING, from debug messages to errors.
+
+· _detailed_ - Show enough detail to understand what is happening.
+
+· _minimal_ - Show an overview of what is going on
+
+· _errors_ - Show only warnings, criticals, errors or fatal events.
+___________________________________________________________________
+
+*-o, --output-format=<__FORMAT__>*::
+  Choose which format to use to output results. Supported formats are
+  _sparql_, _turtle_ and _json-ld_.
+
+== EXAMPLES
+
+Using command line to extract metadata from a file:::
+
+$ tracker extract /path/to/some/file.mp3
+
+== ENVIRONMENT
+
+*TRACKER_EXTRACTORS_DIR*::
+  This is the directory which tracker uses to load the shared libraries
+  from (used for extracting metadata for specific file types). These are
+  needed on each invocation of tracker-store. If unset it will default
+  to the correct place. This is used mainly for testing purposes. The
+  default location is /usr/lib/tracker-1.0/extract-modules/.
+*TRACKER_EXTRACTOR_RULES_DIR*::
+  This is the directory which tracker uses to load the rules files from.
+  The rules files describe extractor modules and their supported MIME
+  types. The default location is /usr/share/tracker/extract-rules/.
+*TRACKER_USE_CONFIG_FILES*::
+  Don't use GSettings, instead use a config file similar to how settings
+  were saved in 0.10.x. That is, a file which is much like an .ini file.
+  These are saved to $HOME/.config/tracker/
+
+== SEE ALSO
+
+*tracker-store*(1), *tracker-sparql*(1), *tracker-stats*(1),
+*tracker-info*(1).
+
+- */usr/lib/tracker-1.0/extract-modules/*
+- */usr/share/tracker/extract-rules/*
diff --git a/docs/manpages/tracker-index.1.txt b/docs/manpages/tracker-index.1.txt
new file mode 100644
index 000000000..039fc5cee
--- /dev/null
+++ b/docs/manpages/tracker-index.1.txt
@@ -0,0 +1,62 @@
+tracker-index(1)
+================
+
+== NAME
+
+tracker-index - List, pause, resume and command data miners indexing
+content
+
+== SYNOPSIS
+
+....
+tracker index --reindex-mime-type <mime1> [[-m [mime2]] ...]
+tracker index --file <file1> [[file2] ...]
+tracker index --import <file1> [[file2] ...]
+tracker index --backup <file> | --restore <file>
+....
+
+== DESCRIPTION
+
+This command perform actions on the current index. The "index" holds a
+snapshot of the working tree in a database.
+
+The index command allows some level of control on existing data indexed,
+such as re-indexing content from a specific demographic - e.g. all JPEG
+images, or simply reindexing an existing or non-existent file.
+
+It may be a good idea to backup your index before an upgrade in case
+there is data loss (which should never happen). In those cases, the
+backup command is made available and of course the restore command will
+import an older data set (or index) into an empty index.
+
+Finally, there is an import feature which makes testing or applying a
+"base" data set for use much easier.
+
+== OPTIONS
+
+*-m, --reindex-mime-type=<__mime1__> [[-m [_mime2_]] ...]*::
+  Re-index files which match the _mime_ type supplied. This is usually
+  used when installing new extractors which support _mime_ types
+  previously unsupported. This forces Tracker to re-index those files.
+  You can use *--reindex-mime-type* more than once per _mime_ type.
+*-f, --index=<__file1__> [[_file2_] ...]*::
+  (Re)index a file matching the _file_ name(s) supplied.
+*-b, --backup=<__file__>*::
+  Begins backing up the Tracker databases and save it to the _file_
+  given.
+*-o, --restore=<__file__>*::
+  Begins restoring a previous backup from the _file_ which points to the
+  location of the backup generated by *--backup*.
+*i, --import=<__file1__> [[_file2_] ...]*::
+  Allows data to be imported into the index / database by providing
+  files with Turtle content.
+
+Multiple _file_ arguments can be provided to import data from multiple
+files.
+
+The _file_ argument can be either a local path or a URI. It also does
+not have to be an absolute path.
+
+== SEE ALSO
+
+*tracker*(1). *Turtle.*
diff --git a/docs/manpages/tracker-miner-fs.1.txt b/docs/manpages/tracker-miner-fs.1.txt
new file mode 100644
index 000000000..34e591d71
--- /dev/null
+++ b/docs/manpages/tracker-miner-fs.1.txt
@@ -0,0 +1,59 @@
+tracker-miner-fs(1)
+===================
+
+== NAME
+
+tracker-miner-fs - Used to crawl the file system to mine data.
+
+== SYNOPSIS
+
+*tracker-miner-fs* [_OPTION_...]
+
+== DESCRIPTION
+
+*tracker-miner-fs* is not supposed to be run by the user since it is
+started by its .desktop file when the user logs in. It can also be
+started manually of course for debugging purposes. You can not run more
+than one instance of this at the same time.
+
+*tracker-miner-fs* mines information about applications and files only.
+
+== OPTIONS
+
+*-?, --help*::
+  Show summary of options.
+*-V, --version*::
+  Returns the version of this binary.
+*-v, --verbosity=\{0|1|2|3}*::
+  Sets the logging level, 0=errors, 1=minimal, 2=detailed, 3=debug.
+*-s, --initial-sleep=SECONDS*::
+  Sets the initial sleep time before crawling the file system is
+  started. If the *--no-daemon* option is used, this option is ignored.
+*-n, --no-daemon*::
+  Tells the miner to exit once all indexing has finished and the
+  database is up to date. This is not the default mode of operation for
+  the miner, usually it stays around acting like a daemon to monitor
+  file updates which may occur over time. This option renders the
+  *--initial-sleep* option moot.
+*-e, --eligible=FILE*::
+  Checks if *FILE* is eligible for being mined based on the current
+  configuration rules. In addition to this, it will check if *FILE*
+  would be monitored for changes. This works with non-existing *FILE*
+  arguments as well as existing *FILE* arguments.
+
+== ENVIRONMENT
+
+*TRACKER_USE_LOG_FILES*::
+  Don't just log to stdout and stderr, but to log files too which are
+  kept in $HOME/.local/share/tracker/. This came into effect in 0.15.3
+  and 0.16.0. After this version of Tracker, logging to file (usually
+  useful for debugging) can only be done by declaring this environment
+  variable.
+*TRACKER_USE_CONFIG_FILES*::
+  Don't use GSettings, instead use a config file similar to how settings
+  were saved in 0.10.x. That is, a file which is much like an .ini file.
+  These are saved to $HOME/.config/tracker/
+
+== SEE ALSO
+
+*tracker-store*(1), *tracker-info*(1).
diff --git a/docs/manpages/tracker-miner-rss.1.txt b/docs/manpages/tracker-miner-rss.1.txt
new file mode 100644
index 000000000..1a752fd26
--- /dev/null
+++ b/docs/manpages/tracker-miner-rss.1.txt
@@ -0,0 +1,46 @@
+tracker-miner-rss(1)
+====================
+
+== NAME
+
+tracker-miner-rss - Used to populate Tracker with RSS feed data.
+
+== SYNOPSIS
+
+*tracker-miner-rss* [_OPTION_...]
+
+== DESCRIPTION
+
+*tracker-miner-rss* is not supposed to be run by the user since it is
+started by its .desktop file when the user logs in. It can also be
+started manually of course for debugging purposes. You can not run more
+than one instance of this at the same time.
+
+*tracker-miner-rss* mines information about RSS feeds only.
+
+== OPTIONS
+
+*-?, --help*::
+  Show summary of options.
+*-V, --version*::
+  Returns the version of this binary.
+*-v, --verbosity=\{0|1|2|3}*::
+  Sets the logging level, 0=errors, 1=minimal, 2=detailed, 3=debug.
+*-a, --add-feed=URL*::
+  Adds a feed to the Tracker store. This must be used with *--title*
+  option. An examples of such a URL would be:
+
+http://planet.gnome.org/atom.xml
+
+http://newsrss.bbc.co.uk/rss/sportplayer_uk_edition/motorsport/rss.xml
+
+...
+
+You can use *tracker-search --feeds* to get the latest feed information.
+
+*-t, --title=STRING*::
+  The title to use when adding a feed (see the *--add-feed* option).
+
+== SEE ALSO
+
+*tracker-store*(1), *tracker-info*(1), *tracker-search*(1).
diff --git a/docs/manpages/tracker-reset.1.txt b/docs/manpages/tracker-reset.1.txt
new file mode 100644
index 000000000..32c1b6f86
--- /dev/null
+++ b/docs/manpages/tracker-reset.1.txt
@@ -0,0 +1,48 @@
+tracker-reset(1)
+================
+
+== NAME
+
+tracker-reset - Reset the index and configuration
+
+== SYNOPSIS
+
+*tracker reset* [--hard | --soft] [--config] [--file _FILE_]
+
+== DESCRIPTION
+
+The reset command will change either your configuration or index
+irreversibly and should be used with care. Other than tags, actual data
+(e.g. files) should not be affected by this command.
+
+The "index" is a link between your content (either locally or remotely)
+and how it can be found quickly using a number of different queries.
+Under the hood, this is done using a database.
+
+Removing all data and starting again from the beginning with an empty
+data set (which is a common use of this command) is done by using the
+hard reset option. This behaves as if Tracker was just installed.
+
+== OPTIONS
+
+*-r, --hard*::
+  This kills all processes in the same way that *tracker daemon* --kill
+  does but it also removes all databases. Restarting *tracker-store*
+  re-creates the databases.
+*-e, --soft*::
+  A soft reset works exactly the same way that *--hard* does, with the
+  exception that the backup and journal are not removed. These are
+  restored when *tracker-store* is restarted. This command is useful if
+  you have a corrupt database but want to reply the journal to restore
+  it to the last known good place.
+*-c, --config*::
+  Resets all configuration to its defaults.
+*-f, --file _FILE_*::
+  Resets all indexed information about _FILE_, works recursively for
+  directories. Nothing will be done if _FILE_ is not currently indexed.
+  After deletion, a request to reindex this data will be immediately
+  issued.
+
+== SEE ALSO
+
+*tracker-daemon*(1). *tracker*(1).
diff --git a/docs/manpages/tracker-search.1.txt b/docs/manpages/tracker-search.1.txt
new file mode 100644
index 000000000..6ab9241f5
--- /dev/null
+++ b/docs/manpages/tracker-search.1.txt
@@ -0,0 +1,98 @@
+tracker-search(1)
+=================
+
+== NAME
+
+tracker-search - Search for content by type or across all types
+
+== SYNOPSIS
+
+*tracker search* [_options_...] [[_expression1_] ...]
+
+== DESCRIPTION
+
+*tracker search* searches all indexed content for _expression_. The
+resource in which _expression_ matches must exist (see *--all* for more
+information). All results are returned in ascending order. In all cases,
+if no _expression_ is given for an argument (like *--folders* for
+example) then ALL items in that category are returned instead.
+
+_expression_::
+  One or more terms to search. The default operation is a logical AND.
+  For logical OR operations, see -r.
+
+== OPTIONS
+
+*-f, --files*::
+  Search for files of any type matching _expression_ (optional).
+*-s, --folders*::
+  Search for folders matching _expression_ (optional).
+*-m, --music*::
+  Search for music files matching _expression_ (optional).
+*--music-albums*::
+  Search for music albums matching _expression_ (optional).
+*--music-artists*::
+  Search for music artists matching _expression_ (optional).
+*-i, --images*::
+  Search for images matching _expression_ (optional).
+*-v, --videos*::
+  Search for videos matching _expression_ (optional).
+*-t, --documents*::
+  Search for documents matching _expression_ (optional).
+*-e, --emails*::
+  Search for emails matching _expression_ (optional). Returns a list of
+  subjects for emails found.
+*-c, --contacts*::
+  Search for contacts matching _expression_ (optional). Returns a list
+  of names and email addresses found.
+*--software*::
+  Search for software installed matching _expression_ (optional).
+  Returns a list of desktop files and application titles found.
+*--software-categories*::
+  Search for software categories matching _expression_ (optional).
+  Returns a list of urns and their categories (e.g. Settings, Video,
+  Utility, etc).
+*--feeds*::
+  Search through RSS feed information matching _expression_ (optional).
+  Returns a list of those found.
+*-b, --bookmarks*::
+  Search through bookmarks matching _expression_ (optional). Returns a
+  list titles and links for each bookmark found.
+*-l, --limit=<__limit__>*::
+  Limit search to _limit_ results. The default is 10 or 512 with
+  --disable-snippets.
+*-o, --offset=<__offset__>*::
+  Offset the search results by _offset_. For example, start at item
+  number 10 in the results. The default is 0.
+*-r, --or-operator*::
+  Use OR for search terms instead of AND (the default)
+*-d, --detailed*::
+  Show the unique URN associated with each search result. This does not
+  apply to --music-albums and --music-artists.
+*-a, --all*::
+  Show results which might not be available. This might bebecause a
+  removable media is not mounted for example. Without this option,
+  resources are only shown if they exist. This option applies to all
+  command line switches except
+*--disable-snippets*::
+  Results are shown with snippets. Snippets are context around the word
+  that was searched for in the first place. This gives some idea of if
+  the resource found is the right one. Snippets require Full Text Search
+  to be compile time enabled AND to not be disabled with --disable-fts.
+  Using --disable-snippets only shows the resources which matched, no
+  context is provided about where the match occurred.
+*--disable-fts*::
+  If Full Text Search (FTS) is available, this option allows it to be
+  disabled for one off searches. This returns results slightly using
+  particular properties to match the search terms (like "nie:title")
+  instead of looking for the search terms amongst ALL properties. It is
+  more limiting to do this, but sometimes searching without FTS can
+  yield better results if the FTS ranking is off.
+*--disable-color*::
+  This disables any ANSI color use on the command line. By default this
+  is enabled to make it easier to see results.
+
+== SEE ALSO
+
+*tracker-store*(1), *tracker-stats*(1), *tracker-tag*(1),
+*tracker-info*(1).
diff --git a/docs/manpages/tracker-status.1.txt b/docs/manpages/tracker-status.1.txt
new file mode 100644
index 000000000..ae9e44b44
--- /dev/null
+++ b/docs/manpages/tracker-status.1.txt
@@ -0,0 +1,65 @@
+tracker-status(1)
+=================
+
+== NAME
+
+tracker-status - Provide status and statistics on the data indexed
+
+== SYNOPSIS
+
+....
+tracker status
+tracker status --stat [-a] [[expression1]...]
+tracker status --collect-debug-info
+....
+
+== DESCRIPTION
+
+Display the status of the current index and data set.
+
+With the *--stat* option, displays statistics about the RDF classes and
+how many of each exist for data set that has been indexed. For example,
+"10 Folders".
+
+This command also provides a way to collect information for debug
+purposes using the *--collect-debug-info* option.
+
+== OPTIONS
+
+*--stat[=__expression__]*::
+  By default, only common and useful classes are shown, e.g.
+  "nfo:Document" or "nfo:Folder", for a full set of statistics, see the
+  *--all* option.
+
+If one or more _expression_ arguments is given, the statistics returned
+are filtered to only show information those RDF types matching
+_expression_ (case folded and matching accented variants). The RDF
+classes are detailed by the Nepomuk otology specification. A list of
+possible classes matching _expression_, see *tracker sparql -c*.
+
+*-a, --all*::
+  Display statistics about ALL RDF classes that exist in the database.
+  Without this option only the common RDF classes will be shown, for
+  example "nfo:Document" and "nfo:FileDataObject".
+
+This option is implied if search terms are provided to filter ALL
+possible statistics.
+
+*--collect-debug-info*::
+  Useful when debugging problems to diagnose the state of Tracker on
+  your system. The data is output to stdout. Useful if bugs are filed
+  against the project itself.
+
+Data collected includes Tracker version in use, disk space available,
+size of the databases on the disk, the configuration in use, states of
+the index (e.g. last filesystem crawl, data set locale, etc.) and
+finally statistics about the data in the database (e.g. how many
+"nfo:FileDataObject" resources exist).
+
+== SEE ALSO
+
+*tracker-store*(1), *tracker-control*(1), *tracker-sparql*(1),
+*tracker-info*(1).
+
+- *http://nepomuk.semanticdesktop.org/*
+- *http://www.w3.org/TR/rdf-sparql-query/*
diff --git a/docs/manpages/tracker-tag.1.txt b/docs/manpages/tracker-tag.1.txt
new file mode 100644
index 000000000..da28d26c7
--- /dev/null
+++ b/docs/manpages/tracker-tag.1.txt
@@ -0,0 +1,75 @@
+tracker-tag(1)
+==============
+
+== NAME
+
+tracker-tag - Add, remove and list tags.
+
+== SYNOPSIS
+
+....
+tracker tag FILE1 [FILE2 ...] [-l <limit>] [-o <offset>] [-r]
+tracker tag -t [[TAG1] [TAG2] ...] [-s] [-r]
+tracker tag -a <TAG> [-e <description>] 
+tracker tag -d <TAG>
+....
+
+== DESCRIPTION
+
+List tags for local files or by the tag labels themselves if -t is used.
+
+It's also possible to manage tags with the -a and and -d options.
+
+The _FILE_ argument can be either a local path or a URI. It also does
+not have to be an absolute path.
+
+== OPTIONS
+
+*-t, --list*::
+  List all tags. Results include the number of files associated with
+  that tag and the tag's unique identifier. You can show the files
+  associated with each tag by using --show-files.
+
+The _TAG_ arguments are optional. If no _TAG_ argument is specified, all
+tags are listed. If one or more __TAG__s are given, either matching tags
+are listed (OR condition). For example, this will match any tags named
+either _foo_, _bar_ or _baz_:
+
+....
+$ tracker-tag -t foo bar baz
+....
+
+*-s, --show-files*::
+  Show the files associated with each tag. This option is ONLY available
+  WITH the *--list* option.
+*-a, --add=TAG*::
+  Add a tag with the name _TAG_. If no _FILE_ arguments are specified,
+  the tag is simply created (if it didn'talready exist) and no files are
+  associated with it. Multiple _FILE_ arguments can be specified.
+*-d, --delete=TAG*::
+  Delete a tag with the name _TAG_. If no _FILE_ arguments are
+  specified, the tag is deleted for ALL files. If _FILE_ arguments are
+  specified, only those files have the _TAG_ deleted.
+*-e, --description=STRING*::
+  This option ONLY applies when using *--add* and provides a description
+  to go with the tag label according to _STRING_.
+*-l, --limit=N*::
+  Limit search to N results. The default is 512.
+*-o, --offset=N*::
+  Offset the search results by N. For example, start at item number 10
+  in the results. The default is 0.
+*-r, --and-operator*::
+  Use AND operator for search terms instead of OR (the default). For
+  example:
+
+....
+$ tracker-tag -s -t sliff sloff
+....
+
+Should show files in the database that have both the _sliff_ and _sloff_
+tags.
+
+== SEE ALSO
+
+*tracker-store*(1), *tracker-sparql*(1), *tracker-search*(1),
+*tracker-info*(1).
diff --git a/docs/manpages/tracker-writeback.1.txt b/docs/manpages/tracker-writeback.1.txt
new file mode 100644
index 000000000..fabfac556
--- /dev/null
+++ b/docs/manpages/tracker-writeback.1.txt
@@ -0,0 +1,42 @@
+tracker-writeback(1)
+====================
+
+== NAME
+
+tracker-writeback - Used to write metadata set in Tracker back to
+physical files.
+
+== SYNOPSIS
+
+*tracker-writeback* [_OPTION_...]
+
+== DESCRIPTION
+
+*tracker-writeback* is not supposed to be run by the user since it is
+started by its .desktop file when the user logs in. It can also be
+started manually of course for debugging purposes. You can not run more
+than one instance of this at the same time.
+
+*tracker-writeback* writes metadata from the Tracker database back into
+files only. Currently support is limited to XMP metadata (which covers
+PNG, JPEG, TIFF, MP4 and 3GPP formats), play lists (which covers
+MPEGURL, SCPLS and IRIVER formats) and taglib supported mime types
+(which covers MP3, MP4, OGG, WAV, FLAC and some Windows media formats).
+
+Data is only written back if write-back is enabled in the
+tracker-miner-fs configuration.
+
+== OPTIONS
+
+*-?, --help*::
+  Show summary of options.
+*-V, --version*::
+  Returns the version of this binary.
+*-v, --verbosity=\{0|1|2|3}*::
+  Sets the logging level, 0=errors, 1=minimal, 2=detailed, 3=debug.
+*-d, --disable-shutdown*::
+  Disable shutting down after 30 seconds of inactivity.
+
+== SEE ALSO
+
+*tracker-store*(1), *tracker-miner-fs*(1). *tracker-extract*(1).
diff --git a/meson.build b/meson.build
index 25b51b174..04b82d9f7 100644
--- a/meson.build
+++ b/meson.build
@@ -106,6 +106,11 @@ if have_tracker_miner_rss
   endif
 endif
 
+if get_option('man')
+  asciidoc = find_program('asciidoc')
+  xsltproc = find_program('xsltproc')
+endif
+
 add_project_arguments('-Wformat', '-Wformat-security', language: 'c')
 
 # There are various gchar vs. unsigned char warnings that occur in extract
diff --git a/meson_options.txt b/meson_options.txt
index 5d40ee2e0..19959dc95 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -9,6 +9,8 @@ option('functional_tests', type: 'boolean', value: true,
        description: 'Enable the Tracker functional test suite')
 option('guarantee_metadata', type: 'boolean', value: false,
        description: 'Set nie:title and nie:contentCreated from filename and mtime if no metadata available')
+option('man', type: 'boolean', value: true,
+       description: 'Install man pages')
 option('miner_fs', type: 'boolean', value: true,
        description: 'Enable the Tracker filesystem miner')
 option('miner_rss', type: 'boolean', value: true,
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]