prepping 2.0.0

excite

docs/README.md

@@ -2,7 +2,7 @@
 
 [Try out the demo.](./demo/ ':ignore')
 
-HAL is an audio library for [Harlowe (v2.1.0 or higher)](https://twine2.neocities.org/) designed to give the format feature parity (or close to it) with [SugarCube's audio subsystem](http://www.motoslave.net/sugarcube/2/docs/#simpleaudio-api). HAL was designed from the ground up *specifically* for use with Harlowe, and is intended to be as easy to use as possible for novice programmers without compromising functionality.
+HAL is an audio library for [Harlowe (v2.1.0 or higher)](https://twine2.neocities.org/) designed to give the format feature parity (or close to it) with [SugarCube's audio subsystem](http://www.motoslave.net/sugarcube/2/docs/#simpleaudio-api). This library was designed from the ground up *specifically* for use with Harlowe, and is intended to be as easy to use as possible for novice programmers without compromising functionality.
 
 ## Features
 
@@ -15,7 +15,7 @@ HAL is an audio library for [Harlowe (v2.1.0 or higher)](https://twine2.neocitie
 
 ## Getting the Library
 
-You can download any version of HAL from [here](https://github.com/ChapelR/harlowe-audio/releases). If you're just getting started, it's highly recommended that you grab the latest version. Once you've downloaded HAL, you'll need to read the [guide](#guide) or the [documentation](v2) to learn how to use it.
+You can download any version of HAL from [here](https://github.com/ChapelR/harlowe-audio/releases). If you're just getting started, it's highly recommended that you grab the latest version. Once you've downloaded the library, you'll need to read the [guide](#guide) or the [documentation](v2) to learn how to use it.
 
 There are two main version of HAL. The latest version 2 release is recommended for most users. If you're already using version 1 in your project, you don't have to update if you don't want to and can instead grab the latest version 1 release. The version 1 docs are [here](v1).
 
@@ -34,37 +34,37 @@ See [below](#guide) for a guide on the basics of using HAL.
 
 # Guide
 
-This is a quick and dirty guide to getting HAL working. You're here for audio, and this guide aims to please. HAL has a lot of other nice features you may need to come to grips with later, but for now, we'll focus on the bare minimum you'll need to know to take your story from a boring, soundless husk to grooving like it's 1999.
+This is a quick and dirty guide to getting HAL working. You're here for audio, and this guide aims to please. This library has a lot of other nice features you may need to come to grips with later, but for now, we'll focus on the bare minimum you'll need to know to take your story from a boring, soundless husk to grooving like it's 1999.
 
 > [!NOTE]
-> This guide is intended to get users up and running with HAL quickly and without too much fuss. It covers v2.0.0 and higher of HAL, [for v1, check out its docs](v1). For detailed reference documentation for v2, [click here](v2).
+> This guide is intended to get users up and running with HAL quickly and without too much fuss. It covers v2.0.0 and higher, [for v1, check out its docs](v1). For detailed reference documentation for v2, [click here](v2).
 
 ## Installing HAL in Twine 2
 
 To install HAL, all you need is the code, which you can get [on the releases page of the repo](https://github.com/ChapelR/harlowe-audio/releases). You should choose the version with the highest version number. Download the `harlowe-audio.zip` file and unzip it. There should be three files, `harlowe-audio.min.js`, `harlowe-audio.min.css`, and `LICENSE`. Open the `harlowe-audio.min.js` file in a text editor, copy all of the contents, and paste it into your story JavaScript area in Twine 2. To find the story JavaScript area, click the up arrow next to your story's name in the editor (bottom left-hand side), then click the appropriate menu option.
 
-<image src='./assets/menu1.jpg' title='The story JavaScript menu option in the Twine 2 editor.' alt='The story JavaScript menu option in the Twine 2 editor.'>
+<img src='./assets/menu1.jpg' title='The story JavaScript menu option in the Twine 2 editor.' alt='The story JavaScript menu option in the Twine 2 editor.'>
 
 You'll then do the same thing with the `harlowe-audio.min.css` file, pasting it into the story Stylesheet area instead.
 
-<image src='./assets/menu2.jpg' title='The story Stylesheet menu option in the Twine 2 editor.' alt='The story Stylesheet menu option in the Twine 2 editor.'>
+<img src='./assets/menu2.jpg' title='The story Stylesheet menu option in the Twine 2 editor.' alt='The story Stylesheet menu option in the Twine 2 editor.'>
 
 > [!TIP]
 > You should open these files in a **text editor**, not a word processor. Any text editor you have, like notepad, will work fine for this. Opening the file in a word processor may cause the code to stop working, as they sometimes convert certain characters into other characters on loading files&mdash;like turning normal quotes (&quot;...&quot;) into curly quotes (&ldquo;...&rdquo;)&mdash;that can mess up programming code.
 
 Once all the code is in place, try playing your story. If you see a gray sidebar on the left with a white arrow at the top, and you don't encounter any errors popping up, you've installed it right!
 
-<image src='./assets/installed.jpg' title='If you have a sidebar like this and no errors, HAL has been installed correctly.' alt='If you have a sidebar like this and no errors, HAL has been installed correctly.'>
+<img src='./assets/installed.jpg' title='If you have a sidebar like this and no errors, HAL has been installed correctly.' alt='If you have a sidebar like this and no errors, HAL has been installed correctly.'>
 
 ## Defining Tracks
 
-There are a few ways to define tracks in HAL, but the easiest (and recommended) way is with a *special passage* called `hal.tracks`.
+There are a few ways to define tracks, but the easiest (and recommended) way is with a *special passage* called `hal.tracks`.
 
 > [!TIP]
 > **What is a Special Passage?**
 > A special passage is a concept from Twine 1 and SugarCube where certain passages with special names have meaning to the story format. Harlowe doesn't use special passages (though it does have [special tags](https://twine2.neocities.org/#section_passagetag)). All you need to know to create a special passage is what name to give it. So to make the special passage, create a new passage in your story and give it the name `hal.tracks`.
 
-<image src='./assets/tracks.jpg' title='An example of the tracks special passage.' alt='An example of the tracks special passage.'>
+<img src='./assets/tracks.jpg' title='An example of the tracks special passage.' alt='An example of the tracks special passage.'>
 
 In this special passage you'll define each track on its own line. Tracks require a name and a list of URLs that point to audio files (that means they end with an audio extension, like `.mp3` or `.ogg`). You can give a track a number of source URLs; if you do, they should be the same track just in different file formats. If you only want to use one file format, `.mp3` is the safest bet. If you have the capability to create duplicates of the track in different formats, including both `.mp3` and `.ogg` versions is recommended, as that combination will give you the maximum possible browser support.
 
@@ -87,7 +87,7 @@ On a basic level, all you need to do to play a track is have this code in a pass
 
 This is the `(track:)` macro, and you give it the name of a track you've defined and a command to perform. Some commands accept additional arguments, which you can just pass to the macro after the command name. For example, to set a track to loop, you'd write `(track: 'que-pena', 'loop', true)`. This is because the *loop command* accepts an argument, which should be boolean `true` or `false`; `true` to set the track to loop, `false` to stop it from looping.
 
-The lion's share of commands in HAL don't require any arguments, and very few commands require more than one, but when they do, they have to be given to the macro in the correct order, so you will need to check the docs for those.
+The lion's share of commands don't require any arguments, and very few commands require more than one, but when they do, they have to be given to the macro in the correct order, so you will need to check the docs for those.
 
 If you just want a looping background track and that's it, define the track in the `hal.tracks` special passage, then place the following code in a [`startup`-tagged passage](https://twine2.neocities.org/#passagetag_startup) or in your first passage:
 
@@ -99,11 +99,11 @@ If you just want a looping background track and that's it, define the track in t
 ```
 
 > [!NOTE]
-> When you write one of HAL's macros in the Twine 2 passage editor, it will show up colored in red like macros that don't exist. It is not possible for a library like HAL to edit Harlowe's syntax highlighting feature, so this is unfortunately impossible to fix. Just know that it's expected behavior and doesn't mean you did anything wrong.
+> When you write one of HAL's custom macros in the Twine 2 passage editor, it will show up colored in red like macros that don't exist. It is not possible for a library like this to edit Harlowe's syntax highlighting feature, so this is unfortunately impossible to fix. Just know that it's expected behavior and doesn't mean you did anything wrong.
 
 ## Examples
 
-Now that you've got HAL installed and you know how to define a few tracks and play them, we'll cover a bunch of common use-cases here. To see more complex examples and use-cases, and learn more about what you can do with HAL, look at the [reference documentation](v2).
+Now that you've got HAL installed and you know how to define a few tracks and play them, we'll cover a bunch of common use-cases here. To see more complex examples and use-cases, and learn more about what else you can do, look at the [reference documentation](v2).
 
 ### Defining Tracks with Absolute URLs
 
@@ -127,7 +127,7 @@ There are about a thousand reasons you *don't* want to use absolute URLs, even t
 
 - If the file is on the file system, users who download your game are going to have to go and place those files in exactly the same places on their systems. E.g., in the example above, a user would have to take your audio folder and literally manually place it in `C:` in a folder called `twine` or the audio just won't work.
 - If the file is hosted on the web and served via `http://` or `https://`, your game will require a web connection for audio, even when it's being played offline.
-- Whatever hosting service you use probably either serves an audio player rather than a song, or even if it does serve a song, it's probably against the Terms of Service of that website to *hot-link* to it. (Hot-linking is using someone else's website to host files for your website, and [it's widely frowned upon](https://tvtropes.org/pmwiki/pmwiki.php/Main/HotlinkedImageSwitch).)
+- Whatever hosting service you use probably either serves an audio player rather than a file, or even if it does point to a file, it's probably against the Terms of Service of that website to *hot-link* to it. (Hot-linking is using someone else's website to host files for your website, and [it's widely frowned upon](https://tvtropes.org/pmwiki/pmwiki.php/Main/HotlinkedImageSwitch).)
 - Relative URLs work basically everywhere, except, ironically, the two places arguably most important to Twine authors, in the Twine 2 application and on [philome.la](http://philome.la/), a free Twine game hosting service.
 
 In the big scheme of things, unless you plan to upload to [philome.la](http://philome.la/), I recommend relative URLs, warts and all.
@@ -143,11 +143,11 @@ que-pena: ./audio/que-pena.mp3, ./audio/que-pena.ogg
 
 Translation: `./` means to look in the current folder the current HTML file is in. So the file `./audio/beep.mp3` means that we look in our current folder for a folder named `audio` and look in *that* folder for our `beep.mp3` file. In other words, the folder containing our game looks like this: 
 
-<image src='./assets/folders1.jpg' title='Our folder containing our Twine project.' alt='Our folder containing our Twine project.'>
+<img src='./assets/folders1.jpg' title='Our folder containing our Twine project.' alt='Our folder containing our Twine project.'>
 
 Then, the inside of that `audio` folder looks like this:
 
-<image src='./assets/folders2.jpg' title='Inside the audio folder.' alt='Inside the audio folder.'>
+<img src='./assets/folders2.jpg' title='Inside the audio folder.' alt='Inside the audio folder.'>
 
 When we want to share our game with friends, all we have to do is zip this folder up and email it. Or rename the game's HTML file to `index.html` and drop it on [itch.io](https://itch.io/). Or drop the whole folder onto your website (depending on how its made and where its hosted). Or send it through [web2executable](https://github.com/jyapayne/Web2Executable) to make it into a `.exe` file. In other words, its ready for anything. Except, as mentioned in the previous example, [philome.la](http://philome.la/) and, more distressingly, the Twine 2 app.
 
@@ -246,6 +246,6 @@ You can wrap the `(track:)` macro to start playback of a track inside a `(link:)
 
 ## This Is Only the Beginning
 
-HAL supports many other features, including master audio controls, playlists, and audio groups, and there are many other track commands you can use. You can also change HAL's configuration settings, use JavaScript event handlers to plug into various audio events and even edit the sidebar to display a menu
+HAL has many other features, including master audio controls, playlists, and audio groups, and a variety of commands for all of it. You can also change the library's configuration settings, use JavaScript event handlers to plug into various audio events and even edit the sidebar to display a menu.
 
-To learn more, check out [HAL's documentation](v2). It's a bit drier and more technical than this guide, but it's worth reading if you have grander designs than what's been covered here.
+To learn more, check out [the reference documentation](v2). It's a bit drier and more technical than this guide, but it's worth reading if you have grander designs than what's been covered here.