# posprint Help

Built-in reference for the template editor and POS markup language.

---

## Application tabs

| Tab | Purpose |
|-----|---------|
| **Design** | Side-by-side template editor and live preview |
| **Help** | This documentation |
| **Settings** | Default page width; LAN printers (TCP 9100) on/off + cache; trusted sites for `noconfirm` |

## Toolbar actions

| Action | Description |
|--------|-------------|
| **New** | Empty template with defaults |
| **Open** | Load a `.pos` file |
| **Save / Save As** | Write `.pos` file (metadata + body) |
| **Insert** | Images, barcodes, QR, date/time, parameters, `@feed`, `@cut` |
| **Print** | Enter parameters, pick a printer, send ESC/POS bytes |

While the Print dialog is open, the rest of the UI (including editor autocomplete) is disabled so parameter fields keep focus.

**Print-only mode** (`posprint --print`, Explorer Print, or a `posprint://` link) shows a live preview on the left and parameters / printer controls on the right. The preview updates as you type parameter values.

## Editor assistance

- Type `@` at the start of a line for **directive autocomplete** (`feed`, `cut`, `image`, `barcode`, `qr`, `date`, `time`).
- Use **Insert → Barcode / QR code** to pick native or raster type before inserting a snippet.

## Page settings

| Setting | Description |
|---------|-------------|
| **Page width (mm)** | Paper width — match your physical roll (e.g. `53`, `58`, `80`) |
| **Preview zoom** | Screen zoom; `100%` is calibrated to typical receipt width on screen |

Preview width and text use the same calibrated screen scale. Preview font size is bumped to match printed Font A. Blank lines / `@feed` use the same line spacing as printed text. Heading `#` uses double width/height like GS `!` on the printer; `##` uses bold only.

If the document does not end with `@cut` (ignoring blank lines after it), a red warning appears next to **Help**.

---

## Template language

A template is plain text: paragraphs, headings, lists, checkboxes, `${text}` / `$[bool]` parameters, and directives. There is **no** inline bold/italic/code markup — asterisks and backticks print literally.

### Paragraphs

Consecutive non-empty lines form one paragraph. Multiple spaces in a row are kept (useful for manual column layout), including spaces at the start of a line. Trailing spaces on a line are ignored.

### Headings

```markdown
# Large heading
## Bold heading
```

### Alignment

`:left:`, `:center:`, or `:right:` before a paragraph.

On **one line**, you can combine markers (e.g. `:left: Appel:right: 10`). That prints as one row with spaces so the right text sits at the end of the paper width. Writing `:right:10:left:Appel` is treated the same (left then right). If both sides are too long for the line, they print on separate lines instead.

### Bullet lists

```markdown
- Groceries
  - Milk
  - Eggs
- Wash car
```

Indent with two spaces (or a tab) per nesting level. Top-level items print as `* `; nested items print as `- ` with the same hanging wrap.

```text
* Groceries
  - Milk
  - Eggs
* Wash car
```

Long items wrap with a hanging indent:

```text
* this is a
  long line
  - nested item that
    wraps too
```

### Parameters

| Syntax | Effect |
|--------|--------|
| `${Name}` | Text parameter (filled at print time) |
| `$[Name]` | Checkbox parameter → `[ ]` or `[x]` |

`${Name}` and `$[Name]` must not share the same name.

### Checkboxes

Inline checkboxes print as ASCII so they stay in the printer’s CP437 font (Unicode ☐ / √ often become CJK garbage):

| Syntax | Result |
|--------|--------|
| `[]` or `[ ]` | `[ ]` |
| `[x]` or `[X]` | `[x]` |

```markdown
[] Unchecked
[ ] Also unchecked
[x] Done
$[Paid]
```

`$[Paid]` is a **parameter**: in the Print dialog it is a true/false checkbox; on the receipt it becomes `[ ]` or `[x]`. CLI: `--set Paid=true`.

### Horizontal rule

```markdown
---
```

### Comments

```markdown
<!-- not printed -->
```

---

## Directives

Directives start with `@` at the beginning of a line.

### Paper feed / cut

```markdown
@feed 3
@cut
```

Blank lines in the editor also feed one line (same as `@feed 1`).

### Date / time

```markdown
@date
@date DD-MM-YYYY
@time
@time 12h
@time 24h
```

- `@date` with no pattern uses the system regional short date.
- Custom patterns use tokens such as `YYYY`, `MM`, `DD`.
- `@time` defaults to 24-hour; use `12h` or `24h`.

### Image

```markdown
@image logo.png
@image https://example.com/logo.png width=50%
@image ${LogoPath} width=50% align=center
```

Local paths resolve relative to the `.pos` file. `http://` and `https://` URLs are downloaded when preview or print needs the image.

### Barcode

**Native** (printer draws barcode via ESC/POS):

```markdown
@barcode CODE128 ${OrderId}
@barcode UPC-A 012345678905
@barcode ITF 12345678 height=80
@barcode CODE128 hallo wereld
@barcode CODE128 ABC show_text=true
```

**Raster** (bitmap). Raster barcodes stretch horizontally to full paper width; height follows `height`.

```markdown
@barcode RASTER CODE128 ${OrderId}
@barcode RASTER CODE128 hallo wereld
@barcode RASTER CODE93 ABC-1234
```

| Native symbology | Notes |
|----------------|-------|
| `CODE128` | Alphanumeric |
| `EAN13`, `EAN8` | Numeric |
| `CODE39` | Alphanumeric |
| `UPC-A`, `UPC-E` | Numeric |
| `ITF` | Interleaved 2 of 5; even digit count |
| `CODABAR` | Numeric + A-D start/stop |

| Raster-only | Use `RASTER` prefix |
|-------------|---------------------|
| `CODE93`, `CODE11` | No native ESC/POS in firmware |

| Attribute | Description |
|-----------|-------------|
| `height` | Height in dots (default `64`) |
| `align` | `left`, `center`, `right` |
| `show_text` | Native only: human-readable text under barcode (default off; `show_text=true` to enable) |

Data may contain spaces; tokens after the symbology are joined until the first `key=value` attribute.

### QR code

**Native** (ESC/POS QR, model 2):

```markdown
@qr https://example.com/${Id}
@qr ${Url} size=6 ecc=H align=center
@qr hallo wereld size=4
```

**Raster** (bitmap; QR versions 1–40):

```markdown
@qr RASTER https://example.com/${Id}
@qr RASTER ${Url} version=5 scale=4 ecc=M
```

| Attribute | Native | Raster |
|-----------|--------|--------|
| `size` | Module dot size 1–16 | — |
| `scale` | — | Pixels per module (default `4`) |
| `version` | — | QR version 1–40 (optional) |
| `ecc` | `L`, `M`, `Q`, `H` | Same |
| `align` | `left`, `center`, `right` | Same |

---

## Parameters

| Form | Type | Print dialog | CLI |
|------|------|--------------|-----|
| `${Name}` | text | text field | `--set Name=Value` |
| `$[Name]` | bool | checkbox | `--set Name=true` / `false` (also `1`/`0`, `yes`/`no`) |

- Same name must not appear as both `${…}` and `$[…]`.
- GUI and CLI require **every** parameter; bools default to unchecked (`false`) in the dialog.
- Usable in text; `${…}` also in barcode/QR/image paths (`$[…]` is text-inline only).

```markdown
# ${StoreName}

$[Paid] Paid in full
[] Pending review

Receipt: ${DocumentNumber}
```

---

## Example receipt

```markdown
# ${StoreName}
:center:

Receipt: ${DocumentNumber}
@date
@time

@barcode CODE128 ${DocumentNumber}
@qr RASTER https://shop.example.com/r/${DocumentNumber} scale=4

@feed 4
@cut
```

---

## GUI printing

1. **Print** → enter parameters → choose a printer → **Print** (next to Refresh). Close with the window ✕.

Printers may appear as:

- **USB printer-class** devices (direct bulk OUT)
- **Windows spooler** queues (Windows)
- **USB-serial** ports with a device attached (`COMx`, `/dev/ttyUSB0`, `/dev/ttyACM0`, …)
- **LAN** printers on TCP port **9100** (raw ESC/POS), when enabled under **Settings → LAN network printers** (off by default). Discovery validates the previous LAN cache first, then scans the local subnet.

Empty motherboard serial ports (common on Linux as `/dev/ttyS*`) are hidden. Use **Enter port, queue, or LAN address manually** for those or for a known `192.168.x.x` / `host:9100`.

**Linux serial:** join the `dialout` group.

---

## CLI

```bash
posprint print receipt.pos -p COM3 --set StoreName=Shop
posprint link receipt.pos
posprint cli-help
```

`-p` accepts a serial port name, USB device label from discovery, or (on Windows) a spooler queue name. See platform CLI help via `posprint cli-help`.

`posprint link` prints a `posprint://` deep link for the file (see [POSPRINT-URL.md](POSPRINT-URL.md)).

---

## posprint:// links

Websites can open the print dialog with an embedded template:

```
posprint://print?v=1&d=…
```

Add `&noconfirm=1&referrer=<percent-encoded verify URL>` to print after the site’s verify endpoint returns HTTP 200 and (on first use) the user trusts that domain (**Settings → Trusted sites**). Auto-print uses the last printer that printed successfully when that device is still available. Encoding helpers live in [`lib/`](../lib/). Full guide: [POSPRINT-URL.md](POSPRINT-URL.md).

`@image` may use `https://…` or `http://…` (downloaded when preview/print needs the image).

---

## `.pos` file format

JSON with `version`, `metadata`, and `body` (template source). See [FILE-FORMAT.md](FILE-FORMAT.md).
