I'd been mentally assuming a zipped directory containing all the file, whereas Skyjake has implemented compressed flat files. I think Skyjake's way is more correct, and certainly easier when implementing a reader, but opening it up for discussion here.
Either way, we need to clarify this in the spec.
I'd been mentally assuming a zipped directory containing all the file, whereas Skyjake has implemented compressed flat files. I think Skyjake's way is more correct, and certainly easier when implementing a reader, but opening it up for discussion here.
Either way, we need to clarify this in the spec.
To elaborate, requiring metadata.txt or index.gmi in the ZIP root (without any subdirectory as a prefix) makes it trivial to detect its presence and read it. This allows a reader to use the .gpub archive in compressed form as-is (that's what Lagrange is doing).
The rest of the .gpub archive doesn't have to be flat in any way, as long as the metadata is in the same place in every .gpub.
To elaborate, requiring `metadata.txt` or `index.gmi` in the ZIP root (without any subdirectory as a prefix) makes it trivial to detect its presence and read it. This allows a reader to use the .gpub archive in compressed form as-is (that's what Lagrange is doing).
The rest of the .gpub archive doesn't have to be flat in any way, as long as the metadata is in the same place in every .gpub.
This file enables Gempub to act as a full eBook format. Gemini capsules can also be simply zip compressed without the metadata file to act as a Gemini archive/offline format - when operating as an archive there must be an index.gmi in the root directory.
I think we'd want to say something along the following lines:
Directory Structure
Gempub files are zipped directories of Gemtext ".gmi" files plus an optional metadata file:
• metadata.txt - a file containing the title, author and any other optional fields. See "Metadata", below.
The optional metadata.txt file enables Gempub to act as a complete e-book format.
Gempub is also designed to support the scenario in which the contents of an existing Gemini capsule are simply zip compressed. This allows a Gempub container to be used as an offline Gemini archival format.
In order to support both the e-book and offline archive scenarios, either the metadata.txt file or an index.gmi file (with text/gemini MIME type) MUST be present in the root directory of the archive.
If the root directory of the archive contains neither a metadata.txt nor an index.gmi file, reader applications MUST not display the contents of the file, and MUST instead display a notification to the user explaining that the archive is not valid due to a missing index or metadata file.
(Not sure about the last requirement, although I do think that the spec needs to require that reader applications refuse to do any sort of "best effort" display attempts.)
Treat the above as a whiteboarding effort. If you like the general sentiment we can clean up the language as we go.
Raph
The current language is:
> This file enables Gempub to act as a full eBook format. Gemini capsules can also be simply zip compressed without the metadata file to act as a Gemini archive/offline format - when operating as an archive there must be an index.gmi in the root directory.
I think we'd want to say something along the following lines:
> ## Directory Structure
>
> Gempub files are zipped directories of Gemtext ".gmi" files plus an optional metadata file:
>
> • `metadata.txt` - a file containing the title, author and any other optional fields. See "Metadata", below.
>
> The optional `metadata.txt` file enables Gempub to act as a complete e-book format.
>
> Gempub is also designed to support the scenario in which the contents of an existing Gemini capsule are simply `zip` compressed. This allows a Gempub container to be used as an offline Gemini archival format.
>
> In order to support both the e-book and offline archive scenarios, either the `metadata.txt` file or an `index.gmi` file (with `text/gemini` MIME type) MUST be present in the root directory of the archive.
>
> If the root directory of the archive contains neither a `metadata.txt` nor an `index.gmi` file, reader applications MUST not display the contents of the file, and MUST instead display a notification to the user explaining that the archive is not valid due to a missing index or metadata file.
(Not sure about the last requirement, although I do think that the spec needs to require that reader applications refuse to do any sort of "best effort" display attempts.)
Treat the above as a whiteboarding effort. If you like the general sentiment we can clean up the language as we go.
Raph
I'd been mentally assuming a zipped directory containing all the file, whereas Skyjake has implemented compressed flat files. I think Skyjake's way is more correct, and certainly easier when implementing a reader, but opening it up for discussion here.
Either way, we need to clarify this in the spec.
To elaborate, requiring
metadata.txtorindex.gmiin the ZIP root (without any subdirectory as a prefix) makes it trivial to detect its presence and read it. This allows a reader to use the .gpub archive in compressed form as-is (that's what Lagrange is doing).The rest of the .gpub archive doesn't have to be flat in any way, as long as the metadata is in the same place in every .gpub.
The current language is:
I think we'd want to say something along the following lines:
(Not sure about the last requirement, although I do think that the spec needs to require that reader applications refuse to do any sort of "best effort" display attempts.)
Treat the above as a whiteboarding effort. If you like the general sentiment we can clean up the language as we go.
Raph