Introduction

Un carnet est un ensemble de chansons qui peut peut être accompagné de divers éléments : index des chansons ou auteurs, page de titre, liste d’accords, préface, etc.

Un carnet est décrit par un fichier .yaml (détaillé ci-après). Il est généré par songbook en assemblant des fichiers de chansons .csg (ou .tsg), des templates .tex, des fichiers LaTeX .tex, des images, etc. Tout ce contenu provient de dossiers de donnée appelés datadir.

Un carnet fini, au format PDF, est l’intégration d’un contenu dans une mise en page particulière. Les options qui gouvernent cette mise en page sont principalement décrites dans les templates. Les différentes manières d’ajouter du contenu à un carnet sont décrites dans la section Gestion du contenu.

Exemple de fichier .yaml

Un exemple de fichier .yaml est fourni avec le code source :

content:
  - section: "Chants Traditionnels"
  - "chevaliers_de_la_table_ronde.csg"
  - "greensleeves.csg"
  - "vent_frais.csg"
  - section: "Exemples"
  - "exemple*.csg"

book:
  lang: en
  encoding: utf-8
  pictures: yes
  template: default.tex
  onesongperpage: no

chords: # Options relatives aux accords
  show: yes
  diagramreminder: important
  diagrampage: yes
  repeatchords: yes
  lilypond: no
  tablatures: no
  instrument: guitar
  notation: alphascale

authors: # Comment sont analysés les auteurs
  separators:
  - and
  ignore:
  - unknown
  after:
  - by

titles: # Comment sont analysés les titres
  prefix:
  - The
  - Le
  - La
  - "L'"
  - A
  - Au
  - Ces
  - De
  - Des
  - El
  - Les
  - Ma
  - Mon
  - Un

Syntaxe des fichiers .yaml

Un fichier .yaml est écrit au format YAML. Le format YAML est un type de fichier texte dans lequel on représente des information de trois manières différentes :

• les listes d’éléments ordonnés : chaque élément commence sur une nouvelle ligne, précédé d’un tiret -. Tous les élements d’une même liste doivent avoir la même indentation (décalage depuis le bord gauche).
• les tableaux associatifs composés de multiples clef: valeur, les clefs étant la plupart du temps des chaînes, et les valeurs pouvant être n’importe quel type (une liste, un autre tableau associatif, une donnée scalaire).
• les données scalaires : chaînes de charactère (délimitées par des guillemets anglais "..."), nombre, booléen (yes/no).

Le fichier .yaml contient un tableau associatif, dont les clefs sont les noms d’options, et les valeurs associées sont les valeurs de ces options. Le type des valeurs dépend de l’option considérée. Les sections sur le contenu des carnets et sur la mise en page contiennent les détails concernant les différentes options.

Compiler un fichier .yaml

Le fichier carnet.yaml peut être compilé (ie transformé en fichier PDF) en ligne de commande, avec la commande suivante :

songbook chemin/vers/carnet.yaml

L’intégralité des options de la commande songbook sont disponible dans la section dédiée.

Ecrire ses propres fichiers .yaml

Le contenu d’un carnet est géré par le mot-clef content d’un fichier .yaml. Les différents types de contenus disponibles sont décrits dans la section Gestion du contenu.

Tous les autres mots-clefs des fichiers .yaml servent à faire la mise en page des carnets. Les options sont présentées dans la section Mise en page du carnet.