mirror of
https://git.code.sf.net/p/zint/code
synced 2026-05-13 09:33:52 +00:00
DATAMATRIX: add manual FNC1 support
CODE128: error on unrecognized extra escape sequences instead of just passing them thru; fix possible shifting before manual FNC1 in 2nd position after single alpha (otherwise won't be recognized as AIM) fix not removing manual FNC1 in 1st/2nd position from content segs (as implied by symbology identifier) CLI: warn if both "--dmre" and "--square" given (as "--square" overwrites "--dmre") common: new routines `z_isalpha()`, `z_extra_escapes()` and `z_ct_set_seg_extra_escapes_eci()` library: new helper `supports_extra_escape_mode()`; fix some error_number dups BWIPP: update to latest, and allow for removal of DBAR_LTD_CC RHS quiet zones & extra row when have add-on in EAN/UPC composites test suite: fix BWIPP escaping manual/man/tcl: update for DATAMATRIX manual FNC1 support Windows: resource scripts: make more consistent (libzint, CLI, GUI) win32/README: update with MSVC 2026
This commit is contained in:
gitlost
111
docs/manual.pmd
111
docs/manual.pmd
@@ -1,6 +1,6 @@
|
||||
% Zint Barcode Generator and Zint Barcode Studio User Manual
|
||||
% Version 2.16.0.9
|
||||
% March 2026
|
||||
% April 2026
|
||||
|
||||
[//]: # ( vim: set ts=4 sw=4 et : )
|
||||
|
||||
@@ -594,9 +594,35 @@ Table: Escape Sequences {#tbl:escape_sequences}
|
||||
codeset from U+0000 to U+D7FF and U+E000 to U+FFFF (i.e. excluding surrogates).
|
||||
Not to be confused with the Windows Bitmap file format BMP!
|
||||
|
||||
(Special escape sequences are available for Code 128 only to manually switch
|
||||
Code Sets and insert special `FNC1` characters - see [6.1.10.1 Standard Code 128
|
||||
(ISO 15417)] for details.)
|
||||
Extra escape sequences are available for certain symbologies using the
|
||||
`--extraesc` option that allows the insertion of special characters or, in the
|
||||
case of Code 128 only, to manually switch Code Sets. Extra escapes begin with
|
||||
the sequence backslash caret ("`\^`"):
|
||||
|
||||
----------------------------------------------------------------------------
|
||||
Extra Escape Interpretation Available for Symbology
|
||||
Sequence
|
||||
----------------- ------------------------------ -----------------------
|
||||
`\^1` Insert `FNC1` character Code128, Data Matrix
|
||||
|
||||
`\^^` Literal `\^` Code128, Data Matrix
|
||||
|
||||
`\^A`, `\^B`, `\^C` Select Code Set A, B or C Code128 only
|
||||
respectively
|
||||
|
||||
`\^@` Exit manual Code Set selection Code128 only
|
||||
and resume automatic Code Set
|
||||
selection
|
||||
---------------------------------------------------------------------------
|
||||
|
||||
Table: Extra Escape Sequences {#tbl:extra_escapes}
|
||||
|
||||
Currently the only special character recognized is the Function Code 1 character
|
||||
`FNC1`. If your data contains the sequence "`\^`" then it must be escaped using
|
||||
the extra escape sequence "`\^^`", i.e. by doubling the caret.
|
||||
|
||||
See [6.1.10.1 Standard Code 128 (ISO 15417)] for the details on manually
|
||||
switching Code Sets.
|
||||
|
||||
Input data can be read directly from file using the `-i` or `--input` switch as
|
||||
shown below. The input file is assumed to be UTF-8 formatted unless an
|
||||
@@ -2526,7 +2552,7 @@ Value Effect
|
||||
`MICROPDF417`, `PDF417`, `QRCODE` and `UPNQR` only).
|
||||
|
||||
`EXTRA_ESCAPE_MODE` Process special symbology-specific escape sequences
|
||||
(`CODE128` only).
|
||||
(`CODE128` and `DATAMATRIX` only).
|
||||
|
||||
`GS1SYNTAXENGINE_MODE` Use the GS1 Syntax Engine (if available) to strictly
|
||||
validate GS1 input.
|
||||
@@ -2565,8 +2591,8 @@ symbol->input_mode = DATA_MODE | GS1_MODE;
|
||||
is not valid.
|
||||
|
||||
Permissible escape sequences (`ESCAPE_MODE`) are listed in
|
||||
[#tbl:escape_sequences], and the special Code 128-only `EXTRA_ESCAPE_MODE`
|
||||
escape sequences are given in [6.1.10.1 Standard Code 128 (ISO 15417)].
|
||||
[#tbl:escape_sequences], and the extra escape sequences (`EXTRA_ESCAPE_MODE`)
|
||||
are listed in [#tbl:extra_escapes].
|
||||
|
||||
The GS1 options `GS1PARENS_MODE` (CLI `--gs1parens`) , `GS1NOCHECK_MODE` (CLI
|
||||
`--gs1nocheck`), `GS1SYNTAXENGINE_MODE` (CLI `--gs1strict`) and `GS1RAW_MODE`
|
||||
@@ -2981,8 +3007,7 @@ Standard Code 2 of 5].
|
||||
|
||||
#### 6.1.2.5 Code 2 of 5 Data Logic
|
||||
|
||||
Data Logic does not include a check digit by default and can encode numeric
|
||||
input (digits 0-9) up to a maximum of 113 digits.
|
||||
Data Logic can encode numeric input (digits 0-9) up to a maximum of 113 digits.
|
||||
|
||||
{.lin}
|
||||
|
||||
@@ -3293,8 +3318,8 @@ hidden modulo-10 check digits.
|
||||
|
||||
#### 6.1.6.1 Telepen Alpha
|
||||
|
||||
Telepen Alpha was developed by SB Electronic Systems Limited and can encode
|
||||
ASCII text input, up to a maximum of 69 characters. Telepen includes a
|
||||
Telepen Alpha was developed in 1972 by SB Electronic Systems Limited and can
|
||||
encode ASCII text input, up to a maximum of 69 characters. Telepen includes a
|
||||
hidden modulo-127 check digit, added by Zint.
|
||||
|
||||
{.lin}
|
||||
@@ -3442,12 +3467,31 @@ supports the encoding of ISO/IEC 8859-1 (non-English) characters in Code 128
|
||||
symbols. The ISO/IEC 8859-1 character set is shown in Annex [A.2 Latin Alphabet
|
||||
No. 1 (ISO/IEC 8859-1)].
|
||||
|
||||
Manual switching of Code Sets is possible using the `--extraesc` option (API
|
||||
Manual insertion of `FNC1` is possible using the `--extraesc` option (API
|
||||
`input_mode |= EXTRA_ESCAPE_MODE`), which apart from processing normal escape
|
||||
sequences also processes the Code 128-specific escapes `\^A`, `\^B`, `\^C` and
|
||||
`\^@` (the latter turns off manual Code Set selection). For instance the
|
||||
following will force switching to Code Set B for the data `"5678"` (normally
|
||||
Code Set C would be used throughout):
|
||||
sequences also processes the extra escape sequences given in
|
||||
[#tbl:extra_escapes]. For instance
|
||||
|
||||
```bash
|
||||
zint -b CODE128 -d "A\^1BC\^1DEF" --extraesc
|
||||
```
|
||||
|
||||
encodes the data `"A<FNC1>BC<FNC1>DEF"`, where `<FNC1>` represents the `FNC1`
|
||||
character.
|
||||
|
||||
If the data contains an extra escape sequence, it can be escaped by doubling the
|
||||
caret (`^`). For instance
|
||||
|
||||
```bash
|
||||
zint -b CODE128 -d "A\^1BC\^^1DEF" --extraesc
|
||||
```
|
||||
|
||||
will encode the data `"A<FNC1>BC\^1DEF"`.
|
||||
|
||||
Manual switching of Code Sets is possible using the Code 128-specific extra
|
||||
escapes `\^A`, `\^B`, `\^C` and `\^@` (the latter turns off manual Code Set
|
||||
selection). For instance the following will force switching to Code Set B for
|
||||
the data `"5678"` (normally Code Set C would be used throughout):
|
||||
|
||||
```bash
|
||||
zint -b CODE128 -d "1234\^B5678" --extraesc
|
||||
@@ -3455,22 +3499,7 @@ zint -b CODE128 -d "1234\^B5678" --extraesc
|
||||
|
||||
The manually selected Code Set will apply until the next Code Set escape
|
||||
sequence or until a `\^@`, with the exception that data that cannot be
|
||||
represented in that Code Set will be switched as appropriate. If the data
|
||||
contains an extra escape sequence, it can be escaped by doubling the caret
|
||||
(`^`). For instance
|
||||
|
||||
```bash
|
||||
zint -b CODE128 -d "\^AABC\^^BDEF" --extraesc
|
||||
```
|
||||
|
||||
will encode the data `"ABC\^BDEF"` in Code Set A.
|
||||
|
||||
There is also the extra escape `\^1`, which will encode a special Function Code
|
||||
1 character (`FNC1`) anywhere you choose in the data, for instance
|
||||
|
||||
```bash
|
||||
zint -b CODE128 -d "A\^1BC\^1DEF" --extraesc
|
||||
```
|
||||
represented in that Code Set will be switched as appropriate.
|
||||
|
||||
Zint can encode a maximum of 102 symbol characters, which allows for e.g. 202
|
||||
all-numeric or 101 all-uppercase characters. Sizes above 120 digits (60
|
||||
@@ -4338,6 +4367,20 @@ GS1 data may be encoded using `FNC1` (default) or `GS` (Group Separator, ASCII
|
||||
29) as separator. Use the option `--gssep` to change to `GS` (API
|
||||
`output_options |= GS1_GS_SEPARATOR`).
|
||||
|
||||
Manual insertion of `FNC1` is possible using the `--extraesc` option (API
|
||||
`input_mode |= EXTRA_ESCAPE_MODE`), which apart from processing normal escape
|
||||
sequences also processes the extra escape sequences given in
|
||||
[#tbl:extra_escapes]. For instance
|
||||
|
||||
```bash
|
||||
zint -b DATAMATRIX -d "A\^1BC\^1DEF" --extraesc
|
||||
```
|
||||
|
||||
encodes the data `"A<FNC1>BC<FNC1>DEF"`, where `<FNC1>` represents the `FNC1`
|
||||
character. If the data contains an extra escape sequence, it can be escaped by
|
||||
doubling the caret (`^`), i.e. `"\^^"` encodes `"\^"`. Note that if using ECIs
|
||||
with manual FNC1s then the ECIs must be ASCII compatible.[^24]
|
||||
|
||||
By default Zint uses a "de facto" codeword placement for symbols of size 144 x
|
||||
144 (version 24). To override this and use the now clarified ISO/IEC standard
|
||||
placement, use option `--dmiso144` (API `option_3 |= DM_ISO_144`).
|
||||
@@ -4360,6 +4403,10 @@ be given as `"123234"`. Note that both `ID1` and `ID2` must be non-zero, so e.g.
|
||||
`"123000"` or `"000123"` would be invalid IDs. If an ID is not given it defaults
|
||||
to `"001001"`.
|
||||
|
||||
[^24]: ASCII-compatible ECIs are ECIs 3 to 18 and 21 to 27 (see
|
||||
[#tbl:eci_codes]). Note in particular that ECI 899, 8-bit binary, is not
|
||||
considered ASCII-compatible.
|
||||
|
||||
### 6.6.2 Royal Mail 2D Mailmark (CMDM) (Data Matrix)
|
||||
|
||||
![`zint -b MAILMARK_2D -d "JGB 01Z999999900000001EC1A1AA1A0SN35TQ"
|
||||
|
||||
Reference in New Issue
Block a user