BlueGit

timfa posprint

Files

posprint / docs / HELP.md

HELP.md

HELP.md 6.5 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

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.

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.

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 (printed/previewed as ASCII *):

* this is a
  long line

Parameters

SyntaxEffect
${Name}Text parameter (filled at print time)
$[Name]Checkbox parameter → [ ] or [√]

${Name} and $[Name] must not share the same name.

Checkboxes

Inline checkboxes use ASCII brackets plus a CP437 check mark so they print in the native font:

SyntaxResult
[] or [ ][ ]
[x], [X], or [√][√] (CP437 √)
[] 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 [√]. CLI: --set Paid=true.

Unicode ballot boxes are not used (they become CJK garbage on CP437 printers).

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 ${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 (bitmap). Raster barcodes stretch horizontally to full paper width; height follows height.

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

QR code

Native (ESC/POS QR, model 2):

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

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.

Printers may appear as:

  • USB printer-class devices (direct bulk OUT)
  • Windows spooler queues (Windows)
  • Serial / USB-serial ports (COMx, /dev/ttyUSB0, …)

Linux serial: join the dialout group.

---

CLI

posprint print receipt.pos -p COM3 --set StoreName=Shop
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.

---

.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
14## Toolbar actions
15
16| Action | Description |
17|--------|-------------|
18| **New** | Empty template with defaults |
19| **Open** | Load a `.pos` file |
20| **Save / Save As** | Write `.pos` file (metadata + body) |
21| **Insert** | Images, barcodes, QR, date/time, parameters, `@feed`, `@cut` |
22| **Print** | Enter parameters, pick a printer, send ESC/POS bytes |
23
24While the Print dialog is open, the rest of the UI (including editor autocomplete) is disabled so parameter fields keep focus.
25
26## Editor assistance
27
28- Type `@` at the start of a line for **directive autocomplete** (`feed`, `cut`, `image`, `barcode`, `qr`, `date`, `time`).
29- Use **Insert → Barcode / QR code** to pick native or raster type before inserting a snippet.
30
31## Page settings
32
33| Setting | Description |
34|---------|-------------|
35| **Page width (mm)** | Paper width — match your physical roll (e.g. `53`, `58`, `80`) |
36| **Preview zoom** | Screen zoom; `100%` is calibrated to typical receipt width on screen |
37
38Preview 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.
39
40If the document does not end with `@cut` (ignoring blank lines after it), a red warning appears next to **Help**.
41
42---
43
44## Template language
45
46A 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.
47
48### Paragraphs
49
50Consecutive non-empty lines form one paragraph.
51
52### Headings
53
54```markdown
55# Large heading
56## Bold heading
57```
58
59### Alignment
60
61`:left:`, `:center:`, or `:right:` before a paragraph.
62
63### Bullet lists
64
65```markdown
66- first item
67- second item
68```
69
70Long items wrap with a hanging indent (printed/previewed as ASCII `*`):
71
72```text
73* this is a
74 long line
75```
76
77### Parameters
78
79| Syntax | Effect |
80|--------|--------|
81| `${Name}` | Text parameter (filled at print time) |
82| `$[Name]` | Checkbox parameter → `[ ]` or `[√]` |
83
84`${Name}` and `$[Name]` must not share the same name.
85
86### Checkboxes
87
88Inline checkboxes use ASCII brackets plus a CP437 check mark so they print in the native font:
89
90| Syntax | Result |
91|--------|--------|
92| `[]` or `[ ]` | `[ ]` |
93| `[x]`, `[X]`, or `[√]` | `[√]` (CP437 `√`) |
94
95```markdown
96[] Unchecked
97[ ] Also unchecked
98[x] Done
99$[Paid]
100```
101
102`$[Paid]` is a **parameter**: in the Print dialog it is a true/false checkbox; on the receipt it becomes `[ ]` or `[√]`. CLI: `--set Paid=true`.
103
104Unicode ballot boxes are not used (they become CJK garbage on CP437 printers).
105
106### Horizontal rule
107
108```markdown
109---
110```
111
112### Comments
113
114```markdown
115<!-- not printed -->
116```
117
118---
119
120## Directives
121
122Directives start with `@` at the beginning of a line.
123
124### Paper feed / cut
125
126```markdown
127@feed 3
128@cut
129```
130
131Blank lines in the editor also feed one line (same as `@feed 1`).
132
133### Date / time
134
135```markdown
136@date
137@date DD-MM-YYYY
138@time
139@time 12h
140@time 24h
141```
142
143- `@date` with no pattern uses the system regional short date.
144- Custom patterns use tokens such as `YYYY`, `MM`, `DD`.
145- `@time` defaults to 24-hour; use `12h` or `24h`.
146
147### Image
148
149```markdown
150@image logo.png
151@image ${LogoPath} width=50% align=center
152```
153
154### Barcode
155
156**Native** (printer draws barcode via ESC/POS):
157
158```markdown
159@barcode CODE128 ${OrderId}
160@barcode UPC-A 012345678905
161@barcode ITF 12345678 height=80
162```
163
164**Raster** (bitmap). Raster barcodes stretch horizontally to full paper width; height follows `height`.
165
166```markdown
167@barcode RASTER CODE128 ${OrderId}
168@barcode RASTER CODE93 ABC-1234
169```
170
171| Native symbology | Notes |
172|----------------|-------|
173| `CODE128` | Alphanumeric |
174| `EAN13`, `EAN8` | Numeric |
175| `CODE39` | Alphanumeric |
176| `UPC-A`, `UPC-E` | Numeric |
177| `ITF` | Interleaved 2 of 5; even digit count |
178| `CODABAR` | Numeric + A-D start/stop |
179
180| Raster-only | Use `RASTER` prefix |
181|-------------|---------------------|
182| `CODE93`, `CODE11` | No native ESC/POS in firmware |
183
184| Attribute | Description |
185|-----------|-------------|
186| `height` | Height in dots (default `64`) |
187| `align` | `left`, `center`, `right` |
188| `show_text` | Native only: human-readable text under barcode |
189
190### QR code
191
192**Native** (ESC/POS QR, model 2):
193
194```markdown
195@qr https://example.com/${Id}
196@qr ${Url} size=6 ecc=H align=center
197```
198
199**Raster** (bitmap; QR versions 1–40):
200
201```markdown
202@qr RASTER https://example.com/${Id}
203@qr RASTER ${Url} version=5 scale=4 ecc=M
204```
205
206| Attribute | Native | Raster |
207|-----------|--------|--------|
208| `size` | Module dot size 1–16 | — |
209| `scale` | — | Pixels per module (default `4`) |
210| `version` | — | QR version 1–40 (optional) |
211| `ecc` | `L`, `M`, `Q`, `H` | Same |
212| `align` | `left`, `center`, `right` | Same |
213
214---
215
216## Parameters
217
218| Form | Type | Print dialog | CLI |
219|------|------|--------------|-----|
220| `${Name}` | text | text field | `--set Name=Value` |
221| `$[Name]` | bool | checkbox | `--set Name=true` / `false` (also `1`/`0`, `yes`/`no`) |
222
223- Same name must not appear as both `${…}` and `$[…]`.
224- GUI and CLI require **every** parameter; bools default to unchecked (`false`) in the dialog.
225- Usable in text; `${…}` also in barcode/QR/image paths (`$[…]` is text-inline only).
226
227```markdown
228# ${StoreName}
229
230$[Paid] Paid in full
231[] Pending review
232
233Receipt: ${DocumentNumber}
234```
235
236---
237
238## Example receipt
239
240```markdown
241# ${StoreName}
242:center:
243
244Receipt: ${DocumentNumber}
245@date
246@time
247
248@barcode CODE128 ${DocumentNumber}
249@qr RASTER https://shop.example.com/r/${DocumentNumber} scale=4
250
251@feed 4
252@cut
253```
254
255---
256
257## GUI printing
258
2591. **Print** → enter parameters → choose a printer → **Print**.
260
261Printers may appear as:
262
263- **USB printer-class** devices (direct bulk OUT)
264- **Windows spooler** queues (Windows)
265- **Serial / USB-serial** ports (`COMx`, `/dev/ttyUSB0`, …)
266
267**Linux serial:** join the `dialout` group.
268
269---
270
271## CLI
272
273```bash
274posprint print receipt.pos -p COM3 --set StoreName=Shop
275posprint cli-help
276```
277
278`-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`.
279
280---
281
282## `.pos` file format
283
284JSON with `version`, `metadata`, and `body` (template source). See [FILE-FORMAT.md](FILE-FORMAT.md).