Make a valid fastn package

The existing content has been modified a little so that it renders
properly using design-system.fifthtry.site package. The published
website will be the primary way to consume this spec content.

.gitignore

@@ -0,0 +1 @@
+.packages/

FASTN.ftd

@@ -0,0 +1,9 @@
+-- import: fastn
+
+-- fastn.package: fast-nspec
+
+-- fastn.dependency: design-system.fifthtry.site
+
+
+-- fastn.auto-import: design-system.fifthtry.site as ds
+-- fastn.auto-import: fastn/processors as pr

index.ftd

@@ -0,0 +1,35 @@
+-- ds.page: `fastn` Specification
+
+-- ds.section-column:
+align-content: left
+inset: $ds.spaces.inset-wide.large
+
+
+-- ds.copy-regular:
+
+`fastn` is a framework to build UIs. This spec describes the syntax for `fastn`
+programs and their capabilities.
+
+[TBD] A more better introduction can be prepared later.
+
+This is not yet a formal document. It is a work in progress, and written in
+relatively plain English. The goal is to make this an unambiguous document that
+can be used to implement `fastn`. Any contribution is welcome.
+
+The conversations related to the spec takes place on
+[fastn-stack/fastn](https://github.com/orgs/fastn-stack/discussions) and on our
+[discord server](https://discord.gg/fastn-stack-793929082483769345)
+
+Currently there is only [one implementation of
+`fastn`](https://github.com/fastn-stack/fastn/), but other alternate
+implementation can be derived using this spec.
+
+
+-- ds.heading-large: Table of Contents
+
+- [Overview](/overview/)
+- [`ftd::p1` grammar](/p1/)
+
+
+-- end: ds.section-column
+-- end: ds.page

01-overview.ftd → overview.ftd

@@ -1,16 +1,13 @@
 -- ds.page: `fastn` Specification
 
-This document describes the specification of the `fastn` language. It is not intended as
-tutorial.
+-- ds.section-column:
+align-content: left
+inset: $ds.spaces.inset-wide.large
 
-This is not yet a formal document. It is a work in progress, and written in relatively plain
-English. The goal is to make this an unambiguous document that can be used to implement `fastn`,
-and any contribution is welcome.
 
-Currently there is only one implementation of `fastn`, but other alternate implementation are
-welcome.
+-- ds.heading-large: Purpose Of The Language
 
--- ds.h1: Purpose Of The Language
+-- ds.copy-regular:
 
 `fastn` language is a HTTP / User Interface language. A `fastn` program is a fullstack web
 application. The HTTP part, and the User Interface, can be implemented in many ways. The
@@ -31,7 +28,9 @@ Instead of JSON authors can chose to return YML etc also, further, a UI also has
 data, so instead of getting the UI, the client can do content negotiation, and request
 the backing data as JSON or YML etc as well.
 
--- ds.h1: Target
+-- ds.heading-large: Target
+
+-- ds.copy-regular:
 
 `fastn` programs are invoked with a target. The target can be `stdio` for pure text output,
 `terminal` for ncurses based terminal UI, `web` for Web Browsers, `windows`, `osx`, `linux`,
@@ -44,33 +43,43 @@ program can use `target` as a switch to provide different UI for different targe
 on all supported `fastn` targets. Each target can also specify its own components, and
 are only available on that target.
 
--- ds.h2: Target Specific Libraries
+-- ds.heading-large: Target Specific Libraries
+
+-- ds.copy-regular:
 
 Target can also specify libraries that are available only on that target. There is a
 target native way to define UI components, and library functions, that are available
 when using that target. fastn ui components can use these target specific components,
 and fastn user defined functions can call target specific functions.
 
--- ds.h2: Target Neutral Vs Target Dependent Code
+-- ds.heading-large: Target Neutral Vs Target Dependent Code
+
+-- ds.copy-regular:
 
 When writing code, authors can write target neutral code, or target dependent code.
 Most programs would use target neutral code, and only use target dependent code when
 absolutely necessary.
 
 
--- ds.h1: Main `fastn` Package
+-- ds.heading-large: Main `fastn` Package
+
+-- ds.copy-regular:
 
 `fastn` code is organised as packages. There is a main package, which is the entrypoint of
 the `fastn` program. The main package is the package that is invoked when the `fastn` program
 is run.
 
--- ds.h1: File Path Based Routing
+-- ds.heading-large: File Path Based Routing
+
+-- ds.copy-regular:
 
 `fastn` programs take route, and other request input, as parameter. The `route` or `path`
 is converted to a file path, and the file path is used to find the `fastn` module within
 the fastn package.
 
--- ds.h2: Dynamic Routes
+-- ds.heading-large: Dynamic Routes
+
+-- ds.copy-regular:
 
 `fastn` package can have dynamic routes. The dynamic routes are specified in `FASTN.ftd`
 file, and the dynamic routes are used to find the `fastn` module within the package.
@@ -79,7 +88,9 @@ The dynamic routes can contain wildcards, and the wildcards are used to extract
 from the route, and these values are passed to the `fastn` module.
 
 
--- ds.h1: `fastn` Package
+-- ds.heading-large: `fastn` Package
+
+-- ds.copy-regular:
 
 `fastn` compiler works at package level. `fastn` files have an extension, `.ftd` and they are
 organised into `fastn` packages. Each `fastn` package has a mandatory `FASTN.ftd` file at the
@@ -96,7 +107,7 @@ lang: ftd
 \-- import: fastn
 \-- fastn.package: hello-world
 
--- ds.h1: `fastn` modules
+-- ds.heading-large: `fastn` modules
 
 Any ftd file in a fastn package is a "fastn module". A fastn package is composed of zero or
 more modules, and zero or more static files.
@@ -108,21 +119,25 @@ lang: ftd
 
 \-- ftd.module foo: ;;
 
--- ds.h1: `p-script`
+-- ds.heading-large: `p-script`
 
 The `fastn` files are composed of "sections", described in 02-p1 chapter. Each
 
 
--- ds.h1: Comments
+-- ds.heading-large: Comments
+
+-- ds.heading-large: Line Comments
 
--- ds.h2: Line Comments
+-- ds.copy-regular:
 
 `fastn` uses `;;` as line comment character. Everything from the first ``;;` till the end
 of line is comment. Comments can be escaped by prefixing a backslash character: `\;;`.
 Literal backslash can be inserted by putting two backslashes, `\\`.
 
 
--- ds.h2: Structural Comments
+-- ds.heading-large: Structural Comments
+
+-- ds.copy-regular:
 
 Entire "section" can be commented out by adding a `/` in the front of the section, e.g.,
 
@@ -137,13 +152,13 @@ the next section or the end of file.
 
 \-- ftd.text: next section, not commented
 
--- ds.markdown:
+-- ds.copy-regular:
 
 In `0.4` we also allow `/` to comment out entire body, but we are deprecating that in
 `0.5`.
 
 `/` can also be added in any of the section header, both simple and multi-line, to comment
 out the entire header.
 
-
--- end: ds.page
+-- end: ds.section-column
+-- end: ds.page

02-p1.ftd → p1.ftd

@@ -1,8 +1,14 @@
 -- ds.page: `ftd::p1` grammar
 
+-- ds.section-column:
+align-content: left
+inset: $ds.spaces.inset-wide.large
+
+-- ds.copy-regular:
+
 `fastn` is based on a low-level grammar called `ftd::p1` grammar.
 
--- ds.h1: `section`
+-- ds.heading-large: `section`
 
 A `ftd::p1` file is composed of "sections". A section looks like this:
 
@@ -18,13 +24,13 @@ the body of the first section
 \-- something:
 yo: 42
 
--- ds.markdown:
+-- ds.copy-regular:
 
 Each section starts with `-- `.
 
 The section has these properties:
 
--- ds.h2: `section kind`
+-- ds.heading-medium: `section kind`
 
 The section kind can be define after `-- ` and before the section name. This is
 optional parameter.
@@ -52,7 +58,7 @@ lang: ftd
 
 
 
--- ds.h2: `section name`
+-- ds.heading-medium: `section name`
 
 The section name is the only **mandatory parameter** for a section. Name starts
 after `-- ` or section kind if present, and ends with the first `:`. Trailing
@@ -66,7 +72,7 @@ hash(`#`), and hyphens(`-`). Colon terminates the section name.
 
 Leading and trailing whitespaces are not considered part of the section name.
 
--- ds.h2: `section caption`
+-- ds.heading-medium: `section caption`
 
 What comes after `:` in the section line, till the end of the first line is called
 the `caption` of the section.
@@ -78,7 +84,7 @@ the second section does not have a caption.
 
 Leading and trailing whitespaces are not considered part of the caption.
 
--- ds.h2: `section headers`
+-- ds.heading-medium: `section headers`
 
 After the "section line" (the first line that starts with `-- `), zero or more
 section headers can be passed. Header can be passed in two ways: `inline` and
@@ -87,7 +93,7 @@ section headers can be passed. Header can be passed in two ways: `inline` and
 A section header consists of name (mandantory), kind (optional) and value
 (optional).
 
--- ds.h3: `inline header`
+-- ds.heading-small: `inline header`
 
 In our example, the section has two headers, having names `header-1` and
 `hello`, with values `some header value` and `world` respectively. Also the
@@ -104,7 +110,7 @@ lang: ftd
 header-kind header-1: some header value
 hello: world
 
--- ds.h3: `block header` - Deprecated
+-- ds.heading-small: `block header` - Deprecated
 
 We can also pass headers in block. This is commonly used when the value of
 header is long and passing it in `inline` creates readability issue.
@@ -116,10 +122,16 @@ lang: ftd
 
 \-- section-name.block-header:
 
-Lorem ipsum dolor sit amet. Vel magni dolorum et doloremque nostrum aut dicta unde 33 quod quisquam sed ducimus placeat et placeat reiciendis ad nostrum rerum. Qui quasi eserunt ut aliquid galisum et harum porro et libero facilis cum corporis voluptatem est beatae minima non voluptatem maxime. Est quod ipsum sed neque labore ut tempora porro ut quae distinctio ad enim voluptatem ex praesentium molestiae. Ea iusto consectetur ab sequi voluptatem et inventore iste.
+Lorem ipsum dolor sit amet. Vel magni dolorum et doloremque nostrum aut dicta
+unde 33 quod quisquam sed ducimus placeat et placeat reiciendis ad nostrum
+rerum. Qui quasi eserunt ut aliquid galisum et harum porro et libero facilis
+cum corporis voluptatem est beatae minima non voluptatem maxime. Est quod ipsum
+sed neque labore ut tempora porro ut quae distinctio ad enim voluptatem ex
+praesentium molestiae. Ea iusto consectetur ab sequi voluptatem et inventore
+iste.
 
 
--- ds.markdown:
+-- ds.copy-regular:
 
 The block header can be declared after `inline` header. It starts with `-- `,
 follow by header kind, if present, then section name with `.` and after
@@ -145,7 +157,7 @@ lang: ftd
 
 \-- end: section-name.block-header
 
--- ds.h3: `end: header`
+-- ds.heading-small: `end: header`
 
 -- ds.code:
 lang: ftd
@@ -159,19 +171,19 @@ end: sidebar
 next-foo-header: 1
 
 
--- ds.markdown:
+-- ds.copy-regular:
 
 In this case the `sidebar` header to `foo` is a block header, and it ends at the
 `end: sidebar`
 
--- ds.h2: `section body`
+-- ds.heading-medium: `section body`
 
 Like header, body can be passed in two ways: `inline` and `block`
 The body is optional.
 
 Leading and trailing newlines are not considered part of the body.
 
--- ds.h3: `inline` body
+-- ds.heading-small: `inline` body
 
 After the first empty line that comes after the section header, till the start
 of next section is considered the body of the section.
@@ -190,7 +202,7 @@ header: header value
 This is body
 
 
--- ds.h3: `block` body
+-- ds.heading-small: `block` body
 
 A section body can be passed as a `block`. This is particularly helpful in case
 if the `block` headers are defined. In that case, the `body` can't be passed in
@@ -208,7 +220,7 @@ lang: ftd
 This is body
 
 
--- ds.markdown:
+-- ds.copy-regular:
 
 In above example, `my-body` is the body of section.
 
@@ -218,7 +230,7 @@ Unlike `header`, `body` doesn't accept list of sections as value.
 
 
 
--- ds.h1: `sub-section`
+-- ds.heading-large: `sub-section`
 
 A section can contain zero or more `sub-sections`:
 
@@ -235,7 +247,7 @@ subsection2 body
 
 \-- end: some-section
 
--- ds.markdown:
+-- ds.copy-regular:
 
 `subsections` are nothing but list of sections itself. If subsections are
 defined, the section need to mark it's end using `end` keyword.
@@ -249,10 +261,11 @@ In above example, `some-section` section has two `sub-section`s, with names
 and the second one has a body, `subsection2 body`.
 
 
--- ds.h1: Programmatic Access
+-- ds.heading-large: Programmatic Access
 
 `ftd::p11` module in `ftd` crate can be used to read `ftd.p1` files. Wrappers of
 this crate in Python and other programming languages would hopefully come soon.
 
 
+-- end: ds.section-column
 -- end: ds.page