**** Ce document a juste pour but d'expliquer a de nouveaux developpeurs quelles fonctionnalites je comptais implementer dans ce logiciel. Il faudra le retravailler avant d'en faire LE man ****


* Intro
Le but de ce programme est de realiser des trombinoscopes, aussi simplement que possible.
Le programme prends en arguments une liste de fichiers (que l'on considere comme des photos) et renvoie le code LaTeX correspondant a un trombinoscope des images donnees en argument. La legende d'une image est le nom du ficher correspondant.
Les photos peuvent etres organisees avec sept niveaux de sections (qui correspondent aux section LaTeX, de chapter a subparagraph).

* Appel
trombi OPTIONS

* Options
Toutes les options sont optionnelles.

--album fichiers, --album[1-7] fichiers, -a fichiers, -a[1-7] fichiers
  Ajoute les photos decrites dans les albums "fichiers" au trombinoscope.
  Si un nombre est precise, il definit le niveau de section de base de l'album (une section de niveau 1 dans un album importe avec -a2 sera une section de niveau 1+2-1=2 (toujours -1).
  Plus de details sur les albums plus bas.

--dim taille, -d taille
  Specifie la taille des photos. "taille" est de la forme "largeurxhauteur" (ex : "2x3"). Les photos sont redimensionnees a "largeur" par "hauteur" centimetres.
  Si la taille ou la hauteur est omise, la proportion des photos est conservee.
  Si la taille est "auto", le logiciel choisit lui meme la taille des photos.
  Voir plus bas pour plus de precisions.

--debug niveau
  Uniquement pour la deboggage du programme.
  Definit le niveau de trace pour afficher ou cacher des informations inutiles sur le deroulement du programme.

--help, -h, -?
  Affiche une courte aide.

--listeDiac, -l
  Affiche la liste de toutes les diacritiques supportees par le programme.
  Voir plus bas pour plus de details.

--nombre chaine, -n chaine
  Nombre de photos par ligne, ou "auto" pour un comportement automatique decrit plus bas.

--out fichier, -o fichier
  Nom du fichier de sortie.
  Si cette option est absente, ou si le nom du fichier est "-", la sortie se fait sur la sortie standard.

--omettre, -O
  Supprime automatiquement les sections vides.

--photos fichiers, -p fichiers
  Ajoute les photos donnees a la liste de fichiers.
  Par defaut, les fichiers correspondant peuvent ne pas exister.

--quiet, -q
  Aucune sortie d'erreur (meme pas les avertissements).

--rep repertoire, --rep[1-7] repertoire, -r repertoire, -r[1-7] repertoire
  Ajoute un repertoire au trombinoscope. Cela signifie :
    creation d'une section portant le nom du repertoire
    ajout de toutes les photos (eps) du repertoire
    puis meme traitement recursif sur tous les sous repertoires

--section titre, --section[1-7] titre, -s titre, -s[1-7] titre
  Ajoute une section, par defaut de niveau 3.

--titre chaine, -t chaine
  Definit le titre du document.
  Si plusieurs titres sont definis, seul le dernier est pris en compte.

--sanstitre, -T
  Specifie que le document n'a pas de titre.
  Prioritaire sur l'option ci-dessus.

--verifier, -v
  Verifie, pour chaque photo ajoutee, que le fichier correspondant existe, et leve une erreur si ce n'est pas le cas.

--verbose, -V
  Donne plein d'informations inutiles et ennuyeuses.

--version
  Affiche la version.

* Gestion des diacritiques
  Chaque legende de photo, chaque section, et le titre ne sont pas integres directement, mais des operations sont appliquees avant:
  - Chaque tiret bas est remplace par une espace
  - Chaque chaine entre tirets est remplacee par la diacritique correspondant au code html.
    Par exemple, le nom de fichier "R-eacute-mi" est traduit en LaTeX en "R\'emi", qui donnera dans le document final : "Rémi".
  - Deux tirets sont remplaces par un tiret.
  - Les autres carcteres speciaux en LaTeX sont echappes : "Pere_&_Fils" devient "Pere \& Fils".
  - Les diacritiques donnees telles quelles sont remplacees de la meme maniere que le code html. Cependant, ce comportement n'est pas garanti : moins je m'interesserai a l'encodage des caracteres, mieux je me porterai.

  C'est bien complique, je suis d'accord. Voici les raisons de ce choix.
  - J'aime bien ne pas avoir les informations correspondant a un fichier dispersees a cinquante endroits. La legende du fichier est ainsi contenue dans le fichier.
    L'utilisateur n'aura donc pas a se poser la question, en deplacant le fichier par exemple, s'il deplace aussi la legende.
  - L'utilisateur peut respecter l'integrite des noms (en conservant les diacritiques) tout en ayant des fichiers dont le nom ne contient que des caracteres alphanumeriques, le tiret et le tiret bas.
  - Les diacritiques LaTeX ne sont pas directement utilisee, car certains caracteres ne sont pas "standards" pour un nom de fichier.
    Par exemple, a-t-on l'envie ou le droit de nommer un fichier "R\'emi" ?
  - Il fallait donc un autre code pour decrire les diacritiques. Le code html existe, autant ne pas reinventer la roue.

* Description d'un fichier album
  Un fichier album contient des informations pour integrer des images et des sections a un trombinoscope.
  Il permet de ne pas avoir a ecrire a chaque fois la ligne de commande complete si l'on fait souvent le meme trombinoscope.
  Les lignes commencant par #, A, R, ou P sont interpretees de la sorte :
    A : la suite de la ligne est une liste d'albums a integrer.
    R : la suite de la ligne est use liste de repertoires a integrer.
    P : la suite de la ligne est use liste de photos a integrer.
    # : la suite de la ligne est le titre d'une section de niveau (relatif) 1
    ## : la suite de la ligne est le titre d'une section de niveau (relatif) 2
    ...
    ####### : la suite de la ligne est le titre d'une section de niveau (relatif) 7
  Si les premiers caracteres de la ligne ne correspondent a aucun de ces signes, la ligne est interpretee comme etant une liste de photos.

  Le niveau d'une section est egal au niveau relatif PLUS le niveau avec lequel a ete appele l'album (ex : --album4 fichier) MOINS un.

* Taille et nombre de photos par ligne
  Par defaut, le programme place les photos les unes a la suite des autres dans le document final, sans modifier leur taille. Ceci n'est neanmoins pas conseille. L'utilisateur peut choisir la taille et le nombre de photos par ligne, ou bien les mettre en automatique.
  Les comportements possibles sont alors :
  taille auto + nombre auto : comportement par defaut decrit juste au dessus.
  taille auto + nombre fixe : la taille est calculee de telle sorte que les photos soient aussi grosses que possible, mais respectent le nombre de photos par ligne donne.
  hauteur fixe + nombre auto : le nombre par ligne est calcule pour mettre autant de photos que possible sur une ligne.
  hauteur fixe + nombre fixe : les deux contraintes sont respectees. Deconseille, car cela peut donner des resultats etranges (comme des lignes trop grandes).

  De plus, si une seule taille est donnee dans toute la commande, elle est appliquee a TOUTES les photos.
  Si plusieurs sont donnees, chacune d'elle ne s'applique qu'aux photos qui suivent, jusqu'a la prochaine definition de taille.
  Par exemple :
    trombi a.eps -d 1x1 b.eps c.eps -d auto d.eps e.eps f.eps g.eps -d 2x2 h.eps
    Dans cet exemple, les photos ont les tailles suivantes :
      a.eps : automatique
      b.eps c.eps : 1cm par 1cm
      d.eps e.eps f.eps g.eps : automatique
      h.eps : 2cm par 2cm

  Cette regle s'applique aussi pour le nombre de photos par ligne.

* Remarques diverses
  ** Tout le programme se fait en une seule passe (ou deux en considerant l'analyse des arguments comme une passe).
    Il serait bon de ne pas en faire plus.

  ** La liste des messages affiches a l'utilisateur (donc pas les traces de deboggage) se trouve dans le paquetage "texte".
    Ceci est fait afin de centraliser tous les messages, pour faciliter la coherence entre eux, et surtout faciliter une eventuelle traduction.

  ** J'ai ecrit une grammaire pour analyser la liste des options, alors qu'apparemment, le paquetage "getopt" le fait tres bien.
    Que faire ? On garde ? On change ?

  ** Le fichier LaTeX produit devrait etre aussi simple que possible, avec dans l'ideal aucun paquetage d'utilise, etc.

* A faire ?
Une liste de choses qui pourraient etre ajoutees, mais auxquelles je n'ai pas vraiment reflechit.

  ** Sera-t-il possible de modifer l'unite donnee pour la taille des photos ?

  ** LaTeX n'accepte par defaut que les photos "eps", et pour le moment, notre programme aussi.
    Faut-il autoriser d'autres formats de photos, quitte a ce que l'utilisateur modifie ensuite le fichier LaTeX pour ajouter par exemple le paquetage permettant de gerer le format en question ?

  ** Les photos sont affichee dans le dossier LaTeX relativement au repertoire courant.
    Faut-il que l'utilisateur puisse choisir le repertoire de reference ?

  ** Ajoute-t-on la gestion de la taille et du nombre de photos par ligne dans l'album ?
    Par exemple, que les lignes suivantes changent respectivement la taille des photos a 4 par 4 centimetres, ou le nombne de photos par ligne a 5 :
      T 4x4
      N 5

  ** Faut-il que l'utilisateur puisse mettre des commentaires dans un album ?
    Par exemple, les lignes commencant par % peuvent etre ignorees.

SEE ALSO:
  http://www.nongnu.org/trombi
