= Spruce - A tool for building CVs
:toc:
:toclevels: 1
:toc-title: Contents

== Overview

Spruce is a tool that generates a PDF document from a CV written in JSON.
The PDF generation is completed in two steps:

1. The application parses the JSON document and generates a TEX file using the TEX template files located in the https://codeflow.dananglin.me.uk/apollo/spruce/src/branch/main/internal/cmd/templates/tex[templates] directory.
2. The application then uses ConTeXt to generate the final PDF document from the generated TEX file.

== Requirements

Below is a list of required tools for installing and using spruce.

=== Go

A minimum version of Go 1.21.0 is required for installing spruce.
Please go https://go.dev/dl/[here] to download the latest version.

=== ConTeXt

ConTeXt is required for generating the PDF documentation.
You can go to the https://wiki.contextgarden.net/Installation[installation page] to find out how
to install ConTeXt for your Operating System.

=== The Carlito font (ttf-carlito)

Carlito is a free, metric compatible alternative to the Calibri font from Microsoft and is used when generating the PDF documentation.

For Debian/Ubuntu distributions you can use `apt` to install the font.
[source,console]
----
apt install font-crosextra-carlito
----

For Arch Linux you can use `pacman`.
[source,console]
----
pacman -S ttf-carlito
----

Alternatively you can download the font from https://fontlibrary.org/en/font/carlito[Font Library].

Once Carlito is installed you'll need to update ConTeXt so it can find the font when generating the PDF:
[source,console]
----
OSFONTDIR=/usr/share/fonts
mtxrun --script fonts --reload
----

=== Mage (Optional)

The project includes a https://codeflow.dananglin.me.uk/apollo/spruce/src/branch/main/magefiles/mage.go[magefile] for automating the build and installation of the spruce binary.
With Mage the build information is built into the binary when it is compiled.
You can visit the https://magefile.org[website] for instructions on how to install Mage.

== Installation

=== With Mage

You can install spruce with Mage using the following commands:
[source,console]
----
git clone https://codeflow.dananglin.me.uk/apollo/spruce.git
cd spruce
mage install
----

The default install prefix is set to `/usr/local` so spruce will be installed to `/usr/local/bin/spruce`.
If you don't have sudo privileges or you want to change the install prefix you can set the `SPRUCE_INSTALL_PREFIX` environment variable before installing.
[source,console]
----
SPRUCE_INSTALL_PREFIX=~/.local mage install
----

=== With Go

If your `GOBIN` directory is included in your `PATH` then you can install spruce with Go.

[source,console]
----
git clone https://codeflow.dananglin.me.uk/apollo/spruce.git
cd spruce
go install .
----

=== Verifying the installation

If you have installed spruce with Mage, you can get the build information to confirm that you have installed the correct version.
[source,console]
----
$ spruce version --full
Spruce
  Version: v0.1.0-14-ge503dbf
  Git commit: e503dbf
  Go version: go1.21.0
  Build date: 2023-08-12T13:00:51Z
----

== Generating the example PDF Document

Once you've installed spruce you can generate a PDF from the example CV by running the following command:

[source,console]
----
spruce generate --input example/cv.json
----

This will create a file called `cv.pdf` which you can view in your favourite PDF viewer.

== Inspirations

- https://mszep.github.io/pandoc_resume/[The Markdown Resume:] This project uses ConTeXt and pandoc to convert Markdown based CVs into multiple formats including PDF, HTML and DOCX. This is where I discovered ConTeXt.
- https://github.com/melkir/resume/tree/master[melkir/resume:] This project generates CVs using Go and LaTeX.