BlueGit

timfa posprint

Files

posprint / docs / HELP.md

HELP.md

cfe7435b History
HELP.md 4.7 KiB Download Raw

posprint Help

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

---

Application tabs

TabPurpose
EditorWrite and edit template source
PreviewLive preview of rendered output
HelpThis documentation

Toolbar actions

ActionDescription
NewEmpty template with defaults
OpenLoad a .pos file
Save / Save AsWrite .pos file (metadata + body)
InsertMenu to insert images, barcodes, QR codes, @feed, @cut
PrintSubstitute 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

SettingDescription
Page width (mm)Paper width — set this to 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 both use the same calibrated screen scale. Preview font size is bumped to match printed Font A (~same visual size as the receipt). 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, directives, and inline markup.

Paragraphs

Consecutive non-empty lines form one paragraph.

Headings

# Large heading
## Bold heading

Alignment

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

Bullet lists

- first item
- second item

Long items wrap with a hanging indent:

* this is a
  long line

Parameters

SyntaxEffect
${Name}Parameter (filled at print time)

Horizontal rule

---

Comments

<!-- not printed -->

---

Directives

Directives start with @ at the beginning of a line.

Paper feed / cut

@feed 3
@cut

Image

@image logo.png
@image ${LogoPath} width=50% align=center

Barcode

Native (printer draws barcode via ESC/POS):

@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.

@barcode RASTER CODE128 ${OrderId}
@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-only symbologyUse RASTER prefix
CODE93, CODE11No native ESC/POS in firmware
AttributeDescription
heightHeight in dots (default 64; raster PNG height)
alignleft, center, right
show_textNative only: human-readable text under barcode

QR code

Native (ESC/POS QR, model 2):

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

Raster (bitmap; supports 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; auto if omitted)
eccL, M, Q, HSame
alignleft, center, rightSame

---

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

# ${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).

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| **Editor** | Write and edit template source |
12| **Preview** | Live preview of rendered output |
13| **Help** | This documentation |
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** | Menu to insert images, barcodes, QR codes, `@feed`, `@cut` |
23| **Print** | Substitute parameters, pick USB printer, send ESC/POS bytes |
24
25## Editor assistance
26
27- Type `@` at the start of a line to see **directive autocomplete** (`feed`, `cut`, `image`, `barcode`, `qr`).
28- Use **Insert → Barcode / QR code** to pick native or raster type before inserting a snippet.
29
30## Page settings
31
32| Setting | Description |
33|---------|-------------|
34| **Page width (mm)** | Paper width — set this to match your physical roll (e.g. `53`, `58`, `80`) |
35| **Preview zoom** | Screen zoom; `100%` is calibrated to typical receipt width on screen |
36
37Preview width and text both use the same calibrated screen scale. Preview font size is bumped to match printed Font A (~same visual size as the receipt). Blank lines / `@feed` use the same line spacing as printed text. Heading `#` uses double width/height like GS `!` on the printer; `##` uses bold only.
38
39If the document does not end with `@cut` (ignoring blank lines after it), a red warning appears next to **Help**.
40
41---
42
43## Template language
44
45A template is plain text: paragraphs, headings, directives, and inline markup.
46
47### Paragraphs
48
49Consecutive non-empty lines form one paragraph.
50
51### Headings
52
53```markdown
54# Large heading
55## Bold heading
56```
57
58### Alignment
59
60`:left:`, `:center:`, or `:right:` before a paragraph.
61
62### Bullet lists
63
64```markdown
65- first item
66- second item
67```
68
69Long items wrap with a hanging indent:
70
71```text
72* this is a
73 long line
74```
75
76### Parameters
77
78| Syntax | Effect |
79|--------|--------|
80| `${Name}` | Parameter (filled at print time) |
81
82### Horizontal rule
83
84```markdown
85---
86```
87
88### Comments
89
90```markdown
91<!-- not printed -->
92```
93
94---
95
96## Directives
97
98Directives start with `@` at the beginning of a line.
99
100### Paper feed / cut
101
102```markdown
103@feed 3
104@cut
105```
106
107### Image
108
109```markdown
110@image logo.png
111@image ${LogoPath} width=50% align=center
112```
113
114### Barcode
115
116**Native** (printer draws barcode via ESC/POS):
117
118```markdown
119@barcode CODE128 ${OrderId}
120@barcode UPC-A 012345678905
121@barcode ITF 12345678 height=80
122```
123
124**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.
125
126```markdown
127@barcode RASTER CODE128 ${OrderId}
128@barcode RASTER CODE93 ABC-1234
129```
130
131| Native symbology | Notes |
132|----------------|-------|
133| `CODE128` | Alphanumeric |
134| `EAN13`, `EAN8` | Numeric |
135| `CODE39` | Alphanumeric |
136| `UPC-A`, `UPC-E` | Numeric |
137| `ITF` | Interleaved 2 of 5; even digit count |
138| `CODABAR` | Numeric + A-D start/stop |
139
140| Raster-only symbology | Use `RASTER` prefix |
141|-----------------------|---------------------|
142| `CODE93`, `CODE11` | No native ESC/POS in firmware |
143
144| Attribute | Description |
145|-----------|-------------|
146| `height` | Height in dots (default `64`; raster PNG height) |
147| `align` | `left`, `center`, `right` |
148| `show_text` | Native only: human-readable text under barcode |
149
150### QR code
151
152**Native** (ESC/POS QR, model 2):
153
154```markdown
155@qr https://example.com/${Id}
156@qr ${Url} size=6 ecc=H align=center
157```
158
159**Raster** (bitmap; supports QR versions 1–40):
160
161```markdown
162@qr RASTER https://example.com/${Id}
163@qr RASTER ${Url} version=5 scale=4 ecc=M
164```
165
166| Attribute | Native | Raster |
167|-----------|--------|--------|
168| `size` | Module dot size 1–16 | — |
169| `scale` | — | Pixels per module (default `4`) |
170| `version` | — | QR version 1–40 (optional; auto if omitted) |
171| `ecc` | `L`, `M`, `Q`, `H` | Same |
172| `align` | `left`, `center`, `right` | Same |
173
174---
175
176## Parameters
177
178`${ParameterName}` in text, barcode data, QR data, or image paths.
179
180- Same name → **one input** at print time (GUI or CLI).
181- CLI requires **every** parameter via `--set Name=Value`.
182
183---
184
185## Example receipt
186
187```markdown
188# ${StoreName}
189:center:
190
191Receipt: ${DocumentNumber}
192
193@barcode CODE128 ${DocumentNumber}
194@qr RASTER https://shop.example.com/r/${DocumentNumber} scale=4
195
196@feed 4
197@cut
198```
199
200---
201
202## GUI printing (USB)
203
2041. **Print** → enter parameters → choose serial port → **Print**.
205
206**Linux:** `dialout` group. **Windows:** printer appears as `COMx`.
207
208---
209
210## `.pos` file format
211
212JSON with `version`, `metadata`, and `body` (template source).