GNOME.org
 

[tracker/sam/website] Use asciidoc to generate manpages

commit 2492e5b41d1940bd3472dd6bb7101f4c9ad1d9c3
Author: Sam Thursfield <sam afuera me uk>
Date:   Sun Mar 29 00:42:52 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                          |  43 ++-
 docs/manpages/tracker-endpoint.1                   |  72 -----
 docs/manpages/tracker-endpoint.1.txt               |  68 +++++
 docs/manpages/tracker-info.1                       |  62 ----
 docs/manpages/tracker-info.1.txt                   |  62 ++++
 .../{tracker-sparql.1 => tracker-sparql.1.txt}     | 337 ++++++++++-----------
 docs/manpages/tracker-sql.1                        |  48 ---
 docs/manpages/tracker-sql.1.txt                    |  50 +++
 8 files changed, 372 insertions(+), 370 deletions(-)
---
diff --git a/docs/manpages/meson.build b/docs/manpages/meson.build
index cd60b2dbe..00dbd2e8f 100644
--- a/docs/manpages/meson.build
+++ b/docs/manpages/meson.build
@@ -1,4 +1,39 @@
-install_man('tracker-endpoint.1')
-install_man('tracker-info.1')
-install_man('tracker-sparql.1')
-install_man('tracker-sql.1')
+# This is part of the asciidoc package.
+asciidoc = find_program('asciidoc')
+
+xsltproc = find_program('xsltproc')
+
+manpages = [
+  'tracker-endpoint.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-info.1.txt b/docs/manpages/tracker-info.1.txt
new file mode 100644
index 000000000..b92ad0246
--- /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 b/docs/manpages/tracker-sparql.1.txt
similarity index 50%
rename from docs/manpages/tracker-sparql.1
rename to docs/manpages/tracker-sparql.1.txt
index c34b89827..5bdcb86ee 100644
--- a/docs/manpages/tracker-sparql.1
+++ b/docs/manpages/tracker-sparql.1.txt
@@ -1,105 +1,100 @@
-.TH tracker-sparql 1 "July 2009" GNU "User Commands"
-
-.SH NAME
-tracker-sparql \- Use SparQL to query the Tracker databases.
-
-.SH SYNOPSIS
-.nf
-\fBtracker sparql\fR \-q <\fIsparql\fR> [\-u] | \-f <\fIfile\fR>
-\fBtracker sparql\fR \-t [\fIclass\fR] [-s <\fIneedle\fR>] [\-p]
-\fBtracker sparql\fR [\-c] [\-p] [\-x] [-n [\fIclass\fR]] [\-i [\fIproperty\fR]] [\-s <\fIneedle\fR>]
-\fBtracker sparql\fR [\-\-get\-longhand <\fIclass\fR>] [\-\-get\-shorthand <\fIclass\fR>]
-.fi
-
-.SH 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 \fIfile\fR with the query or by
-providing a string with the \fIsparql\fR query.
-
-The \fIfile\fR argument can be either a local path or a URI. It also
-does not have to be an absolute path.
-
-.SH OPTIONS
-.TP
-.B \-f, \-\-file\fR=<\fIfile\fR>
-Use a \fIfile\fR with SPARQL content to query or update.
-.TP
-.B \-q, \-\-query\fR=<\fIsparql\fR>
-Use a \fIsparql\fR string to query the database with.
-.TP
-.B \-u, \-\-update
-This has to be used with \fB\-\-query\fR. 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.
-.TP
-.B \-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,
-\fIhttp://www.w3.org/2000/01/rdf-schema#Resource\fR is one of many
-classes which should be returned here.
-.TP
-.B \-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, \fIhttp://www.w3.org/2000/01/rdf-schema#Resource\fR has the
-prefix \fIrdfs\fR so queries can be cut down to:
-
-"SELECT ?u WHERE { ?u a rdfs:Resource }"
-
-.TP
-.B \-p, \-\-list\-properties\fR=[\fIclass\fR]
-Returns a list of properties which pertain to a \fIclass\fR. You can
-use both formats here for the \fIclass\fR, either the full name
-\fIhttp://www.semanticdesktop.org/ontologies/2007/03/22/nfo#Video\fR
-or the shortened prefix name \fInfo:Video\fR.
+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:
 
-.nf
+....
 $ 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
-.fi
-
-These properties \fInfo:frameRate\fR and \fInfo:frameCount\fR can then
-be used in queries.
-
-See also \fB\-\-tree\fR and \fB\-\-query\fR.
-
-.TP
-.B \-n, \-\-list\-notifies\fR=[\fIclass\fR]
-Returns a list of classes which are notified over D-Bus about any
-changes that occur in the database. The \fIclass\fR does not have to be
-supplied here. This is optional and filters the results according to
-any argument supplied. With no \fIclass\fR, all classes are listed.
-
-.TP
-.B \-i, \-\-list\-indexes\fR=[\fIproperty\fR]
-Returns a list of properties which are indexed in the database.
-Indexes improves query speed but also add an indexing penalty. The
-\fIproperty\fR does not have to be supplied here. This is optional and
-filters the results according to any argument supplied. With no
-\fIproperty\fR, all properties are listed.
-
-.TP
-.B \-t, \-\-tree\fR=[\fIclass\fR]
-Prints a tree showing all parent classes of \fIclass\fR in the
-ontology. The \fIclass\fR can be provided in shorthand or longhand (see
-\fB\-\-get\-shorthand\fR and \fB\-\-get\-longhand\fR for details). For
-example:
-
-.nf
+....
+
+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)
@@ -109,19 +104,17 @@ ROOT
   |  |  |  |  `-- nmo:Message (C)
   |  |  |  |  |  +-- nmo:PhoneMessage (C)
   |  |  |  |  |  |  `-- nmo:MMSMessage (C)
-.fi
+....
 
-If no \fIclass\fR is given, the entire tree is shown.
+If no _class_ is given, the entire tree is shown.
 
-The
-.B \-\-search
-command line option can be used to highlight parts of the tree you're
-looking for. The search is case insensitive.
+The *--search* command line option can be used to highlight parts of the
+tree you're looking for. The search is case insensitive.
 
-The \fB\-\-properties\fR command line option can be used to show
-properties for each class displayed, for example:
+The *--properties* command line option can be used to show properties
+for each class displayed, for example:
 
-.nf
+....
 $ tracker sparql -t nfo:FileDataObject -p
 ROOT
   +-- rdfs:Resource (C)
@@ -171,15 +164,14 @@ ROOT
   |  |  |  --> nfo:fileSize (P)
   |  |  |  --> nfo:hasHash (P)
   |  |  |  --> nfo:permissions (P)
-.fi
+....
 
-.TP
-.B \-s, \-\-search\fR=<\fIneedle\fR>
-Returns a list of classes and properties which partially match
-\fIneedle\fR in the ontology. This is a case insensitive match, for
-example:
+*-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:
 
-.nf
+....
 $ tracker sparql -s text
 
 Classes: 4
@@ -193,74 +185,63 @@ Properties: 4
   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
-.fi
+....
 
-See also \fB\-\-tree\fR.
+See also *--tree*.
 
-.TP
-.B \-\-get\-shorthand\fR=<\fIclass\fR>
-Returns the shorthand for a class given by a URL.
-For example:
+*--get-shorthand=<__class__>*::
+  Returns the shorthand for a class given by a URL. For example:
 
-.nf
+....
 $ tracker sparql --get-shorthand 
http://www.semanticdesktop.org/ontologies/2007/03/22/nmo#plainTextMessageContent
 nmo:plainTextMessageContent
-.fi
+....
 
-.TP
-.B \-\-get\-longhand\fR=<\fIclass\fR>
-Returns the longhand for a class given in the form of CLASS:PROPERTY.
-For example:
+*--get-longhand=<__class__>*::
+  Returns the longhand for a class given in the form of CLASS:PROPERTY.
+  For example:
 
-.nf
+....
 $ tracker sparql --get-longhand nmm:MusicPiece
 http://www.tracker-project.org/temp/nmm#MusicPiece
-.fi
+....
+
+== EXAMPLES
 
-.SH EXAMPLES
-.TP
-List all classes
+List all classes::
 
-.BR
-.nf
+....
 $ tracker sparql -q "SELECT ?cl WHERE { ?cl a rdfs:Class }"
-.fi
+....
 
-.TP
-List all properties for the Resources class (see \-\-list-properties)
+List all properties for the Resources class (see --list-properties)::
 
-.BR
-.nf
+....
 $ tracker sparql -q "SELECT ?prop WHERE {
       ?prop a rdf:Property ;
       rdfs:domain <http://www.w3.org/2000/01/rdf-schema#Resource>
  }"
-.fi
+....
 
-.TP
-List all class namespace prefixes
+List all class namespace prefixes::
 
-.BR
-.nf
+....
 $ tracker sparql -q "SELECT ?prefix ?ns WHERE {
       ?ns a tracker:Namespace ;
       tracker:prefix ?prefix
   }"
-.fi
+....
 
-.TP
-List all music files
+List all music files::
 
-.BR
-.nf
+....
 $ tracker sparql -q "SELECT ?song WHERE { ?song a nmm:MusicPiece }"
-.fi
+....
 
-.TP
-List all music albums, showing title, track count, and length in seconds.
+List all music albums, showing title, track count, and length in
+seconds.::
 
-.BR
-.nf
+....
 $ tracker sparql -q "SELECT ?title COUNT(?song)
                      AS songs
                      SUM(?length) AS totallength
@@ -270,24 +251,20 @@ $ tracker sparql -q "SELECT ?title COUNT(?song)
       ?song nmm:musicAlbum ?album ;
       nfo:duration ?length
   } GROUP BY ?album"
-.fi
+....
 
-.TP
-List all music from a particular artist
+List all music from a particular artist::
 
-.BR
-.nf
+....
 $ tracker sparql -q "SELECT ?song ?title WHERE {
       ?song nmm:performer [ nmm:artistName 'Artist Name' ] ;
       nie:title ?title
   }"
-.fi
+....
 
-.TP
-Set the played count for a song
+Set the played count for a song::
 
-.BR
-.nf
+....
 $ tracker sparql -u -q "DELETE {
       <file:///home/user/Music/song.mp3> nie:usageCounter ?count
   } WHERE {
@@ -295,45 +272,37 @@ $ tracker sparql -u -q "DELETE {
   } INSERT {
       <file:///home/user/Music/song.mp3> nie:usageCounter 42
   }"
-.fi
+....
 
-.TP
-List all image files
+List all image files::
 
-.BR
-.nf
+....
 $ tracker sparql -q "SELECT ?image WHERE { ?image a nfo:Image }"
-.fi
+....
 
-.TP
-List all image files with a specific tag
+List all image files with a specific tag::
 
-.BR
-.nf
+....
 $ tracker sparql -q "SELECT ?image WHERE {
       ?image a nfo:Image ;
       nao:hasTag [ nao:prefLabel 'tag' ]
   }"
-.fi
+....
 
-.TP
-List all image files created on a specific month and order by date
+List all image files created on a specific month and order by date::
 
-.BR
-.nf
+....
 $ 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"
-.fi
-
-.SH SEE ALSO
-.BR tracker-sql (1),
-.BR tracker-store (1),
-.BR tracker-info (1).
-.TP
-.BR http://nepomuk.semanticdesktop.org/
-.TP
-.BR http://www.w3.org/TR/rdf-sparql-query/
+....
+
+== 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..424ab6e4d
--- /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]