Sublime Hugo IF

Status: Alpha 1 | 2019/10/17

Hugo Interactive Fiction syntax support for Sublime Text 3.

Created by Tristano Ajmone, 2019/10/17. MIT License.

Project Status: WIP Alpha.

---

Table of Contents

• About
  • Associated File Extensions
  • Encoding
  • Syntax Status
• Installation
  • Troubleshooting

---

About

I've created this Hugo syntax definition for my personal use, so it's currently unavailable as an installable package via PackageControl. In the future — if and when this project reaches maturity status — I might publish it on PackageControl.

Associated File Extensions

The following file extensions will be automatically associated with the Hugo IF syntax:

• .hug
• .g

Unfortunately, the .h extensions is also commonly associated with Hugo library files, but because .h is commonly used for C/C++ header files I didn't associate it to Hugo, to prevent conflicts.

This means that you'll have to manually set the Hugo IF syntax for .h files after opening them. Don't forget to also manually set their encoding to ISO-8859-1, after setting their syntax to Hugo IF.

Encoding

The Hugo syntax will automatically enforce ISO-8859-1 (Latin1) encoding on *.hug and *.g files — as for *.h files, see my previous notes.

Since the Hugo compiler doesn't handle Unicode files, it's important to strictly preserve the ISO encoding in the source files, lest they get corrupted by special non-Ascii characters which are represented as multiple-bytes in UTF-8. This is especially true for cut-and-paste operations from other (UTF-8) documents, which could corrupt the Hugo source file encoding by switching to UTF-8.

Hugo source files should be Ascii only, for the language provides special escape sequences to represent non-Ascii characters. Therefore, the ISO-8859-1 encoding should be fine for most projects.

In any case, you can override the default encoding in your User setting. For example, to adopt ISO-8859-3 (Latin3) for Esperanto, Maltese or Turkish, add to your <data_path>/Packages/User/Hugo-IF.sublime-settings the following:

{
    "default_encoding":  "Western (ISO 8859-3)",
    "fallback_encoding": "Western (ISO 8859-3)",
}

The important thing is to stick to an 8-bit single-byte encoding.

Syntax Status

Right now, the Hugo syntax is still very rudimentary. It detects all Hugo keywords under the generic scope keyword.other.hugo-if.

Eventually, as the syntax evolves, every keyword shall be scoped with the correct category, and the syntax semantics will be improved.

Once the semantic stage is achieved, it will be possible to start handling symbols indexing, auto-completions, and add useful snippets and advanced features and functionality.

Installation

Currently, the only way to install it on your local machine is by manually cloning this repository via Git as a loose package into ST packages folder:

• Create a Hugo-IF folder inside ST <data_path>/Packages/ folder.

• Open a shell and CD to <data_path>/Packages/Hugo-IF/.

• Clone the repository using:

    git clone https://github.com/tajmone/sublime-hugo-if.git .
  

  NOTE: The final . is required to clone the repository directly inside the current folder without creating a new sub-folder.

For the moment, you'll have to manually update the package via git pull, until I find a better solution (e.g. create a PackageControl setting file to handle updates and allow manual installation outside PackageControl).

If you're interested in actually using this package, please contact me or open an issue, so that I might give priority to third party usability of this project.

Troubleshooting

If after the above steps the Package Control plug-in starts to complain and raise error messages, go to

• Preferences » Package Settings » Package Control » Settings — User

and add the following line to your custom setting:

{
    "ignore_vcs_packages": true,
}

For more details, see PackageControl Documentation on Git repositories settings.