This is a community-maintained version of Tonc, the GBA programming tutorial originally written by Jasper Vijn (cearn).

You need Python 3. Dependencies can be installed via pip or your package manager.

# clone the repo
git clone git@github.com:gbadev-org/tonc.git
cd tonc

# install dependencies
# (if your operating system distributor provides Python, follow the
# PEP 668 instructions to set up a venv first)
pip install pelican markdown

# run the development server
make devserver

Then open http://127.0.0.1:8000/toc.html in your browser.

Conversion can be done one page at a time.

You can use pandoc to get you started:

cd content/pages

# rename to avoid conflicts in page generation
mv intro.htm intro-old.htm

# run through pandoc (minus some extensions to get sane output)
pandoc --from=html --to=markdown-fenced_divs-bracketed_spans-escaped_line_breaks-smart --wrap=none -o intro.md intro-old.htm

Then, add metadata and replace the table of contents with a [TOC] marker:

Title: Introduction to Tonc
Date: 2003-09-01
Modified: 2023-08-13
Authors: Cearn

# ii. Introduction to Tonc

[TOC]

Next, go through the page and fix anything that's broken.

For example:

• <span class="dfn"> should be changed back to <dfn> (for some reason pandoc messes this up). Same goes for <kbd> and some other tags.

  sed -i -E 's,<span class="dfn">([^<]+)</span>,<dfn>\1</dfn>,g' pagename.md
  

• Section numbers should be removed from headings (but the number in the page title should stay, e.g. # 3. My first GBA demo)

  sed -i -E 's,^(##+) [0-9]+\.[0-9.]+,\1,g' pagename.md
  

• Tables and Figures should be replaced with the raw HTML from the -old.htm file.

• Code blocks should have the correct language set on them (c, asm, sh, makefile)

• Use backticks (`) around code keywords and italics (*) around file names in the text.

• Container tags may need a markdown attribute adding to them, otherwise the Markdown within won't be rendered properly. For example:

  <div class="note" markdown> ... </div>
  <div style="margin-left:1.2cm;" markdown> ... </div>

  It may help to apply this attribute to all notes.

  sed -i -E 's,<div class="note">,<div class="note" markdown>,g' pagename.md
  

Once it's in good shape, you can delete the original .htm file.

For autonumbering and cross-referencing of figures, tables and equations, we use a syntax based on pandoc-xnos.

• The id attribute is used to define a figure, e.g. id="fig:foobar" or {#fig:foobar}.

• Possible ID kinds are fig:, tbl: and eq: to define figures, tables, and equations respectively.

• Use @fig:foobar to refer to a figure.

• Use *@fig:foobar when the first letter should be capitalised.

• Use !@fig:foobar to print only the number (without the word 'fig').

• Use {@fig:foobar} to avoid clashing with surrounding syntax.

• The figure/table/equation prefix is defined by the page title.

For example, on the page 'ii. Introduction to Tonc', the following Markdown:

<img src="img/toncdirs.png" id="fig:toncdirs" alt="Tonc directory structure">  
**{*@fig:toncdirs}**: directories.

Will be rendered as: