[PATCH seda v2] [doc] Add some documentation

Sylvain Thenault sylvain.thenault at logilab.fr
Tue Apr 11 15:11:18 CEST 2017


# HG changeset patch
# User Sylvain Thénault <sylvain.thenault at logilab.fr>
# Date 1490979229 -7200
#      Fri Mar 31 18:53:49 2017 +0200
# Node ID 64708e1bba834e7642974b2d8f36477bd7206e5e
# Parent  9ca36b8def1f1ac5b26a0eb3c6c39efdd6210e2a
[doc] Add some documentation

diff --git a/doc/profil_simple.rst b/doc/profil_simple.rst
new file mode 100644
--- /dev/null
+++ b/doc/profil_simple.rst
@@ -0,0 +1,8 @@
+Profils simplifiés
+==================
+
+Étant donnés l'étendue et la complexité du SEDA, ainsi que le désir de pouvoir exporté des profils
+vers les anciennes version 1.0 et 0.2, une implémentation simplifiée est mise à disposition.
+
+Seul les profils simplifiés pourront être exportés vers les anciennes versions. Ils seront a priori
+toujours exportable en SEDA 2 également.
\ No newline at end of file
diff --git a/doc/profils.rst b/doc/profils.rst
--- a/doc/profils.rst
+++ b/doc/profils.rst
@@ -1,39 +1,74 @@
-Gestion des identifiants et références
----------------------------------------
+Export des profils SEDA
+=======================
 
-Les identifiants spécifiés dans l'interface utilisateur sur les objets-données
-et les unités d'archives sont reportés via un attribut `seda:profid` sur
-l'élément correspond dans le XSD généré ([1]_). La valeur de cette attribut est
-ensuite utilisée comme valeur par défaut des éléments référençant cet élement.
+Selon leurs caractéristiques, les profils créés dans l'application sont exportable dans une ou
+plusieurs versions du SEDA_ (2, 1 ou 0.2) au format RelaxNG_, celui-ci étant plus adapté à la
+génération de profil que les `schémas XML`_.
 
-Ce mécanisme permet de gérer des identifiants pour des élements XSD qui ne sont
+Les versions supportées sont indiquées dans l'onglet 'diagnostique' du transfer.
+
+Ils est important de noter que quelque soit la version utilisée, le profil seul n'est pas suffisant
+pour valider un bordereau. Il faut également valider ce dernier contre le schéma XSD de la version
+correspondante, car elle permet de valider certains aspects qui ne seront pas validés par le profil.
+
+
+.. _SEDA: https://redirect.francearchives.fr/seda/
+.. _RelaxNG: http://relaxng.org/
+.. _`schémas XML`: https://www.w3.org/XML/Schema
+
+
+Export SEDA 2
+-------------
+
+Gestion des identifiants et références
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Les identifiants spécifiés dans l'interface utilisateur sur les objets-données et les unités
+d'archives sont reportés via un attribut `seda:profid` sur l'élément correspond dans le profil
+RelaxNG_ généré ([1]_). La valeur de cette attribut est ensuite utilisée comme valeur par défaut des
+éléments référençant cet élément.
+
+Ce mécanisme permet de gérer des identifiants pour des éléments XSD qui ne sont
 pas encore créés (puisqu'ils le seront à la création du bordereau), ce qui est
 nécessaire pour pouvoir ensuite les référencer, la norme SEDA 2 faisant
 largement usage de telles références. Il est à noter qu'il est donc à la
 responsabilité de l'outil qui génère le bordereau de gérer les définitions de
-références ainsi créées en substituant dans les éléments référençes la valeur de
-l'identifiant qu'il a attribué à l'élement portant le `seda:profid`
+références ainsi créées en substituant dans les éléments référencés la valeur de
+l'identifiant qu'il a attribué à l'élément portant le `seda:profid`
 correspondant.
 
-Ceci n'étant pas un mécanisme standard du XSD, la cohérence des références entre
+Ceci n'étant pas un mécanisme standard de RelaxNG_, la cohérence des références entre
 le bordereau et le profil ne sera pas vérifiée par les outils de validation XSD
 classiques.
 
 
 .. [1] le préfix `seda` étant associé à l'espace de nom
    "fr:gouv:culture:archivesdefrance:seda:v2.0"
 
+Autres limitations
+~~~~~~~~~~~~~~~~~~
 
-Export RelaxNG des versions 0.2 et 1
-------------------------------------
+Il est à noter que les références sont exporté en utilisant le type `NCName` et non `IDREF` comme
+dans le schéma XSD : c'est lié au fait qu'il n'est pas autorisé en RelaxNG_ d'utiliser le type
+`IDREF` pour le contenu texte d'une balise, mais uniquement pour le contenu d'un attribut : ::
+
+  <reference>id référencé</reference>
+
+vs : ::
+
+  <reference idref="id référencé"/>
+
+
+Export SEDA 0.2 et 1
+--------------------
 
 Les schémas des versions 0.2 et 1 de la norme SEDA utilisent des types personnalisés venant de
 différents espaces de nom (par exemple
 `fr:gouv:culture:archivesdefrance:seda:v1.0:QualifiedDataType:1`,
 `urn:un:unece:uncefact:data:standard:UnqualifiedDataType:10`, etc.). Ces types ne sont
 malheureusement pas utilisables dans un schéma RelaxNG, uniquement XSD. Pour palier à ce problème,
 les éléments utilisant ces types sont exportés en tant que simple chaîne de caractères "xsd:string",
 en supposant que les transferts seront validés contre le profil *et* contre le schéma XSD de la
 norme. La même stratégie était utilisée par Agape V1.
 
-La norme 2 du SEDA n'utilise plus ces types et n'est donc pas exposée à ce problème.
+Le SEDA 2 n'utilise plus ces types et n'est donc pas exposé à ce problème.
diff --git a/doc/seda2_compat.rst b/doc/seda2_compat.rst
new file mode 100644
--- /dev/null
+++ b/doc/seda2_compat.rst
@@ -0,0 +1,50 @@
+Implémentation de la norme SEDA 2
+=================================
+
+Éléments non supportés
+----------------------
+
+Le modèle de données implémenté ne supporte pas l'intégralité du SEDA 2. Certains éléments sont
+simplifiés, d'autres non supportés.
+
+Les élements non supportés sont les suivants :
+
+* groupes d'objets (`DataObjectGroupId`, `DataObjectGroupReferenceId`),
+
+* métadonnées étendues des objets-données (`Metadata`, `OtherMetadata`),
+
+* référence à des profils ou unités d'archives (`ArchivalProfile`,  `ArchiveUnitProfile`),
+
+* `Signature` sous la balise `Content`,
+
+Enfin, il n'y a pas pour le moment de pas de possibilité d'étendre le modèle comme le prévoit le
+SEDA 2 (c.f. les éléments `ArchiveUnitReferenceAbstract`, `ObjectGroupExtenstionAbstract`,
+`OtherManagementAbstract`, `OtherCoreTechnicalMetadataAbstract`, `OtherDimensionsAbstract`,
+`OtherCodeListAbstract` du `schéma XSD`_)
+
+.. _`schéma XSD`: https://redirect.francearchives.fr/seda/seda_v2-0.zip
+
+
+Référence vers des notices d'autorités et vers des vocabulaires
+---------------------------------------------------------------
+
+Dans une approche "référentiel" inspirée du `référentiel SAEM`_, un certain nombre d'éléments sont
+implémentés via des références vers des notices d'autorité EAC ou des concepts de vocabulaires SKOS
+(pour certains extrait du schéma du SEDA 2). De ce fait, tous les éléments de type `CodeListVersion`
+pointent vers des vocabulaires et permettent de contrôler les concepts disponibles pour les éléments
+associés.
+
+Les balises référençant une notice d'autorité sont les suivantes : `Validator`, `Signer`, `Writer`,
+`AuthorizedAgent`, `Addressee`, `Recipient`, `OriginatingAgency`, `SubmissionAgency`,
+`ArchivalAgency`, `TransferringAgency`.
+
+Les balises référençant un ou plusieurs concepts d'un vocabulaires sont les suivants :
+`AcquisitionInformation`, `DescriptionLevel`, `ClassificationLevel`, `FinalAction`, `Encoding`,
+`MimeType`, `EventType`, `LegalStatus`, `KeywordType`, `KeywordReference`, `CompressionAlgorithm`,
+`MeasurementUnits`, `MeasurementWeightUnits`, `unit`, `FinalActionStorageCode`,
+`FinalActionAppraisalCode`, `Level`, `FileFormat`, `VersionId`, `DataObjectVersion`, `FormatId`,
+`Rule`, `RefNonRuleId`, `Type`. Les attributs suivants sont également gérés via référence vers un
+concept : `type` (balise `Relationship`), `algorithm` et `language`.
+
+
+.. _`référentiel SAEM`: http://www.saem.e-bordeaux.org/
\ No newline at end of file


More information about the saem-devel mailing list