`:icons: font

README

This repository contains the source for the textbook Start Concurrent: A Gentle Introduction to Concurrent Programming. It is licensed under Apache License 2.0.

Software Needed

Basic Software Needed

1. Git (and a GitHub account to access the Start Concurrent repository)

2. Ruby

3. Asciidoctor

4. Asciidoctor-Mathematical

5. Asciidoctor Chunker (to convert to HTML chunks)

6. Asciidoctor Rouge (for syntax highlighting)

7. Asciidoctor PDF gem (to generate a PDF version)

Editing the Illustrations

Most (all?) “figures” in the book are Adobe Illustrator documents saved in PDF format, and are located in the figures subdirectory of the chapter in which they appear. For each PDF file, there is a corresponding SVG file located in the images subdirectory. The SVG file is what is imported into the AsciiDoc file.

To create a new figure or edit an existing one…​

1. Create or edit the Illustrator file in the figures subdirectory.

2. Save changes using the default (PDF) format.

3. Temporarily, convert all text to outlines:

   1. Select > Select All

   2. Type > Create Outlines

4. Then, Save a Copy As…​, using SVG format and deselecting the “Preserve Illustrator Editing Capability”, to create an .SVG file in the images subdirectory.

Note: Don’t save the outlined text version back to the original PDF file!

Generating the HTML Files

See the shell script update-html and companion ruby script update-html.rb. The shell script generates both the full book as a single-page html file and a "chunked" version that generates one chapter per html file (for faster downloading).

Generating the PDF

See the shell script update-pdf and companion ruby script update-pdf.rb.

Special Workaround for Tables when Generating PDF

Warning

This section has not been updated lately and a permanent fix may now be in place.

There is a bug in the prawn-table code used by Asciidoctor-PDF when formatting certain tables. There is discussion and a (so-far incomplete) fix here.

Steps to fix the problem (simplified to not use a Gemfile):

1. Download the latest prawn-table code to a separate repository.

   1. git clone https://github.com/prawnpdf/prawn-table.git

   2. cd prawn-table

2. Build and install.

   1. gem build prawn-table.gemspec

   2. gem install prawn-table-0.2.3.gem

These steps do not fix all tables. Specifically, not all tables with autowidth will work. Advice from the Asciidoctor authority is to use column ratios and table width.

Generating E-Book Formats

Warning

In progress.

1. Update book sources to comply with required format. (One time; in progress.)

2. Install the AsciiDoctor EPUB3 gem.

3. Run Asciidoctor EPUB3 to do the conversion:
   $ (cd full; asciidoctor-epub3 index.adoc -D ../epub3)

4. Additional steps (TBD) convert the document to Kindle format (KF8/MOBI).

Other gems needed (apparently):

• gepub

• epubcheck