path: root/gsp.5

.Dd $Mdocdate: October 28 2023 $
.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’ }

    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 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
Sometimes it is also useful to have a newline between nodes, especially when
working with
.Sq code
tags nested within a
.Sq pre
tag.
To specify that you want a newline to be placed after a node, you can prefix the
node name with a greater-than symbol
.Pq Sq > :
.Bd -literal -offset indent
Before

pre {
  >code {-foo}
  >code {-bar}
  code  {-baz}
}
.Ed
.Bd -literal -offset indent
After

<pre><code>foo</code>
<code>bar</code>
<code>baz</code></pre>
.Ed
.Pp
Additionally, sometimes when using literal text with the
.Sq -
special node name, it can be nice to have a way to trim whitespace around the
text without having to minify your markup.
To achieve this, you can use the special equals
.Pq Sq =
node name:
.Bd -literal -offset indent
Before

>foo {- Hello World  }
 bar {= Hello World  }
.Ed
.Bd -literal -offset indent
After

<foo> Hello World  </foo>
<bar>Hello World</bar>
.Ed
.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