This folder contains the AsciiDoc source files of the The Hugo Book.
- HTML Live Preview — The Hugo Book in a single HTML document.
Table of Contents
List of The Hugo Book AsciiDoc sources and contents-assets:
docinfo.html— docinfo file with custom CSS (generated via Sass).warn-editing.asciidoc— a "don't edit me!" notice included in the standalone AsciiDoc build.hugo-book.asciidoc— the main AsciiDoc source file that imports all contents:hugo-book0_preamble.asciidoc— Document Preamble.hugo-book0_colophon.asciidoc— Colophonhugo-book0_preface.asciidoc— Author's Forewordhugo-book1.asciidoc— imports chapters of Book I:hugo-book1_01.asciidoc— 1. Introductionhugo-book1_02.asciidoc— 2. A First Look at Hugohugo-book1_03.asciidoc— 3. Objectshugo-book1_03_object-tree1.svg— SVG object tree example 1 (generated via Dia).hugo-book1_03_object-tree2.svg— SVG object tree example 2 (generated via Dia).hugo-book1_03_object-tree3.svg— SVG object tree example 3 (generated via Dia).
hugo-book1_04.asciidoc— 4. Hugo Programminghugo-book1_05.asciidoc— 5. Routines and Eventshugo-book1_06.asciidoc— 6. Fuses, Daemons, and Scriptshugo-book1_07.asciidoc— 7. Grammar and Parsinghugo-book1_08.asciidoc— 8. Junction Routineshugo-book1_09.asciidoc— 9. The Game Loophugo-book1_10.asciidoc— 10. Using the Object Libraryhugo-book1_11.asciidoc— 11. Advanced Featureshugo-book1_12.asciidoc— 12. Resourceshugo-book1_13.asciidoc— App. A. Summary of Keywords and Commandshugo-book1_14.asciidoc— App. B. The Hugo Libraryhugo-book1_15.asciidoc— App. C. Limit Settingshugo-book1_16.asciidoc— App. D. Hugofix and the Hugo Debuggerhugo-book1_17.asciidoc— App. E. Precompiled Headershugo-book1_18.asciidoc— App. F. Hugo Versionshugo-book1_19.asciidoc— App. G. Additional Resources
hugo-book2.asciidoc— imports chapters of Book II:hugo-book2_01.asciidoc— 13. Introductionhugo-book2_02.asciidoc— 14. Organization of the .HEX Filehugo-book2_03.asciidoc— 15. Tokens and Data Typeshugo-book2_03_tokens-list.csv— CSV list of Hugo tokens for populating the tokens table.
hugo-book2_04.asciidoc— 16. Engine Parsinghugo-book2_05.asciidoc— 17. Grammarhugo-book2_06.asciidoc— 18. Executable Codehugo-book2_07.asciidoc— 19. Encoding Texthugo-book2_08.asciidoc— 20. The Object Tablehugo-book2_09.asciidoc— 21. The Property Tablehugo-book2_10.asciidoc— 22. The Event Tablehugo-book2_11.asciidoc— 23. The Dictionary and Special Wordshugo-book2_12.asciidoc— 24. Resourcefileshugo-book2_13.asciidoc— 25. The Hugo Compiler and How It Workshugo-book2_13_flowchart-compiler.svg— SVG flowchart of Hugo compiler (generated via Dia).
hugo-book2_14.asciidoc— 26. The Hugo Engine and How It Workshugo-book2_14_flowchart-engine.svg— SVG flowchart of Hugo engine (generated via Dia).
hugo-book2_15.asciidoc— 27. Dark Secrets of the Hugo Debuggerhugo-book2_15_flowchart-debugger.svg— SVG flowchart of Hugo debugger (generated via Dia).
hugo-book2_16.asciidoc— App. H. Code Patterns
build.sh— (slow) generates three documents:- The HTML release of the book in the root folder — fully standalone, embedded graphics, syntax highlighted, custom CSS:
- A renamed copy of the HTML release, inside the
../docs/folder, served on the WWW via GitHub Pages: - A standalone AsciiDoc version of the book as a single file, via the
asciidoc-coalescer.rbscript:
preview.sh— (fast) generates a quick HTML preview of the book:preview.html— (ignored by Git) no syntax highlighting, no embedded graphics, use default template.
NOTE 1 — Since the overhead introduced by using the external Highlight tool is considerable on a big document like this one, the
preview.shscript is very handy when editing the document, for it provides a very fast-updating preview of the changes (without syntax highlighting and custom style).Furthermore, the
preview.htmldoesn't embed graphics via data-URIs, so you won't need to rebuild the whole document to view changed images, but only refresh the page since images are loaded from disk.
NOTE 2 — In the future more build scripts will be added, to create other versions of the book in HTML format (e.g. splitting Book I and Book II into independent files, or dividing the book into single chapters for the WWW), as well as targeting other formats (PDF, CHM, ePub, etc.).
The build process depends on further assets stored elsewhere inside this project:
../assets/adoc/haml/— customized Haml templates.../assets/adoc/highlight-treeprocessor_mod.rb— customized Asciidoctor extension to support Highlight.../assets/adoc/hl/— custom Highlight DataDir assets.
These assets are required to introduce support for Hugo highlighting in the Asciidoctor toolchain via the external Highlight tool and our custom syntax definition for Hugo.
In the AsciiDoc sources of the book I've added comments to annotate contents changes, pending tasks, and other points of interest. To simplify looking up these notes via editors S&R functionality, I've adopted a formal convention of comment prefixes:
| comment prefix | indicates |
|---|---|
// @DELME |
Commented-out contents to delete on final release. |
// @EDITED |
Changes to the original contents. |
// @FIXME |
An issue that needs to be addressed. |
// @FOOTNOTE |
An issue regarding footnotes. |
// @HUGO SYNTAX |
Syntax highlighting problems. |
// @NOTE |
Generic note of interest. |
// @TEXT |
Problem or error in original text. |
// @TODO |
A pending task. |
// @XREF |
An issue regarding cross references. |
Often you'll find these prefixes followed by another keyword which narrows down its context. E.g. // @XREF INTERNAL, to mark internal cross references inside tables; // @EDITED TYPO and // @EDITED XREF to distinguish between typo corrections and amended cross references; and so on.
Again, the idea is to use those added words to simplify filtering annotations via S&R, allowing to target specific sets of annotations.
Since annotation prefixes follow an established convention, it's always possible to check if any prefix is present elsewhere in the project, or you're dealing with an isolate issue of that type.
Some of the above prefixes pertain to work in progress which is usually deleted when merging into master branch, while others might be left in the sources for the benefit of other contributors.
In any case, the above system will always be used in development branches, as it simplifies looking up what needs to be done or what is the status for any of the topics associated to these prefixes.
The following tables list all the cross references currently used in The Hugo Book, and the number of times they occur (Qt. column).
For more details on the custom IDs conventions adopted in this book, see
CONVENTIONS.md.
All the cross-references to chapters, appendices and sections:
| Section | Qt. | XRef ID |
|---|---|---|
| The Hugo Programming Manual | 5 | book1 |
| 1.5. Packing List | 1 | sec_1-5 |
| 1.9. Compiler Switches | 1 | sec_1-9 |
| 1.10. Limit Settings | 1 | sec_1-10 |
| 1.11. Directories | 1 | sec_1-11 |
| 2.3. Data Types | 2 | sec_2-3 |
| 3.5. Classes | 1 | sec_3-5 |
| 4.5. Operators and Assignments | 1 | sec_4-5 |
| 4.7. Conditional Expressions and Program Flow | 2 | sec_4-7 |
| 5.1. Routines | 1 | sec_5-1 |
| 5.3. Before and After Routines | 1 | sec_5-3 |
| 7.1. Grammar Definition | 1 | sec_7-1 |
| 7.2. The Parser | 1 | sec_7-2 |
| 8.7. Perform | 1 | sec_8-7 |
| 9. The Game Loop | 2 | chapter_9 |
| 11.1. The Display Object | 1 | sec_11-1 |
| 12. Resources | 1 | chapter_12 |
| App. B: The Hugo Library | 3 | appendix_b |
| App. B.4. Constants | 1 | sec_b-4 |
| App. C: Limit Settings | 1 | appendix_c |
| App. D: HugoFix and the Hugo Debugger | 5 | appendix_d |
| App. E: Precompiled Headers | 3 | appendix_e |
| App. F. Hugo Versions | 2 | appendix_f |
| App. G: Additional Resources | 1 | appendix_g |
| 14.2. The Header | 1 | sec_14-2 |
| 15.2. Data Types | 1 | sec_15-2 |
| 23.2. Special Words | 1 | sec_23-2 |
| 25.2. The Linker | 1 | sec_25-2 |
| App. H: Code Patterns | 2 | appendix_h |
All custom IDs for formal tables, figures, and other captioned block-elements.
| Sec. | Type | Caption | File Ref | XRef ID |
|---|---|---|---|---|
| §2.3 | Table 1 | List of Hugo Data Types | hugo-book1_02# |
table-hugo-data-types |
| §4.1 | Table 2 | Predefined Global Variables | hugo-book1_04# |
table-engine-variables |
| §4.3 | Table 3 | Standard Colors Defined by the Hugo Library | hugo-book1_04# |
table-hugolib-colors |
| §8.1 | Table 4 | Predefined Global Variables and Properties | hugo-book1_08# |
table-engine-globals |
| §8.3 | Table 5 | Default ParseError Responses | hugo-book1_08# |
table-parseerror-responses |
| §14.1 | [Table 6] | Memory Map of a .HEX File | hugo-book2_02# |
table-hex-file-map |
| §14.2 | [Table 7] | Memory Map of a .HEX File Header | hugo-book2_02# |
table-hex-file-header-map |
| §25 | Figure 1 | Flowchart of the Hugo Compiler | hugo-book2_13# |
fig-compiler-flowchart |
| §26 | Figure 2 | Flowchart of the Hugo Engine | hugo-book2_14# |
fig-engine-flowchart |
| §27 | Figure 3 | Flowchart of the Hugo Debugger | hugo-book2_15# |
fig-debugger-flowchart |
| §27.2 | [Table 8] | Memory Map of a .HDX File | hugo-book2_15# |
table-hdx-file-map |
These are the custom inline anchors pointing to specific points in the text:
| File Ref | XRef ID | Qt. | Description | Section |
|---|---|---|---|---|
hugo-book1_04# |
hugolib-colors |
1 | Colors defined by Hugo Library | §4.3. |
hugo-book1_07# |
dynamic-grammars1 |
1 | Dynamic grammars definitions | §7.1. |
hugo-book1_12# |
system_status_values |
1 | system_status return values |
§12.1. |
hugo-book1_14# |
token-case |
1 | Tokens table: case |
App. H |
hugo-book1_14# |
token-if |
3 | Tokens table: if |
App. H |
hugo-book2_05# |
dynamic-grammars2 |
1 | Dynamic grammars definitions | Ch. 17 |
In order to convert The Hugo Book to HTML you'll need to install the following tools on your system:
- AsciiDoctor (Ruby) and the following Ruby gems:
- concurrent-ruby
- haml
- tilt
- Highlight
This project was build by its maintainer under MS Windows 10 x64, using:
- Asciidoctor 2.0.10
- Ruby 2.7.0p0
- Highlight 3.54
The Travis CI build tests the project against the latest stable versions of these packages, to ensure that any compatibility breaking updates are caught in time.
[Table 6]: https://tajmone.github.io/hugo-book/#table-hex-file-map"Live HTML Preview of captioned Table" [Table 7]: https://tajmone.github.io/hugo-book/#table-hex-file-header-map"Live HTML Preview of captioned Table" [Table 8]: https://tajmone.github.io/hugo-book/#table-hdx-file-map"Live HTML Preview of captioned Table"