i17on

Hello, world!

i17on is an intranationalization engine optimized for the output of dynamic documentationa Markdown-based document system you can programa software package for dynamic text documents.

Check it out on GitHub.

Full Documentation

Hide example code.

Show example code.

# Hello, world!

_i17on_ is {

    complex:
		an *intra*nationalization engine optimized for the output of
		dynamic documentation              



    |-tech:
		a _*Markdown*_-based document system you can program       



    |-
		a software package for dynamic text documents           


}.

Check it out on [GitHub](http://github.com/Yuffster/i17on).

Full Documentation

i17on is a text preprocessor which allows you to write dynamic documents using a simple tag-based language.

You can write your document once in i17on, then disable and enable tags as necessary to tailor the text to a wide variety of target audiences.

i17on intelligently ensures that the whitespace of your document is normalized for English sentences and paragraphs. It's also Markdown-aware, meaning that you can include lists, code, headings, bold and italicised text, and many other features which will work in the way you expect.

Other formats can also be used, such as HTML.

Currently the output of the compiler is provided as the raw processed document, which can be sent to other libraries such as pandoc for proper formatting.

Installation

From Git

git checkout git@github.com:Yuffster/i17on.git
cd i17on
python setup.py install

Using Pip

pip install i17on

Usage

The setup.py script will provide you with an i17on command.

You can also call the script without installing by typing python -m i17on from the root directory of this repository.

The i17on command takes the input file as its first parameter. The rest of the parameters are a list of tags which will be set to True for the purpose of output generation.

i17on input.md foo bar bizz

stdin

You can also use stdin instead.

cat input.md | i17on foo bar bizz

debug

The debug mode can be enabled by using --debug, and will output the AST and other helpful information for resolving issues with a particular input file, or the library itself.

It can be placed before, after, or in the middle of tags.

i17on input.md --debug

Syntax Documentation

Dynamic tags

The most basic syntax of i17on is to use a tag, marked by curly braces.

The string of text preceeding the colon is the conditional, in this case just one tag. The text will show up if foo is set to true.

Hello {foo:world}

If you pass this input through i17on, you'll get the following output, based on whether or not the foo tag is set.

foo output
False Hello
True Hello world

Branches

Additional conditionals can be added to a single tag by using the |- (branch) separator.

Hello {foo:this is foo|-bar:this is bar}.

This is very similar to a standard if/else statement. For example, the document above could also be described like this:

python if foo: print("foo") elif bar: print("bar")

foo bar output
False False Hello.
True False Hello this is foo.
False True Hello this is bar.
True True Hello this is foo.

Notice that if foo and bar are True, it will output the conditional branch for foo and stop before checking for other matching conditions.

Default branches

If no condition is provided for a branch, it will always be evaluated as True. This allows you to add a default branch to be executed if none of the preceding conditions are True.

Hello {foo:this is foo|-bar:this is bar|-world}.
foo bar output
False False Hello world.
True False Hello this is foo.
False True Hello this is bar.
True True Hello this is foo.

If we move the default statement to the middle of our tag, we'll get "Hello world" regardless of the value of bar.

Hello {foo:this is foo|-world|-bar:this is bar}.
foo bar output
False False Hello world.
True False Hello this is foo.
False True Hello world.
True True Hello this is foo.

Conditional Clauses

AND

You can combine conditions using a comma, in which case all of them have to be True. For example, foo,bar is analogous to if foo and bar in normal code.

Hello {foo,bar:foo and bar}
foo bar output
False False Hello
True False Hello
False True Hello
True True Hello foo and bar

This is analogous to saying if foo and bar in normal code.

OR

You can combine conditional clauses using the semicolon operator, in which case all of them have to be True.

foo;bar is analogous to if foo or bar, and foo,bar;bizz is analogous to if (foo and bar) or (bizz).

Hello {foo;bar:foo or bar}
foo bar output
False False Hello
True False Hello foo or bar
False True Hello foo or bar
True True Hello foo or bar

Negation

Prepending a tag with an exclaimation point (!) will negate that tag.

Hello {foo,!bar:foo and not bar}
foo bar output
False False Hello
True False Hello foo and not bar
False True Hello
True True Hello

Whitespace

In a more complex document, you might want to nest arbitrary whitespace. The compiler is designed to intelligently discard unnecessary spacing.

Here, we have more readable spacing, which will produce the same output as our earlier example.

Work is ongoing to ensure that the compiled document conforms to expectations concerning English grammar, as well as Markdown specifics, such as indented lists and code examples.

Hello {
    foo:
        this is foo
    |-bar:
        this is bar
    |-
        world
}.
foo bar output
False False Hello world.
True False Hello this is foo.
False True Hello this is bar.
True True Hello this is foo.

Nesting

Tags can be nested within other tags.

Hello {
    foo:
        this is foo {bar:and bar}
    |-
        world
}.
foo bar output
False False Hello world.
True False Hello this is foo.
False True Hello this is bar.
True True Hello this is foo and bar.