Brouillons fiches Groupe Outils Humanistica

FichesOutils.md

API CTS

• Type : Standard d'API
• Language : URL, XML
• Difficulté d'utilisation : Basse
• Tadirah :
  • Research Activities > 7_Dissemination > Sharing
  • Research Activities > 7_Dissemination > Publishing
  • Research Activities > 1_Capture > Discovering
  • Research Activities > 1_Capture > Discovering
• Description courte : Une API CTS donne la capacité de citer des passages de textes en utilisant des identifiants logiques
• Site : http://cite-architecture.github.io/cts/

CapiTainS Guidelines

• Type : Guidelines
• Language : XML, TEI
• Lié à : API CTS; Epidoc
• Difficulté d'utilisation : Basse
• Prérequis : TEI, API CTS
• Tadirah :
  • Research Activities > 7_Dissemination > Sharing
  • Research Activities > 7_Dissemination > Publishing
• Description courte : Les guidelines CapiTainS offrent des règles souples pour structurer ces données en XML TEI ou Epidoc pour les utiliser dans les API CTS
• Site : http://capitains.github.io

CapiTainS Nautilus

• Type : Application Web
• Language : Python
• Lié à : API CTS; CapiTainS Guidelines
• Difficulté d'utilisation : Moyen
• Prérequis : Python, CapiTainS Guidelines
• Tadirah :
  • Research Activities > 7_Dissemination > Sharing
  • Research Activities > 7_Dissemination > Publishing
• Description courte : Nautilus est une application basée sur le framework web Flask (Python) qui permet de fournir une API CTS en utilisant des dossiers suivant les guidelines CapiTainS.
• Informations supplémentaires : la difficulté principale liée à Nautilus est sa mise à disposition sur un serveur et non l'utilisation sur son propre ordinateur
• Site : https://github.com/Capitains/Nautilus

Docker Kitematic

• Type : Logiciel
• Lié à : Machine Virtuelle, Docker
• Difficulté d'utilisation : Basse
• Description courte : Docker Kitematic est une interface utilisateur pour Docker qui permet de partager des machines virtuelles et de les lancer localement sans avoir à configurer ces machines. Docker est aussi utilisé pour mettre en place la maintenance de serveurs plus simplement.
• Site : https://kitematic.com/

utiliserAPICTS.md

Utiliser une API CTS

Qu'est-ce que le CTS et quelle est son utilité ?

La norme CTS (Canonical Text Services) est une norme développée au Centre for Hellenic Studies d'Harvard dont le but premier est de fournir aux classicistes la capacité de citer, via des APIs et des identifiants propres, un morceau de texte. Cette norme se base sur la conception OHCO (Ordered Hierarchy Content Object) du texte qui traite le texte comme une hierarchie de noeud. En littérature, cela se traduit par exemple par les niveaux recueils > poèmes > vers pour une oeuvre de Beaudelaire tandis qu'il s'agirait d'un ensemble livres > chapitres > paragraphes pour un roman de Balzac. Enfin, cette utilisation ne se limite pas à la littérature car elle peut s'appliquer tout autant aux documents historiques manuscrits (registre > date > ligne) ou inscrits (pierre > face > ligne), à un article scientifique (parties > sous-parties) etc.

L'URN CTS en quelques mots

Une URN (Uniform Resource Name) est un identifiant pour une resource numérique. Les URN CTS sont composées comme suit :

L'API CTS en quelques mots

L'API CTS est focalisée sur le service de deux types de données : les métadonnées à propos des textes et les passages de texte. L'API CTS possède 6 appels différents qui mêlent ou concernent uniquement l'un des deux aspects.

Exemple d'utilisation de l'API

Typiquement, un utilisateur d'une API CTS pourra obtenir un morceau de texte en tapant les requêtes suivantes :

• Aller sur une URL correspondant à une API CTS, telle que http://cts.perseids.org/api/cts (Toutes les URLs qui suivent prendront cette base)
• Regarder le contenu de l'API en terme de textes via la requête GetCapabilities : http://cts.perseids.org/api/cts/?request=GetCapabilities
• Selectionner un noeud edition ou translation dans la liste de textes. Pour l'exemple, nous utiliserons les Epigrammata de Martial.
• Dans ce noeud, nous voyons la chose suivante :

<ti:edition urn="urn:cts:latinLit:phi1294.phi002.perseus-lat2" workUrn="urn:cts:latinLit:phi1294.phi002">
	<ti:description xml:lang="eng">M. Valerii Martialis Epigrammaton libri / recognovit W. Heraeus</ti:description>
	<ti:label xml:lang="eng">Epigrammata</ti:label>
	<ti:online>
		<ti:citationMapping>
			<ti:citation label="book" xpath="/tei:div[@n='?']" scope="/tei:TEI/tei:text/tei:body/tei:div">
				<ti:citation label="poem" xpath="/tei:div[@n='?']" scope="/tei:TEI/tei:text/tei:body/tei:div/tei:div[@n='?']">
					<ti:citation label="line" xpath="/tei:l[@n='?']" scope="/tei:TEI/tei:text/tei:body/tei:div/tei:div[@n='?']/tei:div[@n='?']"/>
				</ti:citation>
			</ti:citation>
		</ti:citationMapping>
	</ti:online>
</ti:edition>

Cela nous donne deux informations primordiales :

• Le texte identifié possède l'identifiant urn:cts:latinLit:phi1294.phi002.perseus-lat2

• On reconnait trois niveaux de citations : book, poem, line. Cela veut dire que le texte peut avoir jusqu'à 3 niveaux de citations hiérarchisées.

• A partir de ces informations, nous pouvons donc demander les références des passages existants dans le texte selectionner : http://cts.perseids.org/api/cts/?request=GetValidReff&urn=urn:cts:latinLit:phi1294.phi002.perseus-lat2

La réponse comprend les informations suivantes :

<reff><urn>urn:cts:latinLit:phi1294.phi002.perseus-lat2:1</urn><urn>urn:cts:latinLit:phi1294.phi002.perseus-lat2:2</urn><urn>urn:cts:latinLit:phi1294.phi002.perseus-lat2:3</urn><urn>urn:cts:latinLit:phi1294.phi002.perseus-lat2:4</urn><urn>urn:cts:latinLit:phi1294.phi002.perseus-lat2:5</urn><urn>urn:cts:latinLit:phi1294.phi002.perseus-lat2:6</urn><urn>urn:cts:latinLit:phi1294.phi002.perseus-lat2:7</urn><urn>urn:cts:latinLit:phi1294.phi002.perseus-lat2:8</urn><urn>urn:cts:latinLit:phi1294.phi002.perseus-lat2:9</urn><urn>urn:cts:latinLit:phi1294.phi002.perseus-lat2:10</urn><urn>urn:cts:latinLit:phi1294.phi002.perseus-lat2:11</urn><urn>urn:cts:latinLit:phi1294.phi002.perseus-lat2:12</urn><urn>urn:cts:latinLit:phi1294.phi002.perseus-lat2:13</urn><urn>urn:cts:latinLit:phi1294.phi002.perseus-lat2:14</urn></reff>

Chaque information possède un passage. urn:cts:latinLit:phi1294.phi002.perseus-lat2:1 signifie Livre 1 des Epigrammata de Martial. On peut continuer et obtenir les passages disponibles dans ce livre en faisant http://cts.perseids.org/api/cts/?request=GetValidReff&urn=urn:cts:latinLit:phi1294.phi002.perseus-lat2:1 . Cette requête nous donnera les poèmes du livre 1. Pour obtenir les lignes, on peut soit partir d'un poème ( http://cts.perseids.org/api/cts/?request=GetValidReff&urn=urn:cts:latinLit:phi1294.phi002.perseus-lat2:1.1) ou ajouter le paramètre level afin d'obtenir toutes les références d'une URN à un certain niveau. Donc :

- http://cts.perseids.org/api/cts/?request=GetValidReff&urn=urn:cts:latinLit:phi1294.phi002.perseus-lat2&level=3 renvoie toutes les références du texte au niveau trois (tous les vers du texte)
- http://cts.perseids.org/api/cts/?request=GetValidReff&urn=urn:cts:latinLit:phi1294.phi002.perseus-lat2:1&level=3 renvoie toutes les références du livre 1 au niveau trois (tous les vers du livre 1)
- http://cts.perseids.org/api/cts/?request=GetValidReff&urn=urn:cts:latinLit:phi1294.phi002.perseus-lat2:1.1&level=3 renvoie toutes les références du livre 1 poème 1 au niveau trois (tous les vers du livre 1 poème 1) et correspond aux mêmes résultats que http://cts.perseids.org/api/cts/?request=GetValidReff&urn=urn:cts:latinLit:phi1294.phi002.perseus-lat2:1.1

• A partir de ces informations, on peut récupérer le texte de ces passages en faisant la requête GetPassage : http://cts.perseids.org/api/cts/?request=GetPassage&urn=urn:cts:latinLit:phi1294.phi002.perseus-lat2:1.1
  • Dans la réponse, on retrouve le texte de la référence
  • Si l'on souhaite, on peut effectuer la requête http://cts.perseids.org/api/cts/?request=GetPassage&urn=urn:cts:latinLit:phi1294.phi002.perseus-lat2:1.1 qui nous donne en plus les metadonnées suivantes :
    • Passages précédents et suivants
    • Metadonnées sur le texte (titre, etc)

Addendum :

• On peut effectuer une requête sur un passage composé de deux références, par exemple du livre 1 poème 1 vers 1 au livre 1 poème 2 ligne 2 : http://cts.perseids.org/api/cts/?request=GetPassage&urn=urn:cts:latinLit:phi1294.phi002.perseus-lat2:1.1.1-1.2.2