build status

The Hugo Book

AsciiDoc port of The Hugo Book, written by Kent Tessman, 2004.

Released under CC BY-NC-SA 4.0 license with explicit permission by Kent Tessman.

Project created by Tristano Ajmone in 2019/09/29.

https://github.com/tajmone/hugo-book

To read The Hugo Book on-line, as a single HTML document:

https://git.io/hugo-book

Table of Contents

Project Contents
About
Why AsciiDoc?
Contributing
License
Acknowledgements
Credits
External Links

Project Contents

/assets/ — resources required to build the book.
/assets_src/ — sources of buildable assets.
/docs/ — HTML version of The Hugo Book, served online via GitHub Pages.
/docs_src/ — AsciiDoc sources and build scripts.
CHANGES.md — list of changes from the original book.
CONVENTIONS.md — formatting, styles and code conventions.
hugo-book.asciidoc — standalone preprocessed AsciiDoc version of The Hugo Book.
hugo-book.html — The Hugo Book, HTML release.
LICENSE — CC BY-NC-SA 4.0 license.
validate.sh — EditorConfig code styles validation via EClint.

About

The Hugo Book is the official manual for the Hugo Interactive Fiction authoring system (1995–2006), a cross platform system for creating and playing text adventures with advanced multimedia support, created by Kent Tessman and released under BSD 2-Clause License.

Historically, The Hugo Book was distributed in PDF format, which can be downloaded in the Hugo section of the IF Archive:

https://www.ifarchive.org/indexes/if-archive/programming/hugo/manuals/

I wanted to port the book to AsciiDoc using an open source license, so I e-mailed Kent Tessman; he kindly granted his permission to do so under CC BY-NC-SA 4.0, and sent me his latest Word document of the The Hugo Book.

I chose not to share the original Word document in the repository due to the potential leaks of personal information associated with MS Word files. For comparison between the AsciiDoc version and the original book, please refer to the PDF version from the IF Archive.

Having the chance and honour to consult directly the original author, I grabbed the opportunity to fix a few typos and propose some minor edits here and there, all of which were supervised and approved by Kent Tessman — all changes are listed in the CHANGES.md document, with links to the repository Issues were these changes were proposed, discussed and approved.

None of these changes are significant beyond what might be part of an Errata, so this AsciiDoc port of The Hugo Book still qualifies as the first edition, but was revised in January, 2020 with the author's supervision.

AsciiDoc Sources

/docs_src/ — AsciiDoc sources and build scripts.

The Hugo Book was split into multiple AsciiDoc files to simplify maintainance as well as to allow republishing single chapters individually.

To convert the AsciiDoc sources into HTML, run the docs_src/build.sh script.

Single-File AsciDoc Version

For convenience, the docs_src/build.sh script also creates a single-file AsciiDoc version, by preprocessing the source files via the AsciiDoc Coalescer:

hugo-book.asciidoc

This standalone version is provided for simplifying handling the book as a single source in external projects —

WARNING — Do not edit the preprocessed file, for all changes would be lost on the next build! All changes must be submitted to the sources in the /docs_src/ folder.

HTML Version

Currently The Hugo Book is available only in HTML format in this project:

hugo-book.html

We're planning to add more output formats to the build toolchain, at some point in the future — any help on this front is highly appreciated.

Converting to Other Formats

AsciiDoc being format-agnostic, you should be able to build the book with any Asciidoctor backend, out of the box.

To optimize the final look of the book, you might have to tweak the template used by the backend/converter to cover the custom styles adopted in this project (see CONVENTIONS.md). Furthermore, to beautify the Hugo code examples you'll probably have to create your own Hugo syntax definition for the syntax highlighter employed by the specific backend/converter.

If you've converted The Hugo Book to other formats, please let use know about it.

Releases and Versioning

The project adopts Semantic Versioning 2.0.0 (aka SemVer) as its releases versioning scheme. Release versions refer to the AsciiDoc sources of The Hugo Book, for these constitute the core of the project — all other assets (templates, stylesheets, etc.) and converted documents (HTML, etc.) are just added bonuses.

Any changes to the AsciiDoc sources will result in a version change and a new tagged release, whereas changes to other contents won't. Commits on master branch are not limited to tagged releases, therefore all contents except AsciiDoc sources might undergo any number of changes between tagged releases (including Hugo Book documents in formats like HTML, which might undergo template and stylesheets updates).

End users who rely on this repository for their own projects can count on the following expectations:

master branch will always provide:
- the latest version of the AsciiDoc book.
- the most up-to-date HTML version of the book.
Tags can be used to checkout specific versions of the AsciiDoc book, to ensure compatibility with your project tool chain.

Why AsciiDoc?

These are the main reasons why I wanted to make The Hugo Book available in AsciiDoc format (via the Asciidoctor Ruby implementation).

Multiple output formats support

AsciiDoc source documents are very versatile when it comes to their final use, for they can be converted to a variety of output formats beside PDF, including HTML based formats (websites, ePub, Mobi/Kindle, Microsoft CHM Help), and many other formats.

For example, someone wishing to create a dedicated Hugo IDE could reuse these sources to include The Hugo Book as a CHM Help file.

Many CMSs and static website generators support AsciiDoc, which means that someone wishing to create a website dedicated to IF documents could just drop these sources into the CMS sources folder and be up and running.

The list of supported output formats will grow in time, as the AsciiDoc projects evolve. Since the advent of the Asciidoctor implementation we've seen a new wave of interest in the AsciiDoc format, and many new projects have come into being, including new output formats backends.
Separation between styles and contents.

By separating contents from styles, AsciiDoc allows end users to decide how to customize the final look of the output document via custom templates. Also, AsciiDoc allows end users to choose which syntax highlighter to employ for beautifying the code examples of the document, thus greatly simplifying the task of colouring the Hugo code examples of the book, across different output formats.
Collaborative editing.

Being a text-based syntax, AsciiDoc documents can be version controlled like any other source files, which makes it simple to edit documents collaboratively via tools like Git, Fossil, Mercurial, etc.

Since Hugo is an open source software, people might wish to take on its development, or create new derivative tools based on the Hugo sources. In such cases, having access to The Hugo Book in AsciiDoc format is going to be a blessing for the sake of documenting the project.

The ability to version-control the book also simplifies translating it to other languages by working directly overt the original English sources and being able to easily track changes, resolve conflicts, and undo changes.
Inter-document and cross-project operativity.

Having access to the AsciiDoc sources of The Hugo Book is going to simplify including the book (or parts of it) in other documents or projects. This is going to be very helpful in projects aiming to collect various IF-related documents and books under one umbrella (e.g. documentation websites, IF wikis and encyclopaedias, etc.).
Long-term document preservation.

The AsciiDoc standard is well established enough to grant that in the future it should always be possible to reproduce or recover an AsciiDoc document. Unlike proprietary document file formats, AsciiDoc is both open source and text-based, which is a guarantee that there will always be a backward compatible tool capable of parsing AsciiDoc sources. Since AsciiDoc sources only deal with contents and their semantics, it's going to be easy to convert them to other formats in a lossless manner.

Hopefully, this will contribute to the preservation of The Hugo Book legacy in Interactive Fiction.
Privacy and security concerns.

Unlike proprietary document formats like Word and PDF — which embed private user- and machine-details that pose a privacy and security threat — the AsciiDoc format doesn't leak any private information unintended for public disclosure. Being a text-based document format, there here are no hidden tags and metadata containing private information — what you see in the source document is all there is to it.

I strongly believe that AsciiDoc is an excellent format for sharing documents, and I hope that in the future we'll see more IF-related documents being ported to AsciiDoc, which could greatly simplify preservation and maintenance of the IF literature and its re-usability across different projects and output formats.

Contributing

The project is open to contributions. All pull requested should be made to the dev branch.

Just ensure that your pull request passes the Travis CI build tests, which you can verify locally by running the validate.sh script, before submitting the PR.

There are no plans to update the book contents, so contributions should be limited to AsciiDoc formatting and styling, the build chain, supporting new output formats, improving existing templates, and similar enhancements that don't affect the actual text of the book.

If you really want to work on the book contents, you should do so in a fork of this repository, because the goal of this project is to provide the latest Hugo Book edition officially approved by the original author, Kent Tessman.

License

LICENSE

Explicit permission was granted from Kent Tessman to republish The Hugo Book under the terms of the CC BY-NC-SA 4.0 license.

The Hugo Book (c) by Kent Tessman, 2004.

The Hugo Book is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

You should have received a copy of the license along with this work. If not, see http://creativecommons.org/licenses/by-nc-sa/4.0/.

Acknowledgements

I would like to thank...

Kent Tessman for creating Hugo and donating it to the mankind by open sourcing it, and for having granted me permission to republish The Hugo Book under an open source license. Hugo is a beautiful tool, as well an historical pillar of the Interactive Fiction history.
The people at the IF Archive, for their constant struggle and support in the quest for the preservation of IF historical material and heritage.
Dan Allen and the Asciidoctor Project team, for their relentless dedication to the development of Asciidoctor and the AsciiDoc echo-system.

Credits

This project also employs resources created by third parties. For the full licenses text, see the README file in the folders hosting the specific resources — below is just a quick credits summary.

Base16 Colour Schemes

/assets_src/sass/

For the Sass/CSS themes this project uses the following Base16 colour schemes:

Base16 Eighties — by Chris Kempson (MIT License).

The Base16 project (MIT License) was created by Chris Kempson:

http://chriskempson.com/projects/base16

The Base16 SCSS schemes are taken from the Base16 Sass project by Tristano Ajmone:

https://github.com/tajmone/Base16-Sass

Base16 Sass is released under MIT License:

MIT License

Copyright (c) 2019 Tristano Ajmone <tajmone@gmail.com>
https://github.com/tajmone/Base16-Sass

Copyright (c) 2012 Chris Kempson (http://chriskempson.com)
https://github.com/chriskempson/base16-builder

For more details and the full license text, see:

/assets_src/sass/README.md

Base2Tone Colour Schemes

/assets_src/sass/

For the Sass/CSS themes this project uses the following Base2Tone colour schemes:

Base2Tone Lake — by Bram de Haan (MIT License).

The Base2Tone project was created by Bram de Haan (@atelierbram), based on Simurai's Duotone Themes for the Atom editor:

https://github.com/atelierbram/Base2Tone

The project is released under MIT License:

The MIT License (MIT)

Copyright (c) 2016 Bram de Haan

For more details and the full license text, see:

/assets_src/sass/README.md

The Asciidoctor Project

This project employs various assets taken from The Asciidoctor Project, mostly in adapted form. For more details and the full license texts, see:

/assets/adoc/README.md

Asciidoctor Extensions Lab

https://github.com/asciidoctor/asciidoctor-extensions-lab

The following Asciidoctor extensions and scripts were taken from the Asciidoctor Extensions Lab:

/assets/adoc/asciidoc-coalescer.rb — AsciiDoc Coalescer.
/assets/adoc/highlight-treeprocessor_mod.rb — Highlight TreeProcessor.

Released under MIT License:

The MIT License

Copyright (C) 2014-2016 The Asciidoctor Project

The Highlight TreeProcessor Asciidoctor extension (Ruby) was adapted by Tristano Ajmone from the original highlight-treeprocessor.rb file.

Asciidoctor Backends

/assets/adoc/haml/

The files inside the /haml/ folder were adapted by Tristano Ajmone from the original Haml HTML5 templates taken from the Asciidoctor Backends project:

https://github.com/asciidoctor/asciidoctor-backends