Skip to content

Commit

Permalink
added first 2 docs pages
Browse files Browse the repository at this point in the history
  • Loading branch information
@zehanort
zehanort committed Nov 24, 2023
1 parent c7f49a7 commit b64dba7
Show file tree
Hide file tree
Showing 2 changed files with 265 additions and 0 deletions.
64 changes: 64 additions & 0 deletions docs/pages/1_Introduction.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
---
title: Installation & First Usage
layout: default
permalink: /intro/
nav_order: 1
---

## Installation

You can install the iffinity engine via the npm registry:

```
npm i iffinity -g
```

After that, the `ifc` command line tool becomes available:

```
$ ifc -h
~~~ The iffinity engine compiler ~~~
Running ifc with no command is equivalent to running ifc compile.
For help and options of a specific command, run:
ifc <command> --help/-h (e.g. ifc show --help)
Usage: ifc [command] [commandOptions]
Commands:
ifc compile [options] Compile the project in the given directory to a single
HTML file [default]
ifc init Create a new iffinity project in the current directory
ifc edit [options] Edit the configuration file of the project
ifc show [options] Show several project details
Options:
-p, --projectRoot The root directory of the project (if not specified, the
current directory is used) [string]
-c, --config Specify a configuration file for your project (default:
<projectRoot>/iff-config.json) [string]
-o, --outputFile The output HTML file path [string]
-v, --version Show iffinity engine version number [boolean]
-h, --help Show help [boolean]
```

## First usage

You can create a story right away, without editing a single file! To do that, create a new dictionary, navigate into it and run:

```
ifc init
```

This command will walk you through creating a very basic iffinity project, much like how `npm init` does it. Creating an iffinity project essentially means creating the project's configuration file.

The last question that the `ifc init` command will ask you is whether you want it to create a template project for you. Hit enter and an `example.ejs` file (along with the `iff-config.json` configuration file) will have appeared in your directory!

The `example.ejs` file contains an example story, with a single snippet. Run:

```
ifc
```

to compile the project. Once the compilation is done, an HTML file will have appeared in your directory. Open it with the browser of your choice and enjoy your first story!
201 changes: 201 additions & 0 deletions docs/pages/2_CLI.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,201 @@
---
title: The command line interface
layout: default
permalink: /cli/
nav_order: 2
---

The author interacts with the iffinity engine via the `ifc` (iffinity compiler) command line tool:

```
$ ifc -h
~~~ The iffinity engine compiler ~~~
Running ifc with no command is equivalent to running ifc compile.
For help and options of a specific command, run:
ifc <command> --help/-h (e.g. ifc show --help)
Usage: ifc [command] [commandOptions]
Commands:
ifc compile [options] Compile the project in the given directory to a single
HTML file [default]
ifc init Create a new iffinity project in the current directory
ifc edit [options] Edit the configuration file of the project
ifc show [options] Show several project details
Options:
-p, --projectRoot The root directory of the project (if not specified, the
current directory is used) [string]
-c, --config Specify a configuration file for your project (default:
<projectRoot>/iff-config.json) [string]
-o, --outputFile The output HTML file path [string]
-t, --testFrom Test the story from a different snippet than the start
snippet [string]
-v, --version Show iffinity engine version number [boolean]
-h, --help Show help [boolean]
```

## The `init` command

As explained in the previous page, the `init` command aims to help the author create a stub for their iffinity project. It covers the required fields of the [configuration file](???) (as well as a bit more), and optionally creates an example game as a template. It is heavily inspired by the behavior of `npm init`. Note that it is preferable to run `ifc init` in a newly created, empty directory.

## The `compile` command

```
$ ifc compile -h
ifc compile [options]
Compile the project in the given directory to a single HTML file
Options:
-p, --projectRoot The root directory of the project (if not specified, the
current directory is used) [string]
-c, --config Specify a configuration file for your project (default:
<projectRoot>/iff-config.json) [string]
-o, --outputFile The output HTML file path [string]
-t, --testFrom Test the story from a different snippet than the start
snippet [string]
-v, --version Show iffinity engine version number [boolean]
-h, --help Show help [boolean]
```

The default command (i.e. `ifc compile` is the same as `ifc`). It expects to find an iffinity configuration file with the name `iff-config.json` in the current directory (if the `-c` flag is not specified) and attempts to compile the project into a single output HTML. The command's options are pretty self-explanatory from the help message above. An example of running `ifc` on the template project that `ifc init` creates:

```
$ ifc
Config checks
Story title: test
Story author name: sotiris
Story version: 1.0.0
Basic sanity checks
Found 2 snippet(s) across 1 file(s).
Found 1 starting snippet(s).
So far so good. Compiling...
Rendered game saved to test.html. Enjoy!
```

### Testing from a different snippet

By using the `--testFrom/-t` option, you can instruct `iffinity` to compile your story to an HTML named (by default) `<story name>_from_<testing snippet>.html` where the snippet provided will be the starting snippet instead of the one with the `start` attribute. This facilitates rapid testing of specific snippets without having to change the `start` attribute in your source code every time.

## The `edit` command

```
$ ifc edit [options]
Edit the configuration file of the project
Options:
-c, --config Specify a configuration file for your project
(default: <projectRoot>/iff-config.json)[string]
--title Change the title of the story [string]
--author-name Change the name of the story author [string]
--author-email Change the email of the story author [string]
--story-version Change the version of the story [string]
--repo Change the repository of the story [string]
--add-lib-scripts Append library script(s) to the story [array]
--remove-lib-scripts Remove library script(s) from the story [array]
--clear-lib-scripts Remove all library scripts from the story
[boolean]
--add-lib-styles Append library style(s) to the story [array]
--remove-lib-styles Remove library style(s) from the story [array]
--clear-lib-styles Remove all library styles from the story
[boolean]
--add-story-scripts Append story script(s) to the story [array]
--remove-story-scripts Remove story script(s) from the story [array]
--clear-story-scripts Remove all story scripts from the story[boolean]
--add-story-styles Append story style(s) to the story [array]
--remove-story-styles Remove story style(s) from the story [array]
--clear-story-styles Remove all story styles from the story [boolean]
--add-global-scripts Append global script(s) to the story [array]
--remove-global-scripts Remove global script(s) from the story [array]
--clear-global-scripts Remove all global scripts from the story
[boolean]
--add-script-tag-rule Add a tag rule to the story, along with the
corresponding script(s) [array]
--remove-script-tag-rule Remove a tag rule from the story, along with the
corresponding script [string]
--add-style-tag-rule Add a tag rule to the story, along with the
corresponding style(s) [array]
--remove-style-tag-rule Remove a tag rule from the story, along with the
corresponding style [string]
-v, --version Show iffinity engine version number [boolean]
-h, --help Show help [boolean]
Examples:
ifc edit --story-version 1.1.0
ifc edit --repo https://github.com/user/repo.git
ifc edit --add-global-scripts global-vars.js global-logic.js
ifc edit --add-script-tag-rule 'TAG1 && !TAG2' script1.js script2.js
ifc edit --remove-style-tag-rule 'TAG1 || TAG2'
```

A utility command to help the author edit the configuration file in an automatic, non-manual way. The help message as well as the examples above are pretty self-explanatory. Note that it is totally OK to edit the configuration file manually.

## The `show` command

```
ifc show -h
ifc show [options]
Show several project details
Options:
-p, --projectRoot The root directory of the project [string]
-c, --config Specify a configuration file for your project (default:
<projectRoot>/iff-config.json) [string]
-s, --snippets Show all snippets in the project [boolean]
-t, --tags Show all tags in the project [boolean]
-g, --graph Show the snippet graph of the project [boolean]
-v, --version Show iffinity engine version number [boolean]
-h, --help Show help [boolean]
```

The `show` commands aims to help the user gain insight on their project, especially as it grows larger and larger. It's 3 main options as of v0.2.0 are the following:

### `ifc show --snippets`

The `--snippets/-s` option shows a tree of each file in the project that contains at least one snippet, accompanied by the details of each snippet (name, tags, scripts, styles, whether it is the starting snippet).

Running it on the [convoluted example](https://github.com/zehanort/iffinity/tree/main/examples/convoluted):

```
$ ifc show --snippets
Snippets in project Three Snippets
(files relative to project root: <path>/iffinity/examples/convoluted)
|
├── some-snippets.ejs
│ ├── Magic Place
│ │ ├── tags: THE_WILD
│ │ ├── scripts: scripts/mp1.js, scripts/mp2.js
│ │ └── styles: styles/mp.css
│ ├── Intro [START]
│ └── Square
└── the-castle/the-castle.ejs
└── Castle
└── tags: THE_WILD, CASTLE
```

### `ifc show --tags`

The `--tags/-t` option shows a list of all the tags in the project, accompanied by the list of all the snippets that contain them.

Running it on the [convoluted example](https://github.com/zehanort/iffinity/tree/main/examples/convoluted):

```
$ ifc show --tags
Tags in project Three Snippets
(files relative to project root: /home/sotiris/projects/intfiction/iffinity/examples/convoluted)
|
├── THE_WILD
│ ├── Magic Place (some-snippets.ejs)
│ └── Castle (the-castle/the-castle.ejs)
└── CASTLE
└── Castle (the-castle/the-castle.ejs)
```

### `ifc show --graph`

This is an **EXPERIMENTAL** option. Running it will open a browser window with an interactive graph of the story snippets and their links. The starting snippet is drawn in blue, while all others in green. Interactive *doesn't* mean editable; there is no way to affect the project via the graph. In other words, it is a read-only view of the project.

0 comments on commit b64dba7

Please sign in to comment.