mirrors/zint
2
0
Fork 0
mirror of https://github.com/zint/zint synced 2024-11-16 20:57:25 +13:00
Code Issues Actions Packages Projects Releases Wiki Activity

CLI: return ZINT_ERROR_INVALID_OPTION instead of 1 on bad option and

Browse Source 
ZINT_WARN_INVALID_OPTION instead of 0 on ignored option;
  more barcode synonyms
manual: append man page zint.1.pmd instead of CLI help;
  various tweaks and fiddlings;
  rMQR add ISO 23941 (released the other day but haven't got yet)
man page: expand and tweak
doc/Makefile: add HTML demo
This commit is contained in:
gitlost
2022-05-22 21:33:45 +01:00
parent 6537d4670f
commit 9ae4e347d7
14 changed files with 1533 additions and 593 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
docs/Makefile
View File

@ -14,6 +14,9 @@ INCLUDES_PDF = $(INC_HEADER_PDF) $(INC_BEFORE_BODY_PDF)
INC_PDF = --include-in-header $(INC_HEADER_PDF) --include-before-body $(INC_BEFORE_BODY_PDF)
INCLUDES_TXT = inc_header_txt.tex
INC_TXT = --include-in-header $(INCLUDES_TXT)
SOURCE_MAN_PAGE = zint.1.pmd
OUT_MAN_PAGE = zint.1
INC_HEADER_TEX_MAN = inc_header_man.tex
IMAGES = \
images/zint.png \
images/zint-qt.png \
@ -130,29 +133,55 @@ IMAGES = \
MAIN_FONT = mainfont="TeX Gyre Pagella"
MONO_FONT = monofont="Liberation Mono"
CJK_FONT = CJKmainfont="WenQuanYi Micro Hei Mono"
PDF_OPTS = --pdf-engine=xelatex --filter pandoc-tablenos --highlight-style=$(HIGHLIGHT_THEME) -V block-headings \
-V colorlinks -V geometry:margin=20mm -V papersize=a4 --dpi=300 -M tablenos-warning-level=0
PDF_OPTS = --pdf-engine=xelatex --filter pandoc-tablenos -M tablenos-warning-level=0 \
--highlight-style=$(HIGHLIGHT_THEME) -V colorlinks -V geometry:margin=20mm -V papersize=a4 --dpi=300
TEX_MAN_PAGE = zint.1.tex
TXT_OPTS = --columns 80 --eol=lf -t plain
SOURCE_MAN = zint.1.pmd
OUT_MAN = zint.1
MAN_OPTS = -t man -s
MAN_PAGE_OPTS = -s -t man
all : $(OUT_PDF) $(OUT_TXT) $(OUT_MAN)
all : $(OUT_PDF) $(OUT_TXT) $(OUT_MAN_PAGE)
$(OUT_PDF) : $(SOURCE) $(HIGHLIGHT_THEME) $(INC_HEADER_PDF) $(INC_BEFORE_BODY_PDF) $(IMAGES) Makefile
pandoc $(SOURCE) -f markdown $(INC_PDF) --toc --toc-depth=4 \
-V $(MAIN_FONT) -V $(MONO_FONT) -V $(CJK_FONT) \
$(OUT_PDF) : $(SOURCE) $(SOURCE_MAN_PAGE) $(HIGHLIGHT_THEME) $(INC_HEADER_PDF) $(INC_BEFORE_BODY_PDF) $(IMAGES) Makefile
pandoc $(SOURCE_MAN_PAGE) -f markdown \
$(PDF_OPTS) \
-o $(TEX_MAN_PAGE)
sed -i -e 's/section{/subsection{/' $(TEX_MAN_PAGE) # Convert man page sections to subsections
pandoc $(SOURCE) -f markdown $(INC_PDF) --toc --toc-depth=4 \
-V $(MAIN_FONT) -V $(MONO_FONT) -V $(CJK_FONT) -V block-headings \
$(PDF_OPTS) \
--include-after-body $(TEX_MAN_PAGE) \
-o $(OUT_PDF)
$(OUT_TXT) : $(SOURCE) $(INCLUDES_TXT) Makefile
pandoc $(SOURCE) -f markdown $(INC_TXT) --toc --toc-depth=4 \
$(OUT_TXT) : $(SOURCE) $(SOURCE_MAN_PAGE) $(INCLUDES_TXT) Makefile
pandoc $(SOURCE) $(SOURCE_MAN_PAGE) -f markdown $(INC_TXT) --toc --toc-depth=4 \
-V $(MAIN_FONT) -V $(MONO_FONT) -V $(CJK_FONT) \
$(TXT_OPTS) \
-o $(OUT_TXT)
sed -i -e 's/ *$$//' $(OUT_TXT)
# Indent Man Page sections in TOC and remove trailing spaces
sed -i \
-e 's/^\(- [A-Z][A-Z ]*\)$$/ \1/' \
-e 's/ *$$//' \
$(OUT_TXT)
$(OUT_MAN) : $(SOURCE_MAN) Makefile
pandoc $(SOURCE_MAN) -f markdown \
$(MAN_OPTS) \
-o $(OUT_MAN)
$(OUT_MAN_PAGE) : $(SOURCE_MAN_PAGE) Makefile
pandoc $(SOURCE_MAN_PAGE) -f markdown \
$(MAN_PAGE_OPTS) \
-o $(OUT_MAN_PAGE)
# HTML demo
OUT_HTML = manual.html
HTML_OPTS = --filter pandoc-tablenos -M tablenos-warning-level=0 --highlight-style=$(HIGHLIGHT_THEME) \
--eol=lf -s -t html
$(OUT_HTML) : $(SOURCE) $(SOURCE_MAN_PAGE) Makefile
pandoc $(SOURCE) $(SOURCE_MAN_PAGE) -f markdown --toc --toc-depth=4 \
-V $(MAIN_FONT) -V $(MONO_FONT) -V $(CJK_FONT) \
$(HTML_OPTS) \
-o $(OUT_HTML)
# Indent Man Page sections in TOC & change Man Page sections h1 -> h2
sed -i \
-e 's/\(Man Page<\/a>\)<\/li>/\1<ul>/' \
-e 's/\(AUTHORS<\/a><\/li>\)/\1<\/ul><\/li>/' \
-e 's/^<h1\([^>]*>[A-Z][A-Z ]*<\/\)h1>$$/<h2\1h2>/' \
$(OUT_HTML)

4
docs/inc_header_pdf.tex
View File

@ -13,7 +13,7 @@
%% https://github.com/jgm/pandoc/wiki/Pandoc-Tricks#definition-list-terms-on-their-own-line-in-latex
\let\originalitem\item
\makeatletter
\renewcommand{\item}[1][\@nil]{
\renewcommand{\item}[1][\@nil]{%
\def\tmp{#1}
\ifx\tmp\@nnil\originalitem\else\originalitem[#1]\hfill\par\fi}
\makeatother
@ -27,7 +27,7 @@
%% Unfortunately this messes up wrapping TODO: fix
%% Background color for inline code https://tex.stackexchange.com/a/507116
%\definecolor{icbg}{HTML}{fafafa} % Same as modified pygments.theme
%\newcommand{\code}[1]{
%\newcommand{\code}[1]{%
%\begingroup\setlength{\fboxsep}{1pt}
%\colorbox{icbg}{\oldtexttt{\hspace*{0.1pt}\vphantom{A}#1\hspace*{0.1pt}}}\endgroup}
%\renewcommand{\texttt}[1]{\textcolor{icfg}{\code{\oldtexttt{#1}}}}

211
docs/manual.pmd
View File

@ -29,29 +29,35 @@ Some of the words and phrases used in this document are specific to barcoding,
and so a brief explanation is given to help understanding:
symbol:
: A symbol is an image which encodes data according to one of the standards.
This encompasses barcodes (linear symbols) as well as any of the other
methods of representing data used in this program.
symbology:
: A method of encoding data to create a certain type of symbol.
linear:
: A linear or one-dimensional symbol is one which consists of bars and spaces,
and is what most people associate with the term 'barcode'. Examples include
Code 128.
stacked:
: A stacked symbol consists of multiple linear symbols placed one above
another and which together hold the message, usually alongside some error
correction data. Examples include PDF417.
matrix:
: A matrix symbol is one based on a (usually square) grid of elements called
modules. Examples include Data Matrix, but MaxiCode and DotCode are also
considered matrix symbologies.
composite:
: A composite symbology is one which is made up of elements which are both
linear and stacked. Those currently supported are made up of a linear
'primary' message above which is printed a stacked component based on the
@ -59,6 +65,7 @@ composite:
linear and the stacked components.
X-dimension:
: The X-dimension of a symbol is the size (usually the width) of the smallest
element. For a linear symbology this is the width of the smallest bar. For
matrix symbologies it is the width of the smallest module (usually a
@ -68,11 +75,13 @@ X-dimension:
is determined by the width.
GS1 data:
: This is a structured way of representing information which consists of
'chunks' of data, each of which starts with an Application Identifier (AI).
The AI identifies what type of information is being encoded.
Reader Initialisation:
Reader Initialisation (Programming):
: Some symbologies allow a special character to be included which can be
detected by the scanning equipment as signifying that the data is used to
program or change settings in that equipment. This data is usually not
@ -81,6 +90,7 @@ Reader Initialisation:
to your scanner.
ECI:
: The Extended Channel Interpretations (ECI) mechanism allows for
multi-language data to be encoded in symbols which would usually support
only Latin-1 (ISO/IEC 8859-1 plus ASCII) characters. This can be useful, for
@ -90,10 +100,12 @@ ECI:
Two other concepts that are important are raster and vector.
raster:
: A low level bitmap representation of an image. BMP, GIF, PCX, PNG and TIF
are raster file formats.
vector:
: A high level command- or data-based representation of an image. EMF, EPS
and SVG are vector file formats. They require renderers to turn them into
bitmaps.
@ -245,13 +257,13 @@ preview.
## 3.2 Composite Groupbox
![Zint Barcode Studio encoding GS1 composite data](images/gui_composite.png)
![Zint Barcode Studio encoding GS1 Composite data](images/gui_composite.png)
In the middle of the Data tab is an area for creating composite symbologies
which appears when the currently selected symbology is supported by the
composite symbology standard. GS1 data can then be entered with square brackets
used to separate Application Identifier (AI) information from data as shown
here. For details, see [6.3 Composite Symbols (ISO 24723)].
GS1 Composite symbology standard. GS1 data can then be entered with square
brackets used to separate Application Identifier (AI) information from data as
shown here. For details, see [6.3 GS1 Composite Symbols (ISO 24723)].
## 3.3 Additional ECI/Data Segments Groupbox
@ -280,8 +292,8 @@ part of a Structured Append sequence of symbols.
The Appearance tab can be used to adjust the dimensions and other properties of
the symbol. The `"Height"` value affects the height of symbologies which do not
have a fixed width-to-height ratio, i.e. those other than matrix symbologies.
Boundary bars (`"Border Type"`) can be added and adjusted and the size of the
saved image (`"Printing Scale"`) can be determined.
Boundary bars (`"Border Type"`) can be added and adjusted (`"Border Width"`) and
the size of the saved image (`"Printing Scale"`) can be determined.
## 3.6 Colour Dialog
@ -711,10 +723,11 @@ Value
Table: {#tbl:barcode_types tag=": Barcode Types (Symbologies)"}
[^2]: The symbologies marked with an asterisk (`*`) in the above table used
different names in Zint before version 2.9.0. For example, symbology 29 used the
name `BARCODE_RSS14`. These names are now deprecated but are still recognised by
Zint and will continue to be supported in future versions.
[^2]: The symbologies marked with an asterisk (`*`) in Table
{@tbl:barcode_types} above used different names in Zint before version 2.9.0.
For example, symbology 29 used the name `BARCODE_RSS14`. These names are now
deprecated but are still recognised by Zint and will continue to be supported in
future versions.
## 4.4 Adjusting Height
@ -803,8 +816,8 @@ symbol by corrupting a scan if the scanning beam strays off the top or bottom of
the symbol. Zint can also put a border right around the symbol and its
horizontal whitespace with the `--box` option.
The width of the boundary or box must be specified using the `--border` switch.
For example:
The width of the boundary bars or box borders must be specified using the
`--border` switch. For example:
```bash
zint --box --border=10 -w 10 -d "This Text"
@ -1759,10 +1772,11 @@ Variable Name Type Meaning Default Value
Table: API Structure `zint_symbol` {#tbl:api_structure_zint_symbol tag="$ $"}
[^5]: This value is ignored for Aztec (including HIBC and Aztec Rune), Code One,
Data Matrix (including HIBC), DotCode, Grid Matrix, Han Xin, MaxiCode, QR Code
(including HIBC, Micro QR, rMQR and UPNQR), and Ultracode - all of which have a
fixed width-to-height ratio (or, in the case of Code One, a fixed height).
[^5]: The `height` value is ignored for Aztec (including HIBC and Aztec Rune),
Code One, Data Matrix (including HIBC), DotCode, Grid Matrix, Han Xin, MaxiCode,
QR Code (including HIBC, Micro QR, rMQR and UPNQR), and Ultracode - all of which
have a fixed width-to-height ratio (or, in the case of Code One, a fixed
height).
To alter these values use the syntax shown in the example below. This code has
the same result as the previous example except the output is now taller and
@ -1929,8 +1943,8 @@ Value Effect
`BARCODE_STDOUT` Output the file to stdout.
`READER_INIT` Add a reader initialisation symbol to the data
before encoding.
`READER_INIT` Create as a Reader Initialisation (Programming)
symbol.
`SMALL_TEXT` Use a smaller font for the Human Readable Text.
@ -1958,10 +1972,10 @@ Value Effect
Table: API `output_options` Values {#tbl:api_output_options tag="$ $"}
[^6]: This flag is always set for Codablock-F, Code 16K and Code 49. Special
considerations apply to ITF-14 - see [6.1.2.6 ITF-14].
[^6]: The `BARCODE_BIND` flag is always set for Codablock-F, Code 16K and Code
49. Special considerations apply to ITF-14 - see [6.1.2.6 ITF-14].
[^7]: Codablock-F, Code 16K, Code 49, ITF-14, EAN-2 to EAN-13, ISBN,
[^7]: Codablock-F, Code 16K, Code 49, EAN-2 to EAN-13, ISBN, ITF-14,
UPC-A and UPC-E have compliant quiet zones added by default.
\clearpage
@ -2160,7 +2174,7 @@ Value Meaning
is it UPC/EAN?)
`ZINT_CAP_COMPOSITE` Does the symbology support composite data? (see [6.3
Composite Symbols (ISO 24723)] below)
GS1 Composite Symbols (ISO 24723)] below)
`ZINT_CAP_ECI` Does the symbology support Extended Channel
Interpretations?
@ -2296,7 +2310,7 @@ Human Readable Text, set `--vers=2` (API `option_2 = 2`).
![`zint -b ITF14 --compliantheight -d "9212320967145"`](images/itf14.svg)
ITF-14, also known as UPC Shipping Container Symbol or Case Code, is based on
Interleaved Code 2 of 5 and requires a 13 digit numeric input (digits 0-9). One
Interleaved Code 2 of 5 and requires a 13-digit numeric input (digits 0-9). One
modulo-10 check digit is added by Zint.
If no border option is specified Zint defaults to adding a bounding box with a
@ -2332,7 +2346,7 @@ check digit.
![`zint -b UPCA --compliantheight -d "72527270270"`](images/upca.svg)
UPC-A is used in the United States for retail applications. The symbol requires
an 11 digit article number. The check digit is calculated by Zint. In addition
an 11-digit article number. The check digit is calculated by Zint. In addition
EAN-2 and EAN-5 add-on symbols can be added using the + character. For example,
to draw a UPC-A symbol with the data 72527270270 with an EAN-5 add-on showing
the data 12345 use the command:
@ -2352,7 +2366,7 @@ error = ZBarcode_Encode_and_Print(my_symbol, "72527270270+12345", 0, 0);
![`zint -b UPCA --compliantheight -d "72527270270+12345"`](images/upca_5.svg)
If your input data already includes the check digit symbology `BARCODE_UPCA_CHK`
(35) can be used which takes a 12 digit input and validates the check digit
(35) can be used which takes a 12-digit input and validates the check digit
before encoding.
You can adjust the gap between the main symbol and an add-on in multiples of
@ -2366,7 +2380,7 @@ to a value between 0 and 20 (default 5).
![`zint -b UPCE --compliantheight -d "1123456"`](images/upce.svg)
UPC-E is a zero-compressed version of UPC-A developed for smaller packages. The
code requires a 6 digit article number (digits 0-9). The check digit is
code requires a 6-digit article number (digits 0-9). The check digit is
calculated by Zint. EAN-2 and EAN-5 add-on symbols can be added using the +
character as with UPC-A. In addition Zint also supports Number System 1
encoding by entering a 7-digit article number stating with the digit 1. For
@ -2385,7 +2399,7 @@ error = ZBarcode_Encode_and_Print(my_symbol, "1123456", 0, 0);
```
If your input data already includes the check digit symbology `BARCODE_UPCE_CHK`
(38) can be used which takes a 7 or 8 digit input and validates the check digit
(38) can be used which takes a 7 or 8-digit input and validates the check digit
before encoding.
You can adjust the gap between the main symbol and an add-on in multiples of
@ -2401,7 +2415,7 @@ to a value between 0 and 20 (default 5).
![`zint -b EANX --compliantheight -d "4512345678906"`](images/eanx13.svg)
The EAN system is used in retail across Europe and includes standards for EAN-2,
EAN-5, EAN-8 and EAN-13 which encode 2, 5, 7 or 12 digit numbers respectively.
EAN-5, EAN-8 and EAN-13 which encode 2, 5, 7 or 12-digit numbers respectively.
Zint will decide which symbology to use depending on the length of the input
data. In addition EAN-2 and EAN-5 add-on symbols can be added to EAN-8 and
EAN-13 symbols using the + character as with UPC symbols. For example:
@ -2435,7 +2449,7 @@ All of the EAN symbols include check digits which are added by Zint.
If you are encoding an EAN-8 or EAN-13 symbol and your data already includes
the check digit then you can use symbology `BARCODE_EANX_CHK` (14) which takes
an 8 or 13 digit input and validates the check digit before encoding.
an 8 or 13-digit input and validates the check digit before encoding.
You can adjust the gap between the main symbol and an add-on in multiples of
the X-dimension by setting `--addongap` (API `option_2`) to a value between 7
@ -2547,7 +2561,7 @@ shown in the Human Readable Text, but may be shown by setting `--vers=1` (API
![`zint -b PZN --compliantheight -d "2758089"`](images/pzn.svg)
PZN is a Code 39 based symbology used by the pharmaceutical industry in Germany.
PZN encodes a 7 digit number to which Zint will add a modulo-11 check digit.
PZN encodes a 7-digit number to which Zint will add a modulo-11 check digit.
#### 6.1.7.5 LOGMARS
@ -2630,7 +2644,7 @@ ISO/IEC 8859-1 character set is shown in Appendix [A.2 Latin Alphabet No. 1
![`zint -b CODE128B -d "130170X178"`](images/code128b.svg)
It is sometimes advantageous to stop Code 128 from using subset mode C which
compresses numerical data. The `BARCODE_CODE128B` option (symbology 60)
compresses numerical data. The `BARCODE_CODE128B` variant (symbology 60)
suppresses mode C in favour of mode B.
#### 6.1.10.3 GS1-128
@ -2668,7 +2682,7 @@ zint -b 16 --gs1parens -d "(01)98898765432106(3202)012345(15)991231"
![`zint -b EAN14 --compliantheight -d "9889876543210"`](images/ean14.svg)
A shorter version of GS1-128 which encodes GTIN data only. A 13 digit number is
A shorter version of GS1-128 which encodes GTIN data only. A 13-digit number is
required. The GTIN check digit and AI (01) are added by Zint.
#### 6.1.10.5 NVE-18 (SSCC-18)
@ -2677,7 +2691,7 @@ required. The GTIN check digit and AI (01) are added by Zint.
A variation of Code 128 the 'Nummer der Versandeinheit' standard, also known
as SSCC-18 (Serial Shipping Container Code), includes both modulo-10 and
modulo-103 check digits. NVE-18 requires a 17 digit numerical input. Check
modulo-103 check digits. NVE-18 requires a 17-digit numerical input. Check
digits and AI (00) are added by Zint.
#### 6.1.10.6 HIBC Code 128
@ -2702,15 +2716,15 @@ specified by DPD and adds a modulo-36 check character.
Previously known as RSS (Reduced Spaced Symbology) these symbols are due to
replace GS1-128 symbols in accordance with the GS1 General Specifications. If a
GS1 DataBar symbol is to be printed with a 2D component as specified in ISO/IEC
24723 set `--mode=2` (API `option_1 = 2`). See [6.3 Composite Symbols (ISO
24723 set `--mode=2` (API `option_1 = 2`). See [6.3 GS1 Composite Symbols (ISO
24723)] to find out how to generate DataBar symbols with 2D components.
#### 6.1.11.1 GS1 DataBar Omnidirectional and GS1 DataBar Truncated
![`zint -b DBAR_OMN --compliantheight -d "0950110153001"`](images/dbar_omn.svg)
Previously known as RSS-14 this standard encodes a 13 digit item code. A check
digit and Application Identifier of (01) are added by Zint. (A 14 digit code
Previously known as RSS-14 this standard encodes a 13-digit item code. A check
digit and Application Identifier of (01) are added by Zint. (A 14-digit code
that appends the check digit may be given, in which case the check digit will be
verified.) To produce a truncated symbol set the symbol height to a value
between 13 and 32. Truncated symbols may not be scannable by omnidirectional
@ -2723,11 +2737,11 @@ greater.
![`zint -b DBAR_LTD --compliantheight -d "0950110153001"`](images/dbar_ltd.svg)
Previously known as RSS Limited this standard encodes a 13 digit item code and
Previously known as RSS Limited this standard encodes a 13-digit item code and
can be used in the same way as DataBar Omnidirectional above. DataBar Limited,
however, is limited to data starting with digits 0 and 1 (i.e. numbers in the
range 0 to 1999999999999). As with DataBar Omnidirectional a check digit and
Application Identifier of (01) are added by Zint, and a 14 digit code may be
Application Identifier of (01) are added by Zint, and a 14-digit code may be
given in which case the check digit will be verified.
#### 6.1.11.3 GS1 DataBar Expanded
@ -2757,7 +2771,7 @@ zint -b 31 -d "[01]98898765432106[3202]012345[15]991231"
![`zint -b KOREAPOST -d "923457"`](images/koreapost.svg)
The Korean Postal Barcode is used to encode a six-digit number and includes one
The Korean Postal Barcode is used to encode a 6-digit number and includes one
check digit.
### 6.1.13 Channel Code
@ -2786,7 +2800,7 @@ Table: {#tbl:channel_maxima tag=": Channel Maximum Values"}
\clearpage
## 6.2 Stacked Symbols
## 6.2 Stacked Symbologies
### 6.2.1 Basic Symbol Stacking
@ -2968,7 +2982,7 @@ minimum number of rows to use can be set using the `--rows` option (API
\clearpage
## 6.3 Composite Symbols (ISO 24723)
## 6.3 GS1 Composite Symbols (ISO 24723)
Composite symbols employ a mixture of components to give more comprehensive
information about a product. The permissible contents of a composite symbol is
@ -3097,9 +3111,9 @@ pharmaceuticals. The symbology is able to encode whole numbers between 4 and
Used by the United States Postal Service until 2009, the POSTNET barcode was
used for encoding zip-codes on mail items. POSTNET uses numerical input data
and includes a modulo-10 check digit. While Zint will encode POSTNET symbols of
up to 38 digits in length, standard lengths as used by USPS were `PostNet6` (5
digit ZIP input), `PostNet10` (5 digit ZIP + 4 digit user data) and `PostNet12`
(5 digit ZIP + 6 digit user data).
up to 38 digits in length, standard lengths as used by USPS were `PostNet6`
(5-digit ZIP input), `PostNet10` (5-digit ZIP + 4-digit user data) and
`PostNet12` (5-digit ZIP + 6-digit user data).
### 6.4.3 PLANET
@ -3109,7 +3123,7 @@ Used by the United States Postal Service until 2009, the PLANET (Postal Alpha
Numeric Encoding Technique) barcode was used for encoding routing data on mail
items. PLANET uses numerical input data and includes a modulo-10 check digit.
While Zint will encode PLANET symbols of up to 38 digits in length, standard
lengths used by USPS were `Planet12` (11 digit input) and `Planet14` (13 digit
lengths used by USPS were `Planet12` (11-digit input) and `Planet14` (13-digit
input).
\clearpage
@ -3131,20 +3145,20 @@ included in the input data. Reed-Solomon error correction data is generated by
Zint. Encoding behaviour is determined by the length of the input data according
to the formula shown in the following table:
----------------------------------------------------------
Input Required Input Format Symbol FCC Encoding
Length Length Table
------ ----------------------- ------ --- --------
8 99999999 37-bar 11 None
-------------------------------------------------------------
Input Required Input Format Symbol FCC Encoding
Length Length Table
------ ------------------------- ------ --- --------
8 `99999999` 37-bar 11 None
13 99999999AAAAA 52-bar 59 C
13 `99999999AAAAA` 52-bar 59 C
16 9999999999999999 52-bar 59 N
16 `9999999999999999` 52-bar 59 N
18 99999999AAAAAAAAAA 67-bar 62 C
18 `99999999AAAAAAAAAA` 67-bar 62 C
23 99999999999999999999999 67-bar 62 N
----------------------------------------------------------
23 `99999999999999999999999` 67-bar 62 N
-------------------------------------------------------------
Table: {#tbl:auspost_input_formats tag=": Australia Post Input Formats"}
@ -3208,7 +3222,7 @@ Also known as the OneCode barcode and used in the US by the United States Postal
Service (USPS), the Intelligent Mail system replaced the POSTNET and PLANET
symbologies in 2009. Intelligent Mail is a fixed length (65-bar) symbol which
combines routing and customer information in a single symbol. Input data
consists of a 20 digit tracking code, followed by a dash (`-`), followed by a
consists of a 20-digit tracking code, followed by a dash (`-`), followed by a
delivery point zip-code which can be 0, 5, 9 or 11 digits in length. For example
all of the following inputs are valid data entries:
@ -3428,7 +3442,7 @@ specified by using the `--mask` switch with values 0-3, or in the API by setting
option_3 = ZINT_FULL_MULTIBYTE | (N + 1) << 8
```
### 6.6.4 Rectangular Micro QR Code (rMQR)
### 6.6.4 Rectangular Micro QR Code (rMQR) (ISO 23941)
![`zint -b RMQR -d "0123456"`](images/rmqr.svg)
@ -3519,8 +3533,8 @@ Characters Meaning
unused characters can be filled with the SPACE character
(ASCII 32) or omitted (if omitted adjust the following
character positions).
10 - 12 Three digit country code according to ISO 3166-1.
13 - 15 Three digit service code. This depends on your parcel courier.
10 - 12 Three-digit country code according to ISO 3166-1.
13 - 15 Three-digit service code. This depends on your parcel courier.
Table: {#tbl:maxicode_scm tag=": MaxiCode Structured Carrier Message Format"}
@ -4062,13 +4076,11 @@ international standards:
- ISO/IEC 21471:2020 Information technology - Automatic identification and data
capture techniques - Extended rectangular data matrix (DMRE) bar code
symbology specification
- Uniform Symbology Specification Code One (AIM Inc., 1994)
- AIM Uniform Symbology Specification Code One (1994)
- ANSI/AIM BC12-1998 - Uniform Symbology Specification Channel Code
- ANSI/AIM BC6-2000 - Uniform Symbology Specification Code 49
- ANSI/AIM BC5-1995 - Uniform Symbology Specification Code 93
- ANSI/HIBC 2.6-2016 - The Health Industry Bar Code (HIBC) Supplier Labeling
Standard
- AIM ISS-X-24 - Uniform Symbology Specification Codablock-F
- AIM Europe ISS-X-24 - Uniform Symbology Specification Codablock-F (1995)
- AIM TSC1705001 (v 4.0 Draft 0.15) - Information technology - Automatic
identification and data capture techniques - Bar code symbology
specification - DotCode (Revised 28th May 2019)
@ -4077,6 +4089,8 @@ international standards:
(Released 9th Dec 2008)
- AIMD/TSC15032-43 (v 0.99c) - International Technical Specification -
Ultracode Symbology (Draft) (Released 4th Nov 2015)
- ANSI/HIBC 2.6-2016 - The Health Industry Bar Code (HIBC) Supplier Labeling
Standard
- GS1 General Specifications Release 22.0 (Jan 2022)
- AIM ITS/04-001 International Technical Standard - Extended Channel
Interpretations Part 1: Identification Schemes and Protocol (Released 24th
@ -4147,71 +4161,4 @@ F `¯` `¿` `Ï` `ß` `ï` `ÿ`
Table: {#tbl:iso_iec_8869_1 tag=": ISO/IEC 8859-1"}
# B. CLI Help
```
Zint version 2.10.0.9
Encode input data in a barcode and save as BMP/EMF/EPS/GIF/PCX/PNG/SVG/TIF/TXT
-b, --barcode=TYPE Number or name of barcode type. Default is 20 (CODE128)
--addongap=NUMBER Set add-on gap in multiples of X-dimension for UPC/EAN
--batch Treat each line of input file as a separate data set
--bg=COLOUR Specify a background colour (in hex RGB/RGBA)
--binary Treat input as raw binary data
--bind Add boundary bars
--bold Use bold text
--border=NUMBER Set width of border in multiples of X-dimension
--box Add a box around the symbol
--cmyk Use CMYK colour space in EPS/TIF symbols
--cols=NUMBER Set the number of data columns in symbol
--compliantheight Warn if height not compliant, and use standard default
-d, --data=DATA Set the symbol data content (segment 0)
--direct Send output to stdout
--dmre Allow Data Matrix Rectangular Extended
--dotsize=NUMBER Set radius of dots in dotty mode
--dotty Use dots instead of squares for matrix symbols
--dump Dump hexadecimal representation to stdout
-e, --ecinos Display ECI (Extended Channel Interpretation) table
--eci=NUMBER Set the ECI code for the data (segment 0)
--esc Process escape characters in input data
--fast Use faster encodation (Data Matrix)
--fg=COLOUR Specify a foreground colour (in hex RGB/RGBA)
--filetype=TYPE Set output file type BMP/EMF/EPS/GIF/PCX/PNG/SVG/TIF/TXT
--fullmultibyte Use multibyte for binary/Latin (QR/Han Xin/Grid Matrix)
--gs1 Treat input as GS1 compatible data
--gs1nocheck Do not check validity of GS1 data
--gs1parens Process parentheses "()" as GS1 AI delimiters, not "[]"
--gssep Use separator GS for GS1 (Data Matrix)
--guarddescent=NUMBER Set height of guard bar descent in X-dims (UPC/EAN)
-h, --help Display help message
--height=NUMBER Set height of symbol in multiples of X-dimension
--heightperrow Treat height as per-row
-i, --input=FILE Read input data from FILE
--init Create reader initialisation/programming symbol
--mask=NUMBER Set masking pattern to use (QR/Han Xin/DotCode)
--mirror Use batch data to determine filename
--mode=NUMBER Set encoding mode (MaxiCode/Composite)
--nobackground Remove background (EMF/EPS/GIF/PNG/SVG/TIF only)
--noquietzones Disable default quiet zones
--notext Remove human readable text
-o, --output=FILE Send output to FILE. Default is out.png
--primary=STRING Set primary message (MaxiCode/Composite)
--quietzones Add compliant quiet zones
-r, --reverse Reverse colours (white on black)
--rotate=NUMBER Rotate symbol by NUMBER degrees
--rows=NUMBER Set number of rows (Codablock-F/PDF417)
--scale=NUMBER Adjust size of X-dimension
--scmvv=NUMBER Prefix SCM with "[)>\R01\Gvv" (vv is NUMBER) (MaxiCode)
--secure=NUMBER Set error correction level (ECC)
--segN=ECI,DATA Set the ECI & data content for segment N, where N 1 to 9
--separator=NUMBER Set height of row separator bars (stacked symbologies)
--small Use small text
--square Force Data Matrix symbols to be square
--structapp=I,C[,ID] Set Structured Append info (I index, C count)
-t, --types Display table of barcode types
--vers=NUMBER Set symbol version (size, check digits, other options)
-v, --version Display Zint version
--vwhitesp=NUMBER Set height of vertical whitespace in multiples of X-dim
-w, --whitesp=NUMBER Set width of horizontal whitespace in multiples of X-dim
--werror Convert all warnings into errors
```
# B. zint(1) Man Page

723
docs/manual.txt
View File

File diff suppressed because it is too large Load Diff

303
docs/zint.1
View File

@ -31,6 +31,11 @@
zint takes input data from the command line or a file to encode in a
barcode which is then output to an image file.
.PP
Input data is UTF-8, unless \f[V]--binary\f[R] is specified.
.PP
Human Readable Text (HRT) is displayed by default for those barcodes
that support HRT, unless \f[V]--notext\f[R] is specified.
.PP
The output image file (specified with \f[V]-o\f[R] or
\f[V]--output\f[R]) may be in one of these formats: Windows Bitmap
(\f[V]BMP\f[R]), Enhanced Metafile Format (\f[V]EMF\f[R]), Encapsulated
@ -76,7 +81,7 @@ Automatic code page translation to an ECI page is disabled, and no
validation of the data\[cq]s character encoding takes place.
.TP
\f[V]--bind\f[R]
Add horizontal boundary bars, aka bearer bars, to the symbol.
Add horizontal boundary bars (also known as bearer bars) to the symbol.
The width of the boundary bars must be specified by the
\f[V]--border\f[R] option.
\f[V]--bind\f[R] can also be used to add row separator bars to symbols
@ -85,7 +90,7 @@ case the width of the separator bars must be specified with the
\f[V]--separator\f[R] option.
.TP
\f[V]--bold\f[R]
Use bold text for the Human Readable Text.
Use bold text for the Human Readable Text (HRT).
.TP
\f[V]--border=INTEGER\f[R]
Set the width of boundary bars (\f[V]--bind\f[R]) or box borders
@ -103,8 +108,8 @@ Use the CMYK colour space when outputting to Encapsulated PostScript
.TP
\f[V]--cols=INTEGER\f[R]
Set the number of data columns in the symbol to \f[I]INTEGER\f[R].
Affects Codablock-F, PDF417, MicroPDF417, GS1 DataBar Expanded Stacked
(DBAR_EXPSTK) and DotCode symbols.
Affects Codablock-F, DotCode, GS1 DataBar Expanded Stacked
(DBAR_EXPSTK), MicroPDF417 and PDF417 symbols.
.TP
\f[V]--compliantheight\f[R]
Warn if the height specified by the \f[V]--height\f[R] option is not
@ -122,6 +127,7 @@ is given, in which case it can be anything.
\f[V]--direct\f[R]
Send output to stdout, which in most cases should be re-directed to a
pipe or a file.
Use \f[V]--filetype\f[R] to specify output format.
.TP
\f[V]--dmre\f[R]
For Data Matrix symbols, allow Data Matrix Rectangular Extended (RMRE)
@ -140,6 +146,9 @@ DotCode is always in dotty mode.
\f[V]--dump\f[R]
Dump a hexadecimal representation of the symbol\[cq]s encodation to
stdout.
The same representation may be outputted to a file by using a
\f[V].txt\f[R] extension with \f[V]-o\f[R] or \f[V]--output\f[R] or by
specifying \f[V]--filetype=txt\f[R].
.TP
\f[V]-e\f[R], \f[V]--ecinos\f[R]
Display the table of ECIs (Extended Channel Interpretations).
@ -147,42 +156,36 @@ Display the table of ECIs (Extended Channel Interpretations).
\f[V]--eci=INTEGER\f[R]
Set the ECI code for the input data to \f[I]INTEGER\f[R].
See \f[V]-e\f[R] or \f[V]--ecinos\f[R] for a list of the ECIs available.
ECIs are supported by Aztec Code, Code One, Data Matrix, DotCode, Grid
Matrix, Han Xin Code, MaxiCode, MicroPDF417, PDF417, QR Code, rMQR and
Ultracode
.TP
\f[V]--esc\f[R]
Process escape characters in the input data.
The escape sequences are:
.RS
.IP \[bu] 2
\f[V]\[rs]0\f[R] (0x00) \f[V]NUL\f[R] Null character
.IP \[bu] 2
\f[V]\[rs]E\f[R] (0x04) \f[V]EOT\f[R] End of Transmission
.IP \[bu] 2
\f[V]\[rs]a\f[R] (0x07) \f[V]BEL\f[R] Bell
.IP \[bu] 2
\f[V]\[rs]b\f[R] (0x08) \f[V]BS\f[R] Backspace
.IP \[bu] 2
\f[V]\[rs]t\f[R] (0x09) \f[V]HT\f[R] Horizontal Tab
.IP \[bu] 2
\f[V]\[rs]n\f[R] (0x0A) \f[V]LF\f[R] Line Feed
.IP \[bu] 2
\f[V]\[rs]v\f[R] (0x0B) \f[V]VT\f[R] Vertical Tab
.IP \[bu] 2
\f[V]\[rs]f\f[R] (0x0C) \f[V]FF\f[R] Form Feed
.IP \[bu] 2
\f[V]\[rs]r\f[R] (0x0D) \f[V]CR\f[R] Carriage Return
.IP \[bu] 2
\f[V]\[rs]e\f[R] (0x1B) \f[V]ESC\f[R] Escape
.IP \[bu] 2
\f[V]\[rs]G\f[R] (0x1D) \f[V]GS\f[R] Group Separator
.IP \[bu] 2
\f[V]\[rs]R\f[R] (0x1E) \f[V]RS\f[R] Record Separator
.IP \[bu] 2
\f[V]\[rs]\[rs]\f[R] (0x5C) \f[V]\[rs]\f[R] Backslash
.IP \[bu] 2
\f[V]\[rs]xNN\f[R] (0xNN) Any 8-bit character where NN is hexadecimal
.IP \[bu] 2
\f[V]\[rs]uNNNN\f[R] (U+NNNN) Any 16-bit Unicode BMP character where
NNNN is hexadecimal
.IP
.nf
\f[C]
\[rs]0 (0x00) NUL Null character
\[rs]E (0x04) EOT End of Transmission
\[rs]a (0x07) BEL Bell
\[rs]b (0x08) BS Backspace
\[rs]t (0x09) HT Horizontal Tab
\[rs]n (0x0A) LF Line Feed
\[rs]v (0x0B) VT Vertical Tab
\[rs]f (0x0C) FF Form Feed
\[rs]r (0x0D) CR Carriage Return
\[rs]e (0x1B) ESC Escape
\[rs]G (0x1D) GS Group Separator
\[rs]R (0x1E) RS Record Separator
\[rs]\[rs] (0x5C) \[rs] Backslash
\[rs]xNN (0xNN) Any 8-bit character where NN is
hexadecimal
\[rs]uNNNN (U+NNNN) Any 16-bit Unicode BMP character
where NNNN is hexadecimal
\f[R]
.fi
.RE
.TP
\f[V]--fast\f[R]
@ -200,7 +203,7 @@ Set the output file type to \f[I]TYPE\f[R], which is one of
\f[V]TXT\f[R].
.TP
\f[V]--fullmultibyte\f[R]
Use the multibyte modes of QR Code, Han Xin, and Grid Matrix for
Use the multibyte modes of Grid Matrix, Han Xin and QR Code for
non-ASCII data.
.TP
\f[V]--gs1\f[R]
@ -214,7 +217,7 @@ Do not check the validity of GS1 data.
\f[V]--gs1parens\f[R]
Process parentheses \f[V]\[dq]()\[dq]\f[R] as GS1 AI delimiters, rather
than square brackets \f[V]\[dq][]\[dq]\f[R].
The input data must not contain parentheses.
The input data must not otherwise contain parentheses.
.TP
\f[V]--gssep\f[R]
For Data Matrix in GS1 mode, use \f[V]GS\f[R] (0x1D) as the GS1 data
@ -239,10 +242,10 @@ Affects Codablock-F, Code16K, Code 49, GS1 DataBar Expanded Stacked
Read the input data from \f[I]FILE\f[R].
.TP
\f[V]--init\f[R]
Create a reader initialisation/programming symbol.
Create a Reader Initialisation (Programming) symbol.
.TP
\f[V]--mask=INTEGER\f[R]
Set the masking pattern to use for QR Code, Han Xin or DotCode to
Set the masking pattern to use for DotCode, Han Xin or QR Code to
\f[I]INTEGER\f[R], overriding the automatic selection.
.TP
\f[V]--mirror\f[R]
@ -250,9 +253,34 @@ Use the batch data to determine the filename in batch mode
(\f[V]--batch\f[R]).
.TP
\f[V]--mode=INTEGER\f[R]
For MaxiCode and composite symbols, set the encoding mode to
For MaxiCode and Composite symbols, set the encoding mode to
\f[I]INTEGER\f[R].
The meaning is symbol-specific.
.RS
.PP
For MaxiCode (SCM is Structured Carrier Message, with 3 fields:
postcode, 3-digit ISO 3166-1 country code, 3-digit service code):
.IP
.nf
\f[C]
2 SCM with 9-digit numeric postcode
3 SCM with 6-character alphanumeric postcode
4 Enhanced ECC for the primary part of the message
5 Enhanced ECC for all of the message
6 Reader Initialisation (Programming)
\f[R]
.fi
.PP
For Composite symbols (names end in \f[V]_CC\f[R], i.e.\ EANX_CC,
GS1_128_CC, DBAR_OMN_CC etc.):
.IP
.nf
\f[C]
1 CC-A
2 CC-B
3 CC-C (GS1_128_CC only)
\f[R]
.fi
.RE
.TP
\f[V]--nobackground\f[R]
Remove the background colour (EMF, EPS, GIF, PNG, SVG and TIF only).
@ -261,7 +289,7 @@ Remove the background colour (EMF, EPS, GIF, PNG, SVG and TIF only).
Disable any quiet zones for symbols that define them by default.
.TP
\f[V]--notext\f[R]
Remove the Human Readable Text.
Remove the Human Readable Text (HRT).
.TP
\f[V]-o\f[R], \f[V]--output=FILE\f[R]
Send the output to \f[I]FILE\f[R].
@ -270,14 +298,15 @@ When not in batch mode, the default is \[lq]out.png\[rq] (or
When in batch mode (\f[V]--batch\f[R]), special characters can be used
to format the output filenames:
.RS
.IP \[bu] 2
\f[V]\[ti]\f[R] Insert a number or 0
.IP \[bu] 2
\f[V]#\f[R] Insert a number or space
.IP \[bu] 2
\f[V]\[at]\f[R] Insert a number or \f[V]*\f[R]
.IP \[bu] 2
Any other Insert literally
.IP
.nf
\f[C]
\[ti] Insert a number or 0
# Insert a number or space
\[at] Insert a number or *
Any other Insert literally
\f[R]
.fi
.RE
.TP
\f[V]--primary=STRING\f[R]
@ -286,6 +315,8 @@ For Composite symbols, set the content of the linear symbol.
.TP
\f[V]--quietzones\f[R]
Add compliant quiet zones for symbols that specify one.
This is in addition to any whitespace specified by \f[V]-w\f[R] or
\f[V]--whitesp\f[R] or \f[V]--vwhitesp\f[R].
.TP
\f[V]-r\f[R], \f[V]--reverse\f[R]
Reverse the foreground and background colours (white on black).
@ -310,9 +341,23 @@ For MaxiCode, prefix the Structured Carrier Message (SCM) with
\f[I]INTEGER\f[R].
.TP
\f[V]--secure=INTEGER\f[R]
Set the error correction level (ECC) or check character options to
\f[I]INTEGER\f[R].
The meaning is symbol-specific.
Set the error correction level (ECC) to \f[I]INTEGER\f[R].
The meaning is specific to the following matrix symbols:
.RS
.IP
.nf
\f[C]
Aztec Code 1 to 4 (10%, 23%, 36%, 50%) (approx.)
Grid Matrix 1 to 5 (10% to 50%) (approx.)
Han Xin 1 to 4 (8%, 15%, 23%, 30%) (approx.)
Micro QR 1 to 3 (L, M, Q)
PDF417 0 to 8 (2\[ha](INTEGER + 1) codewords)
QR Code 1 to 4 (L, M, Q, H)
rMQR 2 or 4 (M, H)
Ultracode 1 to 6 (0%, 5%, 9%, 17%, 25%, 33%) (approx.)
\f[R]
.fi
.RE
.TP
\f[V]--segN=ECI,DATA\f[R]
Set the \f[I]ECI\f[R] & \f[I]DATA\f[R] content for segment N, where N is
@ -326,7 +371,7 @@ Set the height of row separator bars for stacked symbologies, where
\f[I]INTEGER\f[R] is in integral multiples of the X-dimension.
.TP
\f[V]--small\f[R]
Use small text for Human Readable Text.
Use small text for Human Readable Text (HRT).
.TP
\f[V]--square\f[R]
For Data Matrix symbols, exclude rectangular sizes when considering
@ -337,6 +382,9 @@ Set Structured Append info, where \f[V]I\f[R] is the 1-based index,
\f[V]C\f[R] is the count of total symbols in the sequence, and
\f[V]ID\f[R], which is optional, is the identifier that all symbols in
the sequence share.
Structured Append is supported by Aztec Code, Code One, Data Matrix,
DotCode, Grid Matrix, MaxiCode, MicroPDF417, PDF417, QR Code and
Ultracode.
.TP
\f[V]-t\f[R], \f[V]--types\f[R]
Display the table of barcode types (symbologies).
@ -347,12 +395,60 @@ The numbers or names can be used with \f[V]-b\f[R] or
Set the symbol version (size, check digits, other options) to
\f[I]INTEGER\f[R].
The meaning is symbol-specific.
For most matrix symbols, it specifies size.
For a number of linear symbols, it specifies check character options.
For a few other symbologies, it specifies other characteristics.
.RS
.PP
For most matrix symbols, it specifies size:
.IP
.nf
\f[C]
Aztec Code 1 to 36 (1 to 4 compact)
Code One 1 to 10
Data Matrix 1 to 48 (31 to 48 DMRE)
Grid Matrix 1 to 13
Han Xin 1 to 84
Micro QR 1 to 4 (M1, M2, M3, M4)
QR Code 1 to 40
rMQR 1 to 38 (33 to 38 automatic width)
\f[R]
.fi
.PP
For a number of linear symbols, it specifies check character options
(\[lq]hide\[rq] or \[lq]hidden\[rq] means don\[cq]t show in HRT,
\[lq]show\[rq] or \[lq]visible\[rq] means do display in HRT):
.IP
.nf
\f[C]
C25IATA 1 or 2 (add visible or hidden check digit)
C25IND ditto
C25INTER ditto
C25LOGIC ditto
C25STANDARD ditto
Codabar 1 or 2 (add hidden or visible check digit)
Code 11 0 or 1 (no or 1 check digit only)
(has 2 check digits by default)
Code 39 1 (add visible check digit)
Code 93 1 (hide the default check characters)
EXCODE39 1 (add visible check digit)
LOGMARS 1 (add visible check digit)
MSI Plessey 0 to 6 (various check digit options)
+10 (hide)
\f[R]
.fi
.PP
For a few other symbologies, it specifies other characteristics:
.IP
.nf
\f[C]
Channel Code 3 to 8 (no. of channels)
DAFT 50 to 900 (permille tracker ratio)
Ultracode 2 (revision 2)
VIN 1 (add international prefix)
\f[R]
.fi
.RE
.TP
\f[V]-v\f[R], \f[V]--version\f[R]
Display the zint version.
Display zint version.
.TP
\f[V]--vwhitesp=INTEGER\f[R]
Set the height of vertical whitespace above and below the barcode, where
@ -364,6 +460,56 @@ Set the width of horizontal whitespace either side of the barcode, where
.TP
\f[V]--werror\f[R]
Convert all warnings into errors.
.SH EXIT STATUS
.TP
\f[V]0\f[R]
Success (including when given informational options \f[V]-h\f[R],
\f[V]--help\f[R], \f[V]-e\f[R], \f[V]--ecinos\f[R], \f[V]-t\f[R],
\f[V]--types\f[R], \f[V]-v\f[R], \f[V]--version\f[R]).
.TP
\f[V]2\f[R]
Invalid option given but overridden by Zint
(\f[V]ZINT_WARN_INVALID_OPTION\f[R])
.TP
\f[V]3\f[R]
Automatic ECI inserted by Zint (\f[V]ZINT_WARN_USES_ECI\f[R])
.TP
\f[V]4\f[R]
Symbol created not compliant with standards
(\f[V]ZINT_WARN_NONCOMPLIANT\f[R])
.TP
\f[V]5\f[R]
Input data wrong length (\f[V]ZINT_ERROR_TOO_LONG\f[R])
.TP
\f[V]6\f[R]
Input data incorrect (\f[V]ZINT_ERROR_INVALID_DATA\f[R])
.TP
\f[V]7\f[R]
Input check digit incorrect (\f[V]ZINT_ERROR_INVALID_CHECK\f[R])
.TP
\f[V]8\f[R]
Incorrect option given (\f[V]ZINT_ERROR_INVALID_OPTION\f[R])
.TP
\f[V]9\f[R]
Internal error (should not happen)
(\f[V]ZINT_ERROR_ENCODING_PROBLEM\f[R])
.TP
\f[V]10\f[R]
Error opening output file (\f[V]ZINT_ERROR_FILE_ACCESS\f[R])
.TP
\f[V]11\f[R]
Memory allocation (malloc) failure (\f[V]ZINT_ERROR_MEMORY\f[R])
.TP
\f[V]12\f[R]
Error writing to output file (\f[V]ZINT_ERROR_FILE_WRITE\f[R])
.TP
\f[V]13\f[R]
Error counterpart of warning if \f[V]--werror\f[R] given
(\f[V]ZINT_ERROR_USES_ECI\f[R])
.TP
\f[V]14\f[R]
Error counterpart of warning if \f[V]--werror\f[R] given
(\f[V]ZINT_ERROR_NONCOMPLIANT\f[R])
.SH EXAMPLES
.PP
Create \[lq]out.png\[rq] (or \[lq]out.gif\[rq] if zint built without PNG
@ -382,34 +528,39 @@ Create \[lq]qr.svg\[rq] in the current directory, as a QR Code symbol.
zint -b QRCode -d \[aq]This Text\[aq] -o \[aq]qr.svg\[aq]
\f[R]
.fi
.PP
Use batch mode to read from an input file \[lq]ean_nos.txt\[rq]
containing 13-digit GTINs, to create a series of EAN-13 barcodes,
formatting the output filenames to \[lq]ean001.gif\[rq],
\[lq]ean002.gif\[rq] etc.
using the special character \[lq]\[ti]\[rq].
.IP
.nf
\f[C]
zint -b EANX --batch -i \[aq]ean_nos.txt\[aq] -o \[aq]ean\[ti]\[ti]\[ti].gif\[aq]
\f[R]
.fi
.SH BUGS
.PP
Please send bug reports to https://sourceforge.net/p/zint/tickets/
Please send bug reports to https://sourceforge.net/p/zint/tickets/.
.SH SEE ALSO
.PP
Full documention for \f[V]zint\f[R] (and the API \f[V]libzint\f[R] and
the GUI \f[V]zint-qt\f[R]) is available from
http://zint.org.uk/Manual.aspx, and at
https://sourceforge.net/p/zint/docs/manual.txt.
.SH STANDARDS
.SH CONFORMING TO
.PP
Zint is designed to be compliant with a number of international
standards, including:
.IP \[bu] 2
.PP
EN 798:1996, EN 12323:2005, ISO/IEC 15420:2009, ISO/IEC 15417:2007,
.IP \[bu] 2
ISO/IEC 15438:2015, ISO/IEC 16022:2006, ISO/IEC 16023:2000,
.IP \[bu] 2
ISO/IEC 16388:2007, ISO/IEC 18004:2015, ISO/IEC 20830:2021,
.IP \[bu] 2
ISO/IEC 24723:2010, ISO/IEC 24724:2011, ISO/IEC 24728:2006,
.IP \[bu] 2
ISO/IEC 24778:2008, ISO/IEC 16390:2007, ISO/IEC 21471:2019,
.IP \[bu] 2
ANSI-HIBC 2.6-2016, ANSI/AIM BC12-1998, ANSI/AIM BC6-2000,
.IP \[bu] 2
ANSI/AIM BC5-1995, AIM ISS-X-24, AIMD014 (v 1.63), USPS-B-3200,
.IP \[bu] 2
USS Code One (1994), GS1 22.0 (2022), AIM ITS/04-023 (2022)
ISO/IEC 15438:2015, ISO/IEC 16022:2006, ISO/IEC 16023:2000, ISO/IEC
16388:2007, ISO/IEC 18004:2015, ISO/IEC 20830:2021, ISO/IEC 24723:2010,
ISO/IEC 24724:2011, ISO/IEC 24728:2006, ISO/IEC 24778:2008, ISO/IEC
16390:2007, ISO/IEC 21471:2019, AIM USS Code One (1994), ANSI/AIM
BC12-1998, ANSI/AIM BC6-2000, ANSI/AIM BC5-1995, AIM ISS-X-24 (1995),
AIMD014 (v 1.63) (2008), ANSI-HIBC 2.6-2016, AIM ITS/04-023 (2022)
.SH AUTHORS
Robin Stuart <robin@zint.org.uk>.
.PP
Robin Stuart <robin@zint.org.uk>

237
docs/zint.1.pmd
View File

@ -1,5 +1,5 @@
% zint(1) Version 2.10.0.9
% Robin Stuart <robin@zint.org.uk>
%
% May 2022
# NAME
@ -15,6 +15,10 @@
zint takes input data from the command line or a file to encode in a barcode which is then output to an image file.
Input data is UTF-8, unless `--binary` is specified.
Human Readable Text (HRT) is displayed by default for those barcodes that support HRT, unless `--notext` is specified.
The output image file (specified with `-o` or `--output`) may be in one of these formats: Windows Bitmap (`BMP`),
Enhanced Metafile Format (`EMF`), Encapsulated PostScript (`EPS`), Graphics Interchange Format (`GIF`), ZSoft
Paintbrush (`PCX`), Portable Network Format (`PNG`), Scalable Vector Graphic (`SVG`), or Tagged Image File Format
@ -27,8 +31,8 @@ Paintbrush (`PCX`), Portable Network Format (`PNG`), Scalable Vector Graphic (`S
`-b TYPE`, `--barcode=TYPE`
: Set the barcode symbology that will be used to encode the data. *TYPE* is the number or name of the barcode
symbology. If not given, the symbology defaults to 20 (Code 128). To see what types are available, use the `-t`
or `--types` option. Type names are case-insensitive, and non-alphanumerics are ignored.
symbology. If not given, the symbology defaults to 20 (Code 128). To see what types are available, use the `-t` or
`--types` option. Type names are case-insensitive, and non-alphanumerics are ignored.
`--addongap=INTEGER`
: For UPC/EAN symbologies, set the gap between the main data and the add-on. *INTEGER* is in integral multiples of
@ -47,12 +51,13 @@ Paintbrush (`PCX`), Portable Network Format (`PNG`), Scalable Vector Graphic (`S
page is disabled, and no validation of the data's character encoding takes place.
`--bind`
: Add horizontal boundary bars, aka bearer bars, to the symbol. The width of the boundary bars must be specified by
the `--border` option. `--bind` can also be used to add row separator bars to symbols stacked with multiple `-d`
or `--data` inputs, in which case the width of the separator bars must be specified with the `--separator` option.
: Add horizontal boundary bars (also known as bearer bars) to the symbol. The width of the boundary bars must be
specified by the `--border` option. `--bind` can also be used to add row separator bars to symbols stacked with
multiple `-d` or `--data` inputs, in which case the width of the separator bars must be specified with the
`--separator` option.
`--bold`
: Use bold text for the Human Readable Text.
: Use bold text for the Human Readable Text (HRT).
`--border=INTEGER`
: Set the width of boundary bars (`--bind`) or box borders (`--box`), where *INTEGER* is in integral multiples of
@ -65,8 +70,8 @@ Paintbrush (`PCX`), Portable Network Format (`PNG`), Scalable Vector Graphic (`S
: Use the CMYK colour space when outputting to Encapsulated PostScript (EPS) or TIF files.
`--cols=INTEGER`
: Set the number of data columns in the symbol to *INTEGER*. Affects Codablock-F, PDF417, MicroPDF417, GS1 DataBar
Expanded Stacked (DBAR_EXPSTK) and DotCode symbols.
: Set the number of data columns in the symbol to *INTEGER*. Affects Codablock-F, DotCode, GS1 DataBar Expanded
Stacked (DBAR_EXPSTK), MicroPDF417 and PDF417 symbols.
`--compliantheight`
@ -80,7 +85,8 @@ Paintbrush (`PCX`), Portable Network Format (`PNG`), Scalable Vector Graphic (`S
`--direct`
: Send output to stdout, which in most cases should be re-directed to a pipe or a file.
: Send output to stdout, which in most cases should be re-directed to a pipe or a file. Use `--filetype` to specify
output format.
`--dmre`
@ -97,7 +103,8 @@ Paintbrush (`PCX`), Portable Network Format (`PNG`), Scalable Vector Graphic (`S
`--dump`
: Dump a hexadecimal representation of the symbol's encodation to stdout.
: Dump a hexadecimal representation of the symbol's encodation to stdout. The same representation may be outputted
to a file by using a `.txt` extension with `-o` or `--output` or by specifying `--filetype=txt`.
`-e`, `--ecinos`
@ -105,27 +112,31 @@ Paintbrush (`PCX`), Portable Network Format (`PNG`), Scalable Vector Graphic (`S
`--eci=INTEGER`
: Set the ECI code for the input data to *INTEGER*. See `-e` or `--ecinos` for a list of the ECIs available.
: Set the ECI code for the input data to *INTEGER*. See `-e` or `--ecinos` for a list of the ECIs available. ECIs
are supported by Aztec Code, Code One, Data Matrix, DotCode, Grid Matrix, Han Xin Code, MaxiCode, MicroPDF417,
PDF417, QR Code, rMQR and Ultracode
`--esc`
: Process escape characters in the input data. The escape sequences are:
- `\0` (0x00) `NUL` Null character
- `\E` (0x04) `EOT` End of Transmission
- `\a` (0x07) `BEL` Bell
- `\b` (0x08) `BS` Backspace
- `\t` (0x09) `HT` Horizontal Tab
- `\n` (0x0A) `LF` Line Feed
- `\v` (0x0B) `VT` Vertical Tab
- `\f` (0x0C) `FF` Form Feed
- `\r` (0x0D) `CR` Carriage Return
- `\e` (0x1B) `ESC` Escape
- `\G` (0x1D) `GS` Group Separator
- `\R` (0x1E) `RS` Record Separator
- `\\` (0x5C) `\` Backslash
- `\xNN` (0xNN) Any 8-bit character where NN is hexadecimal
- `\uNNNN` (U+NNNN) Any 16-bit Unicode BMP character where NNNN is hexadecimal
\0 (0x00) NUL Null character
\E (0x04) EOT End of Transmission
\a (0x07) BEL Bell
\b (0x08) BS Backspace
\t (0x09) HT Horizontal Tab
\n (0x0A) LF Line Feed
\v (0x0B) VT Vertical Tab
\f (0x0C) FF Form Feed
\r (0x0D) CR Carriage Return
\e (0x1B) ESC Escape
\G (0x1D) GS Group Separator
\R (0x1E) RS Record Separator
\\ (0x5C) \ Backslash
\xNN (0xNN) Any 8-bit character where NN is
hexadecimal
\uNNNN (U+NNNN) Any 16-bit Unicode BMP character
where NNNN is hexadecimal
`--fast`
@ -141,7 +152,7 @@ Paintbrush (`PCX`), Portable Network Format (`PNG`), Scalable Vector Graphic (`S
`--fullmultibyte`
: Use the multibyte modes of QR Code, Han Xin, and Grid Matrix for non-ASCII data.
: Use the multibyte modes of Grid Matrix, Han Xin and QR Code for non-ASCII data.
`--gs1`
@ -155,7 +166,7 @@ Paintbrush (`PCX`), Portable Network Format (`PNG`), Scalable Vector Graphic (`S
`--gs1parens`
: Process parentheses `"()"` as GS1 AI delimiters, rather than square brackets `"[]"`. The input data must not
contain parentheses.
otherwise contain parentheses.
`--gssep`
@ -182,11 +193,11 @@ Paintbrush (`PCX`), Portable Network Format (`PNG`), Scalable Vector Graphic (`S
`--init`
: Create a reader initialisation/programming symbol.
: Create a Reader Initialisation (Programming) symbol.
`--mask=INTEGER`
: Set the masking pattern to use for QR Code, Han Xin or DotCode to *INTEGER*, overriding the automatic selection.
: Set the masking pattern to use for DotCode, Han Xin or QR Code to *INTEGER*, overriding the automatic selection.
`--mirror`
@ -194,7 +205,22 @@ Paintbrush (`PCX`), Portable Network Format (`PNG`), Scalable Vector Graphic (`S
`--mode=INTEGER`
: For MaxiCode and composite symbols, set the encoding mode to *INTEGER*. The meaning is symbol-specific.
: For MaxiCode and Composite symbols, set the encoding mode to *INTEGER*.
For MaxiCode (SCM is Structured Carrier Message, with 3 fields: postcode, 3-digit ISO 3166-1 country code, 3-digit
service code):
2 SCM with 9-digit numeric postcode
3 SCM with 6-character alphanumeric postcode
4 Enhanced ECC for the primary part of the message
5 Enhanced ECC for all of the message
6 Reader Initialisation (Programming)
For Composite symbols (names end in `_CC`, i.e. EANX_CC, GS1_128_CC, DBAR_OMN_CC etc.):
1 CC-A
2 CC-B
3 CC-C (GS1_128_CC only)
`--nobackground`
@ -206,17 +232,17 @@ Paintbrush (`PCX`), Portable Network Format (`PNG`), Scalable Vector Graphic (`S
`--notext`
: Remove the Human Readable Text.
: Remove the Human Readable Text (HRT).
`-o`, `--output=FILE`
: Send the output to *FILE*. When not in batch mode, the default is "out.png" (or "out.gif" if zint built without
PNG support). When in batch mode (`--batch`), special characters can be used to format the output filenames:
- `~` Insert a number or 0
- `#` Insert a number or space
- `@` Insert a number or `*`
- Any other Insert literally
~ Insert a number or 0
# Insert a number or space
@ Insert a number or *
Any other Insert literally
`--primary=STRING`
@ -224,7 +250,8 @@ Paintbrush (`PCX`), Portable Network Format (`PNG`), Scalable Vector Graphic (`S
`--quietzones`
: Add compliant quiet zones for symbols that specify one.
: Add compliant quiet zones for symbols that specify one. This is in addition to any whitespace specified by `-w` or
`--whitesp` or `--vwhitesp`.
`-r`, `--reverse`
@ -249,7 +276,16 @@ Paintbrush (`PCX`), Portable Network Format (`PNG`), Scalable Vector Graphic (`S
`--secure=INTEGER`
: Set the error correction level (ECC) or check character options to *INTEGER*. The meaning is symbol-specific.
: Set the error correction level (ECC) to *INTEGER*. The meaning is specific to the following matrix symbols:
Aztec Code 1 to 4 (10%, 23%, 36%, 50%) (approx.)
Grid Matrix 1 to 5 (10% to 50%) (approx.)
Han Xin 1 to 4 (8%, 15%, 23%, 30%) (approx.)
Micro QR 1 to 3 (L, M, Q)
PDF417 0 to 8 (2^(INTEGER + 1) codewords)
QR Code 1 to 4 (L, M, Q, H)
rMQR 2 or 4 (M, H)
Ultracode 1 to 6 (0%, 5%, 9%, 17%, 25%, 33%) (approx.)
`--segN=ECI,DATA`
@ -263,7 +299,7 @@ Paintbrush (`PCX`), Portable Network Format (`PNG`), Scalable Vector Graphic (`S
`--small`
: Use small text for Human Readable Text.
: Use small text for Human Readable Text (HRT).
`--square`
@ -272,7 +308,8 @@ Paintbrush (`PCX`), Portable Network Format (`PNG`), Scalable Vector Graphic (`S
`--structapp=I,C[,ID]`
: Set Structured Append info, where `I` is the 1-based index, `C` is the count of total symbols in the sequence, and
`ID`, which is optional, is the identifier that all symbols in the sequence share.
`ID`, which is optional, is the identifier that all symbols in the sequence share. Structured Append is supported
by Aztec Code, Code One, Data Matrix, DotCode, Grid Matrix, MaxiCode, MicroPDF417, PDF417, QR Code and Ultracode.
`-t`, `--types`
@ -280,13 +317,47 @@ Paintbrush (`PCX`), Portable Network Format (`PNG`), Scalable Vector Graphic (`S
`--vers=INTEGER`
: Set the symbol version (size, check digits, other options) to *INTEGER*. The meaning is symbol-specific. For most
matrix symbols, it specifies size. For a number of linear symbols, it specifies check character options. For a
few other symbologies, it specifies other characteristics.
: Set the symbol version (size, check digits, other options) to *INTEGER*. The meaning is symbol-specific.
For most matrix symbols, it specifies size:
Aztec Code 1 to 36 (1 to 4 compact)
Code One 1 to 10
Data Matrix 1 to 48 (31 to 48 DMRE)
Grid Matrix 1 to 13
Han Xin 1 to 84
Micro QR 1 to 4 (M1, M2, M3, M4)
QR Code 1 to 40
rMQR 1 to 38 (33 to 38 automatic width)
For a number of linear symbols, it specifies check character options ("hide" or "hidden" means don't show in HRT,
"show" or "visible" means do display in HRT):
C25IATA 1 or 2 (add visible or hidden check digit)
C25IND ditto
C25INTER ditto
C25LOGIC ditto
C25STANDARD ditto
Codabar 1 or 2 (add hidden or visible check digit)
Code 11 0 or 1 (no or 1 check digit only)
(has 2 check digits by default)
Code 39 1 (add visible check digit)
Code 93 1 (hide the default check characters)
EXCODE39 1 (add visible check digit)
LOGMARS 1 (add visible check digit)
MSI Plessey 0 to 6 (various check digit options)
+10 (hide)
For a few other symbologies, it specifies other characteristics:
Channel Code 3 to 8 (no. of channels)
DAFT 50 to 900 (permille tracker ratio)
Ultracode 2 (revision 2)
VIN 1 (add international prefix)
`-v`, `--version`
: Display the zint version.
: Display zint version.
`--vwhitesp=INTEGER`
@ -302,6 +373,51 @@ Paintbrush (`PCX`), Portable Network Format (`PNG`), Scalable Vector Graphic (`S
: Convert all warnings into errors.
# EXIT STATUS
`0`
: Success (including when given informational options `-h`, `--help`, `-e`, `--ecinos`, `-t`, `--types`, `-v`,
`--version`).
`2`
: Invalid option given but overridden by Zint (`ZINT_WARN_INVALID_OPTION`)
`3`
: Automatic ECI inserted by Zint (`ZINT_WARN_USES_ECI`)
`4`
: Symbol created not compliant with standards (`ZINT_WARN_NONCOMPLIANT`)
`5`
: Input data wrong length (`ZINT_ERROR_TOO_LONG`)
`6`
: Input data incorrect (`ZINT_ERROR_INVALID_DATA`)
`7`
: Input check digit incorrect (`ZINT_ERROR_INVALID_CHECK`)
`8`
: Incorrect option given (`ZINT_ERROR_INVALID_OPTION`)
`9`
: Internal error (should not happen) (`ZINT_ERROR_ENCODING_PROBLEM`)
`10`
: Error opening output file (`ZINT_ERROR_FILE_ACCESS`)
`11`
: Memory allocation (malloc) failure (`ZINT_ERROR_MEMORY`)
`12`
: Error writing to output file (`ZINT_ERROR_FILE_WRITE`)
`13`
: Error counterpart of warning if `--werror` given (`ZINT_ERROR_USES_ECI`)
`14`
: Error counterpart of warning if `--werror` given (`ZINT_ERROR_NONCOMPLIANT`)
# EXAMPLES
Create "out.png" (or "out.gif" if zint built without PNG support) in the current directory, as a Code 128 symbol.
@ -316,24 +432,35 @@ Create "qr.svg" in the current directory, as a QR Code symbol.
zint -b QRCode -d 'This Text' -o 'qr.svg'
```
Use batch mode to read from an input file "ean_nos.txt" containing 13-digit GTINs, to create a series of EAN-13
barcodes, formatting the output filenames to "ean001.gif", "ean002.gif" etc. using the special character "~".
```bash
zint -b EANX --batch -i 'ean_nos.txt' -o 'ean~~~.gif'
```
# BUGS
Please send bug reports to https://sourceforge.net/p/zint/tickets/
Please send bug reports to https://sourceforge.net/p/zint/tickets/.
# SEE ALSO
Full documention for `zint` (and the API `libzint` and the GUI `zint-qt`) is available from
http://zint.org.uk/Manual.aspx, and at https://sourceforge.net/p/zint/docs/manual.txt.
# STANDARDS
# CONFORMING TO
Zint is designed to be compliant with a number of international standards, including:
- EN 798:1996, EN 12323:2005, ISO/IEC 15420:2009, ISO/IEC 15417:2007,
- ISO/IEC 15438:2015, ISO/IEC 16022:2006, ISO/IEC 16023:2000,
- ISO/IEC 16388:2007, ISO/IEC 18004:2015, ISO/IEC 20830:2021,
- ISO/IEC 24723:2010, ISO/IEC 24724:2011, ISO/IEC 24728:2006,
- ISO/IEC 24778:2008, ISO/IEC 16390:2007, ISO/IEC 21471:2019,
- ANSI-HIBC 2.6-2016, ANSI/AIM BC12-1998, ANSI/AIM BC6-2000,
- ANSI/AIM BC5-1995, AIM ISS-X-24, AIMD014 (v 1.63), USPS-B-3200,
- USS Code One (1994), GS1 22.0 (2022), AIM ITS/04-023 (2022)
EN 798:1996, EN 12323:2005, ISO/IEC 15420:2009,
ISO/IEC 15417:2007, ISO/IEC 15438:2015, ISO/IEC 16022:2006,
ISO/IEC 16023:2000, ISO/IEC 16388:2007, ISO/IEC 18004:2015,
ISO/IEC 20830:2021, ISO/IEC 24723:2010, ISO/IEC 24724:2011,
ISO/IEC 24728:2006, ISO/IEC 24778:2008, ISO/IEC 16390:2007,
ISO/IEC 21471:2019, AIM USS Code One (1994), ANSI/AIM BC12-1998,
ANSI/AIM BC6-2000, ANSI/AIM BC5-1995, AIM ISS-X-24 (1995),
AIMD014 (v 1.63) (2008), ANSI-HIBC 2.6-2016, AIM ITS/04-023 (2022)
# AUTHORS
Robin Stuart <robin@zint.org.uk>