CalcDB/README.md

# Base de données des calculatrices CASIO

Ce dépôt contient des images, métadonnées et propriétés sur les calculatrices
graphiques et formelles CASIO modernes (la plupart des modèles après 2000). Ces
informations sont utilisées par l'index des calculatrices sur Planète Casio.

## Format

Chaque calculatrice est décrite par un fichier YAML dans le dossier
`calculators`. Les propriétés sont classées en catégories avec différents
champs dans chaque catégorie. Les champs peuvent être de types différents et
les valeurs autorisées sont au cas-par-cas, mais souvent on rencontre:

* Du texte brut : `full_name: "Graph 90+E"`
* Des booléens : `touch_screen: no`
* Des entiers: `default_cpu_frequency: 56000000 # Hz`
* Des énumérations : `audience: audience.high_school`

Les énumérations commençent toujours par le nom du champ. Beaucoup de champs
qui acceptent des énumérations acceptent aussi des booléens. Certains champs
acceptent des listes.

Le fichier `model.yaml` décrit le modèle des données : il liste toutes les
catégories, tous les champs, et toutes les calculatrices ; il donnes les unités
pour les champs numériques concernés ; et il attribute des scores aux valeurs
des champs pour permettre de faire des comparatifs.

Les valeurs peuvent contenir du Markdown ainsi que que des marqueurs de la
forme `@lang{...}` pour insérer du texte qui n'est visible que quand les
données sont affichées dans une certaine langue. Les fichiers `lang/*.yaml`
traduisent les noms des catégories, des champs, et les valeurs énumérées, et
`@lang{...}` n'est utilisé que pour les quelques passages de texte qui n'y
sont pas listés.

## Outils et utilisation

On peut soit utiliser la base directement en YAML, soit utiliser le module
Python `calcdb` dans le dossier `tools`. On peut aussi utiliser la version JSON
générée avec `tools/convert-json.py` si c'est plus pratique.

Trois outils sont fournis dans `tools` :

* La bibliothèque `calcdb.py` fournit de quoi manipuler la base en Python. La
  classe principale est `CalcDB`, qui charge les fichiers YAML depuis la racine
  de ce dépôt. Une class `Lang` représente les différents langages, et présente
  quelques méthodes pour simplifier la traduction. Enfin, une fonction
  `render()` implémente toutes les règles d'affichage pour fournir le texte à
  afficher pour chaque valeur dans un tableau.

* Le script `convert-json.py` permet de convertir la base en JSON. Utilisez
  `make json` ou `make json-min` et récupérez le fichier de sortie dans `out`.

* Le script `render-html.py` génère un tableau HTML avec les informations. Ce
  tableau contient des attributs CSS et HTML permettant de le manipuler en
  Javascript, et est notamment utilisé sur l'index des calculatrices de Planète
  Casio. Utilisez `make html-fr` ou `make html-en` pour générer une page web
  autonome pour consulter le tableau, ou `make index-fr` ou `make index-en`
  pour générer la version utilisée sur Planète Casio.

## Résumé des dossiers

* `calculators`: Fichiers YAML avec les propriétés de tous les modèles.
* `lang`: Traduction des noms de catégories, champs, et valeurs énumérées.
* `model.yaml`: Liste de catégories, champs, calculatrices, et scores pour
   toutes les valeurs énumérées comparables.
* `images`: Petites et grandes photos de tous les modèles, en JPG. Les grandes
   photos sont généralements limitées à 1000 pixels de haut ; les petites sont
   toutes fixées à 150 pixels de haut. Le dossier `small` a une image
   supplémentaire `g35+.jpg` avec les deux générations de Graph 35+
   côte-à-côte.
* `tools`: Scripts Python pour manipuler la base de données, et un module
   Python `calcdb` réutilisable pour extraire efficacement des informations.

Ces dossiers ne sont pas indexés par le dépôt :
* `out`: Dossier de sortie pour tous les fichiers générés par les scripts.

## TODO

* Ajouter des liens vers les émulateurs.
* Télécharger les manuels et les héberger sur Planète Casio.
* Télécharger tous les OS updaters, les héberger sur Planète Casio, et les
  ajouter à la base de données.
* Compléter les icônes pixel art.