path: root/gsp.5

.Dd $Mdocdate: April 18 2024 $
.Dt GSP 5
.Os
.Sh NAME
.Nm gsp
.Nd language reference for gsp
.Sh DESCRIPTION
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’ }

    / div {
        p {- This entire div is commented out. }
        p {- Isn’t that neat? }
    }

    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> .
.Sh LANGUAGE SYNTAX
.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 Comments
Comments can be created by using the special
.Sq /
node name.
During transpilation any nodes named
.Sq /
and their children are commented out:
.Pp
.Bd -literal -offset indent
div {
  / p {-I am commented out}
  p {-I am not commented out}
}
.Ed
.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.
.Sh SEE ALSO
.Xr gsp 1
.Pp
.Lk https://www.w3.org/TR/xml "Extensible Markup Language (XML) Reference"
.Sh AUTHORS
.An Thomas Voss Aq Mt mail@thomasvoss.com