Discrepancies in Token Names and Values

[tajmone]

• Fix document source (see below).
• Document the changes in CHANGES.md.
• Document in ChangeLog.
• Get @tessman approval for these changes.
  • Updated commented notes in source files.

In his annotated PDF, @roodyyogurt pointed some discrepancies between the tokens names or values found §15.1. Tokens and those found in Appendix H: Code Patterns:

§15.1	App. H	htokens.h
$47 textdata#	$47 text#	$47 textdata#
$49 label#	$49 debugdata#	$49 debugdata#
$75 colour	$74 colour	$74 colour
$76 picture	$75 picture	$75 picture
$76 picture	$76 label#	$76 label#
$7A addcontext	(missing)	$7A addcontext
$7B video	(missing)	$7B video

The correct list of Hugo token names (and associated values) can be found in the htokens.h header from the Hugo sources repository (as indicated in the third column of the above table).

• Resolve all discrepancies in the tokens names and values by referring to the definition in htokens.h:
  • In §15.1. Tokens:
    • fix tokens table (commit ee29947):
      • $49 label# → $49 debugdata#.
      • $75 colour → $74 colour.
      • $76 picture → $75 picture.
      • add → $76 label#.
      • Document fixes in CHANGES.md.
  • In Appendix H: Code Patterns.
    • fix tokens names (commit ee29947):
      • $47 text# → $47 textdata#.
      • Document fixes in CHANGES.md.
    • Add missing tokens (moved to Issue App. H: Tokens $7A and $7B Missing #73):
      • $7A addcontext
      • $7B video
• Check if the amended tokens names/values also occur in other places of the book:
  • None found by searching for the tokens by names.
  • Check hex values in binary examples:
    • couldn't find any.

NOTE — Addition of the missing tokens (addcontext and video) to App. H has been moved to a separate Issue (#73) because it involves adding new contents, and might therefore require a separate discussion.

Reference Links

• Hugo Book live previews:
  • §15.1. Tokens:
    • original document
    • fixed document (on dev branch)
  • App. H: Code Patterns:
    • original document
    • fixed document (on dev branch)
• Hugo source code:
  • htokens.h — tokens definitions.

[tajmone]

Obvious Fixes Dealt With!

All the issues regarding misnamed tokens, wrong associated hex values, and missing tokens have been dealt with in commit ee29947 — these were rather straight forward business, only requiring to lookup the Hugo sources to establish which were the correct names and values.

Remaining Fixes

Now we're left with the missing descriptions of token 7A and 7B (addcontext and video) in Appendix H: Code Patterns.

It's worth noting that the addcontext and video entries in §15.1. Tokens both have a footnote mentioning they were added in v3.0 and later. So it looks like these were new features not yet documented in Appendix H: Code Patterns.

Since these require adding new contents to the book, I'd like to hear @tessman on this, before laying hands on the book sources.

Moving From Preservation to Update?

These remaining changes to App. H are not simple fixes but active book updates, so they beg for the wider question of whether this project is ready to move from the initial goal of historical preservation to that of further developing the book, actively.

Personally, I'd love to see The Hugo Book grow in contents, but at the same I'd like all the changes in this repository to be blessed by Kent Tessman, so that it can be a sort of official reference (as opposed to being freely edited by third parties).

Furthermore, the active development step would also demand that we edit obsolete contents in the book — e.g. mentioning of usage limitations which are now superseded by the latest open source licenses; various memory and performance considerations which no longer apply to modern PCs; dead links sections; and so on.

Therefore, taking this step would depend greatly on whether Kent is willing to participate in the process of writing new contents, or supervising and approving edits by collaborators to the project.

Another aspect to consider is whether there are enough people willing to participate in the editing process, by revising the text to improve it, writing new contents, examples, etc.

The Hugo Book, in its current state, already covers all that is needed to learn Hugo; but of course, there's always room for improvement.

@roodyyogurt, since you're actively engaged in the Hugo authors community, what's your opinion regarding this? Do you think that there are people willing to participate to the book growth?

[roodyyogurt]

As far as book growth goes, I think everyone who has reached out to me with corrections had only that in mind. I have the backups to the Hugo By Example site and am looking for ways to resurrect it. Maybe down the road, we might decide we want to elaborate on something within The Hugo Book within the book itself but I don't see that as a priority for now.

Maybe the preface to your The Hugo Book could link to Kent's "Vault of Hugo" sample code? It really does go out of its way to show examples of many of the lesser used functions in The Hugo Book and is very valuable to the beginner (and seasoned) Hugo coder.

Also, thanks, the acknowledgements section looks great.

[tajmone]

As far as book growth goes, I think everyone who has reached out to me with corrections had only that in mind.

I thought so. Also, right now is bad moment for IF, due to macOS and many Linux distros dropping 32-bit support, which has cut out a great deal of authors and players from the classic IF tools. Maybe in the future we'll see better times for IF revival in general, and a renewed interest in all IF systems. At the moment, preservation is the most important thing.

Reviving Hugo By Example and The Hugo Vault

I have the backups to the Hugo By Example site and am looking for ways to resurrect it.

The ideal approach would be to:

1. Archive a zipped copy of the whole site (as is) on the IF Archive.
2. Recreate the Hugo By Example site as a repository on GitHub, using a static website generator that compiles HTML pages from markdown or AsciiDoc.

For the latter, we'd need to first convert the website pages for their original format to markdown/AsciiDoc. From what I gather looking at the archived copy of the website, it seems to be in the MediaWiki format, so we could easily batch-convert it to markdown using pandoc, and then either chose one of the many markdown static website generators or use just pandoc itself with some custom templates and scripts.

Could you share the website sources as a zipped file on Google Drive, so I can look at them and do some quick tests with pandoc?

Maybe down the road, we might decide we want to elaborate on something within The Hugo Book within the book itself but I don't see that as a priority for now.

I think the best policy is to keep one project per repository, because third parties might wish to include these projects as Git submodules in their own projects (for whichever reason), so keeping them separate lessens the burden.

By using Git submodules we could easily create an umbrella repository for all Hugo projects, which simply imports all the Hugo related repos as submodules, so that any updates to the upstream projects are easy to integrate.

Maybe the preface to your The Hugo Book could link to Kent's "Vault of Hugo" sample code? It really does go out of its way to show examples of many of the lesser used functions in The Hugo Book and is very valuable to the beginner (and seasoned) Hugo coder.

I've only managed to find the Vault of Hugo II archived on the Wayback Machine, is that the one you're referring to?

• IFWiki » Vault of Hugo II: Electric Boogaloo
• Vault of Hugo II (Wayback Machine)
• IF Archive » Vault of Hugo II

I think it might be worth creating an independent repository to collect all Hugo examples and tutorials under a centralized place. I had started looking into it, but it's going to take some time due to handling credits and licenses. But it's definitely something I want to do, and I could start working on it soon.

[roodyyogurt]

Here is a link to my most recent MediaWiki backup (several years old since that was the last time I updated the site):
https://drive.google.com/drive/folders/0B_4ZXs4Z_yoWalo2a3pmVTBZSjg?usp=sharing

Robb Sherwin was going to look into resurrecting the site, but I haven't gotten any updates from him and haven't wanted to bother him. I found a free MediaWiki-hosting site called ShoutWiki that I thought about using, but their import functionality isn't offered for the time being (they stopped doing imports a year or two ago).

Of course, ideally, its new iteration should also be editable. I worked on Hugo By Example in my pre-Roodylib days so updating the site for information on Roodylib has always been on my "to do" list.

Just the same, good luck working with the backup format. I'll be curious to hear how well it works.

The Vault of Hugo is at https://www.ifarchive.org/if-archive/programming/hugo/examples/sample.hug

The Vault of Hugo II was a joke game I wrote for a PAX East minicomp.

[tajmone]

@tessman, I've moved the discussion on whether to add the missing tokens in App. H to a separate Issue (#73) so we can focus on the obvious fixes here.

The rest of the token-related problems have already been fixed, I just need your blessing to close this Issue as "approved".

Quick live links to the dev branch, showing fixed contents:

• §15.1. Tokens (tokens table)
• Appendix H: Code Patterns