[PATCH seda] [doc] Add some documentation

Philippe Pepiot philippe.pepiot at logilab.fr
Tue Apr 11 14:58:29 CEST 2017


On 04/10/2017 05:47 PM, Sylvain Thenault wrote:
> # 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 5c8d72283fc67366d645f4610dd3e4bec76648ca
> # Parent  3616158ae8e433063556217b62708c5eedb44566
> [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`_.
> +
> +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
> +correspondate, car elle permet de valider certains aspects qui ne seront pas validés par le profil.
    ^
    correspondante

> +
> +
> +.. _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 élement.
                             ^
                             élément

>
>  Ce mécanisme permet de gérer des identifiants pour des élements XSD qui ne sont
                                                           ^
                                                           éléments

>  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
> +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'élement portant le `seda:profid`
                                       ^
                                       élément

>  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