This document is intended to give you a quick overview of the Raku programming language.
For those who are new to Raku it should get you up and running.
| Language | Online | EPUB | |
|---|---|---|---|
| English | raku.guide | Download | Download |
| French | raku.guide/fr | Download | Download |
| German | raku.guide/de | Download | Download |
| Japanese | raku.guide/ja | Download | Download |
| Spanish | raku.guide/es | Download | Download |
| Portuguese | raku.guide/pt | Download | Download |
| Dutch | raku.guide/nl | Download | Download |
| Bulgarian | raku.guide/bg | Download | Download |
| Chinese | raku.guide/zh | Download | Download |
| Italian | raku.guide/it | Download | Download |
| Turkish | raku.guide/tr | Download | Download |
| Indonesian | raku.guide/id | Download | Download |
| Russian | raku.guide/ru | Download | Download |
| Ukrainian | raku.guide/uk | Download | Download |
The document is written in asciidoc format and generated using asciidoctor, with syntax highlighting by rouge. You will need a current version of ruby, asciidoctor, rouge, and rouge-raku, the plugin that teaches rouge to highlight Raku.
Install the required tools:
$ sudo gem install asciidoctor
$ sudo gem install rouge
$ sudo gem install rouge-raku
To produce rakuguide.html, run:
$ asciidoctor -r rouge-raku rakuguide.adoc
The -r rouge-raku option is required. Without it the build still succeeds,
but the Raku code is left unhighlighted.
In addition to the tools above, you will need asciidoctor-pdf:
$ sudo gem install asciidoctor-pdf
To produce rakuguide.pdf, run:
$ asciidoctor-pdf -r rouge-raku rakuguide.adoc
The PDF only shows characters found in the fonts it is built with, and the fonts that come with asciidoctor-pdf do not cover all the scripts used in the guide. With the command above, some characters in the Unicode examples appear as empty boxes, and the Japanese and Chinese translations are mostly unreadable.
To get a complete PDF, with the cover and styling of the published editions, download these fonts from Google Fonts:
- Noto Sans
- Noto Sans Arabic
- Noto Sans KR
- Noto Sans SC
- JetBrains Mono
Create a folder named fonts inside the pdf folder and copy these files
into it. In each download they are inside the static folder:
pdf/fonts/NotoSans-Regular.ttf
pdf/fonts/NotoSansArabic-Regular.ttf
pdf/fonts/NotoSansKR-Regular.ttf
pdf/fonts/NotoSansSC-Regular.ttf
pdf/fonts/JetBrainsMono-Regular.ttf
pdf/fonts/JetBrainsMono-Bold.ttf
pdf/fonts/JetBrainsMono-Italic.ttf
pdf/fonts/JetBrainsMono-BoldItalic.ttf
Then create the cover and build with the theme provided in this repository:
$ pdf/make-cover.sh en
$ asciidoctor-pdf -r rouge-raku -a pdf-theme=pdf/theme.yml -a rouge-style=github rakuguide.adoc
make-cover.sh writes the cover for one language. It takes the greeting
shown under the title from pdf/greetings.txt, so run it with the code of
the language you are about to build:
$ pdf/make-cover.sh fr
$ asciidoctor-pdf -r rouge-raku -a pdf-theme=pdf/theme.yml -a rouge-style=github fr.rakuguide.adoc
For the Chinese translation, also pass -a scripts=cjk so that lines wrap
correctly:
$ pdf/make-cover.sh zh
$ asciidoctor-pdf -r rouge-raku -a pdf-theme=pdf/theme.yml -a rouge-style=github -a scripts=cjk zh.rakuguide.adoc
The Japanese translation has its own theme, which draws Japanese text with a Japanese font:
$ pdf/make-cover.sh ja
$ asciidoctor-pdf -r rouge-raku -a pdf-theme=pdf/theme-ja.yml -a rouge-style=github -a scripts=cjk ja.rakuguide.adoc
Add -a revdate="October 2026" to print a date on the cover, and -v to list
characters that are still missing.
The published PDFs are A4. To print and bind the guide, build it with
pdf/theme-book.yml instead. It produces a 7 × 9.25 in (178 × 235 mm) book,
the usual size for programming books:
$ pdf/make-cover.sh en
$ asciidoctor-pdf -r rouge-raku -a pdf-theme=pdf/theme-book.yml -a rouge-style=github -a media=prepress rakuguide.adoc
-a media=prepress lays the pages out for double-sided printing: the margin
is wider on the binding side, every chapter starts on a right-hand page, and
a blank page follows the cover. Leave it out for single-sided printing.
For the Japanese translation use pdf/theme-book-ja.yml, and for Japanese
and Chinese keep -a scripts=cjk.
This gives you the inside of the book with a front and back page. It is not a cover file for a print service: there is no spine, and the artwork does not extend past the edge of the page.
In addition to the tools for the HTML, you will need asciidoctor-epub3:
$ sudo gem install asciidoctor-epub3
To produce rakuguide.epub, run:
$ asciidoctor-epub3 -r rouge-raku -a rouge-style=github -a listing-caption! rakuguide.adoc
-a listing-caption! stops the code examples that have a title from being
numbered as "Listing 1", "Listing 2" and so on.
The published EPUBs use the first page of the PDF as their cover. To do the
same, build the PDF first, save its first page as an image with pdftoppm,
which is part of poppler-utils, and pass that image to the build:
$ pdftoppm -f 1 -l 1 -jpeg -r 200 -singlefile rakuguide.pdf cover
$ asciidoctor-epub3 -r rouge-raku -a rouge-style=github -a listing-caption! -a front-cover-image=image:cover.jpg[] rakuguide.adoc
To check that the result is a valid EPUB, run it through EPUBCheck.
All feedback is welcomed:
- Corrections
- Suggestions
- Additions
- Translations
If you wish to translate this document, always use the English version as your starting point.
If you are starting a new translation create a new file. For example, the French translation will be in fr.rakuguide.adoc, the Deutsch translation in de.rakuguide.adoc
If you want to modify a translated version, consider modifying the English version first. It is important that all translations be kept in sync.
Currently the translations are in different phases of completion. For completeness rely on the English version.
Kindly prefix your commit title with the language it is targeting. For example, all commits targeting the English version would have a title that starts with [EN]. All commits targeting the Spanish translation have a title that starts with [ES].
- Original English version: Naoum Hankache
- French Translation: Romuald Nuguet
- German Translation: Sören Laird Sörries
- Japanese Translation: Itsuki Toyota
- Spanish Translation: Ramiro Encinas
- Portuguese Translation: Breno G. de Oliveira
- Dutch Translation: Elizabeth Mattijsen
- Bulgarian Translation: Красимир Беров
- Chinese Translation: wenjie1991 and ohmycloud
- Italian Translation: MarsMarsico
- Turkish Translation: Yalın Pala
- Indonesian Translation: Heince Kurniawan
- Russian Translation: Alexander Kiryuhin
- Ukrainian Translation: Dmytro Iaskolko
For the full list of contributors: https://github.com/hankache/rakuguide/graphs/contributors
Creative Commons Attribution-ShareAlike 4.0 International License.
To view a copy of this license, visit https://creativecommons.org/licenses/by-sa/4.0/.