added decktext parser and spec
This commit is contained in:
Luxferre
@@ -0,0 +1,121 @@
|
||||
# DeckText specification and manual
|
||||
|
||||
DeckText is a strictly defined subset of HTML (Hypertext Markup Language) aimed at simple, lightweight, text-only document authoring with basic formatting and page-oriented structure for consumption on low-powered portable devices with line-oriented UI, while being backwards-compatible with any existing Web browser implementation.
|
||||
|
||||
## Rationale
|
||||
|
||||
Rendering full HTML is a very compute-intensive task, especially for the devices that do not need all the features. A subset that would allow conveying all required text-only information, keeping the parser as simple as possible (while still being backwards-compatible with the original HTML specification), is a necessity for such devices without having to switch to alternative "small Web" protocols such as Gopher, Gemini, Nex or Spartan.
|
||||
|
||||
## General definitions
|
||||
|
||||
A **DeckText site** is a simple HTML document that conforms to this specification. Although it is allowed to have multiple HTML documents, it's recommended for the entire site to be served as a single-file HTTP(S) download.
|
||||
|
||||
A DeckText site consists of:
|
||||
|
||||
- document title,
|
||||
- DeckText beginning and end markers,
|
||||
- page separators,
|
||||
- page contents consisting of a strict subset of HTML tags.
|
||||
|
||||
A **DeckText-only client** (henceforth DTOC) is a software application that allows its users to browse DeckText sites without needing to implement a full HTML rendering engine.
|
||||
|
||||
DTOCs MUST support UTF-8 encoding inside the documents and render them accordingly. Particular Unicode character set availability outside ASCII range is not required as it depends on the fonts installed on the target device.
|
||||
|
||||
## Beginning and end markers
|
||||
|
||||
To mark the beginning and the end of a DeckText-compliant document fragment within an HTML page, the following case-insensitive markers are used:
|
||||
|
||||
- `<!-- decktext_begin -->` marks the beginning of DeckText,
|
||||
- `<!-- decktext_end -->` marks the end of DeckText.
|
||||
|
||||
A single HTML page MAY contain several begin-end marker pairs, and a DTOC MUST read through all these sections and compile the document to display from all of them.
|
||||
|
||||
Between the begin-end markers, only text content is allowed.
|
||||
|
||||
## Title
|
||||
|
||||
Just like any HTML document, a valid DeckText document MUST contain a single `<title></title>` tag. A DTOC MUST read and display its contents to the user as a document/site title. The tag MUST NOT have any attributes and MAY be placed outside any other HTML element.
|
||||
|
||||
This tag is the only one that is not required to be placed between the DeckText start and end markers in order to be read by a DTOC.
|
||||
|
||||
## Pages
|
||||
|
||||
Every DeckText document is split into logical pages, which may or may not match physical pages on the target device.
|
||||
|
||||
The horizontal rule element (both `<hr>` and `<hr />` forms are allowed) is solely defined as the **page separator**. DTOCs MUST split the document by this separator and offer the user to switch between pages based on it.
|
||||
|
||||
Any content between the first DeckText start marker and the first page separator forms the first page of the document.
|
||||
|
||||
It is recommended for the first page of the document to contain its overall description and a table of contents with the corresponding page numbers.
|
||||
|
||||
## Page content
|
||||
|
||||
When displaying page content, the following rules apply:
|
||||
|
||||
1. All opening and closing tags not supported by the client are ignored.
|
||||
2. Whitespace IS NOT collapsed.
|
||||
3. All newlines ARE preserved.
|
||||
4. Lines longer than the viewport width MUST wrap.
|
||||
5. Display font SHOULD be monospace, unless the target platform does not support it.
|
||||
|
||||
## Supported HTML tags
|
||||
|
||||
DTOCs MUST implement these tags:
|
||||
|
||||
- `<!-- decktext_begin -->` to mark the beginning of DeckText-compliant document fragments
|
||||
- `<!-- decktext_end -->` to mark the end of DeckText-compliant document fragments
|
||||
- `<title></title>` for document title display
|
||||
- `<hr>`, `<hr/>`, `<hr />` as a page separator
|
||||
- `<a href="(link)">Link name</a>` for defining hyperlinks (see "Link processing" section for details)
|
||||
- `<b></b>`,`<strong></strong>` for bold text
|
||||
- `<i></i>`,`<em></em>` for italic text
|
||||
- `<tt></tt>`,`<code></code>`, `<pre></pre>`, `<xmp></xmp>` for code text
|
||||
- `<s></s>`,`<del></del>` for strikethrough text
|
||||
- `<q></q>`, `<blockquote></blockquote>` for quoted text
|
||||
- `<li></li>` for list items (all lists are considered unordered)
|
||||
|
||||
Nesting any of these elements is NOT supported in DeckText. In case such nesting occurs, a DTOC MAY display the inner element contents verbatim, process it correctly or throw a parsing error, depending on the implementation.
|
||||
|
||||
DTOCs MUST NOT implement attribute support for any tag except `<a>`, and only the `href="..."` attribute is required to be supported.
|
||||
|
||||
Tag support is case-insensitive but mixed case IS NOT supported. I.e. within a single opening/closing tag, all letters MUST be either uppercase or lowercase: `<TITLE>` and `<title>` are supported but `<Title>` is not.
|
||||
|
||||
## Link processing
|
||||
|
||||
Whenever an `<a>` tag is encountered within the DeckText block, a DTOC MUST do the following:
|
||||
|
||||
1. Look for the matching `</a>` tag and record the link label.
|
||||
2. Look for the `href=""` attribute within the opening `<a>` tag and extract the link URL. The URL inside the `href` attribute MUST be wrapped in double quotes (no other quotes allowed).
|
||||
3. Provide a clear UI for the user to visit the URL when selecting the link label.
|
||||
|
||||
A DTOC also SHOULD implement anchored page URLs in the form of `#{page_number}` links, e.g. `<a href="#5">Page 5</a>`, for easy navigation within the DeckText site. This is not mandatory because a DeckText client itself should provide a convenient UI for navigating by page numbers.
|
||||
|
||||
## DeckText compatibility with "traditional" Web browsers
|
||||
|
||||
In order for your DeckText documents to display normally in both DTOCs and full-featured Web browsers according to this specification, the following HTML template is recommended:
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html><head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width,height=device-height,user-scalable=no,initial-scale=1.0"/>
|
||||
<title>Your Document Title</title>
|
||||
<style>
|
||||
*{font-family:monospace;font-variant-ligatures:normal;white-space:pre-wrap;tab-size:4}
|
||||
hr{margin: 1em 0}
|
||||
/* ... other desired CSS styles ... */
|
||||
</style>
|
||||
</head><body>
|
||||
<!-- decktext_begin -->
|
||||
<!-- ... your valid DeckText markup here ... -->
|
||||
<!-- decktext_end -->
|
||||
</body></html>
|
||||
```
|
||||
|
||||
Keep in mind that any valid DeckText markup is also valid HTML markup, but not vice versa. Make sure you adhere to the rules provided in this specification.
|
||||
|
||||
## Credits
|
||||
|
||||
The original version of this specification was created by [Luxferre](https://luxferre.top) and published in December 2025.
|
||||
|
||||
The specification and reference DTOC implementations are released into public domain with no warranties.
|
||||
Reference in New Issue
Block a user