### Install development version from git

Source: https://patacrep.readthedocs.io/fr/latest/installation.html

Clones the Patacrep repository, installs dependencies, and runs the setup script to install the development version.

```bash
git clone https://github.com/patacrep/patacrep.git
cd patacrep
pip3 install -r Requirements.txt
python3 setup.py install
```

--------------------------------

### Test songbook installation

Source: https://patacrep.readthedocs.io/fr/latest/installation.html

Run this command to verify that songbook was installed correctly.

```bash
songbook --version
```

--------------------------------

### Install in a virtualenv

Source: https://patacrep.readthedocs.io/fr/latest/installation.html

Creates a Python 3 virtual environment, activates it, installs patacrep, and checks the songbook version. The output shows the expected messages from the virtualenv creation.

```bash
$ virtualenv -p python3 virtualenv
Already using interpreter /usr/bin/python3
Using base prefix '/usr'
New python executable in virtualenv/bin/python3
Also creating executable in virtualenv/bin/python
Installing setuptools, pip...done.
$ . virtualenv/bin/activate
(virtualenv)$ pip install patacrep
...
$ songbook --version
...
```

--------------------------------

### Intersong file example (brassens.is)

Source: https://patacrep.readthedocs.io/fr/latest/song/latex.html

Example of an intersong file with .is extension. It starts with \begin{intersong} and ends with \end{intersong}. Language and column commands can be placed before \begin{intersong}. The \sortassong command is used for sorting and produces no output in the final document.

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

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

--------------------------------

### Installer les paquets Python pour Debian (avec virtualenv)

Source: https://patacrep.readthedocs.io/fr/latest/installation.html

Commande apt-get pour installer python3-virtualenv, nécessaire pour une installation de patacrep avec virtualenv sur Debian.

```bash
apt-get install python3-virtualenv

```

--------------------------------

### Installer les paquets LaTeX pour Ubuntu 16.04

Source: https://patacrep.readthedocs.io/fr/latest/installation.html

Commande apt-get pour installer texlive-luatex et texlive-xetex, nécessaires pour que LaTeX fonctionne bien sur Ubuntu 16.04.

```bash
apt-get install texlive-luatex  texlive-xetex

```

--------------------------------

### Example YAML file for a songbook

Source: https://patacrep.readthedocs.io/fr/latest/book/introduction.html

A complete example of a .yaml file that defines a songbook. It includes content sections, book settings, chord options, author parsing rules, and title prefix rules. This file is provided with the source code and serves as a template for creating custom songbooks.

```yaml
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

```

--------------------------------

### Installer les paquets Python pour Debian (sans virtualenv)

Source: https://patacrep.readthedocs.io/fr/latest/installation.html

Commande apt-get pour installer Python 3.4 et pip, nécessaire pour une installation de patacrep sans virtualenv sur Debian et ses dérivées.

```bash
apt-get install python3.4 python3-pip

```

--------------------------------

### Check LilyPond version

Source: https://patacrep.readthedocs.io/fr/latest/installation.html

Run this command to verify that LilyPond is installed. If the version number is displayed, the installation is fine; if you get a 'command not found' error, there is a problem.

```bash
lilypond --version
```

--------------------------------

### Activate virtualenv before use

Source: https://patacrep.readthedocs.io/fr/latest/installation.html

If you installed in a virtualenv, you must run this command before each use of songbook or patacrep.

```bash
. PATH_TO_VIRTUALENV/bin/activate
```

--------------------------------

### Install patacrep with pip (without virtualenv)

Source: https://patacrep.readthedocs.io/fr/latest/installation.html

Installs the Patacrep library and songbook program from the Python Package Index using pip3.

```bash
pip3 install patacrep
```

--------------------------------

### Complete song example: Sad robot

Source: https://patacrep.readthedocs.io/fr/latest/song/latex.html

A complete example of a song definition using \selectlanguage, \songcolumns, \beginsong, \cover, \gtab, \utab, \lilypond, \beginverse, \begin{repeatedchords}, and \endsong.

```LaTeX
\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

```

--------------------------------

### Chord notation example: \[D]

Source: https://patacrep.readthedocs.io/fr/latest/song/latex.html

Chord notation example showing the anglo-saxon chord D. The rendered note name depends on the songbook language; for example, \[D] renders as 'Ré' when the language is 'french'.

```latex
\[D]
```

--------------------------------

### Chord diagram examples: \gtab and \utab

Source: https://patacrep.readthedocs.io/fr/latest/song/latex.html

Examples of guitar (\gtab) and ukulele (\utab) chord diagrams. The starred variants \gtab* and \utab* mark non-standard chords as important. The syntax includes the chord name and a fingering pattern.

```latex
\gtab{C}{3:002220}
\gtab*{Amaj7}{5:X0221X}
\utab{C}{0003}
\utab{B&m}{1:2000}
```

--------------------------------

### Verse and unnumbered verse environments

Source: https://patacrep.readthedocs.io/fr/latest/song/latex.html

Example of a verse split into two stanzas: the first uses \beginverse/\endverse and is numbered, the second uses \beginverse*/\endverse* and is not numbered. Chords are written in brackets.

```latex
\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*

```

--------------------------------

### Lilypond score example: partition.ly

Source: https://patacrep.readthedocs.io/fr/latest/song/latex.html

Example of a Lilypond score to be included in a song. It includes the header file and sets paper-height to 3.3 cm for a two-line score. The music is written between braces.

```latex
\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}
```

--------------------------------

### Repeat command example: \rep{4}

Source: https://patacrep.readthedocs.io/fr/latest/song/latex.html

Use \rep{4} to indicate a phrase is repeated four times. This is preferred over writing \bis or (x4) directly.

```latex
Hallelujah \rep{4}
```

--------------------------------

### Echo command example: \echo{Hallelujah}

Source: https://patacrep.readthedocs.io/fr/latest/song/latex.html

The \echo command is used to indicate a chorus or similar repeated section. The argument is the text to be echoed.

```latex
Hallelujah \echo{Hallelujah}
```

--------------------------------

### Syntaxe de l'instruction extends

Source: https://patacrep.readthedocs.io/fr/latest/more/templates.html

Étend un template existant. Le contenu des blocs est placé dans les blocs correspondants du template parent. Si le bloc n'existe pas, le contenu est placé à la fin du fichier et ignoré par LaTeX.

```jinja
(* extends "template.tex" *)

```

--------------------------------

### Créer un paquet .deb avec stdeb

Source: https://patacrep.readthedocs.io/fr/latest/installation.html

Commandes pour créer un paquet Debian à la volée avec stdeb et l'installer avec dpkg. La première commande génère le paquet, la seconde l'installe.

```bash
python setup.py --command-packages=stdeb.command bdist_deb
sudo dpkg -i deb_dist/python3-patacrep_5.0.0-1_all.deb

```

--------------------------------

### Chord notation example: \[A&m]

Source: https://patacrep.readthedocs.io/fr/latest/song/latex.html

Example of a minor chord with a flat: A&m represents A-flat minor. The flat symbol is represented by '&' and the sharp by '#'. Minor chords use a lowercase 'm'.

```latex
[A&m]
```

--------------------------------

### Exemple de fichier YAML avec options par défaut

Source: https://patacrep.readthedocs.io/fr/latest/book/layout.html

Fichier YAML montrant les options par défaut pour la mise en page d'un carnet. Les options peuvent être omises et prendront alors leur valeur par défaut. Le mot-clé content ne gère pas la mise en page mais le contenu du carnet.

```yaml
book: # Options générales
  lang: en
  encoding: utf-8
  pictures: yes
  template: default.tex
  onesongperpage: no

chords: # Options musicales
  show: yes
  diagramreminder: important
  diagrampage: all
  repeatchords: yes
  lilypond: no
  tablatures: no
  instrument: guitar
  notation: alphascale

authors: # Analyse des auteurs
  separators:
  - and
  ignore:
  - unknown
  after:
  - by

titles: # Analyse des titres
  prefix:
  - The
  - Le
  - La
  - "L'"
  - A
  - Au
  - Ces
  - De
  - Des
  - El
  - Les
  - Ma
  - Mon
  - Un
content:

```

--------------------------------

### Définir la fonction parse() pour le plugin foo

Source: https://patacrep.readthedocs.io/fr/latest/more/content.html

Cette fonction parse() retourne une liste d'objets content.Content, ici une instance de Foo avec l'argument passé. Elle est appelée avec le mot-clé, l'argument et la configuration.

```python
def parse(keyword, argument, config):
  return [Foo(argument)]

```

--------------------------------

### Syntaxe de l'instruction block

Source: https://patacrep.readthedocs.io/fr/latest/more/templates.html

Définit un bloc nommé 'mon_bloc' qui peut être rempli par un template parent. Le contenu est placé à l'emplacement correspondant dans le template parent.

```jinja
(* block mon_bloc *)
   Contenu
(* endblock *)

```

--------------------------------

### Exemples d'utilisation de l'instruction if

Source: https://patacrep.readthedocs.io/fr/latest/more/templates.html

Deux exemples de conditions : vérification de la valeur de 'booktype' et comparaison de 'textwidth'.

```jinja
(* if booktype == "chorded" *)
   \addschords
(* endif *)

(* if textwidth > 42 *)
   \collumns{3}
(* endif *)

```

--------------------------------

### Chord notation example: \[E] and \[D]

Source: https://patacrep.readthedocs.io/fr/latest/song/latex.html

Use \[E] to place a chord above the following syllable. Chords must use anglo-saxon notation (A-G). The rendered note name depends on the songbook language; for example, \[D] renders as 'Ré' when the language is 'french'. The 'notenamesout' option customizes this rendering.

```latex
\[E]
```

--------------------------------

### Syntaxe de l'instruction if avec elif et else

Source: https://patacrep.readthedocs.io/fr/latest/more/templates.html

Placement conditionnel de contenu. Les instructions elif et else sont facultatives. Les conditions peuvent être n'importe quelle expression Python valide.

```jinja
(* if <condition1> *)
   Placé si la condition 1 est vraie
(* elif <condition2> *)
   Placé si la condition 2 est vraie
(* else *)
   Placé si les conditions 1 et 2 sont fausses
(* endif *)

```

--------------------------------

### Vérifier l'installation de Python et LaTeX

Source: https://patacrep.readthedocs.io/fr/latest/installation.html

Commandes pour vérifier que Python et lualatex sont correctement installés après avoir installé les dépendances.

```bash
python --version
lualatex --version

```

--------------------------------

### Configuration YAML des options de template

Source: https://patacrep.readthedocs.io/fr/latest/book/layout.html

Exemple de configuration YAML montrant comment définir les options des templates default.tex et patacrep.tex sous la clé 'template'. Les options incluent le titre, l'auteur, les couleurs et les couleurs de fond.

```yaml
# options précédentes `book`, `chords`...

template:
  default.tex:
    title: "Recueil de chansons pour guitare"
    author: "L'équipe Patacrep"
  patacrep.tex:
    color:
      songlink: FF0000
      hyperlink: 0000FF
    bgcolor:
      note: D1E4AE
      songnumber: AED1E4
      index: E4AED1

```

--------------------------------

### Exemple de contenu de recueil avec le mot-clé foo

Source: https://patacrep.readthedocs.io/fr/latest/more/content.html

Ce bloc YAML montre comment le mot-clé 'foo' est utilisé dans le contenu du recueil. La fonction parse() sera appelée avec l'argument correspondant.

```yaml
- foo:
    bar: "something"
    content:
      - "one"
      - "two"

```

--------------------------------

### Add /usr/local/bin to PATH on Mac OS X

Source: https://patacrep.readthedocs.io/fr/latest/installation.html

If you get 'songbook: command not found' on Mac OS X, add /usr/local/bin to your PATH by appending the export line to ~/.bashrc.

```bash
echo "export PATH=$PATH:/usr/local/bin" >> ~/.bashrc
```

--------------------------------

### Syntaxe de la ligne de commande songbook

Source: https://patacrep.readthedocs.io/fr/latest/bin.html

Affiche la syntaxe complète de la commande songbook avec toutes ses options. L'argument obligatoire est un fichier .yaml à compiler en carnet de chants.

```bash
songbook [-h] [--version] [--datadir DATADIR [DATADIR ...]] [--verbose] [--steps STEPS] [--cache CACHE] [--error {failonsong,failonbook,fix}] book.yaml
```

--------------------------------

### Plugin cd : changement de répertoire

Source: https://patacrep.readthedocs.io/fr/latest/book/content.html

Syntaxe du plugin cd pour éviter de répéter les chemins complets. Les deux exemples sont équivalents.

```yaml
content:
  - cd:
    path: des/repertoires/vers
    content:
      - "chanson1.csg"
      - "chanson2.csg"
      - "chanson3.csg"

```

```yaml
content:
  - "des/repertoires/vers/chanson1.csg"
  - "des/repertoires/vers/chanson2.csg"
  - "des/repertoires/vers/chanson3.csg"

```

--------------------------------

### Syntaxe de l'instruction for

Source: https://patacrep.readthedocs.io/fr/latest/more/templates.html

Répète un contenu pour chaque élément de la liste 'languages_list', en utilisant la variable 'lang'.

```jinja
(* for lang in languages_list *)
   Contenu à être répété, en utilisant la variable ((lang))
(* endfor *)

```

--------------------------------

### Inclure un fichier de contenu avec le mot-clef include

Source: https://patacrep.readthedocs.io/fr/latest/book/content.html

Le mot-clef `include` permet d'inclure un autre fichier YAML dans le contenu courant. Le fichier inclus doit contenir une liste d'éléments de contenu valide et peut lui-même contenir d'autres inclusions.

```yaml
- section: "Chansons à boire"
- "boire/*.csg"
- section: "Chansons d'amour"
- include: "amour.sbc"

```

--------------------------------

### Exemple d'utilisation de l'instruction for avec if

Source: https://patacrep.readthedocs.io/fr/latest/more/templates.html

Boucle sur les langues et applique une commande différente selon que la langue est 'french' ou non.

```jinja
(* for lang in languages_list *)
   (* if not lang == "french" *)
      \setlang{ ((lang)) }
   (* else *)
      \setmainlang{ ((lang)) }
   (* endif *)
(* endfor *)

```

--------------------------------

### Exemple de contenu avec sections et tri

Source: https://patacrep.readthedocs.io/fr/latest/book/content.html

Définit une liste de contenu avec des fichiers tex, des sections, des motifs de chants et un tri par auteur puis titre.

```yaml
content:
  - tex: "intro.tex"
  - section: "Chansons à boire"
  - "boire/*.csg"
  - section: "Chansons d'amour"
  - sort:
      key: ["by", "title"]
      content:
        - "amour/*.csg"
        - "love/*.csg"

```

--------------------------------

### Compiler un carnet avec songbook

Source: https://patacrep.readthedocs.io/fr/latest/bin.html

Exemple d'utilisation de songbook pour compiler l'ensemble des chansons du répertoire books de patadata. À exécuter depuis la racine de patadata.

```bash
songbook books/songbook.yaml
```

--------------------------------

### Compile a YAML file with songbook command

Source: https://patacrep.readthedocs.io/fr/latest/book/introduction.html

Command-line instruction to compile a .yaml file into a PDF using the songbook program. Replace 'chemin/vers/carnet.yaml' with the actual path to your YAML file.

```bash
songbook chemin/vers/carnet.yaml

```

--------------------------------

### Exemple complet de chanson au format ChordPro

Source: https://patacrep.readthedocs.io/fr/latest/song/chordpro.html

Exemple complet montrant l'utilisation des directives entre accolades (lang, columns, title, subtitle, artist, cover, album, partition, start_of_chorus, end_of_chorus, comment, guitar_comment, image) et l'insertion des accords entre crochets dans les paroles.

```chordpro
{lang : en}
{columns :  2}
{title : Greensleeves}
{subtitle: Example of the chordpro format}
{artist: Traditionnel}
{cover : traditionnel.jpg}
{album : Angleterre}

{partition : greensleeves.ly}

A[Am]las, my love, ye [G]do me wrong
To [Am]cast me oft dis[E]curteously
And [Am]I have loved [G]you so long
De[Am]lighting [E]in your [Am]companie

{start_of_chorus}
   [C]Greensleeves was [G]all my joy
   [Am]Greensleeves was [E]my delight
   [C]Greensleeves was my [G]heart of gold
   And [Am]who but [E]Ladie [Am]Greensleeves
{end_of_chorus}

I [Am]have been ready [G]at your hand
To [Am]grant what ever [E]you would crave
I [Am]have both waged [G]life and land
Your [Am]love and [E]good will [Am]for to have

I [Am]bought thee kerchers [G]to thy head
That [Am]were wrought fine and [E]gallantly
I [Am]kept thee both at [G]boord and bed
Which [Am]cost my [E]purse well [Am]favouredly

I [Am]bought thee peticotes [G]of the best
The [Am]cloth so fine as [E]fine might be
I [Am]gave thee jewels [G]for thy chest
And [Am]all this [E]cost I [Am]spent on thee

{comment:test of comment}

{guitar_comment: test of guitar comment}

{image: traditionnel.jpg}

Thy [Am]smock of silke, both [G]faire and white
With [Am]gold embrodered [E]gorgeously
Thy [Am]peticote of [G]sendall right
And [Am]this I [E]bought thee [Am]gladly

```

--------------------------------

### Définir la classe Foo héritant de content.Content

Source: https://patacrep.readthedocs.io/fr/latest/more/content.html

Ce code définit la classe Foo qui hérite de content.Content. La méthode render() renvoie la valeur de l'argument 'bar' pour inclusion dans le fichier .tex.

```python
from patacrep.content import Content

class Foo(Content):

  def __init__(self, arguments):
    """Fonction d'initialisation

    Le moteur de plugin ne va pas appeler cette fonction directement : chaque
    plugin est donc libre de définir cette initialisation comme il l'entend.
    """
    self.arguments = arguments

  def render(self, __context):
    return self.arguments['bar']

```

--------------------------------

### Inclure une image avec la commande {image: image.png}

Source: https://patacrep.readthedocs.io/fr/latest/more/datadir.html

Commande pour inclure une image depuis le répertoire img. Le chemin absolu n'est pas nécessaire car ce répertoire est automatiquement inclus dans la recherche.

```markdown
{image: image.png}
```

--------------------------------

### Plugin song : inclusion de chansons avec mot-clé automatique

Source: https://patacrep.readthedocs.io/fr/latest/book/content.html

Équivalent de l'exemple précédent lorsque le mot-clé song est automatique (utilisé par défaut). La liste de chansons est directement sous content.

```yaml
content:
  - "premiere.csg"
  - "boire/*.tsg"

```

--------------------------------

### Including a Lilypond score: \lilypond{partition}

Source: https://patacrep.readthedocs.io/fr/latest/song/latex.html

Use \lilypond{partition} in the song file to insert the score defined in partition.ly.

```latex
\lilypond{partition}
```

--------------------------------

### Plugin cd : inclusion directe avec glob

Source: https://patacrep.readthedocs.io/fr/latest/book/content.html

Inclusion de chansons directement dans un dossier avec une expression glob. Ne prend que les fichiers directement dans le dossier, pas les sous-dossiers.

```yaml
content:
  - "chants_a_boire/*.csg"

```

--------------------------------

### Title and metadata with \beginsong

Source: https://patacrep.readthedocs.io/fr/latest/song/latex.html

Defines the song title and metadata like author, cover, and album. Titles are separated by double backslashes.

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

```