LaTeX

Avertissement

Afin de détecter les méta-informations de la chanson (titre, auteur, etc.), une analyse syntaxique du préambule du fichier (les arguments de \beginsong) est effectuée. Mais puisque LaTeX est Turing-complet, une vraie analyse syntaxique est très complexe, et dépasse de loin le cadre de ce projet. Patacrep n’est donc capable de lire correctement qu’un sous-ensemble du LaTeX. Il n’y a pas de spécification de ce qui est analysé et ce qui ne l’est pas, mais pour faire simple, si tous les arguments sont entourés d’accolades (by={Boris Vian}}) et ne contient aucune commande LaTeX (mis à part les accents), cela devrait fonctionner.

Une chanson est un fichier texte chanson.sg placé dans le répertoire songs (ou un de ses sous-répertoires) d’un datadir. C’est un fichier LaTeX interprété avec le paquet songs. Si la connaissance de LaTeX peut-être nécessaire pour faire des choses compliquées, cette documentation devrait permettre d’écrire des chansons sans connaissance préalable de LaTeX. Pour un langage encore plus simple (moins puisant que LaTeX, mais qui devrait suffire dans la plupart des cas), il est aussi possible d’utiliser Chordpro.

Ce fichier commence par la ligne \beginsong{titres} (éventuellement précédée des commandes définissant la langue de la chanson et le nombre de colonnes), termine par la ligne \endsong, et contient entre ces deux lignes les commandes nécessaires pour renseigner les titres, écrire les couplets et refrains, placer des accords, ou insérer d’autres éléments.

Exemple

Voici un exemple simplifié de la chanson Sad robot par Pornophonique.

\selectlanguage{english}
\songcolumns{2}
\beginsong{Sad robot}
  [by=Pornophonique,cov=8-bit-lagerfeuer,album=8-bit lagerfeuer]

  \cover
  \gtab{Dm}{XX0231}
  \gtab{F}{1:022100}
  \gtab{C}{X32010}
  \utab{Dm}{2210}
  \utab{F}{2010}
  \utab{C}{0003}

  \lilypond{Sad_robot}

  \beginverse
    His \[Dm]steely skin is covered
    By \[F]centuries of dust
    \[C]Once he was a great one
    \[Dm]Now he's dull and rust
  \endverse

  \begin{repeatedchords}
    \beginverse*
      An \[Dm]oily tear he's crying
      \[F]Can you feel the pain
      Of the \[C]sad, sad robot
      And it's \[Dm]driving him insane
    \endverse*

    \beginverse*
      He can't \[Dm]turn back time nor history
      So his \[F]life became a misery
      He \[C]has to face the destiny
      Nobody \[Dm]cares anymore
    \endverse*

    \beginchorus
      \[Dm]Sad, sad robot
      \[F]Sad, sad robot
      \[C]Sad, sad robot
      All a\[Dm]lone
    \endchorus
  \end{repeatedchords}
\endsong

Langue

Définir la langue de la chanson permet de respecter la typographie. Par exemple, en français, un point d’exclamation est précédé d’une espace, alors qu’en anglais, il est collé au mot qui le précède.

La définition de la langue se fait avant la commande \beginsong{Titre}, en utilisant :

\selectlanguage{english}
\beginsong{Titre}

Les langues disponibles sont celles reconnues par le paquet LaTeX Babel.

Titres et méta-informations

Les titres (le titre principal, et des titres alternatifs éventuels), ainsi que le nom de l’auteur, l’album, etc., sont définis avec la commande beginsong{titres}[informations]. Par exemple :

\beginsong{Sad Robot}
  [by={Pornophonique}, cov={8-bit-lagerfeuer}, album={8-bit lagerfeuer}]

Les différents titres sont séparés par des doubles barre obliques : beginsong{titre1 \\ titre2 \\ titre3}.

La liste des paramètres disponibles (certains paramètres de songs, et d’autres ajoutés par patacrep), est donnée ici. Pour une utilisation avancée, il est possible de définir de nouveaux paramètres.

  • Paquet songs

    Nom Description
    by auteurs
    cr informations de copyright
    li licence
    sr référence à la bible (le paquet songs a été écrit à l’origine pour des chants religieux)
    index une entrée supplémentaire dans l’index pour un vers
    ititle une entrée supplémentaire dans l’index pour un titre
  • Paquet patacrep

    Nom Description
    album Album
    original Titre original
    cov Chemin de l’image de couverture (relative ou non au répertoire du fichier .sg)
    url URL de la chanson

Index

Les titres et auteurs des chansons reçoivent un traitement particulier avant d’être intégrés dans l’index.

Titres

Les articles courants (Les, Le, The, A, etc.) en début de titre peuvent être supprimés. Cela permet de trier les titres selon le premier mot « important ».

L’option titleprefixwords permet de définir la liste des articles à ne pas considérer en début des titres.

Par défaut, les titres sont affichés dans la table des matières en rejetant l’article entre parenthèses (par exemple Raven (The)). Il est possible de modifier cela en redéfinissant la commande LaTeX \indextitle{article}{titre}. Par exemple, pour afficher le titre sans modifications (The Raven), on pourra mettre dans le préambule du fichier LaTeX (ou plutôt dans un template) :

\renewcommand{\indextitle}[2]{#1 #2}

Noter que cette commande prend toujours deux arguments, le premier pouvant être vide (par exemple \indextitle{}{Enivrez-vous}). Il faut donc être vigilant à ce que le résultat de la commande prenne en compte ce cas-là.

Auteurs

Le traitement des auteurs est fait de telle manière à ce que, par exemple, une chanson ayant pour auteur Composée par Jean Boyer (1945), chantée par Georges Brassens apparaisse dans l’index des auteurs à Boyer et Brassens.

Les options authwords permettent de paramétrer ce traitement. Cette option est un dictionnaire ayant trois clefs sep, ignore et after. Le traitement est le suivant (en prenant pour exemple Paroles de William Blake (Milton, 1808), musique de Hubert Parry (1916), chanté par Emerson,~Lake~and~Palmer, avec authwords valant « sep »: [« and », « et »], « ignore »: [« anonyme »], « after »: [« de », « par »]).

  1. Les parenthèses (et leur contenu) sont supprimées.

    Paroles de William Blake, musique de Hubert Parry, chanté par Emerson,~Lake~and~Palmer
    
  2. La chaîne est découpée suivant les séparateurs de authwords['sep'] (c’est-à-dire and et et dans le cas présent), ainsi que la virgule.

    Paroles de William Blake
    musique de Hubert Parry
    chanté par Emerson,~Lake~and~Palmer
    

    On remarque que Emerson,~Lake~and~Palmer n’a pas été découpé selon le and, car ce séparateur n’est pas entouré d’espaces mais d’espaces insécables ~.

  3. Tout ce qui précède des éléments de authwords['after'] (par et de dans notre exemple) est supprimé.

    William Blake
    Hubert Parry
    Emerson,~Lake~and~Palmer
    
  4. Les auteurs correspondant à des auteurs de la liste authwords['ignore'] sont supprimés (aucun dans notre exemple).

    William Blake
    Hubert Parry
    Emerson,~Lake~and~Palmer
    
  5. Les auteurs sont découpés entre le prénom (ou l’article pour les groupes) et le nom de famille. Le découpage est fait à la dernière espace.

    William / Blake
    Hubert / Parry
    / Emerson,~Lake~and~Palmer
    
  6. Les auteurs sont passés à la commande \indexauthor{prénom}{nom}, qui va se charger d’afficher correctement les noms (voir paragraphe suivant).

Par défaut, les auteurs sont affichés dans l’index avec le prénom rejeté après le nom, avec une virgule (par exemple Poe, Edgar Allan). Il est possible de modifier cela en redéfinissant la commande LaTeX \indexauthor{prénom}{nom}. Par exemple, pour afficher le prénom entre parenthèse en début de nom ((Edgar Allan) Poe), on pourra mettre dans le préambule du fichier :

\renewcommand{\indexauthor}[2]{(#1) #2}

Cette commande prend toujours deux arguments, le premier pouvant être vide (par example \indexauthor{}{Simon and Garfunkel}). Il faut être donc vigilant à ce que sa définition prenne en compte ce cas spécial.

Couplets, refrains

La chanson se compose d’une succession de couplets (verse) et de refrains (chorus). Un couplet figure dans un environnement verse, c’est-à-dire qu’il commence par \beginverse et se termine par \endverse. De la même manière, un refrain est placé dans un environnement chorus, c’est-à-dire entre les balises \beginchorus et \endchorus. Les paroles sont écrites normalement entre les balises d’ouverture et de fermeture de l’environnement.

Note

Contrairement à ce qui est habituel en LaTeX, les retours à la ligne sont respectés. Il n’est donc pas nécessaire de sauter une ligne ou d’utiliser une commande \\ ou \par à chaque fin de vers.

Numérotation

La numérotation se fait automatiquement pour chaque \beginverse rencontré. Cependant, il est parfois plus lisible de scinder un couplet en deux parties, la deuxième partie ne devant pas être numérotée. Pour cela, nous utilisons la commande \beginverse* ; il faut alors fermer l’environnement par \endverse*. Par exemple, un couplet en huit vers se décompose souvent en deux strophes de quatre vers comme dans l’exemple suivant.

\beginverse
  His \[Dm]steely skin is covered
  By \[F]centuries of dust
  \[C]Once he was a great one
  \[Dm]Now he's dull and rust
\endverse

\beginverse*
  An oily tear he's crying
  Can you feel the pain
  Of the sad, sad robot
  And it's driving him insane
\endverse*

Accords

Pour préciser sur quelle syllabe un accord doit être joué, on utilise une commande spéciale. Par exemple, la commande \[E] produira un Mi au dessus de la syllabe suivante dans le PDF.

Il est impératif d’utiliser la convention anglo-saxone de notation des accords (A, B, C, D, E, F, G) et non pas la notation latine (La, Si, Do, Ré, Mi, Fa, Sol). En revanche, suivant la langue utilisée pour le recueil, le rendu des accords dans le PDF pourra être différent (l’accord \[D] sera affiché si la langue du songbook est french). Ce rendu est paramétrable avec l’option notenamesout.

Par défaut, l’accord est majeur (C fait référence à l’accord de Do majeur). Les accords mineurs sont précisés par un m minuscule. Le symbole bémol ♭ est représenté en utilisant le caractère &. Le dièse ♯ est codé par le caractère #. Les autres notations sont simplement ajoutées comme des caractères à l’accord principal. Par exemple, l’accord de La bémol mineur est noté [A&m].

Note

Pour des raisons techniques, le symbole # (tout comme &) ne peut pas être utilisé dans les environnements nolyrics. Dans ce cas là, il faut utiliser shrp (respectivement flt).

Répétition

De façon à avoir un document lisible et relativement compact, les accords des couplets et des refrains ne sont renseignés qu’une seule fois à leur première occurrence. En effet, même si jouer les morceaux du premier couplet en chantant les paroles du second peut demander un peu de gymnastique, cela fera travailler votre mémoire tout en offrant un texte bien moins surchargé et (beaucoup) moins de pages à imprimer.

Si toutefois vous souhaitez que les accords soient répétés dans toute la chanson, vous pouvez utiliser l’option repeatchords du template de votre recueil (voir la section Création d’un carnet). Il faut évidemment pour cela que les accords soient renseignés dans tous les couplets des chansons.

Chœurs et répétitions

Lorsqu’une phrase ou un couplet est répété plusieurs fois d’affilée, il est conseillé d’utiliser la commande \rep plutôt que d’écrire \bis ou d’indiquer directement (x4). Par exemple, si le mot Hallelujah est répété quatre fois, nous écrirons~:

Hallelujah \rep{4}

La commande echo fait référence à des chœurs (ou similaire).

Hallelujah \echo{Hallelujah}

Caractères spéciaux

Quelques caractères doivent être écrits différemment en utilisant des commandes LaTeX pour un obtenir un meilleur rendu typographique dans le PDF. Les deux exemples principaux sont les trois points de suspension (…) et le caractère œ. Pour représenter ces caractères, vous devez utiliser respectivement les commandes \dots{} et \oe{} (ou utiliser les caractère UTF-8 et œ). On utilise des accolades autour des commandes de sorte que les commandes puissent être insérées où vous le désirez sans interférer avec le reste du texte.

Inclure d’autres éléments

Partitions

Si vous souhaitez ajouter une ligne mélodique dans une chanson, vous pouvez utiliser Lilypond pour générer la partition. Créez pour cela un nouveau fichier partition.ly dans le même répertoire que la chanson. Il faut inclure le fichier d’en-tête header et définir l’option paper-height de façon à ce que la partition produite tienne sur une page avec le moins de blanc possible. Une première estimation est de compter 1.6 cm pour une ligne. Puis, écrivez votre partition entre accolades, comme dans l’exemple suivant.

\begin{lilypond}
\include "header"
\paper{paper-height = 3.3\cm}
{
  \key c \major
  \time 2/4
  \relative c''
    {
      e4 c g'2 a4 a8. a16 g8 e4 c8
      a'4 a8. a16 g8 f e c d2~ d4
      e8 f g4 g8. g16 f8 e d c a c4 a8 g4
      c8 d e8 g4 g,8 e' e d d c2
    }
}
\end{lilypond}

Enfin, pour insérer votre partition partition.ly dans une chanson, utilisez la commande lilypond dans le fichier sg adéquat :

\lilypond{partition}

Diagrammes des accords

Étant donné qu’un accord de guitare ou de ukulélé peut se jouer de plusieurs façons différentes et qu’il est parfois judicieux de privilégier telle ou telle position, patacrep permet de représenter schématiquement ces accords en début de chanson sous forme de diagramme. Pour cela, nous utilisons les commandes \gtab (guitare) et \utab (ukulélé) juste avant le premier couplet ou refrain. Dans le cas où ces accords ne sont pas standards, ils peuvent être marqués comme importants avec les commandes \gtab* et \utab*. Voici quelques exemples classiques~:

\gtab{C}{3:002220}
\gtab*{Amaj7}{5:X0221X}
\utab{C}{0003}
\utab{B&m}{1:2000}
  • Les six chiffres correspondent aux six cordes de la guitare (Mi, La, , Sol, Si, Mi).
  • La valeur du chiffre indique la frette sur laquelle on appuie.
  • Un 0 désigne une corde jouée à vide.
  • Un X indique que la corde ne doit pas être jouée.
  • Une valeur avant un « : » désigne un barré (« 3: » indique un barré à la 3 e frette).

Note

  • X est la lettre majuscule x. Un x minuscule produira une erreur lors de la compilation.
  • 0 est le chiffre zéro et non pas la lettre majuscule o.

Intersongs

Le paquet songs permet d’insérer du texte quelconque entre deux chansons (une autre méthode consiste à utiliser le plugin tex).

Un intersong est un fichier ayant pour extension .is, et contenant un environnement intersong, c’est-à-dire commençant par la ligne \begin{intersong} et finissant par \end{intersong}.

Tout a été fait pour qu’ils puissent être manipulés comme des chansons, c’est-à-dire :

  • il est possible de spécifier la langue et le nombre de colonnes comme pour les chansons (en plaçant les commandes correspondantes en tout début de fichier, avant même \begin{intersong}) ;
  • il est possible de trier les intersong avec les chansons, en utilisant la commande \sortassong{Titre}[Paramêtres]. Cette commande ne produit rien dans le document final, mais indique au plugin sort comment trier les chansons.

Par exemple, pour introduire une biographie de Georges Brassens avant l’ensemble de ses chansons (dans un recueil trié par auteur, album puis titre), on pourra avoir le fichier brassens.is suivant :

\selectlanguage{french}
\begin{intersong}
\sortassong{}[by={Georges Brassens}]

Georges Brassens était un chic type né en 1921.
\end{intersong}

Colonnes

La commande songcolumns détermine le nombre de colonnes sur lequel sera présentée la chanson. Elle s’utilise juste avant la commande beginsong. Généralement une chanson se présente sur 1, 2 ou 3 colonnes. Par convention, utilisez deux colonnes par défaut.

\songcolumns{2}
\beginsong{Titre}