# posprint Help

Built-in reference for the template editor and POS markup language.

---

## Application tabs

| Tab | Purpose |
|-----|---------|
| **Editor** | Write and edit template source |
| **Preview** | Live preview of rendered output |
| **Help** | This documentation |

## Toolbar actions

| Action | Description |
|--------|-------------|
| **New** | Empty template with defaults |
| **Open** | Load a `.pos` file |
| **Save / Save As** | Write JSON `.pos` file (metadata + body) |
| **Insert** | Menu to insert images, barcodes, QR codes, `@feed`, `@cut` |
| **Print** | Substitute parameters, pick USB printer, send ESC/POS bytes |

## Editor assistance

- Type `@` at the start of a line to see **directive autocomplete** (`feed`, `cut`, `image`, `barcode`, `qr`).
- Use **Insert → Barcode / QR code** to pick native or raster type before inserting a snippet.

## Page settings

| Setting | Description |
|---------|-------------|
| **Page width (mm)** | Paper width, typically `58` or `80` |
| **Preview mode** | `Auto-scale` fits preview to panel; `Fixed` uses exact mm width |
| **Code page** | Character encoding sent to printer (default `CP437`) |
| **Cut after print** | Append paper feed + cut if template has no `@cut` |

---

## Template language

A template is plain text: paragraphs, headings, directives, and inline markup.

### Paragraphs

Consecutive non-empty lines form one paragraph.

### Headings

```markdown
# Large heading
## Bold heading
```

### Alignment

`:left:`, `:center:`, or `:right:` before a paragraph.

### Inline markup

| Syntax | Effect |
|--------|--------|
| `**text**` | Bold |
| `*text*` | Italic |
| `` `text` `` | Monospace |
| `${Name}` | Parameter (filled at print time) |

### Horizontal rule

```markdown
---
```

### Comments

```markdown
<!-- not printed -->
```

---

## Directives

Directives start with `@` at the beginning of a line.

### Paper feed / cut

```markdown
@feed 3
@cut
```

### Image

```markdown
@image logo.png
@image ${LogoPath} width=50% align=center
```

### Barcode

**Native** (printer draws barcode via ESC/POS):

```markdown
@barcode CODE128 ${OrderId}
@barcode UPC-A 012345678905
@barcode ITF 12345678 height=80
```

**Raster** (rendered as bitmap — works with any symbology below). Raster barcodes are stretched horizontally to the full paper width for reliable scanning; height follows the `height` attribute.

```markdown
@barcode RASTER CODE128 ${OrderId}
@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 symbology | Use `RASTER` prefix |
|-----------------------|---------------------|
| `CODE93`, `CODE11` | No native ESC/POS in firmware |

| Attribute | Description |
|-----------|-------------|
| `height` | Height in dots (default `64`; raster PNG height) |
| `align` | `left`, `center`, `right` |
| `show_text` | Native only: human-readable text under barcode |

### QR code

**Native** (ESC/POS QR, model 2):

```markdown
@qr https://example.com/${Id}
@qr ${Url} size=6 ecc=H align=center
```

**Raster** (bitmap; supports 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; auto if omitted) |
| `ecc` | `L`, `M`, `Q`, `H` | Same |
| `align` | `left`, `center`, `right` | Same |

---

## Parameters

`${ParameterName}` in text, barcode data, QR data, or image paths.

- Same name → **one input** at print time (GUI or CLI).
- CLI requires **every** parameter via `--set Name=Value`.

---

## Example receipt

```markdown
# ${StoreName}
:center:

Receipt: ${DocumentNumber}

@barcode CODE128 ${DocumentNumber}
@qr RASTER https://shop.example.com/r/${DocumentNumber} scale=4

@feed 4
@cut
```

---

## GUI printing (USB)

1. **Print** → enter parameters → choose serial port → **Print**.

**Linux:** `dialout` group. **Windows:** printer appears as `COMx`.

---

## `.pos` file format

JSON with `version`, `metadata`, and `body` (template source).
