~ivilata/gwit-spec

9671f676adeb963aa4f458cbfbef7e66f5bd0b20 — Ivan Vilata-i-Balaguer 4 months ago e65516b 
Convert site key values in INI files into subsection names.

This breaking change avoids the chance of having two introductions for
different sites with the same full section name, as site IDs are unique (but
proposed names are not).

A subtle burden for the author is introduced since the site configuration must
also include the correctly formatted site ID, but this may be justified for
making site configuration and site introductions more similar, bringing closer
the possibility of using site configurations and introductions
interchangeably (with the same format).

Motivated by a discussion with Mitra Ardron.
patch browse .tar.gz 
1 files changed, 15 insertions(+), 13 deletions(-)

M README.md

M README.md => README.md +15 -13
@@ 92,7 92,7 @@ No restrictions are placed upon content files themselves, but it is RECOMMENDED 
[ini-file]: https://en.wikipedia.org/wiki/INI_file
    "INI file (Wikipedia)"

The `site` section of `_gwit/self.ini` contains some basic information about the gwit site, meant for its readers except where otherwise noted. It has no subsections. Values recognized in the section are:
The `site.<SITE-ID>` section of `_gwit/self.ini` contains some basic information about the gwit site, meant for its readers except where otherwise noted. Its `<SITE-ID>` MUST be the identifier of the site itself, encoded as `0x` plus the lower case hexadecimal digits of the full fingerprint of the PGP site key. Example: `[site "0xfedcba98765432100123456789abcdef76543210"]`. It has no subsections. Values recognized in the section are:

- `name` (single, recommended): A short name or handle for the site. It MUST NOT (i) be empty or consist only of whitespace characters, (ii) contain newline or control characters, (iii) start with `0x` or `0X`. Example: "Foo Bar".



@@ 108,11 108,15 @@ The `site` section of `_gwit/self.ini` contains some basic information about the
- `branch` (single, 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` (multiple, 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 prefixes 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:
`meet.<INTRO-SITE-ID>` sections 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's `<INTRO-SITE-ID>` MUST be the identifier of the introduced site, with the same format as the `site.<SITE-ID>` section (see above). Example: `[meet "0x0123456789abcdef0123456789abcdeffedcba98"]`. Values recognized in the section are:

- `key` (single, mandatory): The identifier of the introduced site, encoded as `0x` or `0X` plus the hexadecimal digits of the full fingerprint of the PGP site key (case insensitive). Example: `0x0123456789ABCDEF0123456789ABCDEFFEDCBA98`.
- `remote` (multiple, mandatory): The URL of a Git remote from where the introduced site can be retrieved (akin to `site.remote`; multiple values are also accepted). Example: `https://hub.example.com/someone/my-gwit-site.git`.
- `branch` (single, optional): The branch of the Git repository to be used as the default branch for the introduced site (akin to `site.branch`). Example: `published`.
- `name` (single, recommended): A short name or handle for the introduced site. Example: `Someone's site`.

  A gwit client MAY regard it as the author's proposed name for that site (its edge name).
- `remote` (multiple, mandatory): The URL of a Git remote from where the introduced site can be retrieved. Example: `https://hub.example.com/someone/my-gwit-site.git`.
- `branch` (single, optional): The branch of the Git repository to be used as the default branch for the introduced site. Example: `published`.

These values have the same number, format and restrictions as their homonyms in the `site.<SITE-ID>` section.

The scope of the different site configuration values is described below:



@@ 124,7 128,7 @@ The scope of the different site configuration values is described below:
This is a sample `_gwit/self.ini` file using all sections and values:

```
[site]
[site "0xfedcba98765432100123456789abcdef76543210"]
name = Foo Bar
title = Foo Bar: the Bar for all your Foos
title-fr = Le Bar de Foo : le Bar pour tous vos Foos


@@ 141,8 145,8 @@ 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
[meet "0x0123456789abcdef0123456789abcdeffedcba98"]
name = Someone's site
remote = https://hub.example.com/someone/my-gwit-site.git
remote = https://lab.example.org/s.one/gwit-site.git
branch = published


@@ 341,23 345,21 @@ One of gwit's goals is to make existing Web or Gemini static sites easy to publi

For a more seamless integration, one should be able to identify such a **combined site** and get the information needed to access it over gwit. However, since the `_gwit` directory is always found in the Git repository's top directory, if the site is configured to use a different root directory (i.e. `site.root` in `_gwit/self.ini`), those files may not be available via legacy URIs.

A Well-Known URI ([RFC8615][]) MAY be used to provide such site metadata, accessible via the `/.well-known/gwit.ini` legacy URI path, i.e. `<SITE-ROOT>/.well-known/gwit.ini`. This file MUST use the same INI syntax as the site configuration file (see further above), and contain a `site` section with the following values:
A Well-Known URI ([RFC8615][]) MAY be used to provide such site metadata, accessible via the `/.well-known/gwit.ini` legacy URI path, i.e. `<SITE-ROOT>/.well-known/gwit.ini`. This file MUST use the same INI syntax as the site configuration file (see further above), and contain a `site.<SITE-ID>` section where `<SITE-ID>` MUST be the identifier of the site itself, with the same format as the homonymous site configuration section. Values recognized in the section are:

[RFC8615]: https://www.rfc-editor.org/rfc/rfc8615.html
    "Well-Known Uniform Resource Identifiers (URIs) (RFC 8615)"

- `key` (mandatory): The identifier of the site, using the same syntax as `meet.key` in the site configuration file.
- `remote` (mandatory): The URL of a Git remote from where the site can be retrieved; equivalent to `site.remote` in the site configuration file. Multiple such values are also accepted.
- `branch` (optional): The branch of the Git repository to be used as the default branch for the site; equivalent to `site.branch` in the site configuration file.

Which is effectively a site's introduction to itself. Other sections and values SHOULD be ignored. An example of such file follows:

```
[site]
key = 0xFEDCBA98765432100123456789ABCDEF76543210
[site "0xfedcba98765432100123456789abcdef76543210"]
remote = https://git.example.net/foo/bar-site.git
remote = https://lab.example.org/foo-mirror/bar-site.git
branch = gemini-output
```

Since the same values of `site.remote` and `site.branch` may also appear in a site's configuration file, and unknown values in it are ignored, a site author may add `site.key` in there, then link that file to `<SITE-ROOT>/.well-known/gwit.ini` to avoid duplicating information among both files.
Since the same values of `site.remote` and `site.branch` may also appear in a site's configuration file, and unknown values in `<SITE-ROOT>/.well-known/gwit.ini` are ignored, a site author may make the latter a symbolic link to the former to avoid duplicating information among both files.