[tracker/wip/carlosg/hotdoc: 7/40] docs: Port "sparql functions" doc to markdown

[Carlos Garnacho <carlosg src gnome org>]

commit 3b93da63946be92f236fe58986dcd1ff7d7a08e8
Author: Carlos Garnacho <carlosg gnome org>
Date:   Thu May 27 19:12:38 2021 +0200

    docs: Port "sparql functions" doc to markdown

 docs/reference/libtracker-sparql/meson.build       |   1 +
 .../libtracker-sparql/sparql-functions.md          | 349 +++++++++++++++
 .../libtracker-sparql/sparql-functions.xml         | 467 ---------------------
 3 files changed, 350 insertions(+), 467 deletions(-)
---
diff --git a/docs/reference/libtracker-sparql/meson.build b/docs/reference/libtracker-sparql/meson.build
index b528ac231..5b66d0eab 100644
--- a/docs/reference/libtracker-sparql/meson.build
+++ b/docs/reference/libtracker-sparql/meson.build
@@ -2,6 +2,7 @@ content = [
   'overview.md',
   'limits.md',
   'performance.md',
+  'sparql-functions.md',
   'tutorial.md',
 ]
 
diff --git a/docs/reference/libtracker-sparql/sparql-functions.md 
b/docs/reference/libtracker-sparql/sparql-functions.md
new file mode 100644
index 000000000..33aebd663
--- /dev/null
+++ b/docs/reference/libtracker-sparql/sparql-functions.md
@@ -0,0 +1,349 @@
+Title: Builtin SPARQL functions
+
+Besides the functions built in the SPARQL 1.1 syntax, type casts
+and functional properties, Tracker supports a number of SPARQL
+functions. Some of these functions have correspondences in XPath.
+
+## String functions
+
+### `fn:lower-case`
+
+```SPARQL
+fn:lower-case (?string)
+```
+
+Converts a string to lowercase, equivalent to `LCASE`.
+
+### `fn:upper-case`
+
+```SPARQL
+fn:upper-case (?string)
+```
+
+Converts a string to uppercase, equivalent to `UCASE`.
+
+### `fn:contains`
+
+```SPARQL
+fn:contains (?haystack, ?needle)
+```
+
+Returns a boolean indicating whether `?needle` is
+found in `?haystack`. Equivalent to `CONTAINS`.
+
+### `fn:starts-with`
+
+```SPARQL
+fn:starts-with (?string, ?prefix)
+```
+
+Returns a boolean indicating whether `?string`
+starts with `?prefix`. Equivalent to `STRSTARTS`.
+
+### `fn:ends-with`
+
+```SPARQL
+fn:ends-with (?string, ?suffix)
+```
+
+Returns a boolean indicating whether `?string`
+ends with `?suffix`. Equivalent to `STRENDS`.
+
+### `fn:substring`
+
+```SPARQL
+fn:substring (?string, ?startLoc)
+fn:substring (?string, ?startLoc, ?endLoc)
+```
+
+Returns a substring delimited by the integer
+`?startLoc` and `?endLoc` arguments. If `?endLoc`
+is omitted, the end of the string is used.
+
+### `fn:concat`
+
+```SPARQL
+fn:concat (?string1, ?string2, ..., ?stringN)
+```
+
+Takes a variable number of arguments and returns a string concatenation
+of all its returned values. Equivalent to `CONCAT`.
+
+### `fn:string-join`
+
+```SPARQL
+fn:string-join ((?string1, ?string2, ...), ?separator)
+```
+
+Takes a variable number of arguments and returns a string concatenation
+using `?separator` to join all elements.
+
+### `fn:replace`
+
+```SPARQL
+fn:replace (?string, ?regex, ?replacement)
+fn:replace (?string, ?regex, ?replacement, ?flags)
+```
+
+Performs string replacement on `?string`. All
+matches of `?regex` are replaced by `?replacement` in
+the returned string. This function is similar to `REPLACE`.
+
+The `?flags` argument is optional, a case search
+is performed if not provided.
+
+If `?flags` contains the character `“s”`, a dot metacharacter (".") in
+`?regex` matches all characters, including newlines. Without it,
+newlines are excluded.
+
+If `?flags` contains the character `“m”`, the “start of line”
+(`^`) and “end of line” (`$`) constructs match immediately following or
+immediately before any newline in the string. If not set these constructs
+will respectively match the start and end of the full string.
+
+If `?flags` contains the character `“i”`, search is caseless.
+
+If `?flags` contains the character `“x”`, `?regex` is
+interpreted to be an extended regular expression.
+
+### `tracker:case-fold`
+
+```SPARQL
+tracker:case-fold (?string)
+```
+
+Converts a string into a form that is independent of case.
+
+### `tracker:title-order`
+
+```SPARQL
+tracker:title-order (?string)
+```
+
+Manipulates a string to remove leading articles for sorting
+purposes, e.g. “Wall, The”. Best used in `ORDER BY` clauses.
+
+### `tracker:ascii-lower-case`
+
+```SPARQL
+tracker:ascii-lower-case (?string)
+```
+
+Converts an ASCII string to lowercase, equivalent to `LCASE`.
+
+### `tracker:normalize`
+
+```SPARQL
+tracker:normalize (?string, ?option)
+```
+
+Normalizes `?string`. The `?option` string must be one of
+`nfc`, `nfd`, `nfkc` or `nfkd`.
+
+### `tracker:unaccent`
+
+```SPARQL
+tracker:unaccent (?string)
+```
+
+Removes accents from a string.
+
+### `tracker:coalesce`
+
+```SPARQL
+tracker:coalesce (?value1, ?value2, ..., ?valueN)
+```
+
+Picks the first non-null value. Equivalent to `COALESCE`.
+
+### `tracker:strip-punctuation`
+
+``` SPARQL
+tracker:strip-punctuation (?string)
+```
+
+Removes any Unicode character which has the General
+Category value of P (Punctuation) from the string.
+
+## DateTime functions
+
+### `fn:year-from-dateTime`
+
+```SPARQL
+fn:year-from-dateTime (?date)
+```
+
+Returns the year from a `xsd:date` type, a `xsd:dateTime`
+type, or a ISO8601 date string. This function is equivalent
+to `YEAR`.
+
+### `fn:month-from-dateTime`
+
+```SPARQL
+fn:month-from-dateTime (?date)
+```
+
+Returns the month from a `xsd:date` type, a `xsd:dateTime`
+type, or a ISO8601 date string. This function is equivalent to `MONTH`.
+
+### `fn:day-from-dateTime`
+
+```SPARQL
+fn:day-from-dateTime (?date)
+```
+
+Returns the day from a `xsd:date` type, a `xsd:dateTime`
+type, or a ISO8601 date string. This function is equivalent to `DAY`.
+
+### `fn:hours-from-dateTime`
+
+```SPARQL
+fn:hours-from-dateTime (?date)
+```
+
+Returns the hours from a `xsd:dateTime` type or a ISO8601
+datetime string. This function is equivalent to `HOURS`.
+
+### `fn:minutes-from-dateTime`
+
+```SPARQL
+fn:minutes-from-dateTime (?date)
+```
+
+Returns the minutes from a `xsd:dateTime` type
+or a ISO8601 datetime string. This function is equivalent to
+`MINUTES`.
+
+### `fn:seconds-from-dateTime`
+
+```SPARQL
+fn:seconds-from-dateTime (?date)
+```
+
+Returns the seconds from a `xsd:dateTime` type
+or a ISO8601 datetime string. This function is equivalent to
+`SECONDS`.
+
+### `fn:timezone-from-dateTime`
+
+```SPARQL
+fn:timezone-from-dateTime (?date)
+```
+
+Returns the timezone offset in minutes. This function is similar, but
+not equivalent to `TIMEZONE` or `TZ`.
+
+## Full-text search functions
+
+### `fts:rank`
+
+```SPARQL
+fts:rank (?match)
+```
+
+Returns the rank of a full-text search match. Must be
+used in conjunction with `fts:match`.
+
+### `fts:offsets`
+
+```SPARQL
+fts:offsets (?match)
+```
+
+Returns a string describing the offsets of a full-text search
+match. Must be used in conjunction with `fts:match`. The returned
+string has the format:
+
+```
+prefix:property:offset prefix:property:offset prefix:property:offset
+```
+
+### `fts:snippet`
+
+```SPARQL
+fts:snippet (?match)
+fts:snippet (?match, ?delimStart, ?delimEnd)
+fts:snippet (?match, ?delimStart, ?delimEnd, ?ellipsis)
+fts:snippet (?match, ?delimStart, ?delimEnd, ?ellipsis, ?numTokens)
+```
+
+Returns a snippet string in accordance to the full-text search string.
+Must be used in conjunction with `fts:match`.
+
+The `?delimStart` and `?delimEnd` parameters allow specifying the
+delimiters of the match strings inside the snippet.
+
+The `?ellipsis` parameter allows specifying
+the string used to separate distant matches in the snippet string.
+
+The `?numTokens` parameter specifies the number
+of tokens the returned string should containt at most.
+
+## URI functions
+
+### `tracker:uri-is-parent`
+
+```SPARQL
+tracker:uri-is-parent (?parent, ?uri)
+```
+
+Returns a boolean value expressing whether
+`?parent` is a parent of `?uri`.
+
+### `tracker:uri-is-descendant`
+
+```SPARQL
+tracker:uri-is-descendant (?uri1, ?uri2, ..., ?uriN, ?child)
+```
+
+Returns a boolean value expressing whether one of the
+given URIs are a parent (direct or indirect) of
+`?child`.
+
+### `tracker:string-from-filename`
+
+```SPARQL
+tracker:string-from-filename (?filename)
+```
+
+Returns a UTF-8 string from a filename.
+
+## Geolocation functions
+
+### `tracker:cartesian-distance`
+
+```SPARQL
+tracker:cartesian-distance (?lat1, ?lat2, ?lon1, ?lon2)
+```
+
+Calculates the cartesian distance between 2 points expressed
+by `?lat1 / ?lon1` and `?lat2 / ?lon2`.
+
+### `tracker:haversine-distance`
+
+```SPARQL
+tracker:haversine-distance (?lat1, ?lat2, ?lon1, ?lon2)
+```
+
+Calculates the haversine distance between 2 points expressed
+by `?lat1 / ?lon1` and `?lat2 / ?lon2`.
+
+## Identification functions
+
+### `tracker:id`
+
+```SPARQL
+tracker:id (?urn)
+```
+
+Returns the internal ID corresponding to a URN.
+Its inverse operation is `tracker:uri`.
+
+### `tracker:uri`
+
+```SPARQL
+tracker:uri (?id)
+```
+
+Returns the URN that corresponds to an ID.
+Its inverse operation is `tracker:id`