Update 'README.md'

README.md

@@ -1,3 +1,121 @@
-# gempub
+# Gempub 1.0.0
 
-A new eBook format based on Gemini Protocol's Gemtext. Gempub can also serve as a Gemini capsule archive format.
+A new eBook format based on Gemini Protocol's [Gemtext](https://gitlab.com/gemini-specification/gemini-text/-/blob/master/specification.gmi). Gempub can also serve as a Gemini capsule archive format.
+
+Questions, comments, help: oppen@fastmail.com
+
+## Rationale
+
+While implementing an .epub reader 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.
+
+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).
+
+## 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):
+
+* 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 client comfortable for daily use which implements every single protocol feature should be a feasible weekend programming project for a single developer.
+
+## 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.
+
+## Extension
+
+Gempub files end with .gpub
+
+## Structure
+
+Gempub files are zipped directories of Gemtext .gmi files plus a couple of optional metadata files:
+
+• mimetype - an ascii file containing the string: application/gpub+zip - this should give existing eBook readers an opportunity to fail gracefully
+
+• metadata - an ascii file containing the title, author and any other optional fields, see Metadata below
+
+These files enable Gempub to act as a full eBook format, if one is present the other must be too. Gemini capsules can also be simply zip compressed without these files to act as a Gemini archive/offline format - when operating as an archive there must be an index.gmi in the root directory.
+
+Example:
+
+```
+book_title.gpub/
+   mimetype
+   metadata
+   cover.jpg
+   capsule/
+      index.gmi
+      chapter1.gmi
+      chapter2.gmi
+      chapter3.gmi
+      images/
+         illustration.png
+```
+
+## Metadata
+
+The metadata 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). Keys are case-insensitive (title:Star Maker and TITLE:Star Maker 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, implementations should handle the lack of an index or index.gmi gracefully.
+
+* title - a mandatory title of the work
+* gpubVersion - mandatory Gempub format version: 1.0.0
+* index - path to start index.gmi
+* author
+* language - ISO 639-1 or ISO 639-2: eg. en or eng
+* charset: iso-8859-1 or UTF-8 (default is UTF-8)
+* description
+* publishDate - ISO 8601 date (ISO 2014): YYYY-MM-DD - do NOT include time (clients may want to add defensive code for this in case auto-generated tools inclue it)
+* revisionDate - ISO 8601 date (ISO 2014): YYYY-MM-DD - again, do NOT include time
+* 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.
+
+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 are not allowed.
+
+Example:
+```
+title: Star Maker
+author: Olaf Stapledon
+index: ./capsule/index.gmi
+gpubVersion: 1.0.0
+```
+
+## Content
+
+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 expect to encounter unfamiliar file formats bundled in the .gpub file, links to this content should always 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.
+
+Only image handling is mandatory (books have images...), any other filetype handling is optional (eg. an inline MP3 player might be a nice feature, but it's entirely down to the reader application to choose to implement that or not). Other text formats should NOT be rendered in the player to prevent Gempub files just becoming containers for other filetypes: Markdown, Html, PDFs etc should all be passed to the OS.
+
+## 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).
+
+Supported formats are PNG and JPEG as they're common and included on most/all platforms.
+
+Images must always include a description for accessibility:
+
+```
+//Invalid Gempub image syntax:
+=> ./header.jpg
+
+//Correct image syntax:
+=> ./header.jpg A man floating through space
+```
+
+## 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)` 
+
+Images should never include text unless it's repeated as text content immediately above or below.
+
+## Code Blocks
+
+For 1.0.0 the only defined behaviour for Gemtext code blocks is that they should be rendered in a monospace font. Readers can optionally handle defined formats (using data that might be present after the initial ```)
+
+## Tools
+
+//todo - write ePub to gPub converter
+//todo - write a Gemini Protocol site scraper