This document lists all the contents changes that theAsciiDoc edition has introduced in The Hugo Book.
Table of Contents
- Introduction
- Changes List
The AsciiDoc edition was created by Tristano Ajmone from a Word document supplied by Kent Tessman. The original Word document was the latest version of The Hugo Book by the original author.
The main motivation for porting The Hugo Book to AsciiDoc is twofold:
- Historical preservation.
- Providing a format-agnostic version of the document convertible to different output formats.
The main motivation for porting The Hugo Book to AsciiDoc is its historical preservation. Providing a format-agnostic version of the document, which can convert to different output formats, is an added benefit.
With preservation being the main goal, this edition doesn't aim at updating the book contents, bur rather stick to the original text as faithful as possible.
This project was privileged by the participation of Kent Tessman, who followed its development and actively engaged in any questions and discussion when crucial editing decisions needed to be taken. This has been a great opportunity for it offered the chance to consult the original author when text amendments were necessary.
Therefore, I opted to point out to Kent any problems with the original text (small inconsistencies, missing text, typos, etc.) so that he might suggest amendments, or approve any of my proposed changes. These problems were very few in number, and most likely due to editing accidents like partial undoing, or accidental deletion of text selections; for the original document was well polished and thoroughly checked.
In any case, all significant changes to the original text have been annotated in this document, so that end users can look them up and compare the with the latest PDF version of The Hugo Book deposited on the IF Archive. Just bare in mind that the Word document from which the AsciiDoc version was derived might contain some text updates by the original author that were never published.
The switch for Word to AsciiDoc called for some aesthetic adaptations — e.g. converting notes within parentheses to admonition blocks — as well as some functional changes — e.g. adding captions to tables and figures, to allow direct linking via anchors or providing an index of tables and figures in those output formats that support this feature (e.g. PDF) — which are more inline with the overall AsciiDoc philosophy on how documents should be organized in order to maximize fruition across different formats and media, and to allow end users full control over customization of the look and feel of the various parts of a document.
Aesthetic changes include resorting to colour and bigger font sizes to highlight key elements in lists or tables, and similar visual enhancements that can be easily controlled (and even suppressed, if so desired) via custom stylesheets or templates.
Some changes were dictated by AsciiDoc specific conventions, or limitations in the converter backend — e.g. the fact that chapters numbering in Book II resumes from Book I, instead of restarting from scratch, or the need to adopt Arabic numerals for chapters numbers instead of the Roman numerals, as in the original.
For the sake of better game transcripts emulation, in some places inline transcripts where substituted with block elements, which also required removing surrounding quotes. The rationale for this was that using ad hoc styled for transcripts examples would have a higher visual impact (especially on the HTML document, which uses colours) and simplify quick reading through chapters and finding required references.
The text of cross references was also slightly adapted to better fit the AsciiDoc model. Occurrences like "The section Sec. 4.5" or "Section Sec. 4.5" were all adapted to "Sec. 4.5", in order to fit a standard cross reference model.
Dead links in the original book were fixed wherever possible, pointing either to the new URL where these resources are currently hosted, or to their archived copy on Wayback Machine in case of no longer available websites and services. The original URLs were kept in the text, for the sake of historical preservation, but clicking on them redirects to their updated URL of destination.
None of these changes disrupt the original contents of the book; and I believe they serve well the original author intentions.
The book contains some code excerpts from the Hugo Library. I've replaced them with the same excerpts from the latest official Hugo Library (v3.1.03.2) so that the reader will be able to match the text of the book against the current Hugo Library.
The differences in the original and update code are usually very small, if any, and I've gone to great length to ensure they won't affect the reading experience (e.g. in case some references changed). All the changes that I've encountered where improvements on the original code, none of which affect backward compatibility nor the context in which the book mentions them.
I believe that these small changes are in line with the original author intention of matching the latest version of The Hugo Book with the latest version of the Hugo Library, and therefore desirable.
The source files of the Hugo Library v3.1.03.2 that I've used can be found here:
Here's the list of all significant changes to the book contents, which are worth mentioning. These changes fall under two main categories:
- Text adaptations to better exploit the new AsciiDoc format, or to provide a more readable text.
- Fixes to minor typos in text or code.
By "significant changes" we mean those changes which would be worth mentioning in an Errata. Minor typos and other obvious fixes are not listed here, but they have been annotated in the documents sources comments nonetheless, for historical accuracy.
List of changes to Book I: The Hugo Programming Manual.
List of changes to Chapter 1. Introduction.
Additionally, you're probably want to download shell.hug,
was amended into:
Additionally, you're going to want to download shell.hug,
(See Issue #28)
In §1.10. Limit Settings, the following admonition block:
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.\$listand\$<setting>=<new limit>or'list','$<setting>=<new limit>', etc.) to override the shell's parsing of those tokens in the compiler invocation line.
was missing the $ symbol in 'list', and was fixed to:
(e.g.
\$listand\$<setting>=<new limit>or'$list',
(See Issue #20)
List of changes to Chapter 2. A First Look at Hugo.
In §2.4. Multiple Lines, inside the tip admonition on how to preserve a double space when splitting a string across multiple lines, the original text:
since normally, if the
/were omitted after “…on one line.”,
was changed to:
since normally, if the
\were omitted after “…on one line.”,
(See Issue #17)
List of changes to Chapter 4. Hugo Programming.
In §4.8. What Should I Be Able to Do Now?, the Mixing Text Styles example:
! 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!"
}
was edited by removing the proportional typeface, since game transcripts are all in proportional font throughout the book:
! Sample to print various typefaces/colors:
#include "hugolib.h"
routine main
{
print "Text may be printed in \Bboldface\b,
\Iitalics\i, or \Uunderlined\u typefaces."
color RED ! or color 4
print "\nGet ready. ";
color YELLOW ! color 14
print "Get set. ";
color GREEN ! color 2
print "Go!"
}
The output transcript was also changed accordingly.
The rationale was that it was better to discard the proportional font example instead of having to use a monospace font as the base typeface for this transcript only, thus breaking consistency with the rest of the transcripts. Using a monospace font for all transcripts would have been counter-productive, for most IF games today use proportional fonts as the base typeface. Furthermore, monospace fonts are already used in code examples and syntax definitions, so using a proportional font for transcripts renders the book more readable.
(See Issue #6)
List of changes to Chapter 5. Routines and Events.
In §5.3. Before And After Routines, toward the section end, there was a paragraph where some ending text went lost:
A drawback of this non-specification is that all verbroutines are matched — both verbs and xverbs. This can be particularly undesirable in the case of location
before/afterproperties, where you may wish to be circumventing any action the player tries to perform in that location, but where the non-specific response will be triggered even forsave,restore, etc. (i.e.,
The paragraph end was amended by Kent Tessman to:
[...] for
save,restore, etc. (i.e., xverbs).
(See Issue #14)
List of changes to Chapter 7. Grammar and Parsing.
In §7.1. Grammar Definition, where dynamic grammars are being discussed, the following TIP admonition block was added:
For more details on dynamic grammars, see the Grammar chapter in Book II.
Because dynamic grammars are only briefly mentioned in the book, custom anchors were added in the only two places where they are discussed, along with a side note cross-referencing them to each other.
For the other added cross reference, see the changes in 17. Grammar.
(See Issue #48)
List of changes to Chapter 9. The Game Loop.
In §9.2. What Should I Be Able to Do Now?, the following code:
case 1
print CThe(player); \
MatchPlural(player, "doesn't, "don't"); \
need to use the word \""; \
parse$; "\"."
was missing the opening quote and a space before need to use, and was fixed to:
case 1
print CThe(player); \
MatchPlural(player, "doesn't", "don't"); \
" need to use the word \""; \
parse$; "\"."
(See Issue #38)
List of changes to Chapter 10. Using the Object Library.
In §10.5. Doors:
The
betweenproperty takes care of making the room available in both locations
"room" was changed with "door":
The
betweenproperty takes care of making the door available in both locations
(See Issue #19)
In §10.6. Vehicles, the accidentally damaged sentence:
It is also necessary to provide grammar to relate the words in the
vehicle_verblist to the object library'sDoMoveInVehicleroutine.Grammar he following is recommended:
was fixed by Kent Tessman to:
It is also necessary to provide grammar to relate the words in the
vehicle_verblist to the object library’sDoMoveInVehicleroutine. Grammar such as the following is recommended:
(See Issue #18)
In §10.6. Vehicles, the sentence:
The
prepositionproperty defaults in thevehicleclass itself defaults to "in" and "out", but in the case of a horse should be changed to the more suitable "on" and "off".
was hard to read due to the double occurring "defaults", which introduced ambiguity as to which one was a verb. It was rephrased to:
In the
vehicleclass theprepositionproperty defaults to "in" and "out", but in the case of a horse it should be changed to the more suitable "on" and "off".
which is smoother on the reader (and shorter too).
(See Issue #30)
List of changes to Chapter 12. Resources.
In §12.2. Pictures, the syntax definition:
LoadPicture("resourcefile", "picture")
LoadPicture("picture")
PictureinText("file", "pic", width, height, preserve)
PictureinText("picture", width, height, preserve)
was edited to make it consistent with other syntax definitions:
LoadPicture("<resourcefile>", "<picture>")
LoadPicture("<picture>")
PictureinText("<file>", "<pic>", <width>, <height>[, <preserve>])
PictureinText("<picture>", <width>, <height>[, <preserve>])
(See Issue #36)
In §12.3. Sound and Music, the syntax definition:
PlaySound(resourcefile, sample, loop, force)
PlayMusic(resourcefile, song, loop, force)
was amended to include some missing parameters and to make it consistent with other syntax definitions:
PlaySound(<resourcefile>, <sample>[, <volume>[, <loop>[, <force>]]])
PlayMusic(<resourcefile>, <song>[, <volume>[, <loop>[, <force>]]])
(See Issue #36)
List of changes to Appendix A. Summary of Keywords and Commands.
In the definition of color, the cross reference 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 containing that page number (in the original Word/PDF document) 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 the relevant paragraph on the topic through a custom anchor (hugolib-colors).
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).
(See Issue #27)
In the definition of print, after the print <output> syntax:
where
<output>can consist of both test strings enclosed in quotation marks ("…"), and values representing dictionary addresses
"test strings" was changed to "text strings":
where
<output>can consist of both text strings enclosed in quotation marks ("…"), and values representing dictionary addresses
(See Issue #28)
List of changes to Appendix B. The Hugo Library.
In §B.7. Utility Routines, Etc., in the definition of the ObjWord Library routine:
calling form:
ObjWord(word, object)Returns either
adjectiveornoun(i.e., the property number) if the given is either an adjective or noun of the specified object.
The missing term "word" was added after "if the given":
if the given
wordis either an adjective ...
(See Issue #47)
List of changes to Book II: Technical System Specification.
List of changes to Chapter 17. Grammar.
In Chapter 17. Grammar, where dynamic grammars are being discussed, the following note within parenthesis was added:
(See also Book I on dynamic grammars.)
Because dynamic grammars are only briefly mentioned in the book, custom anchors were added in the only two places where they are discussed, along with a side note cross-referencing them to each other.
For the other added cross reference, see the changes in 7.1. Grammar Definition.
(See Issue #48)