For consistency sake, in all Hugo code examples:

• Decide how many spaces to use for indentation:
  • Use four spaces.
• Enforce the chosen indentation on all code blocks.
• Styling Conventions document:
  • Mention the default indentation width adopted.
  • Mention Library sources having eight-space indentation.
  • Mention the couple exceptions for print strings spanning multiple lines.

Right now I've been using either two- or four-spaces for indentation.

Further Questions to Decide

• The Hugo Library adopts eight-space indentation.

  • Excerpts from Hugo Library sources should preserve the original indentation.

  Adopting the latter doesn't break EditorConfig validations because it's a multiple of four.

• Some code examples where strings are split across multiple lines would look nicer if the text was aligned with the first character, instead of the double-quotes. E.g.:

  print "It was a dark
         and stormy night."
  

  • Allow this in two places, to show that it can be done if one wishes to.

NOTE — This didn't break EditorConfig validations because AsciiDoc was set to indent_size = unset (exactly to prevent this type of issues).

Convert Ascii-Art diagrams to SVG images.

• In §3.2. The Object Tree:
  • Example 1.
  • Example 2 (player seated).
  • Example 3 (bowl in player).
• Flow-charts:
  • In §25. THE HUGO COMPILER AND HOW IT WORKS.
  • In §26. THE HUGO ENGINE AND HOW IT WORKS.
  • In §27. DARK SECRETS OF THE HUGO DEBUGGER.

EDIT — the SemVer scheme will refer only to the AsciiDoc sources!

We need to decide upon a version scheme for this project, to be associated with release tags on GitHub. The question is rather complex because an update in the project might be due to different reasons.

Here's some brain storming on the issue...

Technically speaking, there are various versions at stake in this repository:

• Book edition.
• AsciiDoc sources revision.
• Template(s) revision.
• Converted book(s) version, in various formats.

As for the Hugo Book edition, it refers to the last time the book contents where changed by its original author. I.e. that would be the First Edition.
The edition date might also be taken into consideration here, which in the PDF book is 2004, with the Word document being last edited in 2018-10-04 — although we might consider changing the date to that of the 1st release of this project, due to the small contents changes that were done with the author's supervision.

In any case, the book edition raises the general question of if and how further contents changes should be handled — although I think that this repository should aim at preserving the last edition by the original author, without further contents changes (these should be done in forks of this project, not here).

So, we could assume that the book edition is unlikely to change in the future, and treat First Edition as an immutable constant in the version scheme (regardless of whether the 2004 date will be preserved, or 2019 adopted).

The AsciiDoc sources revision is the primary focus of the version scheme, for it refers to source code files, and therefore well suited to adopt a scheme like SemVer 2.0.

Templates and pre-converted documents are more complex, for obvious reasons. For example, the HTML template might be updated to improve visual styles, leading to a quite different output document.

• Should this updated HTML document carry a different revision mark?

On the one hand, its contents are unaltered, but on the other hand its visual presentation might be drastically changed. End users focusing on obtaining always the latest document in a given format might wish that it bore some revision mark that allows distinguishing which one of two diffing documents is the latest release.

Since in the future this project might host a variety of output formats other than the current single-file HTML5 document, the issue of providing a good revision scheme should not be underestimated — for it might soon lead to confusion and version entanglement.

From a practical point of view, some third party projects might wish to point to specific tags of this repository to integrate its AsciiDoc source in their project (e.g. an IF documentation project, where the Hugo Book is just one of many AsciiDoc documents). In similar cases release tags are extremely important to allow targeting specific versions of the project (i.e. versions tested to be compatible with the importing project) by means of Git submodules inclusion, or even downloading specific files via cURL and exploiting raw.githubusercontent.com URIs that leverage tags instead of branches.

The same might be true for third party projects aiming to download specific versions of the pre-converted documents — although it's most likely that they'd be just targeting master branch, which always contains the latest release of all converted documents.

Clearly, version schemes like SemVer 2.0 can't pack all these different revisions information into a single semantic value. So the question is whether we should devise a custom scheme that can contain all these different version in a single string that would intuitively deliver clear information as to which version is the latest one, or whether we should focus only on the AsciiDoc source revisions.

It's important to note here that having release tags focusing only on ADoc sources would preclude tag-based checkouts and downloads to benefit from template updates in the importing projects — i.e. unless the whole project version moves forward whenever something changes in either one of the four independent elements (book version, ADoc sources, templates, converted docs).

This latter solution might introduce too many release tags, where projects targeting the ADoc sources would not benefit from most version bumps because updates to the various templates and pre-built documents are going to be more frequent than changes to the ADoc sources.

From these considerations, it's clear that the order in which the various elements at play were presented in the list at the beginning of this post do in fact reflect the natural order of changes propagation: any changes to the book edition (i.e. author contents) would affect the version of all other elements, whereas the reverse is not true (i.e. changes in a template will only affect its output document, without requiring a version bump in the element that precede it in the list).

Ultimately, it's a question of deciding whether the heart of this project are the AsciiDoc source file or the format-specific converted documents. I lean toward the ADoc sources, considering the pre-converted documents just an added bonus — the purpose of this project being the preservation of The Hugo Book in a format-agnostic format, where contents and styles are totally separated.

But, even if sticking to SemVer and the AsciiDoc sources only, we'd need to work out how to convey all these different revision aspects in the converted documents (as mentioned above) so that end users will always be able to tell which one of two documents is the most recent one.

References

• https://semver.org — Semantic Versioning 2.0.0.
• GitHub Help » Managing releases in a repository

Must find a good way to produce an HTML version of the book split by chapters (chunked HTML) while preserving cross references, a TOC for each chapter and a general TOC for the whole book.

See:

• https://github.com/owenh000/asciidoctor-multipage (Asciidoctor <= v1.5.7.1)
• asciidoctor/asciidoctor#626

Fix all XRefs present in The Hugo Book, using the generated auto-ID.

• BOOK I. THE HUGO PROGRAMMING MANUAL
  • 1. INTRODUCTION
  • 2. A FIRST LOOK AT HUGO
  • 3. OBJECTS
  • 4. HUGO PROGRAMMING
  • 5. ROUTINES AND EVENTS
  • 8. JUNCTION ROUTINES
  • 12. RESOURCES
  • APP. A. SUMMARY OF KEYWORDS AND COMMANDS
  • APP. B. THE HUGO LIBRARY
• BOOK II. TECHNICAL SYSTEM SPECIFICATION
  • 13. INTRODUCTION
  • 14. ORGANIZATION OF THE .HEX FILE
  • 16. ENGINE PARSING
  • 17. GRAMMAR
  • 18. EXECUTABLE CODE
  • 21. THE PROPERTY TABLE
  • 27. DARK SECRETS OF THE HUGO DEBUGGER
  • APP. H. CODE PATTERNS
• Other xrefs pointing to inline anchors.

NOTE 1 — Generated auto-IDs won't have a leading underscore due to :idprefix: being unset in the header.

NOTE 2 — This might not be the best solution for handling chuncked documnets, due to some sections sharing the same titles (e.g. "Introduction", or "Limit Settings").

But it will do for now, since we're building just a single HTML document. In the future we need to manually customize every cross-referenced ID (see #26) for consistency sake and to ensure that xrefs will work also on split-chapter contents, like website, CHM, etc.

@tessman, in App. E. "Precompiled Headers", the book mentions the hugolib.hug file:

The file hugolib.hug serves as a good example: it is a small wrapper which compiles the standard Hugo Library. Compile it via

hc -h hugolib.hug

I couldn't find the hugolib.hug file in any version of the Hugo Library from the IF Archive.

What happened to this file? Is it still available, or was it removed from later distributions of the library?

Fixed some obvious of typos.

• Get @tessman approval for these changes.
• Fix document source.
• Document the changes in CHANGES.md.
• Update commented annotation in source file.

1. In §1.5. Packing List:

   Additionally, you're probably want to download shell.hug,

   "you're" was changed to "you'll":

   Additionally, you'll probably want to download shell.hug,

2. In Appendix A, regarding the syntax of print <output>:

   where <output> can consist of both test strings enclosed in quotation marks ("…​"), and values representing dictionary addresses

   "test strings" was changed to "text strings"

To keep cross references brief in the text, it would be nice to use the § section sign instead of the current "Sec." signifier, in order to output xrefs like:

See §5.3, "Customing Text" for more details.

Unfortunately this is currently unachievable due to space insertion after the section-refsig string attribute, and there's no way to inform Asciidoctor that the user-defined section-refsig shouldn't be followed by a space. Therefore, attempting this:

:section-refsig: §

actually produces:

See § 5.3, "Customing Text" for more details.

where the unwanted space between the § and the section number is both incorrect and hugly.

But this should soon become possible, if either my feature request (asciidoctor/asciidoctor#3498) is accepted, or when the upcoming features proposed in asciidoctor/asciidoctor#2212 are implemented.

So we only have to wait and keep an eye open on when this becomes possible in future Asciidoctor releases.

References

• Wikipedia » Section sign
• Asciidoctor Manual » §27.5. Customizing the Cross Reference Text
• asciidoctor/asciidoctor#3498 — Allow Custom :section-refsig: without Trailing Space
• asciidoctor/asciidoctor#2212 — Add support for a custom formatting string in the xrefstyle attribute

The upcoming Asciidoctor v2.0.11 release will introduce a new feature allowing to include:: external files in encodings other than UTF-8 (see asciidoctor/asciidoctor#3248 and mojavelinux/asciidoctor@4c008b00).

When this release is out, we could externalize some code examples to actual Hugo source files — especially the exercises in the various What Should I Be Able to Do Now? sections, as well as Hugo Library snippets and long examples. Of course, that is if these code blocks don't contain extra AsciiDoc elements (footnotes, call-outs, etc.).

This could also allow the project to actually test the source files against Hugo compiler, and even automatically produce their output transcripts (i.e. via a CLI Hugo terp that can accept solution files and generate transcript logs).

These changes would also simplify future maintenance of the book, especially so if the Hugo Library is further developed, for by including its snippets directly from the library source would grant that the Hugo Book always mirrors the latest version of the Hugo Lib.

For more info see:

• Asciidoctor Issue #3248 — Allow Inclusion of non-UTF-8 Files.
• Asciidoctor commit 4c008b00 — allow encoding of include file to be specified using encoding attribute

Possible error found: "room" instead of "door".

• Get @tessman approval for these changes.
• Implement change in sources.
• Document the changes in CHANGES.md.
• Update commented annotation in source file.

In §10.5. Doors we read (UPPERCASE+BOLD added):

The between property takes care of making the ROOM available in both locations as well as determining where the player travels to when leaving either location.

My impression is that the intended text might have actually been:

The between property takes care of making the DOOR available in both locations [...]

For it would make more sense.
I didn't touch the original text (that would be tampering, not editing), but I wanted to propose the above change.

Before merging into master branch for the 1st book release, remember to update all Live HTML Preview links in the various MD documents, so they point to master branch instead of draft.

The last pending tasks of the AsciiDoc porting stage.

• Read whole book again, from beginning to end, to ensure that everything looks fine and keeping an eye for anything that needs to be changed, fixed or improved.

• The following sections need to be thoroughly re-examined and compared with the original Word/PDF edition:

  • APP. A. SUMMARY OF KEYWORDS AND COMMANDS
  • APP. B. THE HUGO LIBRARY
  • APP. C. LIMIT SETTINGS
  • APP. D. HUGOFIX AND THE HUGO DEBUGGER

  They might also benefit from some extra styling to enhance readability (especially the long tables where entries could be coloured), and adding captions to tables and images.

See also:

• All Issues relating to the porting stage

In §5.3. Before And After Routines, toward the section end, there is a paragraph where some text seems to have gone lost:

A drawback of this non-specification [...] even for save, restore, etc. (i.e.,

No meaningful text seems to follow that (i.e.,, which is left hanging there.

It's not the usual note-in-parenthesis which runs across multiple paragraphs; beside a missing closing parenthesis, what follows doesn't seem to provide a context to the previous sentence.

I've also checked the other PDF version, from the IF Archive, and it's the same.

I'm prone to think that the (i.e., is either some leftover text after a deletion, or that what followed went accidentally lost during editing.

My guess is that the missing text was a clarification of the implications of a non-specific before/after block on meta-verbs like save and restore; or something along those lines.

• Find a solution for this problem. Either:
  1. Retrieve the lost text from a previous edition of The Hugo Book.
  2. Ask @tessman is he's willing to amend the missing text.
  3. Eliminate (i.e., from the paragraph.
• Amend text: (i.e., → (i.e., xverbs)..
• Approval by @tessman.
• Document the change in CHANGES.md.

• When upcoming Asciidoctor feature for "block-level content" table cells becomes available, replace all a-styled cells with new b style. (See asciidoctor/asciidoctor#2352)

When footnotes occur in tables, inside a cell styled as a (AsciiDoc), then the footnote will be created at the end of the cell. This happens because AsciiDoc cells are treated as embedded AsciiDoc documents.

NOTE 1 — Nevertheless, footnotes numbering is preserved inside table cells, without breaking the general numbering order.

Although in some cases this might be acceptable, there are tables which contain multiple notes with the same text, which could be externalized as a single footnote — but this would look ugly because they'd appear as a single note pointing to another cell — unless that cell could be styled as d (default), which is fine if any of these cells doesn't require the AsciiDoc style.

My main concern is having to deal with tables where some notes are placed at the bottom of the cell, while others at the bottom of the section (i.e. in HTML docs). I'd rather have a consistent style throughout the book.

The most significant example of this is Appendix H: CODE PATTERNS, which contains 11 footnotes, all inside table cells, 9 of them being also inside a code-block, and many of the being duplicate.

NOTE 2 — Although Asciidoctor allows to reuse a same note more than once, keep in mind that clicking on the footnote link will jump to the note text, but the back-link of the footnote number will only jump back to the first occurrence of that note — which could be a problem for the reader, who will loose track of where he was.

I need to consider if it's worth sharing the same footnote or if it's better to just create a shared attribute containing the same text, to avoid repetition of contents but preserve the redundant footnote, so each has a correct back-link. (This would still introduce a DRY element in the workflow).

References

• Asciidoctor Manual » §61. Footnotes:
  • §61.1. Externalizing a Footnote

Hugo highlighted code: false positive escapes and interpolations in filepath strings.

• Temporary CSS workaround:
  • Create .noescapes class to color escapes and interpolations like strings.
  • Add noescapes role to all code blocks where the problem occurs.
• Fix the Hugo syntax for Highlight.

The Problem

Currently, the HL Hugo syntax looks for escapes and interpolations inside all strings, which is a problem when dealing with filepath strings containing Windows paths, where the backslash dir separator can lead to false positive escape sequences and special characters (interpolations in HL syntax).

An example of this can be seen in §12.1 (commit 37d44a0), before the CSS patch (click here for current view):

resource "GAMERES1"
{
    "c:\hugo\graphics\logo.jpg"
    "h:\data\scenic panorama.jpg"
    "h:\data\background.jpg"       <- \b highlighted as "bold end"
    "c:\music\intro_theme.s3m"     <- \i highlighted as "italic end"
    "c:\music\theme2.xm"
    "c:\sounds\sample1.wav"
    "c:\sounds\sample2.wav"
}

While the syntax was already fixed to prevent escapes and interpolations inside compiler directive strings for #include and #link, fixing the above problem is turning out trickier than expected.

I need to find a way to distinguish between text- and path-strings, by introducing some state tracking variable after keywords like resource, image and all other keywords which are followed by a filepath string.

So far, all attempts in this direction failed (i.e. they didn't work for multiple strings, like in the above example).

Real tests for this can be found on the Hugo dev branch of the Highlight Test Suite on GitLab:

• syntax_test_filepaths-include.hug
• syntax_test_filepaths-resources.hug

A Quick Workaround

As a temporary solution, I can create a .noescape CSS rule that colors escape sequences and interpolations with the same color as strings, effectively hiding the problem to the eye.

Missing $ in Unix shell example: 'list' -> '$list'

• Get @tessman approval for these changes.
• Fix document source.
• Document the changes in CHANGES.md.
• Update commented annotation in source file.

In §1.10. Limit Settings, inside the important admonition block, we read:

Users of Unix or similar systems (including OS X, BeOS, and others) may, depending on the shell being used, need to escape special tokens like $ or enclose these arguments in single quotes (e.g. \$list and \$<setting>=<new limit> or 'list', '$<setting>=<new limit>', etc.) to override the shell's parsing of those tokens in the compiler invocation line.

Where there was a missing $ in "'list'", which I've fixed to:

(e.g. \$list and \$<setting>=<new limit> or '$list', [...]

• Fix SCSS/CSS colour styles for footnotes in:
  • Hugo code blocks (source,hugo)
  • Hugo syntax blocks (literal,role="hugosyntax")
• Verify if there are footnotes in CMD listings (none found).

Footnotes links inside code blocks need to assigned custom CSS styles to make their colour stand out from the dark background.

For an example in Hugo source examples, see §2.3. Data Types:

<some variable> = <some value>[8]

where the [8] is styled as:

<sup class="footnote">[<a id="_footnoteref_8" class="footnote" href="#_footnotedef_8" title="View footnote.">8</a>]</sup>

• POSTPONED — This enhancement is postponed after the 1st release of the book.
• UNCOFIRMED — Still needs testing and evaluation before giving the green light.

Hugo Syntax definitions are not syntax highlighted, they are just literal blocks (see #35) with a custom role (literal, role="hugosyntax") to allow custom styling via CSS (or other means, in different output formats).

The block is styled using the Base2Tone Lake colour scheme by Bram de Haan, which provides 4 base hues available in eight tints variations. Currently we are using just two colours: background and foreground.

We could enhance Hugo syntax definitions by using different colours for keywords, parameters. comments and surrounding code, as well as the various token indicating optionality ([]), alternatives (|) and omissions (...).

But this would require manual implementation by using a combination of bold, italic and custom styles via the [style]#text# notation — or even exploiting classes on bold and italics via the [.style]*text* notation (See §10.5.6. Role » Inline Assignment in Asciidoctor Manual).

It's important here to think carefully on how the document will be rendered by other people targeting different formats or using different templates. The final document must look nice independently of the template and stylesheet employed. Therefore, it's better to use a styling notation that would not affect the visual appearance of the document in other toolchains, but at the same time use a system that allows to enforce these intended styles also across other formats and backends.

Possibly, using bold for styling the keywords that are central to the syntax definition (or syntax example) should be acceptable for it would always provide an acceptable styling across al formats and templates.

As for customization of the additional symbols for optionality, etc., it might be wiser to use custom roles that would not affect visually those elements in non-dedicate templates, just to be on the safe side.

I need to experiment with this first.

• Get @tessman approval for these changes.
• Fix document source.
• Document the changes in CHANGES.md.
• Update commented annotation in source file.

In App. B.7. Utility Routines, Etc., in the definition of the ObjWord Library routine there was a missing word:

calling form:

ObjWord(word, object)

Returns either adjective or noun (i.e., the property number) if the given is either an adjective or noun of the specified object.

I've added "word" after "if the given":

if the given word is either an adjective ...

Publish The Hugo Book on the WWW via GitHub Pages using the docs/ folder on master branch.

• Merge draft into master.
• Activate GH Pages via docs/ folder on master branch.
• Replace Live HTML Preview links with links to the new on-line book.
• Create Git.io vanity URL: hugo-book.git.io.

Add to the Travis CI build the AsciiDoc toolchain:

• Install Highlight.
  • There are a few problems to solve here, for the Linux packages mentioned in the official HL documentation are either no longer available or very old versions:
    • Find a way to always clone the latest stable release:
      • Now master branch contains only tagged release versions and it's safe to clone it (See highlight/#136).
    • Build Highlight CLI from sources.
    • Install Highlight system-wide on the Travis machine.
    • Verify that these steps don't take too long on Travis CI.
• Install Asciidoctor.
• Build a custom build script to execute all tasks.

POSTPONED — This fix is postponed after the 1st release of the book.
(the current workaround works fine for the HTML book)

After a Hugo code block starting with an indentation is processed by Highlight, the indentation on the first line is lost.

• Fix all occurrences in current sources using the {wj} workaround (see below).
• Try to find a real solution to this problem:
  • Update the Haml listing template with v1.1.0 used in the Alan-Docs project: alan-if/alan-docs@aa8fb65
  • Remove all the {wj} previously added for the temporary workaround.

Since this happens only in the first line of code, it could be either:

1. A problem with the Haml template.
2. A problem with the Sass/CSS stylesheet.

For an example, see:

• 5.4. Init And Main (a106ed8).

In order for the build HTML book to be viewable on GitHub Pages it should be named index.hml. This requires some changes in the build toolchain.

• Change docs_src/build.sh so that:
  • it builds the HTML doc in ../hugo-book.html (root folder).
  • Copies of ../hugo-book.html to docs/index.html.

The above will ensure that the root folder of the repo will contain both the AsciiDoc preprocessed version of the book as well as its HTML version properly named:

• hugo-book.asciidoc
• hugo-book.html

This is what most users will expect, so it justifies having a redundant copy of the HTML book in docs/, because the file named index.html is only useful for the website.

Fix token: replaced / with \.

• Get @tessman approval for these changes.
• Document the changes in CHANGES.md.
• Update commented annotation in source file.

In §2.4. Multiple Lines, inside a tip admonition on how to preserve a double space when splitting a string over multiple line, the original text wrote:

since normally, if the / were omitted after “…​on one line.”,

which I changed to:

since normally, if the \ were omitted after “…​on one line.”,

for it looked at obvious typing mistake.
(note that I've added also a leading space before the backslash, on purpose.)

Customize all Section IDs.

• Choose a standard naming convention for:
  • Parts — Books I/II <h1>.
  • Chapters — <h2>.
  • Appendixes — <h2>.
  • Sections — <h3> to <h4>.
• Document it in CONVENTIONS.md
• Replace every auto-generated ID in the book with a custom ID:
  • Parts.
  • Chapters Titles.
    • Level 3 Chapters Subsections.
    • Level 4 Chapters Subsections.
  • Appendices Titles.
    • Level 3 Appendices Subsections.
    • Level 4 Appendices Subsections.
• Fix all existing xrefs, using the new ID.
• Fix Live HTML Preview links in docs_src/README.md

NOTE 1 — In order to preserve anchors consistency across the book, define custom IDs for all chapters, sections and appendices titles.

NOTE 2 — After these changes, all existing Live HTML Preview links to the book inside Issues will be broken. I'll try to fix them in all open Issues as I handle them.

References

• Asciidoctor Manual:
  • §16. Sections
    • §16.1. Titles as HTML Headings
    • §16.2. Auto-generated IDs

POSTPONED — This problem should really be fixed on Asciidoctor, not here.

Fix a security issue in Asciidoctor default HTML5 template, unless the problem is fixed before The Hugo Book is publicly released.

I've just discovered that the HTML5 template is vulnerable to CSRF attacks (Cross-site request forgery) due to lack of the SameSite attribute for cross-site cookies settings, and opened an Issue for this (see asciidoctor/asciidoctor#3496).

If the problem is not fixed before the book is released, I should fix this by adding a custom Haml template or inject a fix in the HTML header.

References

For a detailed introduction to the nature of the CSRF attack problem, and its solution, see:

• asciidoctor/asciidoctor#3496 — HTML5 Template Vulnerable to CSRF Attacks
• SameSite cookies explained, by Rowan Merewood.
• Chrome Platform Status » Cookies default to SameSite=Lax
• Chrome Platform Status » Reject insecure SameSite=None cookies

Fixed malformed sentence due to editing accident (scrambling).

• Get @tessman approval for these changes.
• Document the changes in CHANGES.md.
• Update commented annotation in source file.

In §10.6. Vehicles the original text seem to have been accidentally damaged (LL 356):

It is also necessary to provide grammar to relate the words in the vehicle_verb list to the object library's DoMoveInVehicle routine.Grammar he following is recommended:

And I've fixed it to (LL 395):

It is also necessary to provide grammar to relate the words in the vehicle_verb list to the object library’s DoMoveInVehicle routine. The following grammar is recommended:

which seemed the most obvious fix, and assumed that some selected words were accidentally moved around in the original document while editing.

• Turn every occurrence of Hugo syntax definitions into a literal, role="hugosyntax" block.
• Sass/SCSS — Define custom CSS to handle:
  • Background, foreground and border (none) colors.
    • Choose better colors: Base2Tone Lake.
  • Footnote marker color (so it doesn't get mistaken for arrays [n])

Don't syntax highlight Hugo syntax definitions blocks, because the presences of extra symbols (<param> () [] | ...) doesn't work well with the highlighter. Instead, use a literal block with a custom role for styling.

This way, it will also be easier to distinguish between real Hugo code and syntax definitions.

Color Scheme for Syntax Blocks

The current colors are just temporary; I need to find two colors that fit well with the rest of colors in the document, especially with Hugo code (should contrast it, possibly by adopting a light scheme).

I've now adopted the Base2Tone Lake by Bram de Haan.

Syntax Enhancements

For a proposal to further improve Hugo syntax definitions and examples, see #41.

How to handle identical footnotes?

In various places of the book there are identical footnotes.

• Decide which way to handle them:
  1. Treat them as independent footnotes.
  2. Share same footnote.
• Check the whole book to ensure there are no footnotes set to be shared
  (there are two in the CSV-base table for sure, but these should be the only ones, left there for testing purposes.)
• Discuss it with @tessman.

The former, has the advantage that each independent note has it's own back link to return to the original position where it was encountered, but it produces extra footnotes.

The latter, produces less footnotes but might interrupt reading of the book because once the reader clicks on a footnote (and jumps to the end of the HTML document) there will be a single footnote for all the same-text footnotes, which means that the backlink will be pointing to the first of such notes, instead of returning to the original positions where the note was encountered.

Right now, I'm handling identical notes by defining their text in a shared attribute, which is then injected into each note.

If we decide to adopt the former solution, I'll need to fix them and define a single note with an ID and then reuse the same attribute with all identical notes:

:fn1: footnote:note1[shared footnote text.]
:fn2: {fn1}
:fn3: {fn1}

List of Identical Footnotes

Identical footnotes are found in:

• Book I:
  • §8. JUNCTION ROUTINES: 42-44, 46.
• Book II:
  • §15. TOKENS AND DATA TYPES: 66, 67 (inside CSV file populating table)
  • App H: CODE PATTERNS: 73-77, 80-82 (all inside table)

NOTE 1 — the above list might still be incomplete. I'll update the list as I encounter them.
Since in the HTML document all footnotes are shown as endnotes, it's easy to jump at the end of the document to see how many identical notes there are.

NOTE 2 — Identical footnotes are marked in the source with comment lines:

  // @FOOTNOTE SAME TEXT

References

• Asciidoctor Manual » §61. Footnotes

Adapted text of cross reference: use section number instead of page number.

• Get @tessman approval for these changes:
  • Is the xref link pointing to right place?
• Fix document source.
• Document the changes in CHANGES.md.
• Update commented annotation in source file.

In App. A: Summary of Keywords and Commands, the cross reference text to a specific page number:

Standard color values for <foreground> and <background> with constants defined in hugolib.h (see page 64) are:

was changed to the section number instead:

Standard color values for <foreground> and <background> with constants defined in hugolib.h (see Sec. 4.3) are:

where "Sec. 4.3" is a link pointing to relevant paragraph on the topic.

This was necessary because not all output formats have page numbers (HTML documents, ePub, CHM Help files, etc., either don't have real page numbers or can't handle them well in cross references).

• Fix Hugo syntax handling of preprocessor directives.

Currently, the Highlight syntax is set to capture any token starting with # as a preprocessor directive (up to the end of the line).

This interferes with the use of # token used to find out the number of properties, as in:

<object>.#<property>

An example of how this disrupts highlighting can be found in §10.2. Characters:

print capital object.pronoun; " opened "; object.pronoun #3; " box. "

Where from #3; onward the rest of the line is treated as preprocessor directive, and " box. " as a preprocessor string.

This can be fixed by using a dummy keyword group to capture all preprocessor directives by RegEx pattern, and then use OnStateChange() function to enforce them as preprocessor directive. Doing so, it will allow to also define # as an operator.

Currently the AsciiDoc port of The Hugo Book has no Index, because it only affects DocBook/PDF format.

At some point in the future, it would be good to rebuild the original Index of the book, for the sake of PDF editions; also, there might exist extension to add index-support to the HTML5 backend, so it's worth looking into it.

• INDEX (supported only in PDF format):
  • Rebuild original Index of the Word/PDF edition.
  • Try to find an extension to add index-support to the HTML5 backend.

Enforce consistent title-casing using the conventions of The Chicago Manual of Style (CMS) on all:

• Chapters and Appendices titles.
• Sub-Sections titles.
• Captions (tables, images, etc.)

NOTE — Currently all Level 1 Headings are in all-caps, which has a rather strong impact. Since custom styles can always be employed to force all-caps on any title level, it's better to adopt consistent title casing across all titles, and let end user decide if they want to enforce all-caps in their own builds.

Online Tools

My favourite online tool to quickly correct title casing is:

• https://capitalizemytitle.com

Of course, some special keywords will require manual case-adjustment.

Links

• www.chicagomanualofstyle.org — official website.
• Wikipedia » The Chicago Manual of Style

POSTPONED — This potential improvement is postponed after the 1st release of the book.

Try using for game transcript blocks the default colour scheme of the Hugo interpreter.

Its colours are a bit intense and darkish but, if they don't clash excessively with the overall colours of the book, it would be preferable to use the colours of Hugo's native terp, for they'd look more familiar to the reader, and also give an extra touch of «Hugoness» to the overall publication.

• Get @tessman approval for these changes.
• Fix document source.
• Document the changes in CHANGES.md.
• Document custom anchors in docs_src/README.md.
• Update commented annotation in source file.

Because dynamic grammars are only briefly mentioned in the book, I've added custom anchors in the two places where they are discussed, and added a cross reference side note in the corresponding sections, linking them to each other:

• In §7.1. Grammar Definition, I've added a TIP admonition block:

  For more details on dynamic grammars, see the Grammar chapter in Book II.

• In Ch. 17. Grammar, I've added a note within parenthesis:

  (See also Book I on dynamic grammars.)

I hope you don't mind me having done so — but the topic is not easy to grasp, and being able to read both sections that deal with dynamic grammars really helped me grasping it better; so I thought that adding these cross references would greatly help the reader. After all, the topic is only discussed in those two places in the whole book, and rather briefly too, so I thought that it might justify adding these side notes.

Being these changes just an admonition block and a note within parenthesis, they might qualify as "editorial changes", rather than real contents edits (what is often referred to as side-bars in digital documents), like editors' footnotes — I had thought of adding them as footnotes, but it would have lessened their utility value.

Of course, this is a little beyond mere historical preservation, and I'd perfectly understand if you reject these changes, or if you demand that they might be confined to footnotes. But since Hugo binaries are still available and operative, small changes that could make the learning process could be considered as beneficial too.

Preliminary steps for peparing the publication of the The Hugo Book on the WWW via GitHub Pages using the docs/ folder on master branch.

• Tweak docs_src/build.sh to output HTML doc in docs/ folder instead of docs_src/.
• Update all links in project documentation.

At this point we'll have to wait for the last stage when the repository is merged into master branch to carry out the last steps (Issue #44), because GH Pages website can only be served from master branch with these settings.

NOTE — After the above changes, all the Live HTML Preview links in the Issues will stop working due to the HTML doc being moved to another folder!

WIP WARNING — This list of pending tasks is still incomplete and will be constantly updated to mirror the current progress status and until the project reaches its first tagged release.

We're heading toward 1st Release of the project and need to wrap up all pending tasks before merging into master branch.

• project boards: Porting  1st Release

The task list below presents all relevant open Issues in a meaningful order, with comments, as well as introducing new tasks for which there is no separate Issue, and will be constantly updated to mirror the current progress status.

This will be the last standing open Issue for the 1st Release project, and shall be closed when the book is publicly released.

Blocking Issues

The following Issues are awaiting for @tessman approval 🕑 pending approval before they can be fully integrated in the project and closed:

• Book Metadata (Issue #51) — needs checking if the info is OK.
• §7.1 & Ch17: Add Cross-References to Dynamic Grammars (Issue #48).
• B.7: Missing Word in Hugo Lib Definition (Issue #47).
• Conflicting Legal Information (Book vs BSD-2) (Issue #2) — WIP, just need confirmation it's OK once ready.
• §9.2: Code Errors in Strings (Issue #38).
• Ch 12: Adapt Syntax Definitions (Issue #36).
• §10.6: Hard to Read Sentence (Issue #30) — optional, sentence improvment.

Pending Tasks

• UNRESOLVED QUESTIONS
  • Release Version Scheme (Issue #31) — still need to decide how to handle updates using a scheme able to distinguish between changes to actual contents vs presentation and styles, and between changes to backend-specific templates vs AsciiDoc sources.
• BOOK CONTENTS, FORMATTING & STYLES
  • Porting Stage: Final Tasks (Issue #46) — last minute checks to ensure the AsciiDoc porting stage is definitely over.
  • Colophon:
    • Needs some custom CSS styles for better formatting.
    • Original pubblication data like ISBN might need to be contextualized as being for historical reference (for it does't apply to this digital edition).
  • Books Alt-Titles — the "OR ..." part that follows the main Book title requires custom styles/roles to enlarge the font face and size so it's similar to the main title but slight smaller, possibly with a different color but not black:
    • Add [.text-center.big.ortitle] and customize CSS:
      • Book I — "or How to Write Games and Influence People"
      • Book II — "or Under the Hood of Hugo and the .HEX File Format"
    • Document this custom style either in docs_src/README.md or in CONVENTIONS.md
  • Captions — we should take advantage of Asciidoctor features for handling captions in figures and tables. Although the HTML backend doesn't provide an automatically generated list of all the book figures and tables, other backends do (or might), and it might be possible to find or create an extension to do it in HTML too. Besides, captions aid the reading experience and provide auto-generated anchor IDs for direct linking to the figure/table.
    • Tables Captions — not every AsciiDoc table in the book is a table in the true sense, i.e. some tables are being used just to provide better formatting of some contents, but not qualify as a table in respect to the original document.
      • §2.3: Table 1. List of Hugo Data Types (table-hugo-data-types)
      • §4.1: Table 2. Predefined Global Variables (table-engine-variables)
      • §4.3: Table 3. Standard Colors Defined by the Hugo Library (table-hugolib-colors)
      • §8.1: Table 4. Predefined Global Variables and Properties (table-engine-globals)
      • §8.3: Table 5. Default ParseError Responses (table-parseerror-responses)
      • §14.1: Table 6. Memory Map of a .HEX File (table-hex-file-map)
      • §14.2: Table 7. Memory Map of a .HEX File Header (table-hex-file-header-map)
      • §27.2: Table 8. Memory Map of a .HDX File (table-hdx-file-map)
    • Figures Captions:
      • §25: Figure 1. Flowchart of the Hugo Compiler (fig-compiler-flowchart)
      • §26: Figure 2. Flowchart of the Hugo Engine (fig-engine-flowchart)
      • §27: Figure 3. Flowchart of the Hugo Debugger (fig-debugger-flowchart)
• PROJECT DOCUMENTATION
  📚 documentation
  • CHANGES.md:
    • Document Contents Changes (Issue #11).
  • README.md:
    • Polish document for public release.
  • docs_src/README.md:
    • Move all TODOs to Issues.
    • Polish document for public release.
• GITHUB PAGES WEBSITE — The book will also be available for online reading via GitHub Pages. This requires a two-steps setup, the last one being handled after merging into master (Issue #44):
  GitHub Pages  🔨 GitHub Pages
  • Move HTML Book to "docs/" for GitHub Pages Setup (Issue #43).
  • Rename HTML File in "docs/" Folder (Issue #49).
• PRE-MERGE CHORES — things to be done right before merging into master branch, mostly related URL changes resulting from branch switching.
  🕑 on 1st release
  • Fix Live HTML Links (Issue #9).
  • Fix Travis CI Badge URL (Issue #8).
  • Publish Book on WWW via GitHub Pages (Issue #44).
  • Post-Merge Chores (Issue #52).

Before the 1st release on master branch:

• Create a markdown document listing all the significant changes.
  • Done: CHANGES.md
• Ask Kent for confirmation that he agrees with them.
• Roll-back any unapproved changes.

Overall, I've tried to avoid changing any contents as much as possible, and have annotated all changes via comment in the source files (using: // @NOTE: followed by a description of the changes).

Beside aesthetic changes, like moving long comments within parenthesis into Admonition Blocks, or enforcing consistent styles, actual content-related changes are rare and always justified by either the new medium (AsciiDoc) or changes in the trends regarding computer documentations.

Anyhow, these must all be documented for transparency sake, as well as approved by the original author. (No one likes to see his contents changed by others, after all).

Proofread, check and fix every footnote in The Hugo Book:

• BOOK 1:
  • 1. INTRODUCTION (3).
  • 2. A FIRST LOOK AT HUGO (7).
  • 3. OBJECTS (10):
  • 4. HUGO PROGRAMMING (9):
  • 5. ROUTINES AND EVENTS (10).
  • 6. FUSES, DAEMONS, AND SCRIPTS (1).
  • 8. JUNCTION ROUTINES (6).
  • 10. USING THE OBJECT LIBRARY (10).
  • 12. RESOURCES (2).
  • APP. B. THE HUGO LIBRARY (2).
  • APP. D. HUGOFIX AND THE HUGO DEBUGGER (2).
• BOOK 2:
  • 14. ORGANIZATION OF THE .HEX FILE (6).
  • 15. TOKENS AND DATA TYPES (3) — 1 in doc + 2 in CSV file.
  • 16. ENGINE PARSING (1).
  • 20. THE OBJECT TABLE (2).
  • 26. THE HUGO ENGINE AND HOW IT WORKS (1).
  • APP. H. CODE PATTERNS (11)

Some notes containing XRefs will still need to fixed (separately, when dealing with XRefs); the above is about proofreading and checking that their positions and contents are OK.

See also: #22 — Footnotes inside Tables.

References

• Asciidoctor Manual » §61. Footnotes:
  • §61.1. Externalizing a Footnote
  • §10.4.2. Substitutions in an attribute entry
  • §10.4.4. Splitting attribute values over multiple lines

Improve the Hugo syntax for Highlight.

• Find and add missing Hugo keywords:
  • attribute?
  • resource
• Remove HugoLib-defined keywords/aliases:
  • nouns
  • adjectives
  • any others?
• Distribute tokens into different keyword groups according to category:
  • Decide where to move:
    • true/false.
  • Keywords Group 1:
    • Generic Keywords.
  • Keywords Group 2:
    • Built-in Global Variables.
    • Built-in Properties.
    • Built-in Engine Variables.
  • Keywords Group 3:
    • Chars constants..
    • System Words..
    • Properties Qualifiers.
  • Keywords Group 4:
    • Limit Settings.

Thoughts and Considerations

Some of the above changes might need further considerations to determine how many keywords groups to create:

• Should builtin globals, builtin properties, and predefined constants belong each to a distinct group, or should they share a same group?
• Are there other categories that differentiate the various Hugo tokens?

Also, the introduction of new keywords groups will require updating the Sass stylesheets accordingly.

About the Hugo Syntax for Highlight

The current Hugo syntax definition that ships with Highlight (v1.0.0) is incomplete — it doesn't even capture all Hugo tokens and keywords.

Right now, the hugo-book project host its own tweaked version of hugo.lang (in assets/hl/langDefs/) which is an early release candidate for the upcoming v1.1.0 of the Hugo syntax, so that The Hugo Book might benefit from it before it's updated in the Highlight project.

• https://gitlab.com/tajmone/highlight-test-suite/tree/hugo-lang-dev/hugo

All candidate release work is being carried on in the Highlight Test Suite project on GitLab, inside the hugo-lang-dev branch, where syntax improvements can be fully tested before updating the release candidate Hugo syntax in this repository.

Once the Hugo syntax is finished, it will be published as v1.0.0 on the Highlight project and become available with the next Highlight release.

The Hugo Book project is a good testing ground for checking that the Hugo syntax meets all requirements, thanks to its abundance of code examples, along with the Highlight Test Suite, which carries out both generic and edge-cases tests.

Project Tests and Samples

Now the assets/hl/ folder contains syntax-test files and preview samples (Live HTML Preview links):

• hugolib.h.html
• tokens-list.hug.html

The hugolib sample is intended to provide a real-case example of the look and feel of highlighted code.

The tokens lists sample allows visual inspection of all the tokens covered by the Hugo syntax, to check that they are rendered correctly and that no tokens are missing.

The Hugo syntax source file can be previewed at assets/hl/langDefs/hugo.lang for inspection of the tokens list.

The first game transcript example in §4.8. What Should I Be Able To Do Now?, produced by:

! Sample to print various typefaces/colors:

#include "hugolib.h"

routine main
{
  print "Text may be printed in \Bboldface\b,
    \Iitalics\i, \Uunderlined\u, or
    \Pproportional\p typefaces."
  color RED               ! or color 4
  print "\nGet ready. ";
  color YELLOW            ! color 14
  print "Get set. ";
  color GREEN             ! color 2
  print "Go!"
}

• Add additional CSS sytles:
  • RED
  • YELLOW
  • GREEN
  • proportional (removed from example)
• Tweak example code:
  • Add red, yellow and green styles.
  • Remove proportional example (see below).
• Update output transcript accordingly.
• Document the changes in CHANGES.md.

The last style (proportional) is problematic though, for in all game transcripts the font is assumed to be a proportional font, instead of a monospaced font — i.e. transcripts are shown as if taken for the graphic Hugo interpreter, not the console version.

So, in order for the above example to render properly, I'll need to use a [literal] block instead of an [example] — still, this would break consistency of styling in game transcript examples.

1. I could change all game transcripts to [literal] blocks, using monospaced fonts and preserve whitespace.
2. I could make an exception for this example, and adopt a [literal] block with role role="gametranscript" (to provide consistent color scheme) — but it might require some extra text to justify this sudden change.
3. I could ask @tessman if I could tweak the example to either skip entirely the proportional typeface, or use some other style instead.

Problem

The current Highlight TreeProcessor extension employed in this project to integrate Highlight into the Asciidoctor toolchain is based on very old code and has a number of limitations:

• /assets/adoc/highlight-treeprocessor_mod.rb

Solution

• The whole Highlight extension needs to be re-written from scratch adopting the new SyntaxHighlighter API for Asciidoctor 2.0. For details, see:
  • asciidoctor/asciidoctor-extensions-lab#99
  • asciidoctor/asciidoctor#299

The problem here is that I dont' have enough knowledge of Ruby nor the Asciidoctor API to do it — I've tried many times over, without results (see: alan-if/alan-docs#36).

Any help from someone fluent in Ruby is appreciated.

Known Limitations

In order of severity:

• Doesn't support callouts in code blocks.
• Code blocks inside table cells is not highlighted.
• Limited and buggy support for substitutions in code blocks via the subs attribute.
• Risk of becoming unusable in the future, if the API 2.0 breaks support for legacy extensions.

Reference Links

• asciidoctor/asciidoctor-extensions-lab#99
• asciidoctor/asciidoctor#299
• Highlight repo: /extras/AsciiDoc/ — AsciiDoc assets for Highlight.

Other issues were I discuss this topic:

• alan-if/alan-docs#36
• alan-if/alan-docs#49

Section numbering of Book II will be inconsistent when publishing the book into split files.

Currently, there seems to be no way to control/reset section numbering in Asciidoctor.

This means that, when publishing The Hugo Book as a single-file document, section numbers in Book II (i.e., chapters and appendices) will carry on from Book I — with Introduction of Book II being numbered as §13.

If we publish the two book parts as independent files, section numbering of Book II will be independent from Book I — with Introduction of Book II being numbered as §1.

The latter mirrors the actual numbering of the official Hugo Book PDF document, and it would be desirable to preserve this kind of numbering — we're already trading off roman-numbering of sections for arabic-numbering.

In any case, having different section numbers across the various editions (single doc, split by book parts, or one doc per section) would create unnecessary confusion to the readers, and consistent numbering is preferable.

Beside this general problem regarding section numbering control of the two book parts, there are other technical problems affecting publications as one-section per document — i.e. HTML chunking.

References

See Issues:

• asciidoctor/asciidoctor#1113 — Set section number manually something like this :section: 7.
• asciidoctor/asciidoctor#3311 — Customizable Numerals in Section Numbering.
• asciidoctor/asciidoctor#626 — Support chunked (multi-page) HTML output in Asciidoctor.
• asciidoctor/asciidoctor#979 — Option to allow section numbering to be reset in each part.

See Asciidoctor Manual:

• §16.7. Numbering

• Get @tessman approval for these changes.
• Fix document source.
• Document the changes in CHANGES.md.
• Update commented annotation in source file.

$12.2 LoadPicture() and PictureinText()

In §12.2. Pictures edited the syntax definition:

LoadPicture("resourcefile", "picture")
LoadPicture("picture")
PictureinText("file", "pic", width, height, preserve)
PictureinText("picture", width, height, preserve)

to make it consistent with the other syntax definitions:

LoadPicture("<resourcefile>", "<picture>")
LoadPicture("<picture>")

PictureinText("<file>", "<pic>", <width>, <height>[, <preserve>])
PictureinText("<picture>", <width>, <height>[, <preserve>])

NOTE — @tessman: confirm if I've got optional parameters within […] are correctly!

$12.3 PlaySound() and PlayMusic()

And, in §12.3. Sound and Music, the the syntax definition:

PlaySound(resourcefile, sample, loop, force)
PlayMusic(resourcefile, song, loop, force)

was edited to make it consistent with the other syntax definitions:

PlaySound(<resourcefile>, <sample>, <loop>, <force>)
PlayMusic(<resourcefile>, <song>, <loop>, <force>)

NOTE — @tessman: I have the impression that some of these parameters are optional and should be within […]. This might apply to other syntax definitions in this chapter, so it might be worth giving a quick look to it!

Conflicting use-restrictions between the book and the current Hugo license.

In §1.2. Legal Information we read:

Commercial distribution of the Hugo Compiler, the Hugo Engine, and/or the Hugo Debugger may be allowed by arrangement with the Author. The source code for the Hugo Compiler, the Hugo Engine, and the Hugo Debugger (the "Hugo Source Code") is available for porting to new platforms. Public distribution of modified versions of the Hugo Source Code is not permitted.

But, since the last edition of The Hugo Book, Hugo has now been released under BSD 2 Clause license (see LICENSE file), which removes some of those restrictions:

Therefore, the commercial use and modified versions restrictions seem to no longer apply.

Since this is stated in the very early part of the book, and might affect new Hugo users (who didn't even look at its license file yet), it might be worth looking into it.

• Find out: Did Hugo license differ in the past?
  If so, then:
  • Should an editor's admonition note (or a footnote) be added regarding this?
  • Or, ask @tessman if he wishes to amend the original text in this regard.

NOTE — The new Hugo Book AsciiDoc edition will not alter any contents without the author's permission (only formatting and style adaptations). It has to be a faithful copy of the last edition of the original book.

Of course, the book license will allow users to create derivative works from it, but this repository should offer a a text which is faithful to the original book.

Before merging/squashing the project into master branch, remember to tweak the Travis CI Badge URL in main README.md — it's currently pointing to draft branch:

https://api.travis-ci.org/tajmone/hugo-book.svg?branch=draft

Amended example code output to match source.

• Get @tessman approval for these changes.
• Fix document source.
• Update commented annotation in source file.

In §4.8. What Should I Be Able to Do Now?, "Example: Managing Strings", there where small discrepancies between the source file and the output text regarding punctuation (= instead of : in a couple of places).

In the original, address = didn't match the source address::

(Dictionary address = 887)
s1 contains "This is a sample string."
(Array address = 1625, length = 24)
s2 is "Apple", s3 is "Tomato"

therefore I've compiled the source code of the example and pasted the actual transcript, which differed from the original output shown in the book:

(Dictionary address:  1040)
s1 contains "This is a sample string."
(Array address:  1643, length = 24)
s2 is "Apple", s3 is "Tomato"

Personally, I think that this is such a small change that it's not worth documenting it at all — making you aware of it should be more than enough.

EDIT — this issue was ultimately solved in commit be85089 by using Courier New instad of Consolas, which is a safer solution in view of cross-browser support as well as to other backends SVG compliance.

Risk that SVG diagrams are not shown with intended fonts...

In the various SVG diagrams (See #1) created via Dia Diagram Editor for the book, I've used the Consolas (monospaced) font, which is not granted to be available on all OSs.

I need to:

• Investigate better if by embedding the required fonts in the document, via CSS, it's enough to ensure that the diagrams will show as intended — especially if using the data-uri Asciidoctor option to embed SVG images in the document itself.
• Find a way to set alternative fonts in Dia — which only allows one font per text — or find an SVG post-processor that could add a font-stack.
• Consider using the same monospaced font for code blocks and the diagram (whichever font that will ultimately be), to avoid using too many fonts in the document.

Reference Links

SVG Images

• CSS Tricks » Using Custom Fonts With SVG in an Image Tag — by Thomas Yip.
• Vecta.io » Using Fonts in SVG — by Neel Singh.

Web Safe Fonts

Resources and articles on which fonts are safe to use based on common OSs' availability (this affects fonts used in SVG images too):

• CSS Font Stack — A complete collection of web safe CSS font stacks.
• MIT.edu » Safe web fonts — Article by Jacob Morzinski.
• Lifewire » Make Sure You're Using Web Safe Fonts — Article by Jennifer Kyrnin.

• Get @tessman approval for these changes.
• Fix document source.
• Document the changes in CHANGES.md.
• Update commented annotation in source file.

In §9.2. What Should I Be Able to Do Now? there seems to be some problems with the following code:

case 1
    print CThe(player); \
        MatchPlural(player, "doesn't, "don't"); \
        need to use the word \""; \
        parse$; "\"."

looks like ther's a missing closing d-quote in "doesn't and a missing opening quote in need to use the word \""; \:

case 1
    print CThe(player); \
        MatchPlural(player, "doesn't", "don't"); \
        "need to use the word \""; \
        parse$; "\"."

@tessman:

In §10.6. Vehicles the sentence:

The preposition property defaults in the vehicle class itself defaults to "in" and "out", but in the case of a horse should be changed to the more suitable "on" and "off".

is hard to read due to the double occurring "defaults", which introduces ambiguity as to which one is a verb — it comes natural to interpret the first occurrence as the verb, which then breaks the sentence at the second occurrence, forcing to read the whole sentence again.

Something like this might be smoother on the reader (and shorter too):

In the vehicle class the preposition property defaults to "in" and "out", but in the case of a horse it should be changed to the more suitable "on" and "off".

Of course, the sentence is grammatically correct, but I've found it quite hard to read through in one go, and it struck me as one of the very few places in the whole book where the reading flow was abruptly interrupted. We might as well take this reprint as a change to polish it.

References

• Patterns of the Hypnotic Techniques of Milton H. Erickson — a textbook on how to maximize ambiguities in spoken and written sentences. Offers a classification system for ambiguities, and discusses their psychological impact on the listener and reader.