From d6361b927ae514a4406d8357bfc1a7916639fe16 Mon Sep 17 00:00:00 2001 From: randogoth Date: Wed, 23 Sep 2026 09:31:03 +0300 Subject: [PATCH] Tighten the README around a Markdown-to-WML mapping table The README explained the design before it explained the output. Someone arriving with a document in hand had to read four sections of rationale before learning what a heading or a table actually becomes. The mapping now comes first and is complete: every Markdown construct against the markup wapdown emits for it, with the WML-side reasons in a notes column rather than in prose. Each row was checked against real output rather than carried over from the old text. Cut the "why this is not just another text exporter" section down to two sentences in the intro, folded the navigation and image prose into small tables, and dropped the separate Architecture section into the end of Development. 210 lines to 164, 1673 words to 1176, with more of the reference material a user actually looks things up in. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 204 +++++++++++++++++++++--------------------------------- 1 file changed, 77 insertions(+), 127 deletions(-) diff --git a/README.md b/README.md index 746d8f4..e73f8f7 100644 --- a/README.md +++ b/README.md @@ -6,204 +6,154 @@ Compile Markdown into a [WML](https://en.wikipedia.org/wiki/Wireless_Markup_Lang wapdown trail.md -o trail.wml ``` -Write a document the ordinary way; get back valid WML 1.3 that a 2001 handset can actually navigate. - -## Why this is not just another text exporter - -Most Markdown converters transform a document: same content, different markup, one file in and one file out. A WML deck is not that shape. A WAP screen is a few lines tall, scrolling is painful, and the input device is a numeric keypad — so a deck is a set of short **cards** joined by softkeys and menus, not one long page. - -So wapdown **restructures**. It decides where cards begin, builds a menu that exists nowhere in your source, wires up Back and More controls, and paginates anything still too big for the device's cache. That is why it has more knobs than a plain text exporter needs: the knobs *are* the tool. +A WAP screen is a few lines tall and driven by a numeric keypad, so a deck is a set of short **cards** joined by softkeys — not one long page. wapdown restructures a document into that shape: it decides where cards begin, builds a menu, wires up Back and More, and paginates whatever is still too big. ## Install -Install the CLI with [uv](https://github.com/astral-sh/uv): - ```bash uv tool install --from git+https://codeberg.org/randogoth/wapdown/ wapdown ``` Zero runtime dependencies, Python 3.13+. +## Markdown → WML + +Every mapping, with the markup wapdown actually emits: + +| Markdown | WML | Notes | +| --- | --- | --- | +| `# Heading` (first on a card) | `

…

` | | +| `## Heading` (and any later heading) | `

…

` | WML has no heading element | +| `Text` over `===` / `---` | same as `#` / `##` | setext headings | +| Paragraph | `

…

` | the only block container WML has | +| `- item` | `

- item

` | no list element; the bullet is literal text | +| `1. item` | `

1. item

` | numbering is counted and written out | +| `> quote` | `

…

` | | +| `---` / `***` / `___` | *(nothing)* | **starts a new card**; WML has no rule element | +| `{.card Title}` | *(nothing)* | starts a new card, with a title | +| ` ```fenced``` ` / 4-space indent | `

a
b

` | `
` between lines | +| `**bold**`, `__bold__` | `…` | | +| `*italic*`, `_italic_` | `…` | | +| `` `code` `` | *(markers stripped)* | no equivalent | +| `~~strike~~` | *(markers stripped)* | no equivalent | +| `[label](url)` | `label` | emphasis in the label is stripped | +| `![alt](src)` | `alt` | subject to `--images` | +| Pipe table | `

…

` | header row bolded | +| `{.include file.md}` | *(inlined before conversion)* | | + +Two quirks of WML's own grammar: + +- **A literal `$` becomes `$$`.** WML uses `$` for variable substitution. `Permit fee: $5` is emitted as `$$5` and displays as `$5`. +- **Link labels cannot carry emphasis.** WML declares `` as `(#PCDATA | br | img)*`, so `[**go** now](url)` becomes `go now`. + +WML 1.3 is the only supported DTD, by design. + ## Cards -A document with no dividers becomes a single card. There are three ways to ask for more. +A document with no dividers is one card. Three ways to split it: -**Thematic breaks** — a plain `---` starts a new card. WML has no rule element to draw (its entire layout vocabulary is `
`), and a row of ASCII dashes is noise on a small screen, so the glyph is put to better use as the divider it already looks like: +**`---`** starts a new card, taking its title from the section's first heading: ```markdown -Intro shown on the menu card... +Intro shown on the menu card. --- ## Weather Cold and clear. - ---- - -## Trail Status - -- North Loop: open ``` -Each card takes its title from its own first heading. `***` and `___` work identically — any Markdown thematic break divides. A trailing `---`, or two in a row, adds no empty card. `--no-split-on-rule` turns this off; breaks are then ignored rather than drawn, because there is still nothing to draw them with. +`***` and `___` work the same. A trailing `---`, or two in a row, adds no empty card. `---` *under* text is a setext heading, not a divider. -`---` under a line of text is a setext heading, not a break, and is parsed as one — so a document written in that style keeps its headings instead of shattering into cards. +**`{.card Title}`** is the same thing with an explicit title, for sections with no heading to borrow from. The two compose freely. -**Named dividers** — `{.card Title}` is the same mechanism with an explicit title, for when a section has no heading to borrow one from: - -```markdown -{.card Trail Status} -- North Loop: open -``` - -The two compose freely in one document. - -**Heading-level splitting** — `--split-level 2` starts a new card at every `##`, which fits a document that is already structured by headings and has no dividers in it: - -```bash -wapdown trail.md --split-level 2 -``` - -Explicit dividers win over `--split-level` when both are present: a boundary written into the document is a stronger statement of intent than a rule passed on the command line. +**`--split-level 2`** starts a card at every `##`, for documents structured by headings alone. Explicit dividers win when both are present. ## Navigation -Once a document resolves to two or more cards, wapdown builds the classic WAP-portal shape — a **menu** card listing each section, each spoke reachable in one press and returning with Back: +Two or more cards get the classic WAP portal: a **menu** card listing each section, each spoke returning with Back. -```bash -wapdown trail.md --split-level 2 --menu-style select -``` - -`--menu-style select` renders those choices as a `