GNOME.org
 

[tracker/sam/website-manpages: 1/2] Use asciidoc to generate manpages

commit 758d2b466939826012bedeefea2abc061abce81b
Author: Sam Thursfield <sam afuera me uk>
Date:   Sun Apr 5 13:19:31 2020 +0200

    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            |  45 ++++-
 docs/manpages/tracker-endpoint.1     |  72 --------
 docs/manpages/tracker-endpoint.1.txt |  68 +++++++
 docs/manpages/tracker-export.1.txt   |  31 ++++
 docs/manpages/tracker-import.1.txt   |  23 +++
 docs/manpages/tracker-info.1         |  62 -------
 docs/manpages/tracker-info.1.txt     |  62 +++++++
 docs/manpages/tracker-sparql.1       | 339 -----------------------------------
 docs/manpages/tracker-sparql.1.txt   | 307 +++++++++++++++++++++++++++++++
 docs/manpages/tracker-sql.1          |  48 -----
 docs/manpages/tracker-sql.1.txt      |  50 ++++++
 11 files changed, 580 insertions(+), 527 deletions(-)
---
diff --git a/docs/manpages/meson.build b/docs/manpages/meson.build
index 7274d1d36..8c92333e3 100644
--- a/docs/manpages/meson.build
+++ b/docs/manpages/meson.build
@@ -1,6 +1,39 @@
-install_man('tracker-endpoint.1')
-install_man('tracker-export.1')
-install_man('tracker-import.1')
-install_man('tracker-info.1')
-install_man('tracker-sparql.1')
-install_man('tracker-sql.1')
+asciidoc = find_program('asciidoc')
+xsltproc = find_program('xsltproc')
+
+manpages = [
+  'tracker-endpoint.1',
+  'tracker-export.1',
+  'tracker-import.1',
+  'tracker-info.1',
+  'tracker-sparql.1',
+  'tracker-sql.1',
+]
+
+foreach manpage : manpages
+  manpage_src = manpage + '.txt'
+  manpage_xml = manpage + '.xml'
+
+  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',
+              '--output', '@OUTPUT@',
+              '/etc/asciidoc/docbook-xsl/manpage.xsl', '@INPUT@'],
+    input: xml,
+    output: manpage,
+    install: true,
+    install_dir: get_option('mandir'),
+  )
+endforeach
diff --git a/docs/manpages/tracker-endpoint.1.txt b/docs/manpages/tracker-endpoint.1.txt
new file mode 100644
index 000000000..96ed80b88
--- /dev/null
+++ b/docs/manpages/tracker-endpoint.1.txt
@@ -0,0 +1,68 @@
+tracker-endpoint(1)
+===================
+
+== NAME
+tracker-endpoint - Create a SPARQL endpoint
+
+== SYNOPSIS
+
+....
+tracker endpoint [--dbus-service | -b] <service_name>
+                 [--database-path | -d] <database_path>
+                 [[--ontology | -o] <ontology_name> |
+                  [--ontology-path | -p] <ontology_path>]
+                 [[--system | --session]]
+....
+
+== DESCRIPTION
+
+This command allows creating SPARQL endpoints. The endpoint will be able
+to handle SPARQL select and update queries, and notify about changes in
+it.
+
+The endpoint is exported via DBus, accessible through the given
+_service_name_, either using it in a *SERVICE* clause, or by creating a
+dedicated bus-based SPARQL connection.
+
+When creating a database, the _ontology_name_ (or alternatively, a
+_ontology_path_) must be provided in order to generate the database. If
+_ontology_name_ is used, the ontology must exist in
+_$datadir/tracker/ontologies_
+
+The database itself will be stored according to _database_path_.
+
+== OPTIONS
+
+*-b, --dbus-service=<__service_name__>*::
+  Service name to use on the endpoint.
+*-d, --database-path=<__database_path__>*::
+  The path where the database will be stored.
+*-o, --ontology*::
+  The name of an ontology in _$datadir/tracker/ontologies_ to use on the
+  constructed database.
+*-p, --ontology-path*::
+  Full path to an ontology to use on the constructed database.
+*--session*::
+  Use the session bus. This is the default.
+*--system*::
+  Use the system bus.
+
+== EXAMPLES
+
+Export a Nepomuk endpoint with the _org.example.Example1_ bus name.
+
+  $ tracker endpoint -b org.example.Example1 -o nepomuk -d /tmp/example1
+
+Access this endpoint with the *tracker-sparql(1)* subcommand.
+
+  $ tracker sparql --dbus-service org.example.Example1 -q "
+    SELECT ?s ?o
+    WHERE {
+      ?u a ?o
+    }"
+
+== SEE ALSO
+
+*tracker-sparql*(1),
+
+<https://www.w3.org/TR/sparql11-query/>
diff --git a/docs/manpages/tracker-export.1.txt b/docs/manpages/tracker-export.1.txt
new file mode 100644
index 000000000..6adcd8e0f
--- /dev/null
+++ b/docs/manpages/tracker-export.1.txt
@@ -0,0 +1,31 @@
+tracker-export(1)
+=================
+
+== NAME
+
+tracker-export - Export all data from a Tracker database.
+
+== SYNOPSIS
+
+*tracker export* [_options_...]
+
+== DESCRIPTION
+
+*tracker export* exports all data stored in a Tracker database, in
+Turtle format.
+
+The output is intended to be machine-readable, not human readable. Use a
+tool such as rapper(1) to convert the data to different formats.
+
+== EXAMPLES
+
+Export all data from Tracker Index and prettify the output using
+rapper(1).::
+
+....
+$ tracker export -b org.freedesktop.Tracker1.Miner.Files | rapper - -I . -i turtle -o turtle
+....
+
+== SEE ALSO
+
+*tracker-import*(1), *tracker-sparql*(1).
diff --git a/docs/manpages/tracker-import.1.txt b/docs/manpages/tracker-import.1.txt
new file mode 100644
index 000000000..01286725e
--- /dev/null
+++ b/docs/manpages/tracker-import.1.txt
@@ -0,0 +1,23 @@
+tracker-import(1)
+=================
+
+== NAME
+
+tracker-import - Import data into a Tracker database.
+
+== SYNOPSIS
+
+*tracker import* FILE.ttl
+
+== DESCRIPTION
+
+*tracker import* imports data into a Tracker database.
+
+The data must conform to the existing ontology of the database.
+
+The data must be in Turtle format. You can use a tool such as rapper(1)
+to convert the data from other formats to Turtle.
+
+== SEE ALSO
+
+*tracker-export*(1), *tracker-sparql*(1).
diff --git a/docs/manpages/tracker-info.1.txt b/docs/manpages/tracker-info.1.txt
new file mode 100644
index 000000000..2aceae700
--- /dev/null
+++ b/docs/manpages/tracker-info.1.txt
@@ -0,0 +1,62 @@
+tracker-info(1)
+===============
+
+== NAME
+
+tracker-info - Retrieve all information available for a certain file.
+
+== SYNOPSIS
+
+*tracker info* [_options_...] <__file1__> [[_file2_] ...]
+
+== DESCRIPTION
+
+*tracker info* asks for all the known metadata available for the given
+_file_.
+
+Multiple _file_ arguments can be provided to retrieve information about
+multiple files.
+
+The _file_ argument can be either a local path or a URI. It also does
+not have to be an absolute path.
+
+== OPTIONS
+
+*-f, --full-namespaces*::
+  By default, all keys and values reported about any given _file_ are
+  returned in shortened form, for example, _nie:title_ is shown instead
+  of _http://www.semanticdesktop.org/ontologies/2007/01/19/nie#title_.
+  This makes things much easier to see generally and the output is less
+  cluttered. This option reverses that so FULL namespaces are shown
+  instead.
+*-c, --plain-text-content*::
+  If the resource being displayed has nie:PlainTextContent (i.e.
+  information about the content of the resource, which could be the
+  contents of a file on the disk), then this option displays that in the
+  output.
+*-i, --resource-is-iri*::
+  In most cases, the _file_ argument supplied points to a URL or PATH
+  which is queried for according to the resource associated with it by
+  _nie:url_. However, in cases where the _file_ specified turns out to
+  be the actual URN itself, this argument is required to tell "tracker
+  info" not to do the extra step of looking up the URN related by
+  _nie:url_.
+
+For example, consider that you store URNs by the actual URL itself and
+use the unique nie:url in another resource (which is quite reasonable
+when using containers and multi-resource conditions), you would need
+this argument to tell "tracker info" that the _file_ supplied is
+actually a URN not URL.
+
+*-t, --turtle*::
+  Output results as Turtle RDF. If -f is enabled, full URIs are shown
+  for subjects, predicates and objects; otherwise, shortened URIs are
+  used, and all the prefixes Tracker knows about are printed at the top
+  of the output.
+
+== SEE ALSO
+
+*tracker-store*(1), *tracker-sparql*(1).
+
+*http://nepomuk.semanticdesktop.org/*
+*http://www.w3.org/TR/rdf-sparql-query/*
diff --git a/docs/manpages/tracker-sparql.1.txt b/docs/manpages/tracker-sparql.1.txt
new file mode 100644
index 000000000..1b6d312bc
--- /dev/null
+++ b/docs/manpages/tracker-sparql.1.txt
@@ -0,0 +1,307 @@
+tracker-sparql(1)
+=================
+
+== NAME
+
+tracker-sparql - Use SparQL to query the Tracker databases.
+
+== SYNOPSIS
+
+....
+tracker sparql -q <sparql> [-u] | -f <file>
+tracker sparql -t [class] [-s <needle>] [-p]
+tracker sparql [-c] [-p] [-x] [-n [class]] [-i [property]] [-s <needle>]
+tracker sparql [--get-longhand <class>] [--get-shorthand <class>]
+....
+
+== DESCRIPTION
+
+This command allows probing of the current database schema (also known
+as ontology) and running low level queries or updates on the data set.
+In terms of the database ontology, it's easy to find out what properties
+are indexed for speed, or notified on changes, what classes are
+available and the properties belonging to those classes. There are also
+visual tools to display an ascii tree layout of the classes and their
+relationships to each other.
+
+When the caller runs a query, the query is in RDF and SPARQL. This can
+be done two ways. Either by providing a _file_ with the query or by
+providing a string with the _sparql_ query.
+
+The _file_ argument can be either a local path or a URI. It also does
+not have to be an absolute path.
+
+== OPTIONS
+
+*-f, --file=<__file__>*::
+  Use a _file_ with SPARQL content to query or update.
+*-q, --query=<__sparql__>*::
+  Use a _sparql_ string to query the database with.
+*-u, --update*::
+  This has to be used with *--query*. This tells "tracker sparql" to use
+  the SPARQL update extensions so it knows it isn't a regular data
+  lookup request. So if your query is intended to change data in the
+  database, this option is needed.
+*-c, --list-classes*::
+  Returns a list of classes which describe the ontology used for storing
+  data. These classes are also used in queries. For example,
+  _http://www.w3.org/2000/01/rdf-schema#Resource_ is one of many classes
+  which should be returned here.
+*-x, --list-class-prefixes*::
+  Returns a list of classes and their related prefixes. Prefixes are
+  used to make querying a lot simpler and are much like an alias. For
+  example, _http://www.w3.org/2000/01/rdf-schema#Resource_ has the
+  prefix _rdfs_ so queries can be cut down to:
+
+"SELECT ?u WHERE \{ ?u a rdfs:Resource }"
+
+*-p, --list-properties=[_class_]*::
+  Returns a list of properties which pertain to a _class_. You can use
+  both formats here for the _class_, either the full name
+  _http://www.semanticdesktop.org/ontologies/2007/03/22/nfo#Video_ or
+  the shortened prefix name _nfo:Video_.
+
+This gives the following result:
+
+----
+$ tracker sparql -p nfo:Video
+
+Properties: 2
+  http://www.semanticdesktop.org/ontologies/2007/03/22/nfo#frameRate
+  http://www.semanticdesktop.org/ontologies/2007/03/22/nfo#frameCount
+----
+
+These properties _nfo:frameRate_ and _nfo:frameCount_ can then be used
+in queries.
+
+See also *--tree* and *--query*.
+
+*-n, --list-notifies=[_class_]*::
+  Returns a list of classes which are notified over D-Bus about any
+  changes that occur in the database. The _class_ does not have to be
+  supplied here. This is optional and filters the results according to
+  any argument supplied. With no _class_, all classes are listed.
+
+*-i, --list-indexes=[_property_]*::
+  Returns a list of properties which are indexed in the database.
+  Indexes improves query speed but also add an indexing penalty. The
+  _property_ does not have to be supplied here. This is optional and
+  filters the results according to any argument supplied. With no
+  _property_, all properties are listed.
+
+*-t, --tree=[_class_]*::
+  Prints a tree showing all parent classes of _class_ in the ontology.
+  The _class_ can be provided in shorthand or longhand (see
+  *--get-shorthand* and *--get-longhand* for details). For example:
+
+----
+$ tracker sparql -t nmo:MMSMessage
+ROOT
+  +-- rdfs:Resource (C)
+  |  +-- nie:InformationElement (C)
+  |  |  +-- nfo:Document (C)
+  |  |  |  +-- nfo:TextDocument (C)
+  |  |  |  |  `-- nmo:Message (C)
+  |  |  |  |  |  +-- nmo:PhoneMessage (C)
+  |  |  |  |  |  |  `-- nmo:MMSMessage (C)
+----
+
+If no _class_ is given, the entire tree is shown.
+
+The *--search* command line option can be used to highlight parts of the
+tree you're looking for. The search is case insensitive.
+
+The *--properties* command line option can be used to show properties
+for each class displayed, for example:
+
+----
+$ tracker sparql -t nfo:FileDataObject -p
+ROOT
+  +-- rdfs:Resource (C)
+  |  --> http://purl.org/dc/elements/1.1/contributor (P)
+  |  --> http://purl.org/dc/elements/1.1/coverage (P)
+  |  --> http://purl.org/dc/elements/1.1/creator (P)
+  |  --> http://purl.org/dc/elements/1.1/date (P)
+  |  --> http://purl.org/dc/elements/1.1/description (P)
+  |  --> http://purl.org/dc/elements/1.1/format (P)
+  |  --> http://purl.org/dc/elements/1.1/identifier (P)
+  |  --> http://purl.org/dc/elements/1.1/language (P)
+  |  --> http://purl.org/dc/elements/1.1/publisher (P)
+  |  --> http://purl.org/dc/elements/1.1/relation (P)
+  |  --> http://purl.org/dc/elements/1.1/rights (P)
+  |  --> http://purl.org/dc/elements/1.1/source (P)
+  |  --> http://purl.org/dc/elements/1.1/subject (P)
+  |  --> http://purl.org/dc/elements/1.1/title (P)
+  |  --> http://purl.org/dc/elements/1.1/type (P)
+  |  --> nao:deprecated (P)
+  |  --> nao:hasTag (P)
+  |  --> nao:identifier (P)
+  |  --> nao:isRelated (P)
+  |  --> nao:lastModified (P)
+  |  --> nao:numericRating (P)
+  |  --> rdf:type (P)
+  |  --> rdfs:comment (P)
+  |  --> rdfs:label (P)
+  |  --> tracker:added (P)
+  |  --> tracker:damaged (P)
+  |  --> tracker:modified (P)
+  |  +-- nie:DataObject (C)
+  |  |  --> nfo:belongsToContainer (P)
+  |  |  --> nie:byteSize (P)
+  |  |  --> nie:created (P)
+  |  |  --> nie:dataSource (P)
+  |  |  --> nie:interpretedAs (P)
+  |  |  --> nie:isPartOf (P)
+  |  |  --> nie:lastRefreshed (P)
+  |  |  --> nie:url (P)
+  |  |  --> tracker:available (P)
+  |  |  +-- nfo:FileDataObject (C)
+  |  |  |  --> nfo:fileCreated (P)
+  |  |  |  --> nfo:fileLastAccessed (P)
+  |  |  |  --> nfo:fileLastModified (P)
+  |  |  |  --> nfo:fileName (P)
+  |  |  |  --> nfo:fileOwner (P)
+  |  |  |  --> nfo:fileSize (P)
+  |  |  |  --> nfo:hasHash (P)
+  |  |  |  --> nfo:permissions (P)
+----
+
+*-s, --search=<__needle__>*::
+  Returns a list of classes and properties which partially match
+  _needle_ in the ontology. This is a case insensitive match, for
+  example:
+
+----
+$ tracker sparql -s text
+
+Classes: 4
+  http://www.semanticdesktop.org/ontologies/2007/03/22/nfo#TextDocument
+  http://www.semanticdesktop.org/ontologies/2007/03/22/nfo#PlainTextDocument
+  http://www.semanticdesktop.org/ontologies/2007/03/22/nfo#PaginatedTextDocument
+  http://www.tracker-project.org/temp/nmm#SynchronizedText
+
+Properties: 4
+  http://www.tracker-project.org/ontologies/tracker#fulltextIndexed
+  http://www.semanticdesktop.org/ontologies/2007/01/19/nie#plainTextContent
+  http://www.semanticdesktop.org/ontologies/2007/03/22/nmo#plainTextMessageContent
+  http://www.tracker-project.org/temp/scal#textLocation
+----
+
+See also *--tree*.
+
+*--get-shorthand=<__class__>*::
+  Returns the shorthand for a class given by a URL. For example:
+
+----
+$ tracker sparql --get-shorthand 
http://www.semanticdesktop.org/ontologies/2007/03/22/nmo#plainTextMessageContent
+nmo:plainTextMessageContent
+----
+
+*--get-longhand=<__class__>*::
+  Returns the longhand for a class given in the form of CLASS:PROPERTY.
+  For example:
+
+----
+$ tracker sparql --get-longhand nmm:MusicPiece
+http://www.tracker-project.org/temp/nmm#MusicPiece
+----
+
+== EXAMPLES
+
+List all classes::
++
+....
+$ tracker sparql -q "SELECT ?cl WHERE { ?cl a rdfs:Class }"
+....
+
+List all properties for the Resources class (see --list-properties)::
++
+----
+$ tracker sparql -q "SELECT ?prop WHERE {
+    ?prop a rdf:Property ;
+    rdfs:domain <http://www.w3.org/2000/01/rdf-schema#Resource>
+}"
+----
+
+List all class namespace prefixes::
++
+----
+$ tracker sparql -q "SELECT ?prefix ?ns WHERE {
+    ?ns a tracker:Namespace ;
+    tracker:prefix ?prefix
+}"
+----
+
+List all music files::
++
+----
+$ tracker sparql -q "SELECT ?song WHERE { ?song a nmm:MusicPiece }"
+----
+
+List all music albums, showing title, track count, and length in seconds.::
++
+----
+$ tracker sparql -q "SELECT ?title COUNT(?song)
+                    AS songs
+                    SUM(?length) AS totallength
+                    WHERE {
+    ?album a nmm:MusicAlbum ;
+    nie:title ?title .
+    ?song nmm:musicAlbum ?album ;
+    nfo:duration ?length
+} GROUP BY ?album"
+----
+
+List all music from a particular artist::
++
+----
+$ tracker sparql -q "SELECT ?song ?title WHERE {
+    ?song nmm:performer [ nmm:artistName 'Artist Name' ] ;
+    nie:title ?title
+}"
+----
+
+Set the played count for a song::
++
+----
+$ tracker sparql -u -q "DELETE {
+    <file:///home/user/Music/song.mp3> nie:usageCounter ?count
+} WHERE {
+    <file:///home/user/Music/song.mp3> nie:usageCounter ?count
+} INSERT {
+    <file:///home/user/Music/song.mp3> nie:usageCounter 42
+}"
+----
+
+List all image files::
++
+----
+$ tracker sparql -q "SELECT ?image WHERE { ?image a nfo:Image }"
+----
+
+List all image files with a specific tag::
++
+----
+$ tracker sparql -q "SELECT ?image WHERE {
+    ?image a nfo:Image ;
+    nao:hasTag [ nao:prefLabel 'tag' ]
+}"
+----
+
+List all image files created on a specific month and order by date::
++
+----
+$ tracker sparql -q "SELECT ?image ?date WHERE {
+    ?image a nfo:Image ;
+    nie:contentCreated ?date .
+    FILTER (?date >= '2008-07-01T00:00:00' &&
+            ?date <  '2008-08-01T00:00:00')
+} ORDER BY ?date"
+----
+
+== SEE ALSO
+
+*tracker-sql*(1), *tracker-store*(1), *tracker-info*(1).
+
+*http://nepomuk.semanticdesktop.org/*
+*http://www.w3.org/TR/rdf-sparql-query/*
diff --git a/docs/manpages/tracker-sql.1.txt b/docs/manpages/tracker-sql.1.txt
new file mode 100644
index 000000000..f389a4eb0
--- /dev/null
+++ b/docs/manpages/tracker-sql.1.txt
@@ -0,0 +1,50 @@
+tracker-sql(1)
+==============
+
+== NAME
+
+tracker-sql - Use SQL to query the Tracker databases.
+
+== SYNOPSIS
+
+....
+tracker sql -q <sql> | -f <file>
+....
+
+== DESCRIPTION
+
+This command allows probing of the current database. When using commands
+like *tracker sparql*, the SPARQL used is translated into SQL before
+being run on the database. This allows direct use of the database using
+SQL avoiding the SPARQL engine entirely.
+
+The caller can run a query two ways, either by providing a _file_ with
+the query or by providing a string with the _sql_ query.
+
+The _file_ argument can be either a local path or a URI. It also does
+not have to be an absolute path.
+
+== OPTIONS
+
+*-f, --file=<__file__>*::
+  Use a _file_ with SPARQL content to query. Don't forget to end all
+  queries with a semicolon (;) and also to use quotes around table
+  names. The quotes are important because most tables are named after
+  ontology classes like "nfo:Document" and queries will fail without the
+  quotes.
+*-q, --query=<__sql__>*::
+  Use a _sql_ string to query the database with.
+
+== EXAMPLES
+
+Show first 10 "nfo:Document" entries where the TOC is not NULL::
++
+----
+$ tracker sql -q 'SELECT * FROM "nfo:Document" WHERE "nfo:tableOfContents" NOT NULL LIMIT 10;'
+----
+
+== SEE ALSO
+
+*tracker-sparql*(1), *tracker-store*(1), *tracker-info*(1).
+
+*http://en.wikipedia.org/wiki/SQL*
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]