isn.xml

<?xml version="1.0" encoding="ISO-8859-15"?>
<!-- Dernière modification
     le       $Date$
     par      $Author$
     révision $Revision$ -->

<sect1 id="isn">
 <title>isn</title>

 <indexterm zone="isn">
  <primary>isn</primary>
 </indexterm>

 <para>
  Le module <filename>isn</filename> fournit des types de données pour les
  standards internationaux de numérotation suivants&nbsp;: EAN13, UPC, ISBN
  (livres), ISMN (musique) et ISSN (numéro de série). Les nombres sont
  validés en saisie, et correctement affichés (avec les tirets) en sortie.
 </para>

 <sect2>
  <title>Types de données</title>

  <table>
   <title>Types de données <filename>isn</filename></title>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>Type de données</entry>
      <entry>Description</entry>
     </row>
    </thead>

    <tbody>
     <row>
      <entry><type>EAN13</type></entry>
      <entry>
       Numéro d'article européen (<foreignphrase>European Article
       Numbers</foreignphrase>), toujours affiché dans le format de l'EAN13
      </entry>
     </row>

     <row>
      <entry><type>ISBN13</type></entry>
      <entry>
       Numéro standard international pour les livres
       (<foreignphrase>International Standard Book Numbers</foreignphrase>)
       à afficher dans le nouveau format EAN13
      </entry>
     </row>

     <row>
      <entry><type>ISMN13</type></entry>
      <entry>
       Numéro standard international pour la musique
       (<foreignphrase>International Standard Music Numbers</foreignphrase>)
       à afficher dans le nouveau format EAN13
      </entry>
     </row>
     <row>
      <entry><type>ISSN13</type></entry>
      <entry>
       Numéro de série au standard international
       (<foreignphrase>International Standard Serial Numbers</foreignphrase>)
       à afficher dans le nouveau format EAN13
      </entry>
     </row>
     <row>
      <entry><type>ISBN</type></entry>
      <entry>
       Numéro standard international pour les livres
       (<foreignphrase>International Standard Book Numbers</foreignphrase>)
       à afficher dans l'ancien format court
      </entry>
     </row>
     <row>
      <entry><type>ISMN</type></entry>
      <entry>
       Numéro standard international pour la musique
       (<foreignphrase>International Standard Music Numbers</foreignphrase>)
       à afficher dans l'ancien format court
      </entry>
     </row>
     <row>
      <entry><type>ISSN</type></entry>
      <entry>
       Numéro de série au standard international
       (<foreignphrase>International Standard Serial Numbers</foreignphrase>)
       à afficher dans l'ancien format court
      </entry>
     </row>
     <row>
      <entry><type>UPC</type></entry>
      <entry>
       Code produit universel (<foreignphrase>Universal Product
       Codes</foreignphrase>)
      </entry>
     </row>
    </tbody>
   </tgroup>
  </table>

  <para>
   Quelques notes&nbsp;:
  </para>

  <orderedlist>
   <listitem>
    <para>Les nombres ISBN13, ISMN13, ISSN13 sont tous des nombres EAN13.</para>
   </listitem>
   <listitem>
    <para>Les nombres EAN13 ne sont pas toujours des ISBN13, ISMN13 ou ISSN13
    (mais certains le sont).</para>
   </listitem>
   <listitem>
    <para>Certains nombres ISBN13 peuvent être affichés comme des ISBN.</para>
   </listitem>
   <listitem>
    <para>Certains nombres ISMN13 peuvent être affichés comme des ISMN.</para>
   </listitem>
   <listitem>
    <para>Certains nombres ISSN13 peuvent être affichés comme des ISSN.</para>
   </listitem>
   <listitem>
    <para>Les nombres UPC sont un sous-ensemble des nombres EAN13 (ce sont
    basiquement des EAN13 sans le premier <literal>0</literal>).</para>
   </listitem>
   <listitem>
    <para>Tous les nombres UPC, ISBN, ISMN et ISSN numbers peuvent être
    représentés sous la forme EAN13.</para>
   </listitem>
  </orderedlist>

  <para>
   En interne, tous ces types utilisent la même représentation (un
   entier sur 64 bits), et tous sont interchangeables. Plusieurs types sont
   fournis pour contrôler le formatage de l'affichage et pour permettre une
   vérification très fine de la validité des entrées qui est supposée dénoter
   un type particulier de nombre.
  </para>

  <para>
   Les types <type>ISBN</type>, <type>ISMN</type> et <type>ISSN</type>
   afficheront la version courte du nombre (ISxN 10) quand c'est possible, et
   afficheront la version au format ISxN 13 pour les nombres qui ne tiennent
   pas dans la version courte.
   Les types <type>EAN13</type>, <type>ISBN13</type>, <type>ISMN13</type> et
   <type>ISSN13</type> afficheront toujours la version longue de l'ISxN
   (EAN13).
  </para>
 </sect2>

 <sect2>
  <title>Conversions</title>

  <para>
   Le module <filename>isn</filename> fournit les paires suivantes pour les
   conversions de types&nbsp;:
  </para>

  <itemizedlist>
   <listitem>
    <para>
     ISBN13 &lt;=&gt; EAN13
    </para>
   </listitem>
   <listitem>
    <para>
     ISMN13 &lt;=&gt; EAN13
    </para>
   </listitem>
   <listitem>
    <para>
     ISSN13 &lt;=&gt; EAN13
    </para>
   </listitem>
   <listitem>
    <para>
     ISBN &lt;=&gt; EAN13
    </para>
   </listitem>
   <listitem>
    <para>
     ISMN &lt;=&gt; EAN13
    </para>
   </listitem>
   <listitem>
    <para>
     ISSN &lt;=&gt; EAN13
    </para>
   </listitem>
   <listitem>
    <para>
     UPC  &lt;=&gt; EAN13
    </para>
   </listitem>
   <listitem>
    <para>
     ISBN &lt;=&gt; ISBN13
    </para>
   </listitem>
   <listitem>
    <para>
     ISMN &lt;=&gt; ISMN13
    </para>
   </listitem>
   <listitem>
    <para>
     ISSN &lt;=&gt; ISSN13
    </para>
   </listitem>
  </itemizedlist>

  <para>
   Lors d'une conversion d'<type>EAN13</type> vers un autre type, il y a une
   vérification à l'exécution que la valeur est dans le domaine de l'autre
   type et une erreur est renvoyée dans le cas contraire. Les autres
   conversions sont simplement un renommage qui succèdera à chaque fois.
  </para>
 </sect2>

 <sect2>
  <title>Fonctions et opérateurs</title>

  <para>
   Le module <filename>isn</filename> fournit des opérateurs de comparaison
   standard, plus un support des index B-Tree et hachés pour tous les types
   de données. De plus, il existe plusieurs fonctions spécialisées, listées
   dans <xref linkend="isn-functions"/>. Dans cette table, <type>isn</type>
   signifie un des types de données de ce module&nbsp;:
  </para>

  <table id="isn-functions">
   <title>Fonctions de <filename>isn</filename></title>
   <tgroup cols="3">
    <thead>
     <row>
      <entry>Fonction</entry>
      <entry>Retour</entry>
      <entry>Description</entry>
     </row>
    </thead>

    <tbody>
     <row>
      <entry><function>isn_weak(boolean)</function></entry>
      <entry><type>boolean</type></entry>
      <entry>Configure le mode de saisie faible (renvoie le nouveau
      paramétrage)</entry>
     </row>
     <row>
      <entry><function>isn_weak()</function></entry>
      <entry><type>boolean</type></entry>
      <entry>Récupère le statut actuel du mode faible</entry>
     </row>
     <row>
      <entry><function>make_valid(isn)</function></entry>
      <entry><type>isn</type></entry>
      <entry>Valide un nombre invalide (efface le drapeau d'invalidité)</entry>
     </row>
     <row>
      <entry><function>is_valid(isn)</function></entry>
      <entry><type>boolean</type></entry>
      <entry>Vérifie la présence du drapeau d'invalidité</entry>
     </row>
    </tbody>
   </tgroup>
  </table>

  <para>
   Le mode <firstterm>faible</firstterm> est utilisé pour insérer des données
   invalides dans une table. Invalide signifie que le chiffre de vérification
   est mauvais, pas qu'il manque des numéros.
  </para>

  <para>
   Pourquoi voudriez-vous utiliser le mode faible&nbsp;? Tout simplement
   parce que vous pouvez avoir une grosse collection de nombres ISBN, et
   que beaucoup d'entre eux, quelque soit la raison, ont un mauvais chiffre
   de vérification (peut-être que les nombres ont été scannés à partir d'une
   liste imprimée et que l'OCR s'est trompé sur les numéros, peut-être que les
   numéros ont été saisis manuellement... qui sait). Bref, le fait est que vous
   pouvez vouloir corriger ça, mais que vous voulez être capable d'avoir tous
   les nombres dans votre base de données pour que vous puissiez vérifier
   l'information et peut-être utiliser un outil externe pour localiser les
   nombres invalides dans la base de données, puis les vérifier et valider
   plus facilement&nbsp;; donc par exemple, vous voudrez sélectionner tous
   les nombres invalides dans la table.
  </para>

  <para>
   Quand vous insérez des nombres invalides dans une table en utilisant le
   mode faible, le nombre sera inséré avec le chiffre de vérification
   corrigé, mais il sera affiché avec un point d'exclamation
   (<literal>!</literal>) à la fin, par exemple
   <literal>0-11-000322-5!</literal>. Ce marqueur d'invalidité peut être
   vérifié avec la fonction <function>is_valid</function> et effacé avec la
   fonction <function>make_valid</function>.
  </para>

  <para>
   Vous pouvez aussi forcer l'insertion de nombres invalides, même quand vous
   n'êtes pas dans le mode faible, en ajoutant le caractère
   <literal>!</literal> à la fin du nombre.
  </para>

  <para>
   Une autre fonctionnalité spéciale est que, durant la saisie, vous pouvez
   écrire <literal>?</literal> à la place du chiffre de vérification. Ce
   dernier sera calculé et inséré automatiquement.
  </para>
 </sect2>

 <sect2>
  <title>Exemples</title>

  <programlisting>
--Using the types directly:
SELECT isbn('978-0-393-04002-9');
SELECT isbn13('0901690546');
SELECT issn('1436-4522');

--Casting types:
-- note that you can only cast from ean13 to another type when the
-- number would be valid in the realm of the target type;
-- thus, the following will NOT work: select isbn(ean13('0220356483481'));
-- but these will:
SELECT upc(ean13('0220356483481'));
SELECT ean13(upc('220356483481'));

--Create a table with a single column to hold ISBN numbers:
CREATE TABLE test (id isbn);
INSERT INTO test VALUES('9780393040029');

--Automatically calculate check digits (observe the '?'):
INSERT INTO test VALUES('220500896?');
INSERT INTO test VALUES('978055215372?');

SELECT issn('3251231?');
SELECT ismn('979047213542?');

--Using the weak mode:
SELECT isn_weak(true);
INSERT INTO test VALUES('978-0-11-000533-4');
INSERT INTO test VALUES('9780141219307');
INSERT INTO test VALUES('2-205-00876-X');
SELECT isn_weak(false);

SELECT id FROM test WHERE NOT is_valid(id);
UPDATE test SET id = make_valid(id) WHERE id = '2-205-00876-X!';

SELECT * FROM test;

SELECT isbn13(id) FROM test;
  </programlisting>
 </sect2>

 <sect2>
  <title>Bibliographie</title>

  <para>
   Les informations qui ont permis l'implémentation de ce module ont été
   récupérées sur plusieurs sites, dont&nbsp;:
  </para>
  <programlisting>
   http://www.isbn-international.org/
   http://www.issn.org/
   http://www.ismn-international.org/
   http://www.wikipedia.org/
  </programlisting>

  <para>
   Les préfixes utilisées pour le formatage ont été récupérés à partir
   de&nbsp;:
  </para>
  <programlisting>
   http://www.gs1.org/productssolutions/idkeys/support/prefix_list.html
   http://www.isbn-international.org/en/identifiers.html
   http://www.ismn-international.org/ranges.html
  </programlisting>

  <para>
   Nous avons porté une grande attention lors de la création des
   algorithmes et ils ont été vérifiés méticuleusement par rapport aux
   algorithmes suggérés dans les manuels utilisateurs officiels ISBN, ISMN et
   ISSN.
  </para>
 </sect2>

 <sect2>
  <title>Auteur</title>
  <para>
   Germen Mendez Bravo (Kronuz), 2004 - 2006
  </para>

  <para>
   Ce module est inspiré du code isbn_issn de Garrett A. Wollman.
  </para>
 </sect2>

</sect1>