sitelen anpa ilo v0.1 rules

The easy way to write in all Toki Pona scripts at the same time

Introduction

This document contains the rules and principles of sitelen anpa ilo (Toki Pona markdown) as they stand, and lays the groundwork for future improvement.

I might be the one who hatched this idea but, as they say, it takes a village. So I need to ask you:

What more does this need to be truly useful to you?
Could you help with building converters such as Discord bots or plugins for wikis and content generators?
Can you help out with coordinating updates to this standard?

Reach out to me on Discord. I look forward to hearing from you.
-jan Telakoman

Design goals

Be easy to learn, easy to use
Open doors to wider use of sitelen pona on:
- Personal blogs and websites
- Online chat environments
- Collaborative projects such as zines and wikis
Be flexible and forgiving. Always output legible sitelen pona, even if the writer’s preferences are unavailable, or the writer just writes in normal Latin script
Be compatible with other flavours of Markdown

Concepts

sitelen anpa ilo is a way of writing in Toki Pona. It is “input” that determines how “output” should be in Latin script, sitelen pona, and (soon) other Toki Pona scripts.

The writer is the person who writes in Toki Pona using sitelen anpa ilo. A converter is any application or tool that takes the writer’s text and converts it into Latin script, sitelen pona, or other Toki Pona scripts.

sitelen anpa ilo is font agnostic. The writer tells the converter what they want, the converter gives that to them in the output font if possible.

This document is a specification for both writers and converter developers. It tells writers what is valid sitelen anpa ilo text, and it tells developers how sitelen anpa ilo text should convert into other Toki Pona scripts.

Versioning

Full versions come with a backward compatibility promise. In other words, text that is valid according to sitelen anpa ilo v1.0, v2.0, v3.0 and so on will always be valid and continue to be converted to output in the same way, no matter what is introduced in future updates and versions.

Updates between versions may or may not be compatible with each other. The current version is v0.1. Things could change in v0.2 so that valid text under v0.1 might be invalid or converted differently under v0.2. But when we are sure, we will issue the first full version, v1.0.

Defaults

If we take normal Toki Pona text (written in Latin script according to established conventions) and treat it as sitelen anpa ilo, it will be converted into usable sitelen pona. This is thanks to the following defaults.

Cartouches

In sitelen anpa ilo, a word that starts with capital letter and follows Toki Pona rules for names is a Name and must be converted into a cartouche in sitelen pona.

If the writer does not specify otherwise, glyphs used in a cartouche are chosen from the following list of default cartouche glyphs. This list exists to make behaviour predictable, and these glyphs were chosen to be legible and neutral. Try it.

awen for a
e for e
ilo for i
jan for j
kiwen for k
li for l
moku for m
nasa for n
o for o
pilin for p
sona for s
tan for t
uta for u
wawa for w

Default cartouche glyphs may be adjusted in v0.2 based on feedback

Later on in the document you will find the ways that writers can customize default cartouche glyphs and/or specify which glyphs to use for which Name.

Punctuation

Punctuation in sitelen anpa ilo is left as-is in sitelen pona or Latin script output, with the following exceptions.

Interpuncts

By default, periods in sitelen anpa ilo are converted to interpuncts in sitelen pona, but left as periods in Latin script. Try it. See below for how writers can customize this.

Question marks

By default, question marks in sitelen anpa ilo are converted to interpuncts in sitelen pona, but left as question marks in Latin script. Try it. See below for how writers can customize this.

Syntax

sitelen anpa ilo includes the following syntax elements.

An extender is a plus sign when used with a word or cartouche: +
A modifier is a minus sign when used with a word or cartouche: -
A selector is a period when used with a word: .
A command follows the pattern +( setting : value ). When the converter finds a command in the text it tries to understand and apply the command from that point forward, and does not include the command itself in the output.

For developers, a command is defined as “a plus sign immediately followed by a parenthesis, if that parenthesis contains alphanumeric values (which might include spaces) separated by a colon.”

We will see more about how to use these below.

Cartouches

Updating default cartouche glyphs

The command +(pn ok: word word word ) tells the converter to take each word, find the word in the list of default cartouche glyphs that starts with the same letter, and replace it with that word. Try it.

“pn” is for “poki nimi”
“pn ok” is for “poki nimi [la] o kepeken”

If the command contains more than one word that starts with the same letter, the last word is the one that will be used. So, for example, if the writer gives the command +(pn ok: kasi ken kepeken kala) the converter will use kala for k. Try it.

Name-specific cartouches

The command +(pn Name : word word word ) tells the converter to use word word word for the cartouche whenever it converts Name to sitelen pona. Try it. Note that Name must start with a capital letter and follow Toki Pona rules for names.

Issuing another command for the same Name will update the setting in the converter from that point forward. Try it.

Note that the converter will not “police” you to make sure that the first letter of each word matches each letter of Name. You can use whichever words you like, as few or as many. Try it.

Short cartouches

Using a modifier - immediately after a Name will tell the converter to use a short cartouche. What is in the short cartouche will depend on the writer’s commands.

If the writer has given no commands for that Name, the converter will match the first letter of the Name with a word from the list of default cartouche glyphs and use that. Try it.
If the writer has already given a +(pn Name : word word word ) command, the converter will use the first word from that command. Try it.
If the writer has given a +(pnl Name : word ) command, this overrides everything else. This is a command to use word specifically in short cartouches for Name. Try it. It can be any word, it can even be more than one word. Try it. After such a command, a +(pn Name : word word word ) command will not change the short cartouche setting for Name.

“pnl” stands for “poki nimi lili”

Compound glyphs

If the writer uses an extender + between words instead of a space, the converter will combine them to form a scaled compound glyph. Try it.

In v0.2:

The modifier - will be used for stacked glyphs

The converter will check to make sure the chosen font supports the compound glyph selected by the writer. If it doesn’t, the converter will fall back to using separate glyphs for each word.

Extended glyphs

If the writer uses one or more extenders + immediately after the word “pi”, the converter will extend “pi” to include that number of glyphs following it. A compound glyph counts as one glyph. Try it.

In v0.2:

This behaviour will be extended to all other words that support it

Extenders + added immediately before a word will be converted to pre-extended glyphs

The converter will check to make sure the chosen font supports extensions or pre-extensions for a glyph when a writer adds extenders before for after it

Variant glyphs

To select a variant sitelen pona glyph once, the pattern is word.option.

Definition: “A Toki Pona word, immediately followed by a selector, immediately followed by the code for the option.”

When a writer selects a variant glyph, the converter will use it in sitelen pona if it is supported by the chosen font. The selector and option are ignored for Latin script output. Try it. If the variant glyph is not supported by the chosen font, the converter will fall back to the standard glyph. Try it.

To always select a variant form of a glyph, the command is +(sp word : option ). From that point on, the converter will attempt to use the variant glyph for each occurrence of word. Try it. The writer can update this preference with another command, or override it with word.option. Try it.

Variant glyphs supported in v0.1 are as follows.

word	option	Description
ni	anpa	ni pointing down (standard)
ni	monsi	ni pointing to the left
ni	poka	ni pointing to the right
ni	sewi	ni pointing up
sewi	nasin	religious sewi (standard)
sewi	poki	box-style sewi

This list will be expanded for v0.2. This was enough for v0.1 because the purpose is to demonstrate the concept, and this is one of the areas where feedback will be especially helpful. There are decisions to be made about how to handle randomized variants such as ko and jaki, and option codes need to be finalized.

Punctuation

Interpuncts

The following commands affect interpuncts:

Command	Meaning
`+(sm:1)`	Convert periods to interpuncts in all scripts (basically 1 means, “yes we want interpuncts”). Try it.
`+(sm:0)`	Leave periods as periods in all scripts. Try it.
`+(sm sp:1)`	Convert periods to interpuncts in sitelen pona (default behaviour)
`+(sm sp:0)`	Leave periods as periods in sitelen pona
`+(sm sl:1)`	Convert periods to interpuncts in Latin script
`+(sm sl:0)`	Leave periods as periods in Latin script (default behaviour)

Where a sitelen pona font cannot support the interpunct behaviour selected by the writer, the converter will fall back on default behaviour.

“sm” is for “sitelen meso”
“sm sl” is for “sitelen meso [lon] sitelen Lasina”

Question marks

The following commands affect question marks:

Command	Meaning
`+(sws:1)`	Leave question marks as question marks in all scripts (basically, 1 means “yes we want question marks”) Try it.
`+(sws:0)`	Convert question marks to periods/interpuncts in all scripts. Try it.
`+(sws sp:1)`	Leave question marks as question marks in sitelen pona
`+(sws sp:0)`	Convert question marks to periods/interpuncts in sitelen pona (default behaviour)
`+(sws sl:1)`	Leave question marks as question marks in Latin script (default behaviour)
`+(sws sl:0)`	Convert question marks to periods/interpuncts in Latin script

Note: In the table above, “period/interpunct” means that the output will be a period or an interpunct based on the current behaviour for periods.

Where a sitelen pona font cannot support the question mark behaviour selected by the writer, the converter will fall back on default behaviour.

“sws” is for “sitelen pi wile sona”

Wishlist for v0.2

Mentioned above:

Finalize the default cartouche glyph list
Expand the list of option codes for variant glyphs
Support using the modifier - for stacking glyphs
Say that converters must support extended glyphs for all words that support it and not just pi
Say that converters must support pre-extended glyphs
Say that converters must verify font support for extenders, pre-extenders, compound word combinations (scaled or stacked)

More ideas:

Support cartouche chains
Have a command for default cartouche behaviour (normal, short, Latin script?)
Support interpuncts and undermarks in cartouches (use period and comma?)
Have commands that skip text in sitelen pona or Latin script
Support indentation in sitelen pona (how would we mimic this in Latin script? Just tabs?)

Written with StackEdit.