~ivilata/gwit-spec

9a7cfd18247fd171f90a2a3a56ed35dd036076c4 — Ivan Vilata-i-Balaguer 10 months ago d01d907
Correct mentions to INI "sections" which are actually subsections.

Especially for the `[site "<ID>"]` subsection of site configuration.
1 files changed, 4 insertions(+), 4 deletions(-)

M README.md
M README.md => README.md +4 -4
@@ 89,7 89,7 @@ No restrictions are placed upon content files themselves, but it is RECOMMENDED 

### Site configuration file

`_gwit/self.ini` has the same format as [Git configuration files][git-config-file], which can be summarized as an [INI file][ini-file] where some section definitions have a `[section-name "subsection-name"]` format. It MUST be encoded using UTF-8, all its values MUST be considered as simple strings (i.e. no special parsing of integers or pathnames), and includes MUST be disabled. Each single encoded value MUST NOT exceed 1000 bytes (unless otherwise stated below), values with multiple occurrences MUST NOT have more than 10 single values, and the whole file MUST NOT exceed 65536 bytes.
`_gwit/self.ini` has the same format as [Git configuration files][git-config-file], which can be summarized as an [INI file][ini-file] where subsection definitions have a `[section-name "subsection-name"]` format. It MUST be encoded using UTF-8, all its values MUST be considered as simple strings (i.e. no special parsing of integers or pathnames), and includes MUST be disabled. Each single encoded value MUST NOT exceed 1000 bytes (unless otherwise stated below), values with multiple occurrences MUST NOT have more than 10 single values, and the whole file MUST NOT exceed 65536 bytes.

Recognized sections and values are described below, and unknown ones SHOULD be ignored. If a value marked as "single" is assigned more than once in the file, the last assignment is used.



@@ 98,7 98,7 @@ Recognized sections and values are described below, and unknown ones SHOULD be i
[ini-file]: https://en.wikipedia.org/wiki/INI_file
    "INI file (Wikipedia)"

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:
The `[site "<ID>"]` subsection 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"]`. Values recognized in the subsection 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".



@@ 149,7 149,7 @@ A site's `_gwit` directory may also contain **site introductions**, which allow 

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 and features of a site introduction file are those of a site configuration file (see further above). For introducing a site with identifier `<ID>`, the introduction file MUST contain a `[site "<ID>"]` section (the introduction proper), which MUST define at least one `site.<ID>.remote` value. The site identifier in the file name `_gwit/<ID>.ini` MUST match that in the file's `[site "<ID>"]` section.
The format and features of a site introduction file are those of a site configuration file (see further above). For introducing a site with identifier `<ID>`, the introduction file MUST contain a `[site "<ID>"]` subsection (the introduction proper), which MUST define at least one `site.<ID>.remote` value. The site identifier in the file name `_gwit/<ID>.ini` MUST match that in the file's `[site "<ID>"]` subsection.

While the value of `site.<ID>.remote` 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.



@@ 358,7 358,7 @@ One of gwit's goals is to make existing Web or Gemini static sites easy to publi

For a more seamless integration, it should be possible to use the other protocols supported by such a **combined site** to both identify it as such 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 URIs.

A Well-Known URI ([RFC8615][]) MAY be used to provide such site metadata, accessible via the `/.well-known/gwit.ini` URI path, mapping to the repository file `<SITE-ROOT>/.well-known/gwit.ini`. The format and features of this file are those of a site introduction file (see further above), where the site introduces itself: there MUST be exactly one `[site "<ID>"]` section. As with any introduction, the only truly relevant pieces of information are the site ID and the value(s) of `site.<ID>.remote` (e.g. `git config -f … --get-regexp '^site\.0x[0-9a-f]+\.remote$'`).
A Well-Known URI ([RFC8615][]) MAY be used to provide such site metadata, accessible via the `/.well-known/gwit.ini` URI path, mapping to the repository file `<SITE-ROOT>/.well-known/gwit.ini`. The format and features of this file are those of a site introduction file (see further above), where the site introduces itself: there MUST be exactly one `[site "<ID>"]` subsection. As with any introduction, the only truly relevant pieces of information are the site ID and the value(s) of `site.<ID>.remote` (e.g. `git config -f … --get-regexp '^site\.0x[0-9a-f]+\.remote$'`).

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