writing

The Alan Author's Guide

AsciiDoc port of The ALAN Adventure Language Author's Guide (WIP).

Links to the converted Author's Guide:

NOTE — The AsciiDoc files in this project are intended for Asciidoctor, the Ruby implementation of AsciiDoc; some required features might not be available in AsciiDoc Python!

---

Table of Contents

• Document Status
  • Highlighter Info and Limits
• Folder Contents
  • Manual Source Files
  • Conversion Scripts
• Misc Work Notes
  • Conversion from ODT to AsciiDoc

---

Document Status

The Author's Guide was successfully ported from ODT to AsciiDoc, but the document isn't ready for publication, for most of its document contents still need to be written.

In the meantime, anyone interested in following its development can always preview the latest document via this project.

Further development of the Author's Guide contents shall be done here, in AsciiDoc format, instead of the old ODT file, to simplify collaborative editing and to benefit from the shared assets of the Alan Docs project.

Highlighter Info and Limits

Highlight doesn't support callouts in syntax highlighted code blocks, so don't use them!

This document must use Highlight instead of Rouge because it uses highlight marking inside code blocks, which is currently not supported with Rouge.

Folder Contents

The original files of the Author's Guide used for the AsciiDoc conversion are available in:

• ../_assets-src/original-docs/
  • writing.odt
  • writing.pdf

Manual Source Files

• writing.asciidoc — The main Author's Guide file that imports all other chapters:
  • writing_01.asciidoc — 1. Introduction
  • writing_02.asciidoc — 2. Writing With Alan
• alan-logo.png — Alan logo for cover image.

Conversion Scripts

• html_build.sh — bash script to create manual.html document (fully standalone).

Misc Work Notes

Conversion from ODT to AsciiDoc

The original ODT document was first exported to Office Open XML using LibreOffice, and the resulting .docx file was then converted to AsciiDoc using pandoc:

pandoc ^
     -f docx ^
     -t asciidoc ^
    --wrap=none ^
    --atx-headers ^
    --extract-media=extracted-media ^
        writing.docx ^
     -o writing.asciidoc

Although some styles were lost in the process, the final ADoc was a rather good starting point.