Menu : html yaml json edit check reindex dump unset
* 

title Présentation résumée de YamlDoc
modified 2019-02-23 00:00:00
abstract

YamlDoc

YamlDoc est un système de gestion documentaire fondé sur :

YamlDoc est notamment étendu pour permettre :

yaml

Fondé sur le format Yaml

Le format Yaml permet de structurer des documents ou des données par combinaison de listes, tableaux associatifs et données scalaires. Similaire au format JSON, il a l'avantage d'être très lisible pour nous les humains tout en étant facile à comprendre pour les machines.
Il permet de structurer aussi bien des documents composés principalement de textes comme le présent document, que des bases de données comme par exemple la base historique des communes, des structures de graphe comme le thésaurus EuroVoc ou des documents strcturés complexes comme le modèle de données Inspire déduit du règlement interopérabilité.
Enfin, l'édition de documents Yaml est fournie par divers éditeurs de texte comme Notepad++ sous Windows ou TextMate sur Mac.

semantic

Sémantique bien connue

Lorsque cela est adapté, la sémantique des champs des tableaux associatifs Yaml respecte les standards suivants:

ydclass

Définition de classes de documents

Une classe de documents correspond à:

  • un schéma JSON,
  • une classe d'objets Php définissant:
    • des méthodes de consultation interactive du document,
    • une API REST de consultation en machine to machine,
    • une API Php d'utilisation du document en interne à YamlDoc.

Par exemple la classe YamlSkos définit des documents qui correspondent à un thésaurus décrit en SKOS. Ainsi, le schéma JSON précise coment le thésaurus doit être structuré en Yaml, et la classe Php permet :

  • d'afficher en HTML le thésaurus ou une de ses parties (Concept, micro-thésaurus),
  • d'exposer une API REST de consultation du thésaurus ou d'une de ses parties,
  • de fournir des méthodes Php pour utiliser le thésaurus.

La gestion des classes est développée dans ce document.

markdown

Markdown

Le langage Markdown est utilisé pour formatter des textes (titres, gras, italique, liste de puces, liens URL, ...) ; son utilisation est illustrée ici. Les différentes parties du présent document constituent un autre exemple d'utilisation du Markdown.

viewer

Visualiseur

Un visualiseur en mode web permet de visualiser les documents et de naviguer entre eux. Il permet de vérifier qu'un document est conforme à son schéma. Il offre aussi une fonctionnalité limitée de modification.
Un mode de visualisation par défaut est défini mais le visualisateur peut être étendu pour s'adapter aux différentes structures de document. Par exemples:

  • l'extension YamlData permet de visualiser le contenu d'une base de données,
  • l'extension YamlSkos permet de naviguer facilement au sein d'un thésaurus Skos,
  • l'extension DataModel permet de naviguer facilement au sein d'un modèle de données.

Le visualisateur de l'espace public est accessible sous http://georef.eu/yamldoc/?doc=index.
Son code source est disponible sur: Github.

ypath

Ypath: mécanisme de requêtes simples

La fourniture d'une chaine de caractères particulière (appelée Ypath), permet de sélectionner une partie d'un document ou d'une base de données. Son utilisation est illustrée par les exemples ci-dessous :

textSearch

Recherche plein texte

En tapant un mot ou plusieurs dans le champ de saisie, une recherche plein texte est effectuée dans les documents. Si la chaine ne commence pas par un '/' la chaine est interprétée comme une liste de mots.
Par exemple, en tapant le mot bourgogne on trouve les fragments d'EuroVoc et de geohisto qui contiennent ce mot.
On notera que l'indexation est effectuée par fragment, c'est à dire chaine ou texte à l'intérieur du document, et non document par document. C'est un point important par exemple pour indexer des bases de données.
Ainsi, par exemple, lors de la recherche du mot bourgogne, un des résultats est le fragment d'Eurovoc correspondant au ypath /concepts/5032/historyNote/fr/0 ; il s'agit donc de la première note historique en français associée au concept 5032. Il est simple de remonter ici au concept en modifiant le ypath.

Différentes possibilités de recherche sont proposées :

  • en indiquant plusieurs mots on cherche les fragments contenant au moins un des mots, par exemple la chaine Franche Comté permet de trouver les fragments contenant soit Franche soit Comté,
  • en faisant précéder les mots par un + on cherche les fragments contenant tous les mots, par exemple la chaine +Franche +Comté permet de trouver les fragments contenant à la fois Franche et Comté,
  • en faisant précéder un mot par un - on exclue les fragments contenant ce mot, par exemple la chaine +Franche -Comté permet de trouver les fragments contenant Franche mais pas Comté,
  • en faisant suivre un mot par * on cherche les mots commencant par le mot, par exemple la chaine geograph* permet de trouver géographie et geography.

Il est aussi possible de restreindre la recherche à un document, voire à certains fragments, par exemple on peut rechercher le mot géographie uniquement dans les concepts d'Eurovoc en indiquant dans le champ key eurovoc/concepts.

git

Organisation d'espaces documentaires partagés chacun sous la forme d'une archive Git

Les documents sont partitionnés en différents espaces documentaires avec pour chacun des accès en lecture et/ou en écriture pour certains utilisateurs.
Chaque espace documentaire correspond à une archive Git qui peut ainsi être partagée. Outre l'utilisation en mode web, les différents utilisateurs d'un espace peuvent ainsi modifier les documents sur leur poste local au moyen d'un éditeur de texte. Le logiciel Git est utilisé pour assurer la synchronisation entre les différentes copies.

Dans un premier temps, seuls 2 espaces sont définis: un espace public et un espace privé.
L'archive Git de l'espace public est accessible à l'URL: https://github.com/benoitdavidfr/yamldocs et le visualisateur de cet espace est accessible sous http://georef.eu/yamldoc/?doc=index.

L'utilisation du mécanisme des branches de git permet d'isoler les modifications de différents utilisateurs ; cette fonctionnalité potentielle n'a pas encore été mise en oeuvre.

query

Requêtes en Php

Les documents correspondant à des bases de données peuvent facilement être exploités par des scripts Php qui effectuent des requêtes dans les données. Ces requêtes sont appelées comme des documents.
Par exemples :

Du point de vue implémentation, un document requête est un script Php qui renvoie un array Php à partir duquel sera créé un objet Yamldoc par exemple pour afficher le résultat de la requête.