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 for new documents |
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 |
| 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
# 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
- 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.
* Groceries
- Milk
- Eggs
* Wash car
Long items wrap with a hanging indent:
* 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] |
[] 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
---
Comments
<!-- not printed -->
---
Directives
Directives start with @ at the beginning of a line.
Paper feed / cut
@feed 3
@cut
Blank lines in the editor also feed one line (same as @feed 1).
Date / time
@date
@date DD-MM-YYYY
@time
@time 12h
@time 24h
@datewith no pattern uses the system regional short date.- Custom patterns use tokens such as
YYYY,MM,DD. @timedefaults to 24-hour; use12hor24h.
Image
@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 (TLS certificate errors are ignored so corporate/self-signed hosts still work).
Barcode
Native (printer draws barcode via ESC/POS):
@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.
@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 attribute token (size=…, align=…, etc.). A URL with a query string (https://…?a=1) is still data.
QR code
Native (ESC/POS QR, model 2):
@qr https://example.com/${Id}
@qr ${Url} size=6 ecc=H align=center
@qr hallo wereld size=4
Raster (bitmap; QR versions 1–40):
@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).
# ${StoreName}
$[Paid] Paid in full
[] Pending review
Receipt: ${DocumentNumber}
---
Example receipt
# ${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, …) - Classic Bluetooth SPP after you pair the printer in the OS (
COMxon Windows, often/dev/rfcomm0on Linux). Listed with a Bluetooth label.
Empty motherboard serial ports (common on Linux as /dev/ttyS*) are hidden. Use Enter port or queue manually if you need one of those.
Bluetooth Low Energy (BLE) printers are not supported. Pair Classic Bluetooth SPP in Windows or your Linux Bluetooth settings first; Posprint does not pair devices itself.
Linux serial / RFCOMM: join the dialout group.
---
CLI
posprint print receipt.pos -p COM3 --set StoreName=Shop
posprint link receipt.pos
posprint cli-help
posprint list prints discovered printers. -p accepts a serial port name (including a paired Bluetooth COM/rfcomm node), 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:// links
Websites can open the print dialog with an embedded template:
posprint://print?v=1&d=…
Add &noconfirm=1 to auto-print once a printer is ready (the browser’s protocol prompt is the consent step). Auto-print uses the last printer that printed successfully when that device is still available. Encoding helpers live in lib/. Full guide: 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.
Source
| 1 | # posprint Help |
| 2 | |
| 3 | Built-in reference for the template editor and POS markup language. |
| 4 | |
| 5 | --- |
| 6 | |
| 7 | ## Application tabs |
| 8 | |
| 9 | | Tab | Purpose | |
| 10 | |-----|---------| |
| 11 | | **Design** | Side-by-side template editor and live preview | |
| 12 | | **Help** | This documentation | |
| 13 | | **Settings** | Default page width for new documents | |
| 14 | |
| 15 | ## Toolbar actions |
| 16 | |
| 17 | | Action | Description | |
| 18 | |--------|-------------| |
| 19 | | **New** | Empty template with defaults | |
| 20 | | **Open** | Load a `.pos` file | |
| 21 | | **Save / Save As** | Write `.pos` file (metadata + body) | |
| 22 | | **Insert** | Images, barcodes, QR, date/time, parameters, `@feed`, `@cut` | |
| 23 | | **Print** | Enter parameters, pick a printer, send ESC/POS bytes | |
| 24 | |
| 25 | While the Print dialog is open, the rest of the UI (including editor autocomplete) is disabled so parameter fields keep focus. |
| 26 | |
| 27 | **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. |
| 28 | |
| 29 | ## Editor assistance |
| 30 | |
| 31 | - Type `@` at the start of a line for **directive autocomplete** (`feed`, `cut`, `image`, `barcode`, `qr`, `date`, `time`). |
| 32 | - Use **Insert → Barcode / QR code** to pick native or raster type before inserting a snippet. |
| 33 | |
| 34 | ## Page settings |
| 35 | |
| 36 | | Setting | Description | |
| 37 | |---------|-------------| |
| 38 | | **Page width (mm)** | Paper width — match your physical roll (e.g. `53`, `58`, `80`) | |
| 39 | | **Preview zoom** | Screen zoom; `100%` is calibrated to typical receipt width on screen | |
| 40 | |
| 41 | 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. |
| 42 | |
| 43 | If the document does not end with `@cut` (ignoring blank lines after it), a red warning appears next to **Help**. |
| 44 | |
| 45 | --- |
| 46 | |
| 47 | ## Template language |
| 48 | |
| 49 | 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. |
| 50 | |
| 51 | ### Paragraphs |
| 52 | |
| 53 | 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. |
| 54 | |
| 55 | ### Headings |
| 56 | |
| 57 | ```markdown |
| 58 | # Large heading |
| 59 | ## Bold heading |
| 60 | ``` |
| 61 | |
| 62 | ### Alignment |
| 63 | |
| 64 | `:left:`, `:center:`, or `:right:` before a paragraph. |
| 65 | |
| 66 | 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. |
| 67 | |
| 68 | ### Bullet lists |
| 69 | |
| 70 | ```markdown |
| 71 | - Groceries |
| 72 | - Milk |
| 73 | - Eggs |
| 74 | - Wash car |
| 75 | ``` |
| 76 | |
| 77 | Indent with two spaces (or a tab) per nesting level. Top-level items print as `* `; nested items print as `- ` with the same hanging wrap. |
| 78 | |
| 79 | ```text |
| 80 | * Groceries |
| 81 | - Milk |
| 82 | - Eggs |
| 83 | * Wash car |
| 84 | ``` |
| 85 | |
| 86 | Long items wrap with a hanging indent: |
| 87 | |
| 88 | ```text |
| 89 | * this is a |
| 90 | long line |
| 91 | - nested item that |
| 92 | wraps too |
| 93 | ``` |
| 94 | |
| 95 | ### Parameters |
| 96 | |
| 97 | | Syntax | Effect | |
| 98 | |--------|--------| |
| 99 | | `${Name}` | Text parameter (filled at print time) | |
| 100 | | `$[Name]` | Checkbox parameter → `[ ]` or `[x]` | |
| 101 | |
| 102 | `${Name}` and `$[Name]` must not share the same name. |
| 103 | |
| 104 | ### Checkboxes |
| 105 | |
| 106 | Inline checkboxes print as ASCII so they stay in the printer’s CP437 font (Unicode ☐ / √ often become CJK garbage): |
| 107 | |
| 108 | | Syntax | Result | |
| 109 | |--------|--------| |
| 110 | | `[]` or `[ ]` | `[ ]` | |
| 111 | | `[x]` or `[X]` | `[x]` | |
| 112 | |
| 113 | ```markdown |
| 114 | [] Unchecked |
| 115 | [ ] Also unchecked |
| 116 | [x] Done |
| 117 | $[Paid] |
| 118 | ``` |
| 119 | |
| 120 | `$[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`. |
| 121 | |
| 122 | ### Horizontal rule |
| 123 | |
| 124 | ```markdown |
| 125 | --- |
| 126 | ``` |
| 127 | |
| 128 | ### Comments |
| 129 | |
| 130 | ```markdown |
| 131 | <!-- not printed --> |
| 132 | ``` |
| 133 | |
| 134 | --- |
| 135 | |
| 136 | ## Directives |
| 137 | |
| 138 | Directives start with `@` at the beginning of a line. |
| 139 | |
| 140 | ### Paper feed / cut |
| 141 | |
| 142 | ```markdown |
| 143 | @feed 3 |
| 144 | @cut |
| 145 | ``` |
| 146 | |
| 147 | Blank lines in the editor also feed one line (same as `@feed 1`). |
| 148 | |
| 149 | ### Date / time |
| 150 | |
| 151 | ```markdown |
| 152 | @date |
| 153 | @date DD-MM-YYYY |
| 154 | @time |
| 155 | @time 12h |
| 156 | @time 24h |
| 157 | ``` |
| 158 | |
| 159 | - `@date` with no pattern uses the system regional short date. |
| 160 | - Custom patterns use tokens such as `YYYY`, `MM`, `DD`. |
| 161 | - `@time` defaults to 24-hour; use `12h` or `24h`. |
| 162 | |
| 163 | ### Image |
| 164 | |
| 165 | ```markdown |
| 166 | @image logo.png |
| 167 | @image https://example.com/logo.png width=50% |
| 168 | @image ${LogoPath} width=50% align=center |
| 169 | ``` |
| 170 | |
| 171 | Local paths resolve relative to the `.pos` file. `http://` and `https://` URLs are downloaded when preview or print needs the image (TLS certificate errors are ignored so corporate/self-signed hosts still work). |
| 172 | |
| 173 | ### Barcode |
| 174 | |
| 175 | **Native** (printer draws barcode via ESC/POS): |
| 176 | |
| 177 | ```markdown |
| 178 | @barcode CODE128 ${OrderId} |
| 179 | @barcode UPC-A 012345678905 |
| 180 | @barcode ITF 12345678 height=80 |
| 181 | @barcode CODE128 hallo wereld |
| 182 | @barcode CODE128 ABC show_text=true |
| 183 | ``` |
| 184 | |
| 185 | **Raster** (bitmap). Raster barcodes stretch horizontally to full paper width; height follows `height`. |
| 186 | |
| 187 | ```markdown |
| 188 | @barcode RASTER CODE128 ${OrderId} |
| 189 | @barcode RASTER CODE128 hallo wereld |
| 190 | @barcode RASTER CODE93 ABC-1234 |
| 191 | ``` |
| 192 | |
| 193 | | Native symbology | Notes | |
| 194 | |----------------|-------| |
| 195 | | `CODE128` | Alphanumeric | |
| 196 | | `EAN13`, `EAN8` | Numeric | |
| 197 | | `CODE39` | Alphanumeric | |
| 198 | | `UPC-A`, `UPC-E` | Numeric | |
| 199 | | `ITF` | Interleaved 2 of 5; even digit count | |
| 200 | | `CODABAR` | Numeric + A-D start/stop | |
| 201 | |
| 202 | | Raster-only | Use `RASTER` prefix | |
| 203 | |-------------|---------------------| |
| 204 | | `CODE93`, `CODE11` | No native ESC/POS in firmware | |
| 205 | |
| 206 | | Attribute | Description | |
| 207 | |-----------|-------------| |
| 208 | | `height` | Height in dots (default `64`) | |
| 209 | | `align` | `left`, `center`, `right` | |
| 210 | | `show_text` | Native only: human-readable text under barcode (default off; `show_text=true` to enable) | |
| 211 | |
| 212 | Data may contain spaces; tokens after the symbology are joined until the first attribute token (`size=…`, `align=…`, etc.). A URL with a query string (`https://…?a=1`) is still data. |
| 213 | |
| 214 | ### QR code |
| 215 | |
| 216 | **Native** (ESC/POS QR, model 2): |
| 217 | |
| 218 | ```markdown |
| 219 | @qr https://example.com/${Id} |
| 220 | @qr ${Url} size=6 ecc=H align=center |
| 221 | @qr hallo wereld size=4 |
| 222 | ``` |
| 223 | |
| 224 | **Raster** (bitmap; QR versions 1–40): |
| 225 | |
| 226 | ```markdown |
| 227 | @qr RASTER https://example.com/${Id} |
| 228 | @qr RASTER ${Url} version=5 scale=4 ecc=M |
| 229 | ``` |
| 230 | |
| 231 | | Attribute | Native | Raster | |
| 232 | |-----------|--------|--------| |
| 233 | | `size` | Module dot size 1–16 | — | |
| 234 | | `scale` | — | Pixels per module (default `4`) | |
| 235 | | `version` | — | QR version 1–40 (optional) | |
| 236 | | `ecc` | `L`, `M`, `Q`, `H` | Same | |
| 237 | | `align` | `left`, `center`, `right` | Same | |
| 238 | |
| 239 | --- |
| 240 | |
| 241 | ## Parameters |
| 242 | |
| 243 | | Form | Type | Print dialog | CLI | |
| 244 | |------|------|--------------|-----| |
| 245 | | `${Name}` | text | text field | `--set Name=Value` | |
| 246 | | `$[Name]` | bool | checkbox | `--set Name=true` / `false` (also `1`/`0`, `yes`/`no`) | |
| 247 | |
| 248 | - Same name must not appear as both `${…}` and `$[…]`. |
| 249 | - GUI and CLI require **every** parameter; bools default to unchecked (`false`) in the dialog. |
| 250 | - Usable in text; `${…}` also in barcode/QR/image paths (`$[…]` is text-inline only). |
| 251 | |
| 252 | ```markdown |
| 253 | # ${StoreName} |
| 254 | |
| 255 | $[Paid] Paid in full |
| 256 | [] Pending review |
| 257 | |
| 258 | Receipt: ${DocumentNumber} |
| 259 | ``` |
| 260 | |
| 261 | --- |
| 262 | |
| 263 | ## Example receipt |
| 264 | |
| 265 | ```markdown |
| 266 | # ${StoreName} |
| 267 | :center: |
| 268 | |
| 269 | Receipt: ${DocumentNumber} |
| 270 | @date |
| 271 | @time |
| 272 | |
| 273 | @barcode CODE128 ${DocumentNumber} |
| 274 | @qr RASTER https://shop.example.com/r/${DocumentNumber} scale=4 |
| 275 | |
| 276 | @feed 4 |
| 277 | @cut |
| 278 | ``` |
| 279 | |
| 280 | --- |
| 281 | |
| 282 | ## GUI printing |
| 283 | |
| 284 | 1. **Print** → enter parameters → choose a printer → **Print** (next to Refresh). Close with the window ✕. |
| 285 | |
| 286 | Printers may appear as: |
| 287 | |
| 288 | - **USB printer-class** devices (direct bulk OUT) |
| 289 | - **Windows spooler** queues (Windows) |
| 290 | - **USB-serial** ports with a device attached (`COMx`, `/dev/ttyUSB0`, `/dev/ttyACM0`, …) |
| 291 | - **Classic Bluetooth SPP** after you pair the printer in the OS (`COMx` on Windows, often `/dev/rfcomm0` on Linux). Listed with a **Bluetooth** label. |
| 292 | |
| 293 | Empty motherboard serial ports (common on Linux as `/dev/ttyS*`) are hidden. Use **Enter port or queue manually** if you need one of those. |
| 294 | |
| 295 | Bluetooth Low Energy (BLE) printers are not supported. Pair Classic Bluetooth SPP in Windows or your Linux Bluetooth settings first; Posprint does not pair devices itself. |
| 296 | |
| 297 | **Linux serial / RFCOMM:** join the `dialout` group. |
| 298 | |
| 299 | --- |
| 300 | |
| 301 | ## CLI |
| 302 | |
| 303 | ```bash |
| 304 | posprint print receipt.pos -p COM3 --set StoreName=Shop |
| 305 | posprint link receipt.pos |
| 306 | posprint cli-help |
| 307 | ``` |
| 308 | |
| 309 | `posprint list` prints discovered printers. `-p` accepts a serial port name (including a paired Bluetooth COM/`rfcomm` node), USB device label from discovery, or (on Windows) a spooler queue name. See platform CLI help via `posprint cli-help`. |
| 310 | |
| 311 | `posprint link` prints a `posprint://` deep link for the file (see [POSPRINT-URL.md](POSPRINT-URL.md)). |
| 312 | |
| 313 | --- |
| 314 | |
| 315 | ## posprint:// links |
| 316 | |
| 317 | Websites can open the print dialog with an embedded template: |
| 318 | |
| 319 | ``` |
| 320 | posprint://print?v=1&d=… |
| 321 | ``` |
| 322 | |
| 323 | Add `&noconfirm=1` to auto-print once a printer is ready (the browser’s protocol prompt is the consent step). 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). |
| 324 | |
| 325 | `@image` may use `https://…` or `http://…` (downloaded when preview/print needs the image). |
| 326 | |
| 327 | --- |
| 328 | |
| 329 | ## `.pos` file format |
| 330 | |
| 331 | JSON with `version`, `metadata`, and `body` (template source). See [FILE-FORMAT.md](FILE-FORMAT.md). |