Compact Web Language (COWEL)

Contents

1. Introduction

COWEL is a markup language with TeX-like syntax, intended to generate HTML documents, mainly for proposals and technical text. Many of its features are purpose-built for use in WG21, such as for writing C++ proposals.

2. Motivation

Many similar tools (mpark/wg21, bikeshed, etc.) are based on Markdown. This makes them beginner-friendly, but advanced formatting requires heavy use of Markdown extensions or mixed use of Markdown and HTML tags. Metadata such as bibliographies, document information, etc. also rely on yet another format (e.g. JSON, YAML).

This makes these tools difficult to master and makes the design incoherent. Why do we need three languages glued together just to format our documents?

COWEL is the missing middle, the missing link. It makes producing HTML a natural part of the language, lets you specify metadata, and more, all in one, simple syntax.

3. Getting started

To use and install COWEL, you need to install Node.js and npm. With npm installed, open a terminal and run:

See also https://www.npmjs.com/package/cowel. With COWEL installed, you can convert COWEL documents to HTML by using:

To see a list of available options and commands, run cowel by itself or cowel --help.

3.1. Native installation

There also exists a more limited native CLI for development purposes. To install it and run COWEL:

The npm CLI is slightly different from the native CLI, but they share some options, such as --severity and --help. Running ./build/cowel-cli without extra arguments also brings up the help menu.

4. Syntax

COWEL has a minimalistic but powerful syntax, built on top of only three syntactical constructs:

• Text.
• Escape sequences, such as \{, \}, \\, etc.
• \:Comments
• \directive_splices(positional, args, named-args = 0){and content}

4.1. EBNF grammar

Formally, in EBNF grammar format, a document is constructed as follows:

4.2. Text

Text (such as document-text in the grammar) is a markup element which consists of as many characters as possible, excluding U+005C (\).

4.2.1. Whitespace

COWEL translates text in whitespace directly into HTML in most situations. Additional styling with CSS can be applied to interpret that whitespace literally (like in <pre> elements) or to have it merged into spaces, which happens by default.

At the document top-level, §8.6.1. Paragraph splitting takes place.

4.3. Escape sequences

COWEL supports multiple escape sequences, all of which begin with a \ (like directives), but are followed by some special character. The meaning of the escape sequences is described in the table below.

In EBNF grammar, an escape is constructed like:

If there is an ambiguity between a CRLF escape and a simple U+000D CARRIAGE RETURN escape, this ambiguity is resolved in favor of a CRLF escape.

4.4. Comments

Comments begin with \: and extend until the end of the line. In almost every context, comments are discarded instead of being emitted into the output HTML.

This makes them useful for adding information to the COWEL markup.

In EBNF grammar, a comment is constructed as follows:

Comments include a line-terminator, which means that a trailing comment won't add any lines (not even blank lines) to the generated markup.

4.5. Directives splices

A directive is a way of generating plaintext, HTML, both, or neither. You can think of it as a "command" or "function call".

Splicing means to evaluate a directive (or something else, in the future) and to insert the result between the surrounding markup elements. Splicing consists of three steps:

1. Looking up the name of the spliced directive.
2. Evaluating the directive (and its arguments, if any). Evaluation of the directive usually produces a result. This may not happen when evaluation raises an error.
3. Feeding the result into the current content policy (§5.1. Content policies).

Every directive has three parts:

• The \directive_name selects a specific directive to be processed.
• An optional (comma-separated, positional, arguments, named-arguments = ...) group provides additional inputs to the directive.
• An optional {block of content} provides a "main input" to a directive.

In EBNF grammar, a directive-splice is constructed as follows:

4.5.1. Directive names

A directive name selects a specific directive to be processed. The name begins with a U+005C (\) character, followed by a sequence of ASCII alphanumeric characters or U+005F (_). However, the first character after U+005C (\) cannot be an ASCII digit.

4.5.2. Directive arguments

Grammatically, the arguments are a group, which is constructed as follows:

Directive arguments can be positional arguments, named arguments, or ellipses. Arguments are separated by commas. Unlike in the surrounding markup, whitespace and comments surrounding directive arguments (i.e. blank) are ignored.

4.5.2.1. Named arguments

A named argument is a group-member of the form name = value, where spaces anywhere around name and value are ignored. Named arguments are matched to directive parameters before any positional arguments, meaning that positional arguments fill the remaining unmatched arguments.

Argument names can consist of any character, except ASCII control characters, U+0020 SPACE, U+0022 ("), U+0027 ('), U+002C (,), U+002F (/), U+003D (=), U+003E (>), U+005B ([), U+005C (\), U+005D (]), U+007B ({), U+007D (}), and noncharacters.

Grammatically, a member-name is constructed as follows:

4.5.2.2. Positional arguments

A positional argument is a group-member of the form member-value.

Positional arguments are content just like any other content, except that an unbalanced closing U+005D (]) or a U+002C (,) ends the content.

4.5.2.3. Ellipses

An ellipsis argument is a group-member spelled .... Ellipsis arguments are placeholders which expand to arguments provided to a surrounding macro. See also §8.8.2. \cowel_macro — Define a macro and §8.8.3. \cowel_put — Process provided macro content or arguments.

Specifically, any positional argument which begins with ... (ignoring leading whitespace and comments) is considered an ellipsis. The text ... is not considered an ellipsis if it appears anywhere else or has preceding content within an argument.

An error is raised if an ellipsis is used as an argument outside of a macro expansion.

4.5.2.4. Groups

Groups make it possible to group any of the aforementioned constructs. Groups begin with ( and end with ). They can appear both in positional and in named arguments.

4.5.3. Directive content

The directive content is the primary input to a directive. It is delimited by a '{' and ends with a matching closing '}'. This means that you can have opening and closing braces inside text, but they need to be balanced.

Escape sequences don't participate in this "brace matching", so they can be used to literally produce a brace character.

Unlike in the directive arguments, whitespace is not trimmed.

5. Document processing

A COWEL document is processed from top to bottom, left to right, where each piece of content is fed into the current content policy.

There exists a top-level content policy which takes its input and writes it to the output HTML file.

5.1. Content policies

A content policy dictates how each pice of content (text, comments, escapes, directives) is transformed into HTML or consumed in some other way. For example, most content policies ignore comments, process directives, etc., but other policies can process all these pieces of content into text.

Content policies are piped, meaning that the output of one policy is used as the input to another policy. In a COWEL document, it is common to create long pipes of content policies. These ultimately terminate in the top-level content policy or in a policy which captures the output and writes it to memory for further processing.

The following builtin content policies exist:

To-HTML policy

Comments are ignored, escape sequences are expanded, text is sanitized and converted to "inner HTML" text for elements, and directives are processed as usual. Received HTML is taken literally, and received plaintext is sanitized like text.

Highlight policy

Like a to-HTML policy, but any text content and any received plaintext has syntax highlighting applied to it.

Paragraphs policy

Like a to-HTML policy, but surrounds given text content in paragraphs, and treats blank lines in text as paragraph separators. See §8.6.1. Paragraph splitting for details.

No-invoke policy

Like a to-HTML policy, but directives are not processed. Instead, the source code of directives is taken, sanitized, and fed as HTML into the surrounding policy.

Actions policy

Ignores text, escape sequences, and comments, and passes any other content (e.g. directives) to the surrounding policy.

Text-only policy

Comments are ignored, escape sequences are expanded, text is taken literally, and directives are processed as usual. HTML content fed into this policy is ignored.

Text-as-HTML policy

Like a text-only policy, but instead of feeding its parent policy with the generated plaintext, all plaintext is reinterpreted as HTML before being fed into the parent policy.

Source-as-text policy

The source code of all processed content is interpreted as plaintext and fed into the surrounding policy. This includes comments.

To process directives as usual means that when a directive is encountered, a definition matching the directive name is looked up, and the definition is invoked with the arguments and content of the directive.

The top-level content policy within a document is a paragraph split content policy, feeding content into an HTML content policy.

5.2. Directive processing

The job of directives is to feed the current content policy with content. Unlike text or escape sequences, directives can do so programmatically.

5.2.1. Lazy processing

Unlike in typical programming languages, where the input to a function is processed at the call site and the resulting values are passed into the function, COWEL directives have absolute control over their inputs and how they are processed.

Say you have a JavaScript function:

f has no idea that its input was originally 2 + 2. It only sees the value 4 and prints it, "oblivious to the outside".

COWEL follows a different model:

No <b> tag is ever generated because \b{x} is never processed. \comment is not magical feature; it simply has control over all of its contents and arguments, and it can choose not to process them.

You can even make a \comment2 directive that works just like \comment yourself:

6. Types

While most of the content a user writes tends to be in a markup context, some is written in a scripting context. For example, inside the group of a directive-splice.

A scripting context functions similarly to other programming languages, like JavaScript; there are values and types, which can be combined using expressions.

The commas in a *type-list* act as separators and have no impact on the type.

Note that the type `group(int)` is a unambigously a *prefix-type* where `int` is the only element in the *type-list*, not a `group` *type-prefix* followed by an `(int)` *optional-type*.

Also note that in `group(int)?`, the `?` forms an optional group, not a group of an optional `int`.

6.1. General principles

The process of converting any union type $U$ into its canonical form is called *canonicalization*. A type is in its *canonical* form if canonicalization leaves the type unchanged; otherwise it is in its *degenerate* form.

Two types are *equivalent* if they are identical after both are canonicalized. Equivalent types are semantically the same, but may be spelled differently.

For example, the degenerate union type `any | any` is equivalent to `any`.

6.2. Basic types

Basic types are the most simple building block of the type system. They cannot be broken down any further, although some basic types (namely `any` and `nothing` are symbolic types).

Canonicalization has no effect for basic types; they are always in their canonical form.

6.2.1. any — Top type

any is the root of the type hierarchy, i.e. every other type is a subtype of any. This is also known as a "top type".

any may be used as a type for parameters and variables, but there are no value of type any.

6.2.2. nothing — Bottom type

nothing is a type of which there are no values. This is also known as a "bottom type".

It is the type of expressions that terminate, i.e. don't return.

6.2.3. unit — Unit type

unit is a unit type, i.e. a type with only one possible value also spelled unit.

This is used as a result for directives that don't produce any other result.

6.2.4. null — Null type

null is a unit type with only one possible value also spelled null.

Unlike unit, null is used to indicate errors.

6.2.5. bool — Boolean type

bool is a boolean type. It can represent two values: true and false.

6.2.6. int — Integer

int is an integer. It can represent any integer value (although in practice, there is an implementation limit); this includes negative numbers.

An int can be obtained using integer literals such as 123 or 0xff.

6.2.7. f32 — 32-bit floating-point number

f32 is a single-precision floating-point number. That is, a number in binary32 format, as specified in IEEE-754.

6.2.8. f64 — 64-bit floating-point number

f32 is a single-precision floating-point number. That is, a number in binary64 format, as specified in IEEE-754.

6.2.9. str — String

str is a UTF-8 encoded string.

A value of type str can be obtained using string literals such as "abc".

6.2.10. block — Block

block stores markup elements. It is very similar to str, but is evaluated lazily, meaning that it has no effect until spliced.

A value of type block can be obtained using block literals such as {abc}.

6.3. Compound types

Compound types are formed from other types, possibly from other compound types.

6.3.1. group — Product type

group combines other types, called its members, in sequence. This is also known as a product type.

Canonicalization of a group $G$ is performed as follows:

1. All members of $G$ are canonicalized.
2. If any member of $G$ is nothing, $G$ is nothing.

6.3.2. named — Named group member

named is a compound type only nestable in a group or pack.

For example, group named int is a group containing only a single int. A value of such a type can be obtained with the literal (x = 0).

Canonicalization of a named $N$ is performed as follows:

1. The nested type of $N$ is canonicalized.
2. If the nested type of $N$ is nothing, $N$ is nothing.

6.3.3. pack — Variadic pack of group members

pack is a compound type only nestable in a group. It indicates a variadic repetition of the same type.

Canonicalization of a pack $P$ is performed as follows:

1. The nested type of $P$ is canonicalized.
2. If the nested type of $P$ is nothing, $P$ is nothing.

6.3.4. lazy

lazy is a lazily evaluated value. That is, when specified as a parameter of a directive, it only gets evaluated when actually needed by that directive.

Canonicalization of a lazy $L$ is performed by canonicalizing its nested type.

6.3.5. Union

Unions can be formed by combining other types with |. They describe variables and parameters that can hold one of a fixed number of alternatives. However, a value cannot be of union type.

Alternatives of a union type are subtypes of that union type. Furthermore, a union type $S$ is a subtype of a union type $U$ if the set of alternatives of $S$ is a subset of the alternatives of $U$.

Canonicalization of a union $U$ is performed as follows:

1. Every alternative of $U$ is canonicalized. $U$ is converted to another union type where each alternative that is also a union is expanded or "flattened" into the top-level union. For example, int | (str | bool) is converted to int | str | bool.
2. Any nothing alternatives are removed.
3. The alternatives are sorted using an unspecified total order of types.
4. Any duplicate alternatives are removed.
5. If $U$ now holds a single alternative, $U$ is that alternative.
6. If $U$ now holds no alternatives, $U$ is nothing.
7. If any alternative of $U$ is any, $U$ is any.

6.3.5.1. Shorthand notation for optional types (?)

The type suffix ? forms a union of the given type and null.

6.4. Splicing

Values can be spliced into strings and blocks. For example, "Hello, \d!" splices the result of the directive \d (with no arguments and no block provided) into a string, and {Hello, \d!} splices the result of \d into a block.

Splicing a directive always results in evaluation of that directive. For example, splicing \cowel_macro evaluates \cowel_macro, and its resulting unit is spliced (resulting in no produced text).

When a value is spliced, it is converted into plaintext. When splicing into strings, that plaintext simply becomes part of the string content. For blocks (which are always lazy-evaluated), splicing means that the resulting plaintext is fed into the current content policy once the block itself is spliced.

The effect of splicing depends on the type of value:

• Splicing a value of type unit produces no characters.
• Splicing a value of type null produces the string "null".
• Splicing a value of type bool produces "true" if the value is true, and "false" otherwise.
• Splicing a value of type int produces a string representing the value in decimal form. For example, both 15 and 0xf result in "15" when spliced.
• Splicing a value of type f32 or f64 produces a string representing the value in decimal form. For example, both 0.5f32 0.5f64 result in "0.5" when spliced.
• Splicing a value of type str produces its string contents.
• Splicing a value of type block splices each markup element within.
• Splicing a value of type group raises an error.

7. Themes

COWEL outputs documents that can be viewed in light mode and dark mode.

When the document is opened with support for JavaScript, there is an button in the top-right that can be used to switch between three modes:

• Sync the theme with the OS (default)
• Light mode (ignoring system preference)
• Dark mode (ignoring system preference)

Forced light/dark mode works by adding a light or dark class to the <html> element in the DOM.

8. New directives

Find below a list of builtin directives. That is, directives that you can always use because they are "built into the language".

8.1. Common principles

There are a few common principles, which all builtin directives have in common:

• Unless otherwise stated, arguments to builtin directives are processed using the text-only policy (§5.1. Content policies).
• Arguments to builtin directives use the usual argument matching (§8.1.2. Usual argument matching).
• Whenever content or arguments are said to be ignored, a warning is emitted when content or arguments are provided by the user, respectively.

8.1.1. Parameter notation

While COWEL does not yet support a syntax for defining directives with parameters of a specific type, this documentation does for the builtin directives. This notation consists of

• the directive name,
• a list of parameters in parentheses, consisting of the parameter name and the parameter type (§6. Types), separated by ':' and optionally followed by '=' and a default value, and
• optionally, the symbol {...} to indicate that the directive accepts content.
• the result type of the directive, separated by ':'

cowel_html_element(
  name: str,
  attr: lazy(group pack named string)?,
){...}: block

cowel_html_element(
  name: string,
  attr: lazy(group(pack(named(string))))?,
){...}: block

8.1.2. Usual argument matching

The usual argument matching allows matching positional and named arguments to parameters of directives. An error is raised if positional and named arguments are mixed, unless all positional arguments appear contiguously at the start of the argument list.

The usual argument matching is performed as follows:

1. Positional arguments match parameters in the same order. An error is raised if there are more positional arguments than parameters.
2. The following named arguments match parameters with the same name. An error is raised if a named argument does not match any parameter.
3. If any parameter has not been matched by an argument, the parameter is matched by its default argument value if there is one, otherwise, if it has optional type, it is matched by nothing, and otherwise an error is raised.

8.2. Character utilities

It is quite common that a text document should include special characters. While COWEL is built on UTF-8 and in theory, one could just write the character directly into the source code, not every text editor handles special characters well, not to mention that some characters are invisible when rendered.

For portability and convenience COWEL has builtin directives for generating and querying characters.

8.2.1. \cowel_char_by_entity — Character by HTML character reference

cowel_char_by_entity(){...}: str

The \cowel_char_by_entity directive takes the name of a character and outputs the respective code points as text. The input to a \c directive is provided as content, which consists of an HTML entity without the leading '&' and trailing ';'. All arguments are ignored.

8.2.2. \cowel_char_by_name — Character by Unicode name

cowel_char_by_name(){...}: str

The input to a \cowel_char_by_num directive is text content which should be a Unicode name for a code point. That is, the name of a code point, or one of its "control", "alternate", or "correction" aliases.

8.2.3. \cowel_char_by_num — Character by code point number

cowel_char_by_num(){...}: str

The input to a \cowel_char_by_num directive is text content which should be a sequence of hexadecimal numbers specifying a Unicode scalar value; that is, a code point which UTF-8 permits to be encoded. All arguments are ignored.

8.2.4. \cowel_char_get_num — Get digits of character

cowel_char_get_num(
  zfill: bool = 0,
  base: int = 16,
  lower: bool = false,
){...}: block

The \cowel_char_get_num directive is essentially the inverse of the \cowel_char_by_num directive. Its input is also plaintext content. Rather than producing a code point from a digit sequence, it produces a digit sequence from its input code point.

This can be fine-tuned with the following parameters:

\cowel_char_get_num uses only the first code point within the input text, even though the entire input text is processed into plaintext.

8.3. HTML utilities

8.3.1. \cowel_html_element — HTML element

cowel_html_element(
  name: string,
  attr: lazy(group pack named string)?,
){...}: block

The \cowel_html_element directive generates content, surrounded in HTML opening and closing HTML tags. That is, it

• writes an opening tag, where any named arguments are converted to HTML attributes,
• feeds the provided content into the current content policy, and then
• writes a closing tag.

The name of the HTML element is contained in the name parameter, and the attributes within the HTML element are contained within the attr parameter.

A \cowel_html_element directive produces an error if the given tag name is not a valid HTML tag name, or if any of the argument names are not valid HTML attribute names.

8.3.2. \cowel_html_self_closing_element — Self-closing HTML element

cowel_html_self_closing_element(
  name: string,
  attr: lazy(group pack named string)?,
): block

The \cowel_html_self_closing_element directive generates a self-closing HTML element. That is, an element with no content, and where there is no closing tag. Content is ignored.

The name of the HTML element is contained in the name parameter, and the attributes within the HTML element are contained within the attr parameter.

8.4. Content policies

As explained in §5.1. Content policies, all content within the document and produced by directives is fed into a content policy, which, in turn, feeds content into some parent content policy.

The table below lists directives which process content using some content policy.

8.4.1. \cowel_to_html — Process with to-HTML policy

cowel_to_html(){...}: block

\cowel_to_html simply processes the provided content using the to-HTML policy.

The purpose of this policy/directive is mainly to feed its parent policy pure HTML content, rather than a mixture of plaintext and HTML. This also suppresses paragraph splitting, syntax highlighting, and other such "special treatments" of plaintext, since none of those operate on HTML.

8.4.2. \cowel_no_invoke — Process with no-invoke policy

cowel_no_invoke(){...}: block

\cowel_no_invoke processes the provided content using the no-invoke policy.

8.4.3. \cowel_actions — Process with actions policy

cowel_actions(){...}: block

\cowel_actions processes the provided content using the actions policy.

This is particularly useful in macros and surrounding macros because it prevents whitespace from being emitted into the HTML file. Normally, whitespace is preserved, unless explicitly eliminated (e.g. with newline escapes or commas).

8.4.4. \cowel_text_only — Process with text-only policy

cowel_text_only(){...}: block

\cowel_text_only processes the provided content using the text-only policy.

8.4.5. \cowel_text_as_html — Process with text-as-HTML policy

cowel_text_as_html(){...}: block

\cowel_no_invoke processes the provided content using the text-as-HTML policy.

8.4.6. \cowel_source_as_text — Process with source-as-text policy

cowel_source_as_text(){...}: block

\cowel_no_invoke processes the provided content using the source-as-text policy.

8.5. Syntax highlighting

Syntax highlighting improves the readability of inline code and code snippets by applying different formatting (usually colors) based on the syntactical meaning of text. Many examples can be found in this document.

8.5.1. \cowel_highlight — Perform syntax highlighting

cowel_highlight(
  lang: string,
){...}: block

The \cowel_highlight processes content using the highlight policy, which wraps parts of code in HTML tags for the purpose of syntax highlighting.

\cowel_highlight has a single lang parameter. This specifies the name of language (e.g. cowel) in which the content is to be highlighted. The name has to be one of the language short names supported by the µlight syntax highlighter, which is the highlighter that COWEL uses internally.

8.5.2. \cowel_highlight_as — Syntax highlight override

cowel_highlight_as(
  name: string,
){...}: block

The \cowel_highlight_as directive forces certain syntax highlighting to be applied to some text; it is a manual override for when automatic syntax highlighting is insufficient or broken. This is done by wrapping the given content in HTML tags for syntax highlighting and feeding the provided content, converted to HTML into the surrounding policy, so it is not subject to automatic highlighting.

\cowel_highlight_as has a single name parameter, which is the µlight long name for a highlight type.

8.5.3. \cowel_highlight_phantom — Syntax highlight phantom text

cowel_highlight_phantom(){...}: block

The \cowel_highlight_phantom directive can be used to further customize syntax highlighting. It outputs phantom text, which is fed into the syntax highlighter, but is not part of the output content.

The provided content is processed using a text-only policy (§5.1. Content policies). If the current policy is a highlight policy, the text output by the former is turned into phantom text within the latter. Otherwise, the generated text is discarded. All arguments are ignored.

8.6. Paragraph control

Dividing content into paragraphs manually would take a huge amount of effort, so COWEL provides means of doing so semi-automatically. Text within in a paragraphs policy (§5.1. Content policies) is automatically wrapped in paragraphs (<p>...</p>), divided at blank lines.

While content expanded from macros and from \cowel_include is fed into the surrounding content policy (which may be a paragraphs policy) directly, directives are generally treated as "black boxes" for the purpose of paragraph splitting, and they neither begin nor end a paragraph. The following paragraph control directives define interactions between paragraph splitting and directives.

8.6.1. Paragraph splitting

At the top-level in the document and within the content of certain directives, paragraph splitting takes place. All content in COWEL is either inline content, block content, or meta content. Text and escape sequences are inline content, and directives are sometimes inline and sometimes block content. Certain directives (e.g. \comment) that don't generate anything rendered are meta content.

The process of paragraph splitting works as follows:

• Blank-line-separated blocks of inline content is wrapped in in <p>...</p> tags. Meta content is not counted as a blank line, so it "continues" inline content, but no effort is made to wrap it in <p>...</p>.
• Block content stays untouched, i.e. it is not wrapped in <p>...</p>. However, it also terminates prior inline content, like a blank line.

8.6.2. \cowel_paragraphs — Perform paragraph splitting

cowel_paragraphs(){...}: block

The \cowel_paragraphs directive creates a paragraphs policy (§5.1. Content policies) and feeds all provided content into that policy. The beginning and end of the provided content are considered to be outside a paragraph. All arguments are ignored.

8.6.3. \cowel_paragraph_enter — Enter a paragraph

cowel_paragraph_enter(): block

If the current content policy is a paragraphs policy and and the paragraph state is "outside", the paragraph state becomes "inside", and a <p> tag is emitted. Otherwise, has no effect.

8.6.4. \cowel_paragraph_leave — Leave a paragraph

cowel_paragraph_leave(): block

If the current content policy is a paragraphs policy and and the paragraph state is "inside", the paragraph state becomes "outside", and a closing </p> tag is emitted. Otherwise, has no effect.

8.6.5. \cowel_paragraph_inherit — Activate paragraph splitting inside a directive

cowel_paragraph_inherit(): block

As already stated, paragraph splitting generally treats directives as "black boxes". However, content expanded from \cowel_include and macros inherits the surrounding paragraph for splitting, i.e. any content produced by such directives is fed directly into the paragraphs policy. \cowel_paragraph_inherit can be used inside programmatic directives defined by the user to achieve the same behavior.

8.7. File management

Once projects get larger, it often becomes difficult to manage everything in a single file. Also, tooling may benefit from having separate files. For example, keeping separate SVG files or CSS files may have better IDE support than writing these out directly inside of COWEL.

COWEL provides directives to load content from other files.

8.7.1. \cowel_include — Include a sub-document

cowel_include(){...}: block

The \cowel_include directive loads the content from another COWEL document, and processes it using the current content policy. The path to the document is provided as content to \cowel_include, and is assumed to be relative to the current file. All arguments are ignored.

If the current content policy is a paragraphs policy (§5.1. Content policies), paragraph splitting of the included sub-document takes place as if its contents were expanded directly where \cowel_include appears. In other words, \cowel_include inherits the paragraph context, or is not a "black box" to paragraph splitting.

8.7.2. \cowel_include_text — Include text from a file

cowel_include_text(){...}: block

The \cowel_include_text directive reads the UTF-8 text contents of another file and feeds that text into the current content policy. The path to the document is provided as content to \cowel_include_text, and is assumed to be relative to the current file.

8.8. Aliases and macros

8.8.1. \cowel_alias — Define aliases for an existing directive

cowel_alias(
  names: pack string,
){...}: unit

The \cowel_alias directive defines one or more aliases for an existing directive. The content of \cowel_alias is converted to text, and must be the name of an existing directive or directive alias. Each positional argument is converted to text, and results in the definition of a new directive alias. After processing \cowel_alias, the target can also be invoked using the alias name.

A fatal error is raised if

• generation of the alias or target names is erroneous,
• the target name or any of the alias names are empty,
• the target name or any of the alias names are not valid directive names,
• the target was not found, or
• an alias name matches the name of an existing macro or alias.

8.8.2. \cowel_macro — Define a macro

cowel_macro(
  names: pack string,
){...}: unit

The \cowel_macro directive defines a block of content which can be processed at a later point in the document. The provided content is not processed, but remembered. Each positional argument is converted to text, and results in the definition of a new macro. After processing \cowel_macro, the target can also be invoked using the macro name. Named arguments are ignored.

A fatal error occurs if

• generation of the alias or target names is erroneous,
• any macro name is not a valid directive name (this includes empty names), or
• a macro name matches the name of an existing macro or alias.

When a macro is processed, the behavior is as if \cowel_paragraph_inherit (§8.6.5. \cowel_paragraph_inherit — Activate paragraph splitting inside a directive) was invoked immediately before processing the content in the macro definition. This means that blank lines in the macro definition may also result in paragraph splits outside the macro.

8.8.3. \cowel_put — Process provided macro content or arguments

cowel_put(
  else: lazy any,
){...}: any

The \cowel_put directive processes content which was provided when a macro was invoked.

The content provided to \cowel_put is converted to text, and designates

• if that text is empty, the provided macro content;
• otherwise, if that text expands to only ASCII digits, the provided positional macro argument at the index obtained by parsing the digits (counting starts at zero);
• otherwise, if there exists a named macro argument whose name matches the target text, that argument;
• otherwise, nothing.

\cowel_put has the following effect:

• If any content is designated, the designated content is processed.
• Otherwise, if an argument matches the else parameter, the content within the else parameter is processed.
• Otherwise, an error is raised.

The behavior is erroneous if \cowel_put is not expanded from a macro, such as when \cowel_put appears at a top-level in the document.

8.9. Invocations

8.9.1. \cowel_invoke — Invoke a directive

cowel_invoke(
  name: string,
){...}: any

The \cowel_invoke directive invokes a directive by name. This process is called a dynamic invocation. Most invocations are static invocations.

The name of the invoked directive is provided as the first positional argument. All other arguments are ignored. The content provided to \cowel_invoke is the content provided to the invoked directive.

9. Legacy directives

9.1. Comments

In addition to the \: syntax for single-line comments, there exists a \comment directive which discards all of its contents. This can be used for multi-line comments.

9.1.1. \comment — Comments

The \comment directive does not process its arguments or content. It outputs no plaintext or HTML.

9.2. Text formatting

COWEL allows for basic text formatting using various directives. Many of the formatting directives are some direct equivalent of an HTML element. For these, there is a fixed HTML element that will always be used. You can rely on this when adding custom CSS.

All such formatting directives convert all named arguments directly into HTML attributes.

9.3. Code and syntax highlighting

COWEL uses µlight for syntax highlighting. While the set of supported language is relatively small, the highlighter is ultra-light, extremely fast, and deals with modern C++ features correctly.

9.3.1. \code — Inline code

The \code directive produced syntax-highlighted text in code font.

Arguments

• lang (plaintext) — the syntax highlighting language.
• nested (true/false) — whether to omit <code> tags.

Input content

The input to a \code directive is a plaintext context. However, there are special rules for formatting directives and pure plaintext directives (see below).

HTML output

In an HTML context, the \code takes the input source code, applies syntax highlighting, and outputs the result surrounded by <code>...</code>.

Plaintext output

In a plaintext context, \code simply outputs the input source code.

Display style

Inline

9.3.1.1. Manual nested highlighting

The nested parameter is a plaintext context, which accepts either true or false, where false is the default. When enabled, the surrounding <code> tags are omitted, which makes it suitable for nesting languages within other \code or \codeblock directives.

Note that by default, you may often not even notice a visual difference between using the nested parameter and not using it. However, the difference would be obvious once you want to style <code> elements to have borders, background color, padding, and other such styling features. nested=true directly emits the highlighting HTML elements, which is more composable.

9.3.1.2. Further advice on highlighting

9.3.2. \codeblock — Code blocks

The \codeblock directive works exactly like \code, but it is a block directive, not an inline directive.

Additionally, code blocks render using borders and a dark background by default. This can be controlled using the borders.

9.3.3. \hl — Syntax highlight override

The \hl directive forces certain syntax highlighting to be applied to some text; it is a manual override for when automatic syntax highlighting is insufficient or broken. It displays as inline content and wraps its content (which is an HTML context) in the appropriate syntax highlighting tags.

It has a single name argument, which is the µlight long name for a highlight type. You can obtain a list of possible long names at ulight.h from the definition of enum ulight_highlight_type. The long name is the enumerator name without the ULIGHT_HL prefix, all lowercase, and with hyphens instead of underscores.

9.3.4. \pre — Preformatted blocks

The \pre directive contains pre-formatted content. It can be used to contain code, however, there is no syntax highlighting in a \pre block.

Hello, world!
=============
    a b c

9.3.5. \literally — Treat input literally as text

The \literally directive treats its input source code as plain text, even if it contains directives or escape sequences. It outputs the given input source code as text.

Its content is an unprocessed context, and it takes no arguments.

\: Even comments are preserved!
This \comment{comment} \{ is taken literally \}!

9.3.6. \unprocessed — Suppress directive processing

The \unprocessed directive works just like \literally, except that escape sequences are processed into their escaped characters.

This \comment{comment} { is unprocessed }!

9.4. Math

In recent years, browser support for MathML within HTML has become widespread. COWEL relies entirely on the browser for properly rendering math as MathML, which is very simple and lightweight, but not as portable as "baking" the math into an SVG.

However, hand-writing MathML would be extremely tedious and verbose, so COWEL offers some convenience directives, listed below.

9.4.1. \math — Inline math

A \math directive surrounds its content with <math display=inline>...</math> tags, and displays as inline content.

Its content is an HTML context, and within it, additional pseudo-directives like \mi or \mn corresponding to MathML elements can be used. Essentially, this allows you to build MathML using COWEL syntax.

See Mozilla's MathML elements reference for a list of supported elements/directives.

9.4.2. \mathblock — Math blocks

The \mathblock directive functions almost exactly as the \math directive, but it displays as block content instead of inline content, and it produces an opening <math display=block> tag.

9.5. Separators and word breaking

9.5.1. \br — Break line

The \br directive produces a line break, and corresponds to the HTML element <br/>. It displays as inline content, and its input content is ignored.

\br is particularly useful when line breaks are treated same as spaces, which is the case in most HTML content.

9.5.2. \hr — Horizontal rule

The \hr directive produces a horizontal rule, and corresponds to the HTML element <hr/>. It displays as block content, and its input content is ignored.

Here is an example:

9.5.3. \wbr — Word break opportunity

The \wbr directive produces a word break opportunity, and corresponds to the HTML element <wbr>. It displays as inline content, and its input content is ignored.

<wbr> elements can be inserted into the middle of long words, which, if they don't fit on one line, will be broken at the point of the <wbr> element (without a hyphen at the end of the line).

Since µlight only supports UTF-8 output, \wbr is equivalent to \U{200B}, which outputs a U+200B ZERO-WIDTH SPACE code point.

9.5.4. \nobr — Unbroken words

The \nobr directive is a formatting directive which prevents word breaks within its content. Its content is an HTML context. This is done by applying a white-space: nowrap; style its content.

9.6. Special blocks

Often, the content we write falls into some special category like "example", "note", etc. COWEL supports a large number of special block directives, which wrap their content in a block, with background color, borders, etc.

The input to all special block directives is an HTML context, they all convert their arguments to HTML attributes, and they all display as block content.

9.6.1. \Babstract — Abstract blocks

9.6.2. \Bquote — Quote blocks

The \blockquote directive directly corresponds to the <blockquote> element.

Quotes blocks or "block quotes" display quoted text.

9.6.3. \blockquote — Alias for \Bquote

The \blockquote directive is equivalent to the \Bquote directive.

9.6.4. \Bug — Bug blocks

9.6.5. \Bdecision — Decision blocks

9.6.6. \Bdel — Deletion blocks

9.6.7. \Bdetails — Details blocks aka spoilers

The \Bdetails directive directly corresponds to the <details> element. Within \Bdetails, the \summary directive can be used to specify summary text.

9.6.8. \details — Alias for \Bdetails

The \details directive is equivalent to the \Bdetails directive.

9.6.9. \Bdiff — Difference blocks

9.6.10. \Bex — Example blocks

9.6.11. \Bins — Insertion blocks

9.6.12. \Bimp — Important blocks

9.6.13. \Bnote — Note blocks

9.6.14. \Btip — Tip blocks

9.6.15. \Btodo — TODO blocks

9.6.16. \Bwarn — Warning blocks

9.7. Lists

9.7.1. \ul — Unordered lists

The \ul directive corresponds to the <ul> element, and produces an unordered list.

9.7.2. \ol — Ordered lists

The \ol directive corresponds to the <ol> element, and produces an ordered list.

9.7.3. \li — List items

The \li directive corresponds to the <li> element, and produces a list item with <ul> or <ol>.

9.7.4. \item — List item pseudo-directive

Within \ul and \ol, the \item pseudo-directive can also be used instead of \li.

9.7.5. \dl — Definition lists

The \dl directive corresponds to the <dl> element, and produces a definition list. Within that list, you can use

• \dt for definition terms, and
• \dd for definition descriptions.

9.8. Tables

Tables are simply produced by using the \table, \thead, \tbody, \tfoot, \tr, \th, \td, \colgroup, \col, and \caption directives to produce the corresponding HTML tags with the same name.

9.9. Headings

Headings can be produced using the \h1, \h2, \h3, \h4, \h5, and \h6 directives to produce the corresponding HTML tags with the same name.

Headings take a listed argument, which is a yes/no plaintext argument. Unless its value is no, headings are numbered and added to the table of contents (§9.9.1. \make_contents — Make table of contents) automatically.

Headings also take a show-number argument, which is a yes/no plaintext argument. Unless this is no, the heading number will be included in the title, in the format 1.2.3. Title. However, even if show-number is no, the number heading is internally numbered as usual, and its number can be seen in the table of contents.

Other arguments to these headings are converted into attributes of the corresponding HTML element. An id argument can be provided explicitly.

If none is provided, an id is synthesized from the content within the heading.

9.9.1. \make_contents — Make table of contents

The \make_contents directive generates the table of contents, which is comprised of all the headings within the document. It takes no arguments and its content is ignored. It displays as a block.

The table of contents is is populated by headings (§9.9. Headings) as the document is processed.

9.10. Bibliography

In technical writing it is common for documents to reference other papers, and it is expected that references are properly cited. To support this,

COWEL provides directives for adding bibliography entries, and for generating a bibliography automatically.

9.10.1. \bib — Add bibliography entry

The \bib directive adds a single entry to the bibliography. Its content is ignored, and it displays as a meta directive.

It has a number of parameters, each of which is a plaintext context:

id

The identifier of the bibliography entry. This can later be referenced using \ref(id).

author

The name of the author(s). This is in no particular format, and if you want to provide multiple authors, you can do so via a comma-separated list here.

title

The title of the cited work.

date

The date of publication. No particular format is enforced; this is simply a string, so you can choose some local format.

publisher

The name of the publisher.

link

The primary link to the document. This should typically be a short link because it is copied into each \ref to the bibliography entry.

long-link

A "long link" to the document. If present, this will be rendered within the bibliography, and it is typically meant to be a semantic or more stable link than the link. You can also think of it as a "link for pretty printing".

issue-link

A link to issue tracking for the document. For example, in WG21 circles, this may be a link to the GitHub issue where a paper is tracked.

Every argument except the id is optional, although you will hardly get meaningful bibliography output if only the id is specified.

9.10.2. \make_bib — Generate bibliography

The \make_bib directive generates a bibliography. This is typically done towards the bottom of the document, but can be done anywhere.

It takes no arguments, its content is ignored, and it displays as a block.

The \make_bib directive is populated by uses of \bib directives in order of use. That is, the bibliography is not automatically sorted for you; the order in which \bib directives are used is also the order in which the bibliography entries are generated.

9.11. References

9.11.1. \ref — References

The \ref directive takes a single to argument, which can be a URL, anchor, or something else. It produces an <a> tag with some content inside.

The content is an HTML context, and is what actually gets displayed. If no content is provided, it can be synthesized from the following types of references:

• mailto URLs (e-mail addresses)
• tel URLs (telephone numbers)
• http and https URLs
• Anchors (#id) for some heading in the document
• Anything defined in the bibliography using \bib

9.11.2. \mail — E-Mail addresses

A \mail directive behaves the same \ref directive that is given a mailto URL. However, the input is provided as content instead of an argument, and the displayed text cannot be customized.

9.11.3. \tel — Telephone numbers

A \tel directive behaves the same \ref directive that is given a tel URL. However, the input is provided as content instead of an argument, and the displayed text cannot be customized.

9.12. Foreign languages

9.12.1. \script — JavaScript blocks

The content of a \script directive is a plaintext context, where the input is treated as JavaScript code and surrounded in <script>/*...*/</script> tags.

\script displays as meta content (like \comment).

9.12.2. \noscript — No-JavaScript content

The \noscript directive corresponds to the <noscript> element. Its content is an HTML context, and will only be shown by the browser when JavaScript is disabled.

9.12.3. \style — CSS blocks

The content of a \style directive is a plaintext context, where the input is treated as JavaScript code and surrounded in <style>/*...*/</style> tags.

\style displays as meta content (like \comment).

9.13. Sections

Often, you want to produce content in one place, but have it display in another place within the document. A classic example is collecting headings automatically in a table of contents, or copying the content of a heading into a preview when referenced by \ref(#id).

9.13.1. \there — Append content to section

The \there directive displays as meta content. Basically, it stashes away its input content (which is an HTML context) somewhere else.

It takes a single section argument which specifies the name of the section. The section argument is a plaintext context.

By default, all document content is placed within a <main> element, inside <body>, inside html. \there allows you to write outside of the <main> element:

• \there(std.head){text} will write text inside of the <head> element (following auto-generated content).
• \there(std.body){text} will write text inside of the <body> element (following <main> and other automatically inserted elements).

9.13.2. \here — Copy section content

The \here directive inserts the content from another section at its location. It displays as inline content.

It takes a single section argument which specifies the name of the section. The section argument is a plaintext context.

All references produced by \here are resolved in a post-processing step, which allows forward-references.

9.13.3. \hereblock — Copy section content in block

The \hereblock directive functions exactly like the \here directive, but displays as block content instead of inline content.

9.14. Miscellaneous

9.14.1. \div — Content division

The \div directive surrounds its contents in <div>...</div> tags. It displays as a block, and its content is an HTML context. \div's named arguments are turned into HTML attributes.

9.14.2. \trim — Trim input

The content of a \text directive is an HTML context (§5.1. Content policies). Its arguments are ignored. \text is a formatting directive.

The process of trimming eliminates leading and trailing whitespace in the input, at the COWEL source level.

9.14.3. \text — Plaintext context

The content of a \text directive is a plaintext context (§5.1. Content policies). Its arguments are ignored.

It simply outputs the input that it was given as text. Therefore, it acts as a sort of wrapper for plaintext. Notably, this forces the generation of plaintext even when \text is within an HTML context.

9.14.4. \p — Paragraphs

The \p directive surrounds its content in <p>...</p> tags.

9.15. Variables and calculations

While COWEL is not intended to be general purpose programming language, and more advanced interactive features are better suited for JavaScript, it does provide a few ways to perform calculations.

9.15.1. \Vset — Set a variable

\Vset sets the value of a variable to some provided plaintext. It displays as a meta directive.

It takes a single var argument, which is a plaintext context for the name of the variable. The directive content is also a plaintext context, and provides the value of the variable.

9.15.2. \Vget — Get a variable

\Vget obtains the value of a variable, and displays as inline. Its content is ignored.

It takes a single var argument, which is a plaintext context for the name of the variable. See above for an example.

If the variable denoted by the var argument does not exist, \Vget expands to nothing.