From 5cf8e6e4ea355dbbdfaca5998088704a43e0ceab Mon Sep 17 00:00:00 2001
From: Thomas Voss <mail@thomasvoss.com>
Date: Sun, 10 Sep 2023 18:32:37 +0200
Subject: Write the initial gsp(5) manual
---
gsp.5 | 268 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 267 insertions(+), 1 deletion(-)
diff --git a/gsp.5 b/gsp.5
index 04d45cc..a91f97f 100644
--- a/gsp.5
+++ b/gsp.5
@@ -1,11 +1,277 @@
-.Dd $Mdocdate: September 9 2023 $
+.Dd $Mdocdate: September 10 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 and XML which can be transpiled into
+either by making use of the
+.Xr gsp 1
+transpiler.
+The
+.Nm
+language allows you to structure data in the same manner as XML while offering
+an easier\-to\-read and less verbose syntax, and also some nice shortcuts for
+working with HTML. An example
+.Nm
+document might look as follows:
+.Bd -literal -offset indent
+!html{}
+
+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
+.Ss Node names
+Node names follow the exact same naming rules as names do in XML.
+See the XML references 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 HTML IDs and -classes
+When transpiling to HTML, 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
+.Ss Document types
+Both HTML and XML make use of document types at the start of the document. In
+HTML the document type is of the form
+.Ql <!DOCTYPE attributes>
+while in XML the document type is of the form
+.Ql <?xml attributes?> .
+You can specify a document type in
+.Nm
+by using the special node name
+.Sq \&!
+or
+.Sq \&?
+for an HTML- or XML document type respectively.
+Unlike with the usual node name, you do not need to include whitespace between
+the special node name and the attributes.
+The following example includes a document type that will transpile into
+.Ql <!DOCTYPE html> :
+.Bd -literal -offset indent
+!html{}
+html {
+ head {...}
+ body {...}
+}
+.Ed
+.Pp
+Here is an example of using an XML document type:
+.Bd -literal -offset indent
+?version="1.1" encoding="UTF-8"{}
+document {...}
+.Ed
+.Pp
+You may only specify one document type, and it must be the first node of the
+document.
+.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{}
+
+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
+The typical behavior of
+.Nm
+is to compact whitespace.
+Here you can see a before\-and\-after of transpilation:
+.Bd -literal -offset indent
+Before
+
+foo {
+ bar{- Hello World }
+ baz{-Hello World}
+}
+.Ed
+.Bd -literal -offset indent
+After
+
+<foo><bar>Hello World</bar><baz>Hello World</baz></foo>
+.Ed
+.Pp
+The one exception to this use is when using embedded nodes.
+If your literal text contains an embedded node, then whitespace around the node
+is preserved:
+.Bd -literal -offset indent
+Before
+
+foo {-
+ Hello @bar{-there} world!
+}
+.Ed
+.Bd -literal -offset indent
+After
+
+<foo>Hello <bar>there</bar> world!</foo>
+.Ed
+.Pp
+Therefore if you would like to remove the whitespace, you need to manually
+compact your document:
+.Bd -literal -offset indent
+Before
+
+foo {-
+ Hello@bar{-there}world!
+}
+.Ed
+.Bd -literal -offset indent
+After
+
+<foo>Hello<bar>there</bar>world!</foo>
+.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
--
cgit v1.2.3