code generation

the songbook tool is a code generator. Syntax is :

songbook <songdir> <docdir> <builddir>

it takes inputs :

• songdir : the root dir of songs
• bookdir : the root dir of books

and will generate code in builddir

when and why do we need to generate ?

we could have used omake scanner facility to replace some features, but it would have been tricky.

We need to regenerate whenever a master song.json has changed, or a song was added or removed, so that the makefiles are up-to-date. The action of generating is a few ms so in our workflow there is no point in trying to optimize that, compared to the generation of pdfs that is 100 times longer.

So the answer is : generate each time you build, it is harmless.

thanks omake

Omake uses digest of files to know if a target needs to be rebuild. So when you regenerate you will have source files that are more recent than the output pdf file, but omake will not rebuild the target.

tree structure

all files are generated in the builddir tree. No file is generated in the source directory : code generate leaves the sources unchanged.

<builddir>
    OMakeroot
    OMakefile
    +--- delivery
    |        +--- .... all the delivery files : pdfs and wav
    +--- songs
    |        +--- artist 1
    |        |        +--- song 1
    |        |        |       +--- OMakefile
    |        |        |            --> ... generated files : main.tex, ...
    |        |        |            --> ... all vmount files...
    |        |        |            --> ... files generated by the build
    |        |        +--- song N
    |        |               ....
    |        +--- artist N
    |                 +--- songs....
    +--- books
             +--- book 1
             |        +--- OMakefile
             |              --> ... generated files : main.tex
             |              --> ... files generated by the build
             +--- book N

vmount files

omake has the vmount feature : any file used as a dependency in an OMakefile is copied from the source directory to the build directory, and this is done each time you run the build. So it looks as if the srcdir is mounted in the builddir.

For that to work, source files have to be declared in the OMakefile, and this is done because they are declared in the master json file. Other mounted files added automatically are :

1. body.tex ( we have to have it, so it does not need to be declared in the master json file )
2. the tex lyrics ( one per section ) : this list is generated

the code generator will generate :

files for running omake :

1. OMakeroot
2. root OMakefile
3. song OMakefile
4. book OMakefile

latex files

1. main.tex
2. preamble.tex
3. sections.tex
4. struct.tex
5. chords.tex

OMakeroot

omake requires to have a OMakeroot file, (see omake doc) the code is a handle bar template, others/makefiles/omakeroot

root OMakefile

this is the root makefile. Here we define some phony targets, the code is a handle bar template, others/makefiles/root_omakefile

song OMakefile

this is the makefile you find in every song directory, the code is a handle bar template, others/makefiles/omakefile

book OMakefile

this is the makefile you find in every book directory, the code is a handle bar template, others/makefiles/omakefile_book

main.tex

this is the main.tex file, where the latex document is declared. This is file is the input of the lualatex command. the code is a handle bar template, others/texfiles/main.tex

We have here the input of other generated files, and the input of the user's code : body.tex

preamble.tex

this is where we define the latex preamble, that is the require of all latex packages we need. others/texfiles/preamble.tex

sections.tex

This is where, for each section type xxx, we define the latex macro \songbooksectionxxx and \\songbookcolor that can be reused in latex code others/texfiles/sections.tex

data.tex

This is where, using the data from master file song.json, latex macros are defined : others/texfiles/data.tex

1. \songtitle
2. \songauthor
3. \songtempo
4. \makesongtitle : will format the string
5. \songlastupdate
6. \songbooksongstruct : this one has the sections of the song, it is the one you want to put in your body.tex file

chords.tex

see the fonts section

Our design is to define our fonts to display chords, so there will be one glyph per chord, for instance D flat 7 will be one glyph.

In this file we define marcros that map chords to glyphs : others/texfiles/chords.tex. For instance, we have for D flat 7 :

\newcommand\chordDfsept{{\songbookfontflat\fontsize{18pt}{18pt}\selectfont R ~ }}