Chromadoc

A script language to create documents with notes written in Chromatic-Solfege.

Chromadoc

Introduction

Chromadoc is a toolkit for writing documentation with Chromatic-Solfege notation. This toolkit contains a compiler which compiles Chromadoc document into TeX and Lilypond, then builds PDF documents.

Chromadoc format is a file-format which can contain paragraphs with Chromatic-Solfège notation embedded in them. These paragraphs are compiled into TeX document. And the notations embedded to paragraphs are converted to Lilypond documents and then embedded to the TeX document. The compiler also generates singing voice data from Lilypond documents.

This toolkit contains programs to perform following tasks :

System Requirement

This system is built on following systems :

Please note that although this system is partially written by nodejs, NPM is not necessary.

Installation

Chromadoc does not need installation. You can place any directory.

Go to any directory you want to place the Chromadoc and clone the GitHub repository as:

git clone https://github.com/chromatic-solfege/chromadoc.git

Usage

After clone Chromadoc, go to the directory and source the file init-chromadoc in the root directory of the repository.

	. init-chromadoc

This will set up some environment variables including PATH.

The main task of using this system is writing Chromadoc scripts. The chromadoc is designed to automate the generation of TeX files and Lilypond files.

A chromadoc file is a JavaScript program which later will be compiled with additional headers and footers. The converted program outputs TeX scripts and Lilypond scripts.

A typical Chromadoc script is as:

t_abstract`
	This document presents how to use the Chromatic-Solfege Documentation
	System. Brab rab rabra ...
`;

t_header0`Introduction`;
t_textBody`
	This system is so-and-so and such-and-such.
`;

writeNewPage();

// Ouput Table of Contents
writeTOC();
writeNewPage();

writeScore( 'example01', `@do do4 re mi `, {} );

Note that the extensive use of template string. The main forcus of writing Chromadoc script is writing a number of template string literals.

After writing the script file, save it as “ex1.chromadoc”. In order to convert the script you have written into a beautifully readable documents, use
chromadoc command.

It firstly converts the script to JavaScript program, and then execute the program. The program outputs a number of tex scripts and lilypond scripts. And chromadoc command automatically invokes necessary conversions to build a document we want.

> chromadoc ex1.chromadoc

chromadoc clears the output directory and then executes the specified i JavaScript file and invokes Lilypond and Festival Speech System to the created files.

Command Reference

The available tag-functions are prefixed by t_. Every function has its corresponding TeX tag as describing following.

The functions prefixed by write are advanced version of t_ functions. The write functions can perform more precise control since these accept more parameters than t_ version.

t_abstract Outputs \\begin{abstract} TEXT \\end{abstract}.

t_headerPart Outputs \\part{ TEXT }.

t_header0 Outputs \\section{ TEXT }.

t_header1 Outputs \\subsection{ TEXT }.

t_header2 Outputs \\subsubsection{ TEXT }.

t_header3 Outputs \\paragraph{ TEXT }.

t_header4 Outputs \\subparagraph{ TEXT }.

t_textBody Outputs TEXT as is.

t_score Outputs a musical score. This accepts Csall scripts. For further information, see Chromatic-Solfege for JavaScript.

t_commands Outputs a TeX command directly.

t_diagram TODO

t_TOC Outputs \\tableofcontents.

t_newPage Outputs ~\\newpage.

t_newLine Outputs \\\\~.

writeAbstract

writeHeaderPart

writeHeader0

writeHeader1

writeHeader2

writeHeader3

writeTextBody

writeCommands

writeScore

writeDiagram

writeTOC

writeNewPage

writeNewLine

The Directory Structure

	> chmake-concat infile1 infile2... outfile

	- chmake-mp4
		This script generates a video from the output of `chromadoc` 
		command.

	> chmake-mp4 in-dir background-image out-dir

	- lypdf2png
		This script converts a Lilypond generated PDF to a PNG file.

	- pdfwav2mp4
		This script converts a TeX generated PDF and reading voice data 
		into a mp4 movie file.
		
	- pngwav2mp4
		This script converts a Lilypond generated PNG and reading voice 
		data into a mp4 movie file.

	- replace_text.js
		This script replaces a specific string literal in a file with 
		another specific string literal. This script is used for 
		templating.

	- txtwav2mp4
		This script creates a movie from a text caption data and audio 
		data.
	- txtwav2mp4-header-template.svg
		This is a SVG template for headers. This template is used for 
		generating videos.
		
	- txtwav2mp4-template.svg
		This is a SVG template for musical scores. This template is used 
		for generating videos.

	- vid2effect
		This script adds effects to the generated video files by using 
		GStreamer. This script is experimental and currently not used.

	- wav2mp4
		This script takes a filename of a wave file which _chromadoc_ 
		output. Then it checks the filename and determin if the audio data 
		is from a music singing audio or reading a caption audio.
		And then the script creates videos from the audio data.

Further Information

For further information, please refer the documents of the respective modules/commands.