FAQ for R Users

How do I get started?

Assuming you have a fairly new version of R and an IDE installed (e.g. RStudio), install bookdown and songbookdown. If you want to produce pdf later on, install tinytex and run the function install_tinytex().

install.packages("bookdown")
devtools::install_github("ratnanil/songbookdown")

# to produce pdf outputs later on:
install.packages("tinytex")
tinytex::install_tinytex()

And then?

Next, create the files minimally needed for bookdown project. This consists of the following files:

• _bookdown.yaml
• index.Rmd
• a folder where the (intermediate) Rmd files can be stored (e.g. rmd)
• a folder where the book is compiled to (e.g. docs)

Additionally, songbookdown requires the following files:

• _songbookdown.yaml
• a folder where the raw song-files are stored. (e.g. songs_raw)

These files can be generated using the function create_template()

How do I add a new song?

Add subfolders to songs_raw. These subfolders will create different chapters in your book, e.g. “Classics” and “Christmas Songs”.

Create a plain text file (e.g. mysong.txt) in one of the subfolders of songs_raw and import the song into this file. You can add metadata in the yaml format, wrapped with tripple dashes (see below).

---
title: Here Comes the Sun
artist: the Beatles
year: 1969
---

Here comes the sun
Doo doo doo doo
Here comes the sun and I say
It's alright
...

What metedata can I add and how is this used?

You can add any metadata in this form, and this data will be displayed in a tabular fashion at the end of the song. Some keywords have a special meaning:

• title is required and used to build the songs’s header.
• title, artist, composer, lyricist and album are used in the glossary.
• declaring the source is recommened.

Even if you can add any metadata, using the chordpro syntax is recommended. Here’s a list of keywords that are used in the chord-pro syntax:

• title
• subtitle
• artist
• composer
• lyricist
• copyright
• album
• year
• key
• time
• tempo
• duration
• capo
• source

What about the rest of the song?

Add the rest of the song in plain text. It will be rendered into a monospaced font where lines are not broken. The reasoning behind this is that you can copy and paste plain text songs from sources like ultimate-guitar.com where monospacing helps keep chords and text aligned.

You add further structure to the song in a chordpro type manner. From the chord pro syntax, the following environment directives are implemented (short forms only).

• {start_of_chorus}
• {end_of_chorus}
• {chorus}
• {start_of_verse}
• {end_of_verse}
• {start_of_bridge}
• {end_of_bridge}
• {start_of_tab}
• {end_of_tab}
• {start_of_grid}
• {end_of_grid}

As in the chordpro specification, all environment directives may include an optional label to identify the section. For example: {start_of_verse: Verse 1} The label should not include special characters and must be seperated from the : with a space.

How do I add a new chapter into the book?

Create a subfolder in the songs_raw folder. Add the name of the folder to subfolders: in _songbookdown.yml and add a title.

subfolders: 
  mynewfolder:
    title: The title of the new chapter (required) 
    description: |
      An optional description
      that can span over muliple lines
      (currently this description is not used anywhere,
      but will be implemented in the near future)