<commit_before># php-htmlo

## Introduction

`htmlo` is for those people that find writing HTML tedious.  It provides
a short-hand way of writing HTML, but allows for richer markup than
techniques such as markdown.

For example:

    htmlo( '.h1: Hello, World!' );

will generate:

    <h1>Hello, World!</h1>

## Usage

Include `cl-htmlo.php` in the file that wants to use it.  An `exodep` file
for this is available at `exodep-exports/php-htmlo.exodep` which can be
copied and modified to your project to facilitate updates.

## Detail

`htmlo` has two main functions.  `htmlo()` echos the generated string to the
output, and `htmls()` returns the generated string - as a string.

In this overview the examples will talk about the string that is input to
either `htmlo()` or `htmls()` rather than expliciting showing these function
calls in the examples.  Thus the initial example shown above would be shown
as:

    .h1: Hello, World!

`htmlo` directives are line based.  `htmlo` directive lines consist of leading
whitespace followed by a `.`.  Any non-directive line is output unmodified.
HTML can be mixed into the output as needed (just by including it in the
input string).

For example:

    .p

will yield:

    <p>

Directives can optionally have content that follows a `:`. For example:

    .p: My paragraph

will yield:

    <p>My paragraph</p>

Note that when a directive contains content it is automatically closed.

The content can in fact be another directive.  For example:

    .i:.b: SHOUT

yields:

    <i><b>SHOUT</b></i>

With CSS, classes on tags are common.  A class is specified within single
quotes, for example:

    .p 'big': My para

will yield:

    <p class='big'>My para</p>

`div` and `span` with classes have special forms.  For example:

    .'my-class'

yields:

    <div class='my-class'>

and:

    .'my-class': important

yields:

    <span class='my-class'>important</span>

Two dots will create an end tag.  For example:

    ..p

will create:

    </p>

`htmlo` attempts to keep track of tag nesting, so two dots on their own
close the last opened tag.  For example:

    .p
        Text
    ..

will yield:

    <p>
        Text
    </p>

Similarly, 3 dots will close the current tag and then re-open it.  So:

    .p
        Text
    ...
        More Text
    ..

will yield:

    <p>
        Text
    </p>
    <p>
        More Text
    </p>

Note that each call to the `htmlo()` or
`htmls()` functions maintains their own tag stack.  Therefore tag nesting
can not be pushed in one function call and automatically popped in
a subsequent function call.

Three dots will close a tag and start a new one, for example:

    ...'my-class'

will cause:

    </div>
    <div class='my-class'>

Certain HTML elements have special handling.

In the case of the `a` element:

    .a http://codalogic.com: My home page

yields:

    <a href='http://codalogic.com'>My home page</a>

As a CSS class is always in single quotes, both the following:

    .a 'my-class' http://codalogic.com: My home page
    .a http://codalogic.com 'my-class': My home page

yield:<commit_msg>Re-ordered some of the README documentation<commit_after># php-htmlo

## Introduction

`htmlo` is for those people that find writing HTML tedious.  It provides
a short-hand way of writing HTML, but allows for richer markup than
techniques such as markdown.

For example:

    htmlo( '.h1: Hello, World!' );

will generate:

    <h1>Hello, World!</h1>

## Usage

Include `cl-htmlo.php` in the file that wants to use it.  An `exodep` file
for this is available at `exodep-exports/php-htmlo.exodep` which can be
copied and modified to your project to facilitate updates.

## Detail

`htmlo` has two main functions.  `htmlo()` echos the generated string to the
output, and `htmls()` returns the generated string - as a string.

In this overview the examples will talk about the string that is input to
either `htmlo()` or `htmls()` rather than expliciting showing these function
calls in the examples.  Thus the initial example shown above would be shown
as:

    .h1: Hello, World!

`htmlo` directives are line based.  `htmlo` directive lines consist of leading
whitespace followed by a `.`.  Any non-directive line is output unmodified.
HTML can be mixed into the output as needed (just by including it in the
input string).

For example:

    .p

will yield:

    <p>

Directives can optionally have content that follows a `:`. For example:

    .p: My paragraph

will yield:

    <p>My paragraph</p>

Note that when a directive contains content it is automatically closed.

The content can in fact be another directive.  For example:

    .i:.b: SHOUT

yields:

    <i><b>SHOUT</b></i>

With CSS, classes on tags are common.  A class is specified within single
quotes, for example:

    .p 'big': My para

will yield:

    <p class='big'>My para</p>

`div` and `span` with classes have special forms.  For example:

    .'my-class'

yields:

    <div class='my-class'>

and:

    .'my-class': important

yields:

    <span class='my-class'>important</span>

Two dots will create an end tag.  For example:

    ..p

will create:

    </p>

Three dots will close a tag and start a new one, for example:

    ...'my-class'

will cause:

    </div>
    <div class='my-class'>

`htmlo` attempts to keep track of tag nesting, so two dots on their own
close the last opened tag.  For example:

    .p
        Text
    ..

will yield:

    <p>
        Text
    </p>

Similarly, 3 dots on their own will close the current tag and then re-open it.  So:

    .p
        Text
    ...
        More Text
    ..

will yield:

    <p>
        Text
    </p>
    <p>
        More Text
    </p>

Note that each call to the `htmlo()` or
`htmls()` functions maintains their own tag stack.  Therefore tag nesting
can not be pushed in one function call and automatically popped in
a subsequent function call.

Certain HTML elements have special handling.

In the case of the `a` element:

    .a http://codalogic.com: My home page

yields:

    <a href='http://codalogic.com'>My home page</a>

As a CSS class is always in single quotes, both the following:

    .a 'my-class' http://codalogic.com: My home page
    .a http://codalogic.com 'my-class': My home page

yield:
{'fraction_non_alphanumeric': 0.09355509355509356, 'fraction_numerical': 0.0015992323684631377, 'mean_word_length': 2.879652605459057, 'pattern_counts': {'":': 0, '<': 53, '<?xml version=': 0, '>': 53, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3537045', 'n_tokens_mistral': 2066, 'n_tokens_neox': 1919, 'n_words': 879}