Stylz Cheatsheet

Copyright (C) 2015 by Steve Litt.
When stable this page will have an open-content license.

Identifiers

An entity is a markup tag and the text it affects. The markup tag consists of an entity group letter, an entity letter, a class designation (basically its style), and an id designation. All letters and designations must be lower case, consisting of only letters, numbers and the underscore character. The following is an example of a top level header with id "myid", followed by a paragraph of class "showoff" with id "cool_paragraph", followed by a standard body text paragraph:

:h1,myid: This is my top level header.

:pp.showoff,cool_paragraph: Isn't this an outstanding paragraph? Wow!

This is just a normal, everyday, body text paragraph.
Notice you don't need to mark it up in any way. Fast!
Notice that the paragraph continues until a blank line or
until a container tag. This is true of all paragraph
type entities.

In the preceding example, note that the strings "h1,myid" and "pp.showoff,cool_paragraph" are identifiers. For a paragraph type entity, the identifier consists of everything between the colon at the start of the line to the next colon. The identifier consists of the entity group letter, followed by the entity letter, optionally followed by a period and the class name, and then optionally followed by a comma and the ID. If there's an ID but no class name, you just skip the dot and the class name. However, when there's a class, it must always appear before the ID.

Types of Entity Groups

Type Code Comment
Paragraph :identifier: At start of line.
String ::identifier{content} within line. Can't transcend paragraphs, not nestable in Version 1 (V1)
Token :;key;: within line. key must contain only a-z and "/" and "_" and ".".
No uppercase, no whitespace. Sorry.
key can be a filename whose contents
define the value replacing the key,
or a special key like _contents_ ,
_index_ and the like. Only special
keys may begin with underscore. Special
keys must begin with an underscore.
Container !!bidentifier
or !!eidentifier
(begin/end) on its own line. Not nestable in Version 1 (V1).
Include @@identifier filename At start of line, must occur on a single line.
Must be preceded and followed by blank lines.
Only one level of inclusion is possible.

List of entity groups

Group Ltr V1? Type Comment
Paragraph p Y Paragraph If markup absent, it's a default body text paragraph
Hierarchical Header h Y Paragraph h1 thru h9, does not necessarily correspond with final HTML output <h1> thru <h9>
Outline member o ? Paragraph o1 thru o9, always wordwraps. If you want it not to word-wrap,
that must be handled through a class (style). A non-outline
paragraph member ends the current outline. There will be provision
for outline numbering, though not necessarily in V1.
String s Y String Can't transcend paragraphs, not nestable in Version1 (V1)
Container c Y Container Must contain whole paragraphs.
Import i Y String Content is attribs of element
formatted in HTML without quotes.
Used for images, sounds, videos, text, etc.
Reference r Y/N String Content contains ID, URL or filepath of target material.
URL u Y String Content is attribs of url
formatted in HTML without quotes.
Used for Links: Offpage references to
other material.
Target t ? Container??? Content contains text of reference.
Not well defined yet.
Frame f N String Must contain whole paragraphs or other stuff.
Include n Y Include 1 line, blank lines before and after, 1 level of inclusion.
Token k Y Token Use anywhere appropriate.

Entities By Group

Note:

The letter "z" for entity groups and for entities is reserved for user-created enhancements. Stylz will never ship with a "z" entity group or entity, nor will it ship with any code that specifically acts on such entity groups or entities.

About Comments

Comments, whether container comments, or paragraph comments, are a special case that acts a special way, because they're preprocessed out of the file right after applying backslash escaping, and before anything else.

Container comments can be applied to partial paragraphs. Their removal from inside a paragraph does not split the paragraph in two: They are replaced by nothing, not even a blank line. Paragraph comments must occur at the start of a line and comment out only the line they start: Not the remainder of the paragraph.

There are no string paragraphs because that would be too complicated. If you need a string comment, just break the line within its paragraph until the string you want to comment out is on a single line.

Escaping characters

You can escape any character except whitespace by preceding the character with a backslash. The usual reason to do this is to make the character literal when it might otherwise be construed as a Stylz entity. For instance:

The way to comment a line is to use :pm: at the start of the line.

In the preceding, if word-wrapping put the ":pm: at the front of a line, the whole line would disappear from the output. This is prevented as follows:

The way to comment a line is to use \:pm: at the start of the line.

The first operation of Stylz to Xhtml conversion is to change backslash escaped characters to special escaped forms of the letter that can't be mistaken for Stylz entities. The final step in the conversion is to reconvert the escaped forms back to their original character.