BlueGit

timfa posprint

Files

posprint / docs / HELP.md

HELP.md

HELP.md 9.0 KiB Download Raw

posprint Help

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

---

Application tabs

TabPurpose
DesignSide-by-side template editor and live preview
HelpThis documentation
SettingsDefault page width; LAN printers (TCP 9100) on/off + cache; trusted sites for noconfirm

Toolbar actions

ActionDescription
NewEmpty template with defaults
OpenLoad a .pos file
Save / Save AsWrite .pos file (metadata + body)
InsertImages, barcodes, QR, date/time, parameters, @feed, @cut
PrintEnter 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

SettingDescription
Page width (mm)Paper width — match your physical roll (e.g. 53, 58, 80)
Preview zoomScreen 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

SyntaxEffect
${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):

SyntaxResult
[] 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
  • @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

@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):

@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 symbologyNotes
CODE128Alphanumeric
EAN13, EAN8Numeric
CODE39Alphanumeric
UPC-A, UPC-ENumeric
ITFInterleaved 2 of 5; even digit count
CODABARNumeric + A-D start/stop
Raster-onlyUse RASTER prefix
CODE93, CODE11No native ESC/POS in firmware
AttributeDescription
heightHeight in dots (default 64)
alignleft, center, right
show_textNative 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):

@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
AttributeNativeRaster
sizeModule dot size 1–16—
scale—Pixels per module (default 4)
version—QR version 1–40 (optional)
eccL, M, Q, HSame
alignleft, center, rightSame

---

Parameters

FormTypePrint dialogCLI
${Name}texttext field--set Name=Value
$[Name]boolcheckbox--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, …)
  • 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

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:// 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/. 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
3Built-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; LAN printers (TCP 9100) on/off + cache; trusted sites for `noconfirm` |
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
25While 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
41Preview 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
43If 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
49A 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
53Consecutive 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
66On **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
77Indent 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
86Long 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
106Inline 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
138Directives start with `@` at the beginning of a line.
139
140### Paper feed / cut
141
142```markdown
143@feed 3
144@cut
145```
146
147Blank 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
171Local paths resolve relative to the `.pos` file. `http://` and `https://` URLs are downloaded when preview or print needs the image.
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
212Data may contain spaces; tokens after the symbology are joined until the first `key=value` attribute.
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
258Receipt: ${DocumentNumber}
259```
260
261---
262
263## Example receipt
264
265```markdown
266# ${StoreName}
267:center:
268
269Receipt: ${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
2841. **Print** → enter parameters → choose a printer → **Print** (next to Refresh). Close with the window ✕.
285
286Printers 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- **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.
292
293Empty 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`.
294
295**Linux serial:** join the `dialout` group.
296
297---
298
299## CLI
300
301```bash
302posprint print receipt.pos -p COM3 --set StoreName=Shop
303posprint link receipt.pos
304posprint cli-help
305```
306
307`-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`.
308
309`posprint link` prints a `posprint://` deep link for the file (see [POSPRINT-URL.md](POSPRINT-URL.md)).
310
311---
312
313## posprint:// links
314
315Websites can open the print dialog with an embedded template:
316
317```
318posprint://print?v=1&d=…
319```
320
321Add `&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).
322
323`@image` may use `https://…` or `http://…` (downloaded when preview/print needs the image).
324
325---
326
327## `.pos` file format
328
329JSON with `version`, `metadata`, and `body` (template source). See [FILE-FORMAT.md](FILE-FORMAT.md).