.Dd $Mdocdate: November 1 2023 $

.Os

.Nm gsp

.Nd language reference for gsp

The

.Nm

language is an alternative language to HTML which can be transpiled by making

use of the

.Xr gsp 1

transpiler.

The

.Nm

language allows you to structure data in the same manner as HTML while offering

an easier-to-read and less verbose syntax, and also some nice shortcuts.

An example

.Nm

document might look as follows:

.Bd -literal -offset indent

html lang="en" {

head {

meta charset="UTF-8" {}

meta

name="viewport"

content="width=device-width, initial-scale=1.0"

{}

link href="/favicon.svg" rel="shortcut icon" type="image/svg" {}

link href="/style.svg" rel="stylesheet" {}

title {-My Website Title}

}

body {

p #my-id {- This is a paragraph with the id ‘my-id’ }

p .my-cls {- This is a paragraph with the class ‘my-cls’ }

p

#some-id

.class-1

.class-2

key-1="value-1"

key-2 = "value-2"

{-

This paragraph has an ID, two classes, and two additional

attributes. GSP allows us to use the ‘#ident’ and ‘.ident’

syntaxes as shorthands for applying IDs, and classes. This is a

text node, so nothing is being interpreted as GSP nodes, but we can

include them inline if we want. As an example, here is some @em

{-emphatic} text. Your inline nodes can also have attributes @em

#id .cls {-just like a regular node}.

}

}

}

.Ed

.Pp

As can be seen in the above example, nodes in

.Nm

take the form of

.Ql name attributes {...}

as opposed to the more verbose

.Ql <name attributes>...</name> .

.Ss Nodes

Nodes are the central building block of a

.Nm

document, and take the form of

.Ql name attributes {...} .

For example, a footer node with the attributes

.Sq foo

and

.Sq bar

and no child nodes is written as:

.Pp

.Bd -literal -offset indent

footer foo bar {}

.Ed

.Pp

To nest nodes within other nodes, simply place them within the braces.

As such, the following defines a footer with the attributes

.Sq foo

and

.Sq bar

with two empty div-nodes as children:

.Pp

.Bd -literal -offset indent

footer foo bar { div{} div{} }

.Ed

.Pp

When compiling an empty node

.Ql foo{} ,

you get the result

.Ql <foo> .

If you want both an opening- and closing tag with no children, such as in

.Ql <foo></foo> ,

then you can use an empty text-node as in

.Ql foo{-} .

.Ss Node names

Node names follow the exact same naming rules as names do in XML.

See the XML reference in

.Sx SEE ALSO

for more details.

.Ss Attributes

Attributes are optional components of a node.

They take the form of an attribute name and an optional attribute value.

To specify an attribute, simply write the attribute name:

.Pp

.Bd -literal -offset indent

name

.Ed

.Pp

If you want to provide a value, you must follow the name with an equals sign

.Pq Sq =

and then wrap the value in double quotes

.Pq Sq \(dq :

.Pp

.Bd -literal -offset indent

name="value"

.Ed

.Pp

You can optionally include whitespace for visual clarity, and double quotes and

backslashes

.Pq Sq \e

can be escaped using a backslash:

.Pp

.Bd -literal -offset indent

name = "he said \e"hello there\e""

.Ed

.Pp

Like with node names, the details about which characters are allowed within an

attribute name are detailed in the XML reference found in the

.Sx SEE ALSO

section of this manual.

.Ss IDs and classes

When transpiling, you will be wanting to use IDs and classes all of the time.

Due to the frequency of use of these parts of HTML,

.Nm

offers a shorthand syntax for specifying them.

The shorthand syntax looks like the equivalent CSS selectors for said IDs and

classes.

Valueless attributes prefixed with a period

.Pq Sq \&.

or hash

.Pq Sq #

are transpiled to classes and IDs respectively.

Therefore the following two examples are identical:

.Bd -literal -offset indent

div #foo .bar .baz {

div .bar {}

}

.Ed

.Bd -literal -offset indent

div id="foo" class="bar baz" {

div class="bar" {}

}

.Ed

.Pp

It is important to note that HTML5 allows for an ID- or class name to contain

just about anything, therefor

.Ql .→Ħ{}

is a valid class shorthand.

This is important because it means that the following doesn’t actually create a

node with no children:

.Bd -literal -offset indent

div .foo{}

.Ed

.Pp

You must instead include a space:

.Bd -literal -offset indent

div .foo {}

.Ed

.Ss Document types

.Nm

does not support document types.

The HTML5 document type is automatically generated when transpiling to HTML.

If you want to use a different document type, you’ll have to do that yourself.

There is an example of this in the

.Xr gsp 1

manual.

.Ss Literal text

If you want to include literal text within a node you can make use of the

special node name

.Sq - .

Unlike with the usual node name, you do not need to include whitespace between

the special node name and the attributes.

The following example shows how you can set a page title and paragraph text:

.Bd -literal -offset indent

html {

head {

title {-My Amazing Website}

}

body {

p {-

Welcome to my website! Here on my website you can find cute cat

pictures, amongst other things.

}

}

}

.Ed

.Pp

When writing literal text, all occurrences of

.Sq } ,

.Sq @ ,

and

.Sq \e

must be backslash escaped as they have special meaning.

.Ss Embedded nodes

If you want to embed a node within literal text, you can make use of an embedded

node.

Embedded nodes are exactly the same as regular nodes, but they are prefixed with

the at

.Pq Sq @

symbol.

For example if you want to emphasize some text in a paragraph, you could do the

following:

.Bd -literal -offset indent

p {-

This is some text, but @em .my-class {-some} of it is emphatic!

}

.Ed

.Ss Whitespace control

By default GSP transpiled to HTML will be automatically minified with the

exception of literal text whose whitespace is untouched.

Sometimes though, we want to have proper control over whitespace.

The first trick to manual whitespace control is to make use of the special node

name

.Sq = .

It acts identially to the special

.Sq -

node, except it removes all leading- and trailing whitespace:

.Bd -literal -offset indent

Before

p {= Hello World

}

After

<p>Hello World</p>

.Ed

.Pp

This can be useful for trimming whitespace, but sometimes we want to preserve

it.

This is especially crucial with HTML

.Ql <pre>

tags for which whitespace is not squashed.

We can get around this issue by making use of the fact that the special

.Sq -

node does not trim whitespace.

The following is an example of how not to display two seperate lines in a

.Ql <pre>

tag:

.Bd -literal -offset indent

Before

pre {

code{-Foo}

code{-Bar}

}

After

<pre><code>Foo</code><code>Bar</code></pre>

.Ed

.Pp

Instead, you can do the following:

.Bd -literal -offset indent

Before

pre {-

@code{-Foo}

@code{-Bar}

}

After

<pre>

<code>Foo</code>

<code>Bar</code>

</pre>

.Ed

.Pp

If you would like to have the whitespace between the opening- and closing

.Ql pre

tags and the inner

.Ql code

tags removed, you can use the

.Sq =

node instead of the

.Sq -

node.

.Xr gsp 1

.Pp

.Lk https://www.w3.org/TR/xml "Extensible Markup Language (XML) Reference"

.An Thomas Voss Aq Mt mail@thomasvoss.com