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

zint.h: increase symbol->text size 160 -> 200;

Browse Source 
rename `ZINT_CAP_EXTENDABLE` -> `ZINT_CAP_EANUPC`
  (`ZINT_CAP_EXTENDABLE` marked as legacy)
CODE128: increase no. symbol chars max 60 -> 99
EAN-2/EAN-5: fix `BARCODE_BIND_TOP/BIND/BOX` output
GS1_128: warn if data > 48 (GS1 General Specifications max)
common: `is_extendable()` -> `is_ucpean()`
raster: add `ZFONT_HALIGN_CENTRE/LEFT/RIGHT` flags and process
  in `draw_string()` (for drawing EAN/UPC outside digits), and
  for `ZFONT_HALIGN_CENTRE` round when calculating centre
  (shifts some texts 1 pixel left)
raster/vector: use offsets into `symbol->text` for EAN/UPC
  instead of `out_upcean_split_text()` (removed)
BMP/EMF/GIF/PCX/PNG/PS/SVG/TIF: use new `out_colour_get_rgb()`
  routine (replaces `colour_to_XXX()`)
general: simplify/fix some `error_number` handling/returning
frontend: truncate overlong `--primary` instead of ignoring;
  negative floating pt option (for `--textgap`)
man page: list size detail for matrix symbols (`--vers`)
manual: further fiddling with scaling text; some typos
This commit is contained in:
gitlost
2023-11-19 19:39:54 +00:00
parent ca964f9098
commit 323b34502b
113 changed files with 2016 additions and 1550 deletions
Download Patch File Download Diff File Expand all files Collapse all files

267
docs/manual.html
View File

@ -258,7 +258,7 @@
.display.math{display: block; text-align: center; margin: 0.5rem auto;}
/* CSS for syntax highlighting */
pre > code.sourceCode { white-space: pre; position: relative; }
pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
pre > code.sourceCode > span { line-height: 1.25; }
pre > code.sourceCode > span:empty { height: 1.2em; }
.sourceCode { overflow: visible; }
code.sourceCode > span { color: inherit; text-decoration: inherit; }
@ -329,7 +329,7 @@
<h1 class="title">Zint Barcode Generator and Zint Barcode Studio User
Manual</h1>
<p class="author">Version 2.12.0.9</p>
<p class="date">July 2023</p>
<p class="date">November 2023</p>
</header>
<nav id="TOC" role="doc-toc">
<ul>
@ -2230,11 +2230,11 @@ aria-hidden="true"><code>zint -d "This Text" --rotate=90</code></figcaption>
<h2 id="adjusting-image-size-x-dimension">4.9 Adjusting Image Size
(X-dimension)</h2>
<p>The size of the image can be altered using the <code>--scale</code>
option, which sets the X-dimension. The scale is multiplied by 2 (with
the exception of MaxiCode) before being applied to the X-dimension. The
default scale is 1.</p>
<p>For MaxiCode, the scale is multiplied by 10 for raster output, by 40
for EMF vector output, and by 2 otherwise (non-EMF vector output).</p>
option, which sets the X-dimension. The default scale is 1.</p>
<p>The scale is multiplied by 2 (with the exception of MaxiCode) before
being applied to the X-dimension. For MaxiCode, it is multiplied by 10
for raster output, by 40 for EMF vector output, and by 2 otherwise
(non-EMF vector output).</p>
<p>For non-Maxicode raster output, the default scale of 1 results in an
X-dimension of 2 pixels. For example for non-Maxicode PNG images a scale
of 5 will increase the X-dimension to 10 pixels. For Maxicode, see <a
@ -2245,19 +2245,77 @@ of 0.5, i.e. 0.5, 1, 1.5, 2, 2.5, 3, 3.5, etc., to avoid the X-dimension
varying across the symbol due to interpolation. 0.5 increments are also
faster to render.</p>
<p>The minimum scale for non-Maxicode raster output in non-dotty mode is
0.5, giving a minimum X-dimension of 1 pixel. The minimum scale for
raster output in dotty mode is 1 (see <a href="#working-with-dots">4.15
Working with Dots</a>). For raster output, text will not be printed for
scales less than 1.</p>
0.5, giving a minimum X-dimension of 1 pixel. For MaxiCode, it is 0.2.
The minimum scale for raster output in dotty mode is 1 (see <a
href="#working-with-dots">4.15 Working with Dots</a>). For raster
output, text will not be printed for scales less than 1.</p>
<p>The minimum scale for vector output is 0.1, giving a minimum
X-dimension of 0.2 (or for Maxicode EMF output, 4).</p>
<p>The maximum scale for both raster and vector is 200.</p>
<p>Using measurable units to specify the X-dimension is often more
useful, as discussed in the next section.</p>
X-dimension of 0.2 (or for Maxicode EMF output, 4). The maximum scale
for both raster and vector is 200.</p>
<p>To summarize the more intricate details:</p>
<div id="tbl:scaling_multiplers" class="tablenos">
<table id="tbl:scaling_multiplers" style="width:92%;"
data-tag=": Scaling Multipliers and Minima">
<caption><span>Table : Scaling Multipliers and Minima</span> </caption>
<colgroup>
<col style="width: 15%" />
<col style="width: 25%" />
<col style="width: 16%" />
<col style="width: 19%" />
<col style="width: 15%" />
</colgroup>
<thead>
<tr class="header">
<th>MaxiCode?</th>
<th style="text-align: left;">Output</th>
<th>Multiplier</th>
<th style="text-align: left;">Min. Scale (non-dotty)</th>
<th style="text-align: left;">Min. Scale (dotty)</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>No</td>
<td style="text-align: left;">Raster</td>
<td>2</td>
<td style="text-align: left;">0.5</td>
<td style="text-align: left;">1</td>
</tr>
<tr class="even">
<td>No</td>
<td style="text-align: left;">Vector</td>
<td>2</td>
<td style="text-align: left;">0.1</td>
<td style="text-align: left;">0.1</td>
</tr>
<tr class="odd">
<td>Yes</td>
<td style="text-align: left;">Raster</td>
<td>10</td>
<td style="text-align: left;">0.2</td>
<td style="text-align: left;">N/A</td>
</tr>
<tr class="even">
<td>Yes</td>
<td style="text-align: left;">Vector (non-EMF)</td>
<td>2</td>
<td style="text-align: left;">0.1</td>
<td style="text-align: left;">N/A</td>
</tr>
<tr class="odd">
<td>Yes</td>
<td style="text-align: left;">EMF</td>
<td>40</td>
<td style="text-align: left;">0.1</td>
<td style="text-align: left;">N/A</td>
</tr>
</tbody>
</table>
</div>
<h3 id="scaling-by-x-dimension-and-resolution">4.9.1 Scaling by
X-dimension and Resolution</h3>
<p>An alternative way to specify the scale which takes the above details
into account and uses measurable units is to use the
<p>An alternative way to specify the scale, which takes the above
details into account, is to specify measurable units using the
<code>--scalexdimdp</code> option, which has the format</p>
<pre><code>--scalexdimdp=X[,R]</code></pre>
<p>where <code>X</code> is the X-dimension (in mm by default) and
@ -2321,9 +2379,10 @@ alt="zint --bold -d &quot;This Text&quot; --small" />
aria-hidden="true"><code>zint --bold -d "This Text" --small</code></figcaption>
</figure>
<p>The gap between the barcode and the text can be adjusted using the
<code>--textgap</code> option, where the gap is given in X-dimensions
(maximum 10X). A zero value uses the default gap (1X). Note that a very
small gap may cause accented texts to overlap with the barcode:</p>
<code>--textgap</code> option, where the gap is given in X-dimensions,
and may be negative (minimum -5X, maximum 10X). The default gap is 1X.
Note that a very small gap may cause accented texts to overlap with the
barcode:</p>
<figure>
<img src="images/code128_textgap.svg" title="fig:" class="lin"
alt="zint -d &quot;Áccent&quot; --textgap=0.1" />
@ -3411,7 +3470,7 @@ X-dimensions).</td>
<td style="text-align: left;">float</td>
<td style="text-align: left;">Gap between barcode and text (HRT) in
X-dimensions.</td>
<td style="text-align: left;">0 (default 1X)</td>
<td style="text-align: left;">1.0</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>guard_descent</code></td>
@ -3428,13 +3487,19 @@ symbols.</td>
<td style="text-align: left;">count 0 (disabled)</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>debug</code></td>
<td style="text-align: left;">integer</td>
<td style="text-align: left;">Debugging flags.</td>
<td style="text-align: left;">0</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>warn_level</code></td>
<td style="text-align: left;">integer</td>
<td style="text-align: left;">Affects error/warning value returned by
Zint API - see <a href="#handling-errors">5.7 Handling Errors</a>.</td>
<td style="text-align: left;"><code>WARN_DEFAULT</code></td>
</tr>
<tr class="even">
<tr class="odd">
<td style="text-align: left;"><code>text</code></td>
<td style="text-align: left;">unsigned character string</td>
<td style="text-align: left;">Human Readable Text, which usually
@ -3442,31 +3507,31 @@ consists of input data plus one more check digit. Uses UTF-8 formatting,
with a terminating <code>NUL</code>.</td>
<td style="text-align: left;"><code>""</code> (empty) (output only)</td>
</tr>
<tr class="odd">
<tr class="even">
<td style="text-align: left;"><code>rows</code></td>
<td style="text-align: left;">integer</td>
<td style="text-align: left;">Number of rows used by the symbol.</td>
<td style="text-align: left;">(output only)</td>
</tr>
<tr class="even">
<tr class="odd">
<td style="text-align: left;"><code>width</code></td>
<td style="text-align: left;">integer</td>
<td style="text-align: left;">Width of the generated symbol.</td>
<td style="text-align: left;">(output only)</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>encoding_data</code></td>
<tr class="even">
<td style="text-align: left;"><code>encoded_data</code></td>
<td style="text-align: left;">array of unsigned character arrays</td>
<td style="text-align: left;">Representation of the encoded data.</td>
<td style="text-align: left;">(output only)</td>
</tr>
<tr class="even">
<tr class="odd">
<td style="text-align: left;"><code>row_height</code></td>
<td style="text-align: left;">array of floats</td>
<td style="text-align: left;">Representation of the height of rows.</td>
<td style="text-align: left;">Heights of each row.</td>
<td style="text-align: left;">(output only)</td>
</tr>
<tr class="odd">
<tr class="even">
<td style="text-align: left;"><code>errtxt</code></td>
<td style="text-align: left;">character string</td>
<td style="text-align: left;">Error message in the event that an error
@ -3474,7 +3539,7 @@ occurred, with a terminating <code>NUL</code> - see <a
href="#handling-errors">5.7 Handling Errors</a>.</td>
<td style="text-align: left;">(output only)</td>
</tr>
<tr class="even">
<tr class="odd">
<td style="text-align: left;"><code>bitmap</code></td>
<td style="text-align: left;">pointer to unsigned character array</td>
<td style="text-align: left;">Pointer to stored bitmap image - see <a
@ -3482,21 +3547,21 @@ href="#buffering-symbols-in-memory-raster">5.4 Buffering Symbols in
Memory (raster)</a>.</td>
<td style="text-align: left;">(output only)</td>
</tr>
<tr class="odd">
<tr class="even">
<td style="text-align: left;"><code>bitmap_width</code></td>
<td style="text-align: left;">integer</td>
<td style="text-align: left;">Width of stored bitmap image (in pixels) -
see <code>bitmap</code> member.</td>
<td style="text-align: left;">(output only)</td>
</tr>
<tr class="even">
<tr class="odd">
<td style="text-align: left;"><code>bitmap_height</code></td>
<td style="text-align: left;">integer</td>
<td style="text-align: left;">Height of stored bitmap image (in pixels)
- see <code>bitmap</code> member.</td>
<td style="text-align: left;">(output only)</td>
</tr>
<tr class="odd">
<tr class="even">
<td style="text-align: left;"><code>alphamap</code></td>
<td style="text-align: left;">pointer to unsigned character array</td>
<td style="text-align: left;">Pointer to array representing alpha
@ -3504,7 +3569,7 @@ channel of stored bitmap image (or <code>NULL</code> if no alpha channel
used) - see <code>bitmap</code> member.</td>
<td style="text-align: left;">(output only)</td>
</tr>
<tr class="even">
<tr class="odd">
<td style="text-align: left;"><code>vector</code></td>
<td style="text-align: left;">pointer to vector structure</td>
<td style="text-align: left;">Pointer to vector header containing
@ -3561,7 +3626,7 @@ data-tag=": API Warning and Error Return Values">
<tr class="odd">
<td style="text-align: left;"><code>ZINT_WARN_HRT_TRUNCATED</code></td>
<td style="text-align: left;">The Human Readable Text returned in
<code>text</code> was truncated (maximum 159 bytes).</td>
<code>text</code> was truncated (maximum 199 bytes).</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>ZINT_WARN_INVALID_OPTION</code></td>
@ -4057,9 +4122,10 @@ Text?</td>
<td style="text-align: left;">Is the symbology stackable?</td>
</tr>
<tr class="odd">
<td style="text-align: left;"><code>ZINT_CAP_EXTENDABLE</code></td>
<td style="text-align: left;">Is the symbology extendable with add-on
data? (i.e. is it EAN/UPC?)</td>
<td style="text-align: left;"><code>ZINT_CAP_EANUPC</code><a
href="#fn12" class="footnote-ref" id="fnref12"
role="doc-noteref"><sup>12</sup></a></td>
<td style="text-align: left;">Is the symbology EAN/UPC?</td>
</tr>
<tr class="even">
<td style="text-align: left;"><code>ZINT_CAP_COMPOSITE</code></td>
@ -4684,8 +4750,8 @@ aria-hidden="true"><code>zint -b CODE128 --bind -d "130170X178"</code></figcapti
128 was developed in 1981 by Computer Identics. This symbology supports
full ASCII text and uses a three-Code Set system to compress the data
into a smaller symbol. Zint automatically switches between Code Sets A,
B and C (but see the special escapes below) and adds a hidden modulo-103
check digit.</p>
B and C (but see following) and adds a hidden modulo-103 check
digit.</p>
<p>Manual switching of Code Sets is possible using the
<code>--extraesc</code> option (API
<code>input_mode |= EXTRA_ESCAPE_MODE</code>) and the Code 128-specific
@ -4707,6 +4773,8 @@ Zint 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
href="#a.2-latin-alphabet-no.-1-isoiec-8859-1">A.2 Latin Alphabet No. 1
(ISO/IEC 8859-1)</a>.</p>
<p>Zint can encode a maximum of 99 symbol characters, which allows for
e.g. 198 all-numeric characters.</p>
<h4 id="code-128-suppress-code-set-c-code-sets-a-and-b-only">6.1.10.2
Code 128 Suppress Code Set C (Code Sets A and B only)</h4>
<figure>
@ -4717,8 +4785,8 @@ aria-hidden="true"><code>zint -b CODE128AB -d "130170X178"</code></figcaption>
</figure>
<p>It is sometimes advantageous to stop Code 128 from using Code Set C
which compresses numerical data. The <code>BARCODE_CODE128AB</code><a
href="#fn12" class="footnote-ref" id="fnref12"
role="doc-noteref"><sup>12</sup></a> variant (symbology 60) suppresses
href="#fn13" class="footnote-ref" id="fnref13"
role="doc-noteref"><sup>13</sup></a> variant (symbology 60) suppresses
Code Set C in favour of Code Sets A and B.</p>
<p>Note that the special escapes to manually switch Code Sets mentioned
above are not available for this variant (nor for any other).</p>
@ -8920,7 +8988,8 @@ raster output (BMP, GIF, PCX, PNG and TIF).</p>
<p>Scale the image according to X-dimension <em>X</em> and resolution
<em>R</em>, where <em>X</em> is in mm and <em>R</em> is in dpmm (dots
per mm). <em>X</em> and <em>R</em> may be floating-point. <em>R</em> is
optional and defaults to 12 dpmm (approximately 300 dpi).</p>
optional and defaults to 12 dpmm (approximately 300 dpi). <em>X</em> may
be zero in which case a symbology-specific default is used.</p>
<p>The scaling takes into account the output filetype, and deals with
all the details mentioned above. Units may be specified for <em>X</em>
by appending “in” (inch) or “mm”, and for <em>R</em> by appending “dpi”
@ -8987,7 +9056,7 @@ names can be used with <code>-b</code> | <code>--barcode</code>.</p>
<dd>
<p>Adjust the gap between the barcode and the Human Readable Text (HRT).
<em>NUMBER</em> is in X-dimensions, and may be floating-point. Maximum
is 10; zero results in the default 1X being used.</p>
is 10 and minimum is -5. The default is 1.</p>
</dd>
<dt><code>--vers=INTEGER</code></dt>
<dd>
@ -8995,13 +9064,108 @@ is 10; zero results in the default 1X being used.</p>
<em>INTEGER</em>. The meaning is symbol-specific.</p>
<p>For most matrix symbols, it specifies size:</p>
<pre><code>Aztec Code 1 to 36 (1 to 4 compact)
Code One 1 to 10
Data Matrix 1 to 48 (31 to 48 DMRE)
1 15x15 13 53x53 25 105x105
2 19x19 14 57x57 26 109x109
3 23x23 15 61x61 27 113x113
4 27x27 16 67x67 28 117x117
5 19x19 17 71x71 29 121x121
6 23x23 18 75x75 30 125x125
7 27x27 19 79x79 31 131x131
8 31x31 20 83x83 32 135x135
9 37x37 21 87x87 33 139x139
10 41x41 22 91x91 34 143x143
11 45x45 23 95x95 35 147x147
12 49x49 24 101x101 36 151x151
Code One 1 to 10 (9 and 10 variable width) (WxH)
1 16x18 6 70x76
2 22x22 7 104x98
3 28x28 8 148x134
4 40x42 9 Wx8
5 52x54 10 Wx16
Data Matrix 1 to 48 (31 to 48 DMRE) (HxW)
1 10x10 17 72x72 33 8x80
2 12x12 18 80x80 34 8x96
3 14x14 19 88x88 35 8x120
4 16x16 20 96x96 36 8x144
5 18x18 21 104x104 37 12x64
6 20x20 22 120x120 38 12x88
7 22x22 23 132x132 39 16x64
8 24x24 24 144x144 40 20x36
9 26x26 25 8x18 41 20x44
10 32x32 26 8x32 42 20x64
11 36x36 28 12x26 43 22x48
12 40x40 28 12x36 44 24x48
13 44x44 29 16x36 45 24x64
14 48x48 30 16x48 46 26x40
15 52x52 31 8x48 47 26x48
16 64x64 32 8x64 48 26x64
Grid Matrix 1 to 13
1 18x18 6 78x78 11 138x138
2 30x30 7 90x90 12 150x150
3 42x42 8 102x102 13 162x162
4 54x54 9 114x114
5 66x66 10 126x126
Han Xin 1 to 84
1 23x23 29 79x79 57 135x135
2 25x25 30 81x81 58 137x137
3 27x27 31 83x83 59 139x139
4 29x29 32 85x85 60 141x141
5 31x31 33 87x87 61 143x143
6 33x33 34 89x89 62 145x145
7 35x35 35 91x91 63 147x147
8 37x37 36 93x93 64 149x149
9 39x39 37 95x95 65 151x151
10 41x41 38 97x97 66 153x153
11 43x43 39 99x99 67 155x155
12 45x45 40 101x101 68 157x157
13 47x47 41 103x103 69 159x159
14 49x49 42 105x105 70 161x161
15 51x51 43 107x107 71 163x163
16 53x53 44 109x109 72 165x165
17 55x55 45 111x111 73 167x167
18 57x57 46 113x113 74 169x169
19 59x59 47 115x115 75 171x171
20 61x61 48 117x117 76 173x173
21 63x63 49 119x119 77 175x175
22 65x65 50 121x121 78 177x177
23 67x67 51 123x123 79 179x179
24 69x69 52 125x125 80 181x181
25 71x71 53 127x127 81 183x183
26 73x73 54 129x129 82 185x185
27 75x75 55 131x131 83 187x187
28 77x77 56 133x133 84 189x189
Micro QR 1 to 4 (M1, M2, M3, M4)
1 11x11 3 15x15
2 13x13 4 17x17
QR Code 1 to 40
rMQR 1 to 38 (33 to 38 automatic width)</code></pre>
1 21x21 15 77x77 29 133x133
2 25x25 16 81x81 30 137x137
3 29x29 17 85x85 31 141x141
4 33x33 18 89x89 32 145x145
5 37x37 19 93x93 33 149x149
6 41x41 20 97x97 34 153x153
7 45x45 21 101x101 35 157x157
8 49x49 22 105x105 36 161x161
9 53x53 23 109x109 37 165x165
10 57x57 24 113x113 38 169x169
11 61x61 25 117x117 39 173x173
12 65x65 26 121x121 40 177x177
13 69x69 27 125x125
14 73x73 28 129x129
rMQR 1 to 38 (33 to 38 automatic width) (HxW)
1 7x73 14 11x77 27 15x139
2 7x59 15 11x99 28 17x43
3 7x77 16 11x139 29 17x59
4 7x99 17 13x27 30 17x77
5 7x139 18 13x43 31 17x99
6 9x43 19 13x59 32 17x139
7 9x59 20 13x77 33 7xW
8 9x77 21 13x99 34 9xW
9 9x99 22 13x139 35 11xW
10 9x139 23 15x43 36 13xW
11 11x27 24 15x59 37 15xW
12 11x43 25 15x77 38 17xW
13 11x59 26 15x99</code></pre>
<p>For a number of linear symbols, it specifies check character options
(“hide” or “hidden” means don’t show in HRT, “visible” means do display
in HRT):</p>
@ -9062,7 +9226,7 @@ Success (including when given informational options <code>-h</code> |
</dd>
<dt><code>1</code></dt>
<dd>
Human Readable Text was truncated (maximum 159 bytes)
Human Readable Text was truncated (maximum 199 bytes)
(<code>ZINT_WARN_HRT_TRUNCATED</code>)
</dd>
<dt><code>2</code></dt>
@ -9222,9 +9386,12 @@ class="footnote-back" role="doc-backlink">↩︎</a></p></li>
<li id="fn11"><p>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.<a
href="#fnref11" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
<li id="fn12"><p><code>BARCODE_CODE128AB</code> previously used the name
<code>BARCODE_CODE128B</code>, which is still recognised.<a
<li id="fn12"><p><code>ZINT_CAP_EANUPC</code> was previously named
<code>ZINT_CAP_EXTENDABLE</code>, which is still recognised.<a
href="#fnref12" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
<li id="fn13"><p><code>BARCODE_CODE128AB</code> previously used the name
<code>BARCODE_CODE128B</code>, which is still recognised.<a
href="#fnref13" class="footnote-back" role="doc-backlink">↩︎</a></p></li>
</ol>
</aside>
</body>