Handbook pdf

Purpose

The Audiveris Handbook is the main documentation meant for the end user. This article describes how to generate a PDF version of Audiveris Handbook.

Web version

Technically, the Audiveris Handbook is written as a hierarchy of Markdown files. These files are rendered as HTML pages and delivered on-line from the GitHub web site.

Via any web browser, we can:

• Access the documentation on-line,
• Navigate through its hierarchy (via the side navigation pane),
• Search the documentation for matching words (via the "Search Audiveris Pages" field),
• Read desired web pages interactively.

You can see the latest web version here.

PDF version

As opposed to the web version, the PDF version is made of a single downloadable PDF file.

The PDF file is organized as follows:

1. A hierarchical table of content, with hyperlinks to the related chapters,
2. All the pages, one chapter after the other,
3. Possibly an index of major entities (this feature is not yet implemented).

With a PDF version, we can:

• Read the documentation off-line,
• Navigate through its hierarchy (via the table of content),
• Print it on paper,
• Convert it to spoken audio (via some "text-to-speech" application).

You can see a PDF version here.

Generation

The PDF version is generated from the web version, using "prince" software.

The workflow is implemented by the dedicated pdf-build.sh bash file.
This file is derived from hamoid / justTheDocsToPDF.bash work.

In the Audiveris project folder, the docs/pdf sub-folder contains:

File	Purpose
pdf-build.sh	Workflow implementation
pdf-nav-style.css	Style file used by the table of content
build/	Sub-folder where results are generated

Portability

The bash file has been tested on Windows/Cygwin.
It should also run on Linux and MacOS.

It uses standard Linux utilities: curl, grep, head, perl, sed, tail, echo, cat

It also uses the "prince" software which is assumed to be found on PATH.
Prince can be downloaded from https://www.princexml.com/download/ for various OSes and can be freely used for non-commercial use.

Operation

The pdf-build.sh file is meant to be run from the docs/pdf folder.

# Assuming we are located at root of Audiveris project
cd docs/pdf

By default, the HTML content is retrieved from the current Audiveris pages on GitHub:

# Option A: HTML content from current content of GitHub site (https://audiveris.github.io)
./pdf-build.sh

Instead, to retrieve the HTML content from some not-yet-published pages, rendered and delivered by a local generator, pdf-build.sh accepts an optional parameter, named "local":

# Option B: HTML content from a local Jekyll generator (http://localhost:4000)
./pdf-build.sh local

Path to the resulting file is docs/pdf/build/Audiveris_Handbook.pdf which can then be pushed into Audiveris releases on GitHub.

Appendix

pdf-build.sh

https://github.com/Audiveris/audiveris/blob/652c73d9474e87dfd806c96bf5f5ff0479775a69/docs/pdf/pdf-build.sh

pdf-nav-style.css

https://github.com/Audiveris/audiveris/blob/652c73d9474e87dfd806c96bf5f5ff0479775a69/docs/pdf/pdf-nav-style.css