[tracker/wip/carlosg/hotdoc: 36/47] docs: Include Nepomuk documentation in hotdoc

From: Carlos Garnacho <carlosg src gnome org>
To: commits-list gnome org
Cc:
Subject: [tracker/wip/carlosg/hotdoc: 36/47] docs: Include Nepomuk documentation in hotdoc
Date: Thu, 26 Aug 2021 12:06:34 +0000 (UTC)

commit 043de63c47b983fae517be1230a0e05e972dba6e
Author: Carlos Garnacho <carlosg gnome org>
Date:   Tue Aug 3 16:53:13 2021 +0200

    docs: Include Nepomuk documentation in hotdoc
    
    Move away from it being in its on gtk-doc build.

 docs/reference/libtracker-sparql/meson.build       |  21 +--
 .../libtracker-sparql/mfo-introduction.md          |  17 +++
 .../libtracker-sparql/nco-introduction.md          |   5 +
 docs/reference/libtracker-sparql/nepomuk.md        |  10 ++
 .../libtracker-sparql/nie-introduction.md          |  82 +++++++++++
 .../libtracker-sparql/nmm-introduction.md          |  23 +++
 docs/reference/libtracker-sparql/sitemap.txt       |  10 ++
 docs/reference/meson.build                         |   1 -
 docs/reference/ontology/meson.build                |  23 ---
 docs/reference/ontology/mfo-introduction.xml       |  21 ---
 docs/reference/ontology/mlo-introduction.xml       |  58 --------
 docs/reference/ontology/nco-introduction.xml       |  55 -------
 docs/reference/ontology/nie-introduction.xml       | 158 ---------------------
 docs/reference/ontology/nmm-introduction.xml       |  28 ----
 docs/reference/ontology/nmo-introduction.xml       |  90 ------------
 docs/reference/ontology/ontology-docs.xml          |  52 -------
 docs/reference/ontology/ontology-sections.txt      |   0
 docs/reference/ontology/version.xml.in             |   1 -
 18 files changed, 159 insertions(+), 496 deletions(-)
---
diff --git a/docs/reference/libtracker-sparql/meson.build b/docs/reference/libtracker-sparql/meson.build
index d616dc1f2..bb24c56ba 100644
--- a/docs/reference/libtracker-sparql/meson.build
+++ b/docs/reference/libtracker-sparql/meson.build
@@ -28,6 +28,18 @@ base_ontology_docs = custom_target('ontology-docgen',
     build_by_default: true,
 )
 
+nepomuk_ontology_docs = custom_target('nepomuk-docgen',
+    output: ['nie-ontology.md'],
+    command: [tracker_docgen,
+              '--md',
+              '-d', join_paths(source_root, 'src/ontologies/nepomuk'),
+              '-o', join_paths(meson.current_build_dir()),
+              '-e', meson.current_source_dir()],
+    depends: tracker_docgen,
+    depend_files: [base_ontology],
+    build_by_default: true,
+)
+
 content = [
   'overview.md',
   'ontologies.md',
@@ -39,15 +51,6 @@ content = [
   'tutorial.md',
 ]
 
-generated_content = [
-  'examples.md',
-  'xsd-ontology.md',
-  'dc-ontology.md',
-  'rdf-ontology.md',
-  'rdfs-ontology.md',
-  'nrl-ontology.md',
-]
-
 required_hotdoc_extensions = [
   'gi-extension',
   'devhelp-extension',
diff --git a/docs/reference/libtracker-sparql/mfo-introduction.md 
b/docs/reference/libtracker-sparql/mfo-introduction.md
new file mode 100644
index 000000000..73b0b09b2
--- /dev/null
+++ b/docs/reference/libtracker-sparql/mfo-introduction.md
@@ -0,0 +1,17 @@
+# Overview
+
+## Introduction
+
+This ontology is an abstract representation of entries coming from feeds. These feeds can be blogs (any of 
the common syndication formats can be translated into this representation), podcasts or even some online 
services (like flickr).
+
+The basic assumption in the ontology is that all these feeds are unidirectional conversations with (from) 
the author of the content and every post on those channels is a message.
+
+The source of the posts, the feed itself, is an instance of 
[mfo:FeedChannel](mfo-ontology.md#mfo:FeedChannel). Each post in that feed will be an instance of 
[mfo:FeedMessage](mfo-ontology.md#mfo:FeedMessage). The relation between the messages and the channel comes 
from their superclasses, [nmo:communicationChannel](nmo-ontology.md#nmo:communicationChannel) (taking into 
account that [mfo:FeedChannel](mfo-ontology.md#mfo:FeedChannel) is a subclass of 
[nmo:CommunicationChannel](nmo-ontology.md#nmo:CommunicationChannel) and 
[mfo:FeedMessage](mfo-ontology.md#mfo:FeedMessage) a subclass of [nmo:Message](nmo-ontology.md#nmo:Message).
+
+A post can be plain text but can contain also more things like links, videos or Mp3. We represent those 
internal pieces in instances of [mfo:Enclosure](mfo-ontology.md#mfo:Enclosure). This class has properties to 
link with the remote and local representation of the resource (in case the content has been downloaded).
+
+Finally, the three important classes (mfo:FeedChannel, mfo:FeedMessage, mfo:Enclosure) are subclasses of 
[mfo:FeedElement](mfo-ontology.md#mfo:FeedElement), just an abstract class to share the link with 
mfo:FeedSettings. [mfo:FeedSettings](mfo-ontology.md#mfo:FeedSettings) contains some common configuration 
options. Not all of them applies to all, but it is a quite cleaner solution. For instance the 
[mfo:maxSize](mfo-ontology.md#mfo:maxSize) property only makes sense per-enclosure, while the 
[mfo:updateInterval](mfo-ontology.md#mfo:updateInterval) is useful for the channel.
+
+## Special remarks
+
+In some feeds there can be multiple enclosures together in a group, representing the same resource in 
different formats, qualities, resolutions, etc. Until further notify, the group will be represented using 
[nie:identifier](nie-ontology.md#nie:identifier) property. To mark the default enclosure of the group, there 
is a [mfo:groupDefault](mfo-ontology.md#mfo:groupDefault) property.
diff --git a/docs/reference/libtracker-sparql/nco-introduction.md 
b/docs/reference/libtracker-sparql/nco-introduction.md
new file mode 100644
index 000000000..0bc29ff42
--- /dev/null
+++ b/docs/reference/libtracker-sparql/nco-introduction.md
@@ -0,0 +1,5 @@
+# Overview
+
+## Introduction
+
+This is the ontology modelling contacts and postal addresses. It also extends the original nepomuk adding 
the Instant Messaging account details, because an 'identity' in an IM account can be consider also a contact.
diff --git a/docs/reference/libtracker-sparql/nepomuk.md b/docs/reference/libtracker-sparql/nepomuk.md
new file mode 100644
index 000000000..4745414b6
--- /dev/null
+++ b/docs/reference/libtracker-sparql/nepomuk.md
@@ -0,0 +1,10 @@
+---
+title: Nepomuk
+short-description: The Nepomuk ontology
+...
+
+# Nepomuk
+
+Nepomuk is the swiss army knife of the semantic desktop. It defines
+data structures for almost any kind of data you might want to store
+in a workstation machine.
diff --git a/docs/reference/libtracker-sparql/nie-introduction.md 
b/docs/reference/libtracker-sparql/nie-introduction.md
new file mode 100644
index 000000000..cc386c45b
--- /dev/null
+++ b/docs/reference/libtracker-sparql/nie-introduction.md
@@ -0,0 +1,82 @@
+# Overview
+
+## Introduction
+
+The core of the NEPOMUK Information Element Ontology and the entire
+Ontology Framework revolves around the concepts of [nie:DataObject](nie-ontology.md#nie:DataObject) and
+[nie:InformationElement](nie-ontology.md#nie:InformationElement). They express  the representation
+and content of a piece of data. Their specialized subclasses (defined
+in the other ontologies) can be used to classify
+a wide array of desktop resources and express them in RDF.
+
+[nie:DataObject](nie-ontology.md#nie:DataObject) class represents a bunch of
+bytes somewhere (local or remote), the physical entity that contain
+data. The *meaning* (interpretation) of that entity, the
+information for the user contained in those bytes (e.g. a music file,
+a picture) is represented on the
+[nie:InformationElement](nie-ontology.md#nie:InformationElement) side of the
+ontology.
+
+Both sides are linked using the
+property [nie:interpretedAs](nie-ontology.md#nie:interpretedAs) (and its reverse
+[nie:isStoredAs](nie-ontology.md#nie:isStoredAs)), indicating the correspondence
+between the physical element and its interpretation. There is also a
+property to
+link [nie:InformationElement](nie-ontology.md#nie:InformationElement)s,
+representing the logical containment between them (like a picture and
+its album).
+
+## Common properties
+
+Given that the classes defined in this ontology are the superclasses for almost
+everything in the Nepomuk set of ontologies, the
+properties defined here will be inherited for a lot of classes. It is
+worth to comment few of them with special relevance:
+
+ - [nie:title](nie-ontology.md#nie:title): Title or name or short text describing the item
+ - [nie:description](nie-ontology.md#nie:description): More verbose comment about the element
+ - [nie:language](nie-ontology.md#nie:language): To specify the language of the item.
+ - [nie:plainTextContent](nie-ontology.md#nie:plainTextContent): Just the raw content of the file, if it 
makes sense as text.
+ - [nie:generator](nie-ontology.md#nie:generator): Software/Agent that set/produced the information.
+ - [nie:usageCounter](nie-ontology.md#nie:usageCounter): Count number of accesses to the information. It can 
be an indicator of relevance for advanced searches
+
+## Date and timestamp representations
+
+There are few important dates for the life-cycle of a resource. These dates are properties of the 
nie:InformationElement class, and inherited for its subclasses:
+
+ - [nie:informationElementDate](nie-ontology.md#nie:informationElementDate): This is an ''abstract'' 
property that act as superproperty of the other dates. Don't use it directly.
+ - [nie:contentLastModified](nie-ontology.md#nie:contentLastModified): Modification time of a resource. 
Usually the mtime of a local file, or information from the server for online resources.
+ - [nie:contentCreated](nie-ontology.md#nie:contentCreated): Creation time of the content. If the contents 
is created by an application, the same application should set the value of this property. Note that this 
property can be undefined for resources in the filesystem because the creation time is not available in the 
most common filesystem formats.
+ - [nie:contentAccessed](nie-ontology.md#nie:contentAccessed): For resources coming from the filesystem, 
this is the usual access time to the file. For other  kind of resources (online or virtual), the application 
accessing it should update its value.
+ - [nie:lastRefreshed](nie-ontology.md#nie:lastRefreshed): The time that the content was last refreshed. 
Usually for remote resources.
+
+## URIs and full representation of a file
+
+One of the most common resources in a desktop is a file. Given the split between Data Objects and 
Information Elements, some times it is not clear how a real file is represented into Nepomuk. Here are some 
indications:
+
+ 1. Every file (local or remote) should generate one DataObject instance and an InformationElement instance.
+ 2. Even when Data Objects and Information Elements are different entities.
+ 3. The URI of the DataObject is the real location of the item (e.g. ''file://path/to/file.mp3'')
+ 3. The URI of the InformationElement(s) will be autogenerated IDs.
+ 4. Every DataObject must have the property [nie:url](nie-ontology.md#nie:url), that points to the location 
of the resource, and should be used by any program that wants to access it.
+ 5. The InformationElement and DataObject are related via the nie:isStoredAs / nie:interpretedAs properties.
+
+Here comes an example, for the image file /home/user/a.jpeg:
+
+```
+# Properties as nmm:Photo
+<urn:uuid:10293801928301293> a nmm:Photo ;
+       nie:isStoredAs <file:///home/user/a.jpeg> ;
+       nfo:width 49 ;
+       nfo:height 36 ;
+       nmm:flash &lt;nmm:flash-off&gt;;
+       nmm:whiteBalance <nmm:white-balance-automatic> ;
+       nfo:equipment [ a nfo:Equipment ; nfo:make 'Nokia'; nfo:model 'N900'; nfo:equipmentSoftware 
'Tracknon' ] .
+
+# Properties from nfo:FileDataObject
+<file:///home/user/a.jpeg> a nfo:FileDataObject ;
+       nie:interpretedAs <urn:uuid:10293801928301293> ;
+       nfo:fileSize 12341234 ;
+       # Mandatory for any nfo:DataObject
+       nie:url <file:///home/user/a.jpeg> .
+```
diff --git a/docs/reference/libtracker-sparql/nmm-introduction.md 
b/docs/reference/libtracker-sparql/nmm-introduction.md
new file mode 100644
index 000000000..8b89fc709
--- /dev/null
+++ b/docs/reference/libtracker-sparql/nmm-introduction.md
@@ -0,0 +1,23 @@
+# Overview
+
+## Introduction
+
+This ontology extends NIE (Nepomuk Information Element ontology) and NFO (Nepomuk File Ontology) into the 
domains of multimedia, including Images, Videos, Music and Radio, and includes a couple of properties to 
support uPnP sharing.
+
+This ontology replaces/complements NID3 and NEXIF. Those ontologies are a direct map of the respective 
metadata standards, which makes very difficult to map cleanly other standards (like gstreamer metadata, mp4, 
ogg, and so on). Besides, those ontologies contain a lot of very low level technical information that is 
useless to the average user of the desktop.
+
+Our approach in NMM is to keep the minimum properties that make sense for the user, and are present in all 
(or almost all) specific metadata formats. A profesional photographer (or musician) who needs more 
fine-grained details for its documents, is free to add also nID3 information or other extensions to the 
ontology.
+
+## Images domain
+
+The core of images in NMM ontology is the class [nmm:Photo](nmm-ontology.md#nmm:Photo). It is (through a 
long hierarchy) a [nie:InformationElement](nie-ontology.md#nie:InformationElement), an interpretation of some 
bytes. It has properties to store the basic information (camera, metering mode, white balance, flash), and 
inherits from [nfo:Image](nfo-ontology.md#nfo:Image) orientation 
([nfo:orientation](nfo-ontology.md#nfo:orientation)) and resolution 
([nfo:verticalResolution](nfo-ontology.md#nfo:verticalResolution) and 
[nfo:horizontalResolution](nfo-ontology.md#nfo:horizontalResolution)).
+
+Note that for tags, nie:keywords (from nie:InformationElement) can be used, or the [NAO](nao-ontology.md) 
ontology.
+
+## Radio domain
+
+NMM includes classes and properties to represent analog and digital radio stations. There is a class 
[nmm:RadioStation](nmm-ontology.md#nmm:RadioStation) on the 
[nie:InformationElement](nie-ontology.md#nie:InformationElement) side of the ontology, representing what the 
user sees about that station (genre via PTY codes, icon, plus title inherited from nie:InformationElement)
+
+A [nmm:RadioStation](nmm-ontology.md#nmm:RadioStation) can have one or more 
[nmm:carrier](nmm-ontology.md#nmm:carrier) properties representing the different frequencies (or links when 
it is digitial) it can be tuned. This property links the station with 
[nfo:MediaStream](nfo-ontology.md#nfo:MediaStream), but usually it will point to one of the subclasses: 
[nmm:DigitalRadio](nmm-ontology.md#nmm:DigitalRadio) (if digital) or 
[nmm:AnalogRadio](nmm-ontology.md#nmm:AnalogRadio) (if analog). An analog station has properties as 
modulation and frequency, while the digial station has streaming bitrate, encoding or protocol.
+
+Note that nfo:MediaStream refers to a flux of bytes/data, and it is on the 
[nie:DataObject](nie-ontology.md#nie:DataObject)<link linkend="nie-DataObject">nie:DataObject</link> side of 
the ontology.
diff --git a/docs/reference/libtracker-sparql/sitemap.txt b/docs/reference/libtracker-sparql/sitemap.txt
index 25fca8227..750975a03 100644
--- a/docs/reference/libtracker-sparql/sitemap.txt
+++ b/docs/reference/libtracker-sparql/sitemap.txt
@@ -3,6 +3,16 @@ index.md
        examples.md
        tutorial.md
        ontologies.md
+               nepomuk.md
+                       nie-ontology.md
+                       nao-ontology.md
+                       nfo-ontology.md
+                       nco-ontology.md
+                       nmm-ontology.md
+                       mfo-ontology.md
+                       slo-ontology.md
+                       tracker-ontology.md
+                       osinfo-ontology.md
                base-ontology.md
                        xsd-ontology.md
                        dc-ontology.md
diff --git a/docs/reference/meson.build b/docs/reference/meson.build
index 0c76203fa..4919f91a0 100644
--- a/docs/reference/meson.build
+++ b/docs/reference/meson.build
@@ -10,4 +10,3 @@ icon_images = files(
 )
 
 subdir('libtracker-sparql')
-subdir('ontology')
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]