~ivilata/gwit-spec

51b9b875e421266049c99eb026a2f28160b58a08 — Ivan Vilata-i-Balaguer 1 year, 2 months ago 2bc706e 
Make references to INI values more consistent.

Also consistent with the way they are used with `git config`.
patch browse .tar.gz 
1 files changed, 17 insertions(+), 17 deletions(-)

M README.md

M README.md => README.md +17 -17
@@ 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.<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:
The `site.<ID>` section of `_gwit/self.ini` contains some basic information about the gwit site, meant for its readers except where otherwise noted. Its `<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".



@@ 110,10 110,10 @@ The `site.<SITE-ID>` section of `_gwit/self.ini` contains some basic information

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`, `site.alt`: The value in a specific version, if defined, SHOULD be applied only to that version.
- `site.remote`, `site.branch`: 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.
- `site.<ID>.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.<ID>.title(-*)`, `site.<ID>.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.<ID>.license`, `site.<ID>.root`, `site.<ID>.index`, `site.<ID>.alt`: The value in a specific version, if defined, SHOULD be applied only to that version.
- `site.<ID>.remote`, `site.<ID>.branch`: 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/self.ini` file using all sections and values:



@@ 140,13 140,13 @@ alt = gemini://foo.example.net/bar-site/

A site's `_gwit` directory may also contain **site introductions**, which allow the site author to provide the information needed for the retrieval of other gwit sites. *This is the main means of content discovery in gwit*, thus site authors SHOULD provide such introductions for the sites that they link to.

An introduction for a given site MUST be contained in the file `_gwit/<SITE-ID>.ini`, where `<SITE-ID>` is the identifier of the introduced site, encoded as `0x` plus the lower case hexadecimal digits of the full fingerprint of the PGP site key. Example: `_gwit/0x0123456789abcdef0123456789abcdeffedcba98.ini`.
An introduction for a given site MUST be contained in the file `_gwit/<ID>.ini`, where `<ID>` is the identifier of the introduced site, encoded as `0x` plus the lower case hexadecimal digits of the full fingerprint of the PGP site key. Example: `_gwit/0x0123456789abcdef0123456789abcdeffedcba98.ini`.

The format of a site introduction is that of a site configuration file (see further above), with the exception that `site.remote` becomes a mandatory value. For any given introduction, its `<SITE-ID>` MUST match between the file name `_gwit/<SITE-ID>.ini` and its section `[site "<SITE-ID>"]`.
The format of a site introduction is that of a site configuration file (see further above), with the exception that `site.<ID>.remote` becomes a mandatory value. For any given introduction to a site, its identifier MUST match with the file name `_gwit/<ID>.ini` and its section `[site "<ID>"]`.

While the values of `site.remote` and `site.branch` may be used for retrieving the introduced site, the rest of values may be considered as mere hints (since there is no guarantee that they come from that site's author), and they SHOULD be overridden by the client with the equivalent values of the actual site configuration file, once available locally.
While the values of `site.<ID>.remote` and `site.<ID>.branch` may be used for retrieving the introduced site, the rest of values may be considered as mere hints (since there is no guarantee that they come from that site's author), and they SHOULD be overridden by the client with the equivalent values of the actual site configuration file, once available locally.

Also note that a gwit client MAY regard an introduction's `site.name` as this site author's proposed name for that site (its edge name); as such, the client SHOULD allow configuring a petname value that overrides it along other proposed names for the site.
Also note that a gwit client MAY regard an introduction's `site.<ID>.name` as this site author's proposed name for that site (its edge name); as such, the client SHOULD allow configuring a petname value that overrides it along other proposed names for the site.

This is a sample introduction, stored in the `_gwit/0x0123456789abcdef0123456789abcdeffedcba98.ini` file:



@@ 205,7 205,7 @@ If someone wants to retrieve updates to a gwit site identified by `<SITE-ID>` fo

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. If the Git clone includes additional remotes, the client MAY choose to repeat the procedure with another one in case of error, or to look for newer content.

After the previous steps, the client MAY access the `_gwit/self.ini` file in the `HEAD` commit (e.g. `git cat-file blob <COMMIT>:_gwit/self.ini`) and apply any relevant configuration values (see further above). In particular, a change in `site.remote` or `site.branch` MAY trigger another update with the new values (e.g. after `git remote set-url origin <NEW-REMOTE>` and `git symbolic-ref HEAD refs/heads/<NEW-BRANCH>`).
After the previous steps, the client MAY access the `_gwit/self.ini` file in the `HEAD` commit (e.g. `git cat-file blob <COMMIT>:_gwit/self.ini`) and apply any relevant configuration values (see further above). In particular, a change in `site.<SITE-ID>.remote` or `site.<SITE-ID>.branch` MAY trigger another update with the new values (e.g. after `git remote set-url origin <NEW-REMOTE>` and `git symbolic-ref HEAD refs/heads/<NEW-BRANCH>`).

### Site history rewrites



@@ 286,7 286,7 @@ A client MAY display a petname-decorated version of a gwit URI. Such representat

As mentioned further above, a gwit client may learn the self-proposed name of a site from its configuration file, as well as the edge names of introduced sites. In that case, it should also allow to set a different petname for any such site.

For instance, Alice retrieves Bob's site (with ID `<BOB-ID>`) for the first time using her gwit client. That site's `_gwit/self.ini` file sets `Bob's site` as the value of `site.name`; the site also contains an introduction of Carol's site (with ID `<CAROL-ID>`) having `This is Carol` as the value of `site.name`.
For instance, Alice retrieves Bob's site (with ID `<BOB-ID>`) for the first time using her gwit client. That site's `_gwit/self.ini` file sets `Bob's site` as the value of `site.<BOB-ID>.name`; the site also contains an introduction of Carol's site (with ID `<CAROL-ID>`) having `This is Carol` as the value of `site.<CAROL-ID>.name`.

Alice's gwit client follows the petname implementation hints described in the paper [Implementation of a petnames system in an existing chat application][petnames-impl]. Thus, when the client finds a link to



@@ 344,21 344,21 @@ 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 `site.alt`).
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.<SITE-ID>.title`) or replace site URI prefixes for other publication systems in links (as per `site.<SITE-ID>.alt`).

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

One of gwit's goals is to make existing Web or Gemini static sites easy to publish in parallel as gwit sites. This may be as simple as distributing site files in a Git repository, along with `_gwit/self.key` and `_gwit/self.ini` files, and using the key in `_gwit/self.key` to sign commits.

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.
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.<ID>.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.<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:
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.<ID>` section where `<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)"

- `remote` (multiple, mandatory): The URL of a Git remote from where the site can be retrieved; equivalent to `site.remote` in the site configuration file.
- `branch` (single, 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.
- `remote` (multiple, mandatory): The URL of a Git remote from where the site can be retrieved; equivalent to `site.<ID>.remote` in the site configuration file.
- `branch` (single, optional): The branch of the Git repository to be used as the default branch for the site; equivalent to `site.<ID>.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:



@@ 369,4 369,4 @@ 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 `<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.
Since the same values of `site.<ID>.remote` and `site.<ID>.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.