Textual is a text-to-CSS conversion engine that takes formatted plain-text as the input, and spits out a valid, well-formed stylesheet as the output. It uses intuitive indentation to establish dependencies between selectors, and allows the use of variables to automate repetitive tasks such as defining colours, sizes, or complete attributes. You can test it out at the demo page.

Table of contents

• Selectors
• Variables
• Attributes
• Comments
• Symbols
• Package Usage

---

Selectors

Every selector must begin with a space of a line between the last block of declarations and the new block. Textual supports dependencies up to a depth of 3, beyond which it will not recognise the selector.

Every top level selector (referred to as parent in this documentation) must start from the extreme left of the line. That means no spaces or tabs before it. This establishes that selector as the parent for all selectors following it until the next parent selector is encountered.

.selector:
    attribute:value
    attribute:value

    .child-1
        attribute:value

        .child-2
            attribute:value

.selector-2

The above code block will create a dependency between .child-1 and .selector, but define .selector-2 as a separate declaration. The output CSS will be:

.selector { ... }
.selector .child1 {attribute:value}
.selector .child1 .child2 {attribute:value}
.selector-2 { ... }

Remember: Any dependency between two selectors has to be marked by an extra tab space which was used to demarcate the previous selector, up to 2 tab spaces (for the third level selector).

---

Variables

Textual allows you to define variables, which can be reused anywhere and in any way you want. It’s left completely to your creativity. Some standard uses would be to define custom colours, or attribute:value pairs which can be referenced repetitively, saving you the time of writing them again. Variables can be defined anywhere in the document, from the beginning of the line, using the format:

[variable_name]: value

And then when you need to use it, call it using:

.selector:
    attribute: [variable_name]

Remember: Variable definitions should start from the beginning of the line. Spaces and tabs before the definitions should work, but you might get unexpected results.

---

Attributes

Attributes remain the same as in traditional CSS, with the one rule that they should be indented to one more tab space than the selector they belong to. Hence, a first level child will have attributes with two tab spaces, and a second level child will have attributes with three tab spaces before them:

.top-selector:
    /* attributes for top */

    .child-1:
        /* attributes for child1 */

        .child-2:
            /* attributes for child2 */

Remember: Attributes given more than three tab spaces will be discarded, or might result in unexpected behaviour at this point.

---

Comments

You can now use normal programming-syntax like comments throughout your stylesheet, wherever you want. This includes single line comments with //, or block level comments with /* .. */. You can also add one line section-demarcating comments using more than three symbols like ` and * in a row, followed by whatever you like. Hence, all of the following are valid:

.selector:              //this is a comment
    attribute:value     /*this works too*/

/* block level comments
* that just aims to 
* please
*/

``````SECTION2``````
*****SECTION3******

Remember: The final output will contain no trace of these comments, to keep the output as compact as possible. Since the output is dynamically generated, your source file will be untouched, hence your comments can be anything you like.

---

Symbols

Symbols are just an extension of variables, and can be used to make things easier. Currently, only the [!] symbol is pre-defined, which is substituted for !important, to mark priority attributes. You can define more and use them at your leisure, but I’ll suggest you let me know if you do. The more pre-defined symbols, the merrier.

---

Package Usage

There are two functions defined each to convert Textual markup to CSS, and to convert it back. The functions are as follows:

• Use Enginize_str($string) to convert a string of markup to CSS. Pass the string as an argument, and the function will echo (not return) the converted string. Use Enginize_file($string) to convert a file, taking the file path as the argument. Make sure the file is in plain text (ANSI/UTF-8).

• Use textual_str($string, $echo=1) and textual_file($string, $echo=1) (using the respective prototype as above) to convert CSS back to Textual markup. The functions take an extra integer argument to decide if you want to return the string or output it. The default value is ‘1’, which gives the output. This is in case you want to convert your existing CSS to Textual, and then back (for minification and validity).

Some considerations

A tab space is defined as four spaces, or one use of the TAB key. It is necessary to get this clear because Textual only checks for tab spaces, and not general one character white spaces. However, as a failsafe, there is a self-conversion mechanism which converts consecutive four white spaces to one literal tab, so it shouldn’t be much of a problem.

Every block of definitions should be separated by an empty line. If there is no empty line between definitions for two selectors, the following selector will be skipped, and it’s attributes will be appended to the former selector. This is done on purpose, to keep the visual presentation as organised and clean as possible.

The minification of the output CSS is a little crude, in the sense that there is no attribute merging, and new line removal. There is a function to clean up punctuations, and the output itself is a line-wise approach, rather than a segment wise one. You can always run the output CSS through CSSTidy if you want a segmentised output. There will be a configuration setting to toggle the output in the future.

Disclaimers

Textual is not a substitute for CSS. Your browser will not be able to render Textual markup as it is, and you will need the engine to translate your source into valid CSS. This will happen at the server level, so visitors shouldn’t see any difference whatsoever.

Textual is not be used in productions, as it is still in alpha. If you do use it however, it is at your own risk, but let me know so that I can link to it.

Textual is released under a GPL License, and it is free to use for personal projects. If you’re using it for commercial purposes, I request a donation to keep sustain the project. Any and all contributions are welcome.