~ivilata/gwit-spec

65b8c17fa4db162ea2e9fbecac1d8520e9339af8 — Ivan Vilata-i-Balaguer 5 months ago b1732b4 
Use multiple `site.alt` values instead of `alt` sections.

In a similar way as `site.remote` and `meet.remote`.

This breaking change is justified by 3 reasons: (i) easier provision of
alternates, with less syntax; (ii) no need for thinking alternate names (nor
assume there is some "correct" name for a given protocol); (iii) avoid
misguiding alternate names.

The example also shows two HTTPS alternates since there is no restriction on
two of them being for the same protocol (and it may be the case for sites
which changed their location in the past).
patch browse .tar.gz 
1 files changed, 6 insertions(+), 12 deletions(-)

M README.md

M README.md => README.md +6 -12
@@ 106,10 106,7 @@ The `site` section of `gwit.ini` contains some basic information about the gwit 
- `index` (optional): The name of the **index file**. It MUST NOT be empty, `.` or `..`, or contain slash characters (`/`). When a gwit client is told to retrieve a directory, and it contains a file named as the index file, the contents of the file SHOULD be produced instead of a directory listing. Example (for a site containing Gemini files): `index.gmi`.
- `remote` (recommended): A location recommended by the author for retrieving the site, the URL of a Git remote. Multiple such locations may be given (for increased availability), each as a different `remote` value, which a client MAY consider in order of appearance. Example: `https://git.example.net/foo/bar-site.git`.
- `branch` (optional): If given, the name of the Git branch to be used as the default branch for the site. This is useful when the given branch of the Git repository contains files output by a static site generator, while `remote`'s default branch (usually `master` or `main`) only contains sources. It takes precedence over other values of `meet.branch` for this site (see further below). Example (for a site converted to Gemini files): `gemini-output`.

`alt` sections with arbitrary, unique names (like `www`) allow the site author to indicate URI prefixes of the site for other publication systems. The gwit client MAY interpret site links using those prefixes as if they began with a single slash (`/`) instead of the prefix and subsequent slashes. This enables reusing site contents in gwit without needing to adapt local absolute links. Values recognized in the section are:

- `base` (mandatory): The prefix of site URIs for this publication system. Example: `https://foo.example.net/bar/` under `alt` section `www` enables rewriting `https://foo.example.net/bar//page.html` to `/page.html`.
- `alt` (optional): If given, the prefix for this site's URIs in a publication system other than gwit. The gwit client MAY interpret links in this site using those prefixes as if they began with a single slash (`/`) instead of the prefix and subsequent slashes. This enables reusing site contents in gwit without needing to adapt local absolute links. Multiple such locations may be given, each as a different `alt` value. Example: `https://foo.example.net/bar/` enables rewriting `https://foo.example.net/bar//page.html` to `/page.html`.

`meet` sections with arbitrary, unique names (like `Someone's site`) constitute **site introductions**, which allow the site author to provide the information needed for the initial retrieval of other gwit sites (see further below). *This is the main means of content discovery in gwit*, thus site authors SHOULD provide such introductions for the sites that they link to. The section name MUST follow the same restrictions as the value of `name` in the `site` section. A gwit client MAY regard it as the author's proposed name for that site (its edge name). Values recognized in the section are:



@@ 121,7 118,7 @@ The scope of the different site configuration values is described below:

- `site.name`: The value in the latest site version, if defined, SHOULD be read on initial site retrieval, then applied to all versions of the site (past and future, until manually overridden).
- `site.title(-*)`, `site.desc(-*)`: The value in the latest site version, if defined, MAY be applied to previous versions as well, though the value in a specific version, if defined, SHOULD be applied to that version.
- `site.license`, `site.root`, `site.index`, `alt.*`: The value in a specific version, if defined, SHOULD be applied only to that version.
- `site.license`, `site.root`, `site.index`, `site.alt`: The value in a specific version, if defined, SHOULD be applied only to that version.
- `site.remote`, `site.branch`, `meet.*`: The value in the latest site version, if defined, MAY be applied on initial site retrieval and updates. The handling of old values is at the discretion of the gwit client.

This is a sample `gwit.ini` file using all sections and values:


@@ 140,12 137,9 @@ remote = https://git.example.net/foo/bar-site.git
remote = https://lab.example.org/foo-mirror/bar-site.git
remote = https://hut.example.org/foo-mirror/bar-site
branch = gemini-output

[alt "www"]
base = https://foo.example.net/bar/

[alt "gemini"]
base = gemini://foo.example.net/bar-site/
alt = https://example.net/~foo/bar/
alt = https://foo.example.net/bar/
alt = gemini://foo.example.net/bar-site/

[meet "Someone's site"]
key = 0x0123456789ABCDEF0123456789ABCDEFFEDCBA98


@@ 335,7 329,7 @@ The client MUST then resolve the path `<PATH>` in the URI (which has already bee

Any error or failed check in the previous steps would cause the process to stop at the current step, discard any temporary data, and report an error.

When producing or displaying contents on URI retrieval, the gwit client MAY make use of any site configuration value which applies to the chosen version. For instance, it may show the site title (from `site.title`) or replace site URI prefixes for other publication systems in links (as per `alt.base`).
When producing or displaying contents on URI retrieval, the gwit client MAY make use of any site configuration value which applies to the chosen version. For instance, it may show the site title (from `site.title`) or replace site URI prefixes for other publication systems in links (as per `site.alt`).

## Appendix: Enabling discovery of combined sites via Well-Known URIs