# 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) |
| **Print** | Substitute parameters, pick USB printer, send ESC/POS bytes |

## 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.

```markdown
Thank you for your visit!
Please come again.
```

### Headings

```markdown
# Large heading (store name)
## Bold heading (section title)
```

### Alignment

Prefix a paragraph with `:left:`, `:center:`, or `:right:` (default is left).

```markdown
:center:
Your Store Name
```

### Inline markup

| Syntax | Effect |
|--------|--------|
| `**text**` | Bold |
| `*text*` | Italic |
| `` `text` `` | Monospace |
| `${Name}` | Parameter (filled at print time) |

### Horizontal rule

```markdown
---
```

### Comments (not printed)

```markdown
<!-- note to designer only -->
```

---

## Directives

Directives start with `@` at the beginning of a line.

### Paper feed

```markdown
@feed 3
```

Feeds three blank lines.

### Cut paper

```markdown
@cut
```

Partial cut (if the printer supports it).

### Image

```markdown
@image logo.png
@image ${LogoPath} width=50%
@image promo.png width=384 align=center
```

| Attribute | Description |
|-----------|-------------|
| Path | File relative to the `.pos` file, or `${Parameter}` |
| `width` | `NN%` of printable width or dots (e.g. `384`) |
| `align` | `left`, `center`, `right` |

### Barcode

```markdown
@barcode CODE128 ${OrderId}
@barcode EAN13 5901234123457 height=80 show_text=true
```

| Field | Values |
|-------|--------|
| Symbology | `CODE128`, `EAN13`, `EAN8`, `CODE39` |
| Data | Literal text or `${Parameter}` |
| `height` | Height in dots (default `64`) |
| `align` | `left`, `center`, `right` |
| `show_text` | `true` / `false` — human-readable text under barcode |

### QR code

```markdown
@qr https://example.com/receipt/${DocumentNumber}
@qr ${PaymentUrl} size=6 ecc=M align=center
```

| Attribute | Description |
|-----------|-------------|
| Data | URL or text; may include `${Parameter}` |
| `size` | Module size 1–16 (default `4`) |
| `ecc` | Error correction: `L`, `M`, `Q`, `H` |
| `align` | `left`, `center`, `right` |

---

## Parameters

Write `${ParameterName}` anywhere in text, barcode data, QR data, or image paths.

- Names: letters, digits, underscore; must start with a letter or `_`.
- **Same name → one input** at print time; all occurrences receive the same value.
- The print dialog pre-fills values from the last print session.

---

## Example receipt

```markdown
# ${StoreName}
:center:

123 Main Street

---
Receipt: ${DocumentNumber}
Date: ${Date}

${LineItems}

---
:right:
**TOTAL: ${GrandTotal}**

@barcode CODE128 ${DocumentNumber}
@feed 2
@qr https://shop.example.com/r/${DocumentNumber}

Thank you!
@feed 4
@cut
```

---

## Printing (USB)

1. Click **Print**.
2. Enter parameter values in the dialog.
3. Choose a USB serial printer from the list (refresh if needed).
4. The app sends raw ESC/POS bytes directly to the port (no system print spooler).

**Linux:** your user must be in the `dialout` group to access serial devices.

**Windows:** the printer usually appears as `COM3`, `COM4`, etc.

---

## `.pos` file format

JSON file with extension `.pos`:

- `version` — format version (currently `1`)
- `metadata` — page width, preview mode, code page, etc.
- `body` — template source string
