zinricky
/
gempub
mirror of https://codeberg.org/oppenlab/gempub.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request 'Minor grammatical changes.' (#11) from raphm/gempub:main into main 

Reviewed-on: https://codeberg.org/oppenlab/gempub/pulls/11
This commit is contained in:
ÖLAB 2021-04-27 21:10:54 +02:00
parent af5f353a49 9ea1db0272
commit 8dff4a6ee1
1 changed files with 17 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
README.md
View File

@ -1,6 +1,5 @@
![GEMPUB](GEMPUB.png)
**[1 Overview](#1-overview)**
     [1.1 Goals](#1-1-goals)
     [1.2 Non-Goals](#1-2-non-goals)
@ -23,33 +22,33 @@ Questions, comments, help: oppen@fastmail.com
## 1 Overview
While [implementing an .epub reader](https://codeberg.org/oppenlab/OppenBok) it became apparant that it's practically impossible to separate the data from the presentation. .ePubs are zipped html + metadata, even Google with their infinite resources don't manage to render pages correctly for all titles in Play Books (mangled and unusable index pages are common). It's a lot of work and effort to attempt to convert html markup into another format that can be rendered natively.
While [implementing an .epub reader](https://codeberg.org/oppenlab/OppenBok) it became apparent that it is practically impossible to separate an ebook's data from its presentation. EPUB archives are zipped HTML and metadata, and even Google with its infinite resources is unable to render pages correctly for all titles in Play Books, where mangled and unusable index pages are common. It's a lot of work and effort to attempt to convert HTML markup into another format that can be rendered natively.
Gemini Protocol intentionally leaves presentation to the clients (which is why, unfortunately, capsule/gemtext authors often feel the need to customise their content with ascii-art).
## 1.1 Goals
Simplicity, Gempub follows the same original aims as the Gemini Protocol (the lines-of-code target may be ambitious but the spirit is the same):
Simplicity. Gempub follows the same original aims as the Gemini Protocol.
* It should be possible for somebody who had no part in designing the protocol to accurately hold the entire protocol spec in their head after reading a well-written description of it once or twice.
* A basic but usable (not ultra-spartan) client should fit comfortably within 50 or so lines of code in a modern high-level language. Certainly not more than 100.
* A basic but usable (not ultra-spartan) client should fit comfortably within 50 or so lines of code in a modern high-level language. Certainly not more than 100. (In the case of gempub, the lines-of-code target may be ambitious but the spirit is the same.)
* A client comfortable for daily use which implements every single protocol feature should be a feasible weekend programming project for a single developer.
### 1.2 Non-Goals
There are lots of use-cases where Gempub isn't appropriate, it's not intended for complex layouts or scientific notation. There are other formats that serve those use-cases better.
There are lots of use-cases where Gempub isn't appropriate. For example, it is not intended for complex layouts or scientific notation. There are other formats that serve those use-cases better.
## 2 Format
### 2.1 File Extension
Gempub files end with .gpub
Gempub files end with the extension ".gpub".
### 2.2 Directory Structure
Gempub files are zipped directories of Gemtext .gmi files plus an optional metadata file:
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
• metadata.txt - a file containing the title, author and any other optional fields. See "Metadata", below.
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.
@ -70,7 +69,7 @@ book_title.gpub/
### 2.3 Metadata
The metadata.txt file contains key value pairs separated by line, values start after the first colon and are trimmed, (author: Olaf Stapledon and author:Olaf Stapledon are equivalent). All values are optional apart from title and gpubVersion, order doesn't matter. If no index path is specified there must be an index.gmi in the directory root.
The metadata.txt file contains key-value pairs separated by line. Values start after the first colon and are trimmed (e.g., `author: Olaf Stapledon` and `author:Olaf Stapledon ` are equivalent). All values are optional apart from `title` and `gpubVersion`. Order does not matter. If no index path is specified there must be an index.gmi in the directory root.
* `title` - a mandatory title of the work
* `gpubVersion` - mandatory Gempub format version: 1.0.0
@ -85,9 +84,9 @@ The metadata.txt file contains key value pairs separated by line, values start a
* `copyright`
* `license`
* `version` - human readable only, not meant to be parsed
* `cover` - a jpg or png image which can be anywhere in the directory structure. For accessibility, and also because clipping will occur when maintaining the aspect ratio of the image - do NOT use text in the image.
* `cover` - a JPG or PNG image which can be anywhere in the directory structure. For accessibility, and also because clipping will occur when maintaining the aspect ratio of the image - do NOT use text in the image.
This metadata is intended so readers can display a useful catalogue of multiple .gpub files and display a cover for individual books, it should never be used to specify flags for content rendering - content should always be simple Gemtext. Custom parameters should be ignored.
This metadata is intended so readers can display a useful catalogue of multiple .gpub files and display a cover for individual books. Metadata must never be used to specify flags for content rendering. Content should always be simple Gemtext. Reader applications must ignore custom parameters.
Example:
```
@ -99,13 +98,13 @@ gpubVersion: 1.0.0
### 2.4 Content
All content should follow the [gemtext specification](https://gitlab.com/gemini-specification/gemini-text/-/blob/master/specification.gmi).
All content must follow the [gemtext specification](https://gitlab.com/gemini-specification/gemini-text/-/blob/master/specification.gmi).
Reader implementations should use the index.gmi to determine what to display next when the user reaches the end of a chapter.
### 2.5 Images
The Gemini Protocol doesn't allow auto-loading of images for various reasons none of which are applicable in an eBook. Gempub implementations can choose to handle images:
The Gemini Protocol doesn't allow auto-loading of images for various reasons, none of which are applicable in an eBook. Gempub implementations can choose to handle images:
* Inline: any links that end in an image extension can be automatically inlined, retaining aspect-ratio based on available screen width.
* Linked: for implementation simplicity a clicked image link could take the user to a separate in-app image viewer (or even pass to the OS to display).
@ -124,7 +123,7 @@ Images must always include a description for accessibility:
## 3 Accessibility
As well as including appropriate alt-text for images make sure screen readers are able to correctly interpret Gemtext. Gemtext has syntax for 3 different header types which may handled differently by screen readers, eg. on Android a text view may have the accessibility heading attribute `setAccessibilityHeading(boolean)`
As well as including appropriate alt-text for images make sure screen readers are able to correctly interpret Gemtext. Gemtext has syntax for 3 different header types which may handled differently by screen readers. E.g., on Android, a text view may have the accessibility heading attribute `setAccessibilityHeading(boolean)`.
Images should never include text unless it's repeated as text content immediately above or below.
@ -140,14 +139,15 @@ Gempub readers should use the same approach.
### 4.2 External Links
Readers should handle external links for both https:// and gemini:// passing the URI to another application or the OS to render. Only local/packaged media files should be handled in the reader (don't inline remote images). URLs are ephemeral but linking to external capsules and websites would be useful for zines and articles. Novels/stories should obviously never do this.
Readers should handle external links for both `https://` and `gemini://` by passing the URI to another application or the OS to render. Only local media files (i.e., files contained within the gempub archive) should be handled in the reader. The reader must not inline remote images. URLs are ephemeral, but linking to external capsules and websites would be useful for zines and articles. Novels or stories should obviously never do this.
### 4.3 Unfamiliar File Formats
Readers should expect to encounter unfamiliar file formats bundled in the .gpub file, links to this content should be rendered as the surrounding text might not make sense without the link text in place: simple readers could just display a label with the filename and an 'unrecognised filetype:' prefix, more advanced readers might pass the file to the OS to handle. Never omit the link text entirely if the filetype can't be handled.
Readers should expect to encounter unfamiliar file formats bundled in the `.gpub` file. Links to this content should be displayed, as the surrounding text might not make sense without the link text in place. Simple readers could just display a label with the filename and an 'unrecognised filetype:' prefix, whereas more advanced readers might pass the file to the OS to handle. The reader application must never omit the link text entirely if the filetype can't be handled.
## 5 Tools
* todo: write ePub to gPub converter
* todo: gPub validator (check image alt text, check all links are local/relative, check metadata)
* Capsule Scraper to gPub Archive: [cget](https://codeberg.org/oppenlab/cget) - in progress Gemini capsule scraper
* Capsule Scraper to gPub Archive: [cget](https://codeberg.org/oppenlab/cget) - in progress Gemini capsule scraper