zint.1.pmd: fix whitesp info, other tweaks; manual.pmd tweak

2024-11-16 20:57:25 +13:00 · 2022-05-20 09:42:19 +01:00 · 2022-05-20 09:42:19 +01:00 · 6537d4670f
commit 6537d4670f
parent 7a32402b93
7 changed files with 65 additions and 27 deletions
--- a/.gitignore
+++ b/.gitignore
@ -9,6 +9,7 @@ build/
 CMakeLists.txt.user*
 backend/Makefile
 frontend/Makefile
+docs/manual.pdf
 build-*
 win32/*.VC.opendb
 win32/*.VC.db
--- a/docs/README
+++ b/docs/README
@ -13,6 +13,26 @@ On Ubuntu/Debian (tested on Ubuntu 22.04)
    sudo apt install fonts-wqy-microhei
    make

+On Fedora (tested on Fedora Linux 36 (Workstation Edition))
+
+    wget https://github.com/jgm/pandoc/releases/download/2.18/pandoc-2.18-linux-amd64.tar.gz
+    tar xf pandoc-2.18-linux-amd64.tar.gz
+    sudo mv -i pandoc-2.18/bin/pandoc /usr/local/bin
+    sudo dnf install python3-pip
+    pip install pandoc-tablenos --user
+    export PATH=~/.local/bin:"$PATH"
+    sudo dnf install librsvg2-tools.x86_64
+    sudo dnf install texlive-xetex
+    sudo dnf install texlive-ctex.noarch
+    sudo dnf install texlive-framed.noarch
+    sudo dnf install texlive-fvextra.noarch
+    sudo dnf install texlive-mdwtools.noarch
+    sudo dnf install texlive-sectsty.noarch
+    sudo dnf install texlive-xecjk.noarch
+    sudo dnf install texlive-tex-gyre.noarch
+    sudo dnf install wqy-microhei-fonts.noarch
+    make
+
 On Windows

 Install https://github.com/jgm/pandoc/releases/download/2.18/pandoc-2.18-windows-x86_64.msi
@ -29,6 +49,8 @@ From command prompt run as administrator
 From normal command prompt run from zint "docs" directory

    set "PATH=<location-of-pandoc-tablenos>:%PATH%"
+    # e.g. set "PATH=%userprofile%\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.10_qbz5n2kfra8p0\LocalCache\local-packages\Python310\Scripts:%PATH%"

 TODO
-??? On make, get various font errors Helvetica, TeX Gyre Pagella which miktex can't handle ???
+??? Various font errors Helvetica, TeX Gyre Pagella which miktex can't handle (ok may be non-activated Windows issue) ???
+??? pandoc-tablenos filter craps out ???
--- a/docs/manual.pmd
+++ b/docs/manual.pmd
@ -2786,7 +2786,7 @@ Table: {#tbl:channel_maxima tag=": Channel Maximum Values"}

 \clearpage

-## 6.2 Stacked Symbologies
+## 6.2 Stacked Symbols

 ### 6.2.1 Basic Symbol Stacking

--- a/docs/manual.txt
+++ b/docs/manual.txt
@ -117,7 +117,7 @@ May 2022
            -   6.1.11.3 GS1 DataBar Expanded
        -   6.1.12 Korea Post Barcode
        -   6.1.13 Channel Code
-    -   6.2 Stacked Symbologies
+    -   6.2 Stacked Symbols
        -   6.2.1 Basic Symbol Stacking
        -   6.2.2 Codablock-F
        -   6.2.3 Code 16K (EN 12323)
@ -2736,7 +2736,7 @@ the table below:

  : {#tbl:channel_maxima tag=“: Channel Maximum Values”}

-6.2 Stacked Symbologies
+6.2 Stacked Symbols

 6.2.1 Basic Symbol Stacking

--- a/docs/zint.1
+++ b/docs/zint.1
@ -73,7 +73,7 @@ RRGGBB or RRGGGAA format.
 \f[V]--binary\f[R]
 Treat input data as raw 8-bit binary data instead of the default UTF-8.
 Automatic code page translation to an ECI page is disabled, and no
-validation of the data\[cq]s encodation takes place.
+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.
@ -104,7 +104,7 @@ Use the CMYK colour space when outputting to Encapsulated PostScript
 \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.
+(DBAR_EXPSTK) and DotCode symbols.
 .TP
 \f[V]--compliantheight\f[R]
 Warn if the height specified by the \f[V]--height\f[R] option is not
@ -116,10 +116,12 @@ any).
 Specify the input \f[I]DATA\f[R] to encode.
 The \f[V]--esc\f[R] option may be used to enter non-printing characters
 using escape sequences.
+The \f[I]DATA\f[R] should be UTF-8, unless the \f[V]--binary\f[R] option
+is given, in which case it can be anything.
 .TP
 \f[V]--direct\f[R]
-Send output to stdout, which in most cases should be re-directed via a
-pipe.
+Send output to stdout, which in most cases should be re-directed to a
+pipe or a file.
 .TP
 \f[V]--dmre\f[R]
 For Data Matrix symbols, allow Data Matrix Rectangular Extended (RMRE)
@ -129,6 +131,7 @@ sizes when considering automatic sizes.
 Set the radius of the dots in dotty mode (\f[V]--dotty\f[R]).
 \f[I]NUMBER\f[R] is in multiples of the X-dimension, and may be
 floating-point.
+The default is 0.8.
 .TP
 \f[V]--dotty\f[R]
 Use dots instead of squares for matrix symbols.
@ -230,7 +233,7 @@ and TIF).
 \f[V]--heightperrow\f[R]
 Treat height as per-row.
 Affects Codablock-F, Code16K, Code 49, GS1 DataBar Expanded Stacked
-(DBar_ExpStk), MicroPDF417 and PDF417.
+(DBAR_EXPSTK), MicroPDF417 and PDF417.
 .TP
 \f[V]-i\f[R], \f[V]--input=FILE\f[R]
 Read the input data from \f[I]FILE\f[R].
@ -293,6 +296,9 @@ can be 0, 90, 270 or 360.
 .TP
 \f[V]--rows=INTEGER\f[R]
 Set the number of rows for Codablock-F or PDF417 to \f[I]INTEGER\f[R].
+It will also set the minimum number of rows for Code 16k or Code 49, and
+the maximum number of rows for GS1 DataBar Expanded Stacked
+(DBAR_EXPSTK).
 .TP
 \f[V]--scale=NUMBER\f[R]
 Set the X-dimension.
@ -334,22 +340,27 @@ the sequence share.
 .TP
 \f[V]-t\f[R], \f[V]--types\f[R]
 Display the table of barcode types (symbologies).
+The numbers or names can be used with \f[V]-b\f[R] or
+\f[V]--barcode\f[R].
 .TP
 \f[V]--vers=INTEGER\f[R]
 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.
 .TP
 \f[V]-v\f[R], \f[V]--version\f[R]
 Display the zint version.
 .TP
 \f[V]--vwhitesp=INTEGER\f[R]
-Set the height of vertical whitespace either side of the barcode, where
+Set the height of vertical whitespace above and below the barcode, where
 \f[I]INTEGER\f[R] is in integral multiples of the X-dimension.
 .TP
 \f[V]-w\f[R], \f[V]--whitesp=INTEGER\f[R]
-Set the width of horizontal whitespace above and below the barcode,
-where \f[I]INTEGER\f[R] is in integral multiples of the X-dimension.
+Set the width of horizontal whitespace either side of the barcode, where
+\f[I]INTEGER\f[R] is in integral multiples of the X-dimension.
 .TP
 \f[V]--werror\f[R]
 Convert all warnings into errors.
@ -379,7 +390,7 @@ Please send bug reports to https://sourceforge.net/p/zint/tickets/
 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.pmd.
+https://sourceforge.net/p/zint/docs/manual.txt.
 .SH STANDARDS
 .PP
 Zint is designed to be compliant with a number of international
--- a/docs/zint.1.pmd
+++ b/docs/zint.1.pmd
@ -44,7 +44,7 @@ Paintbrush (`PCX`), Portable Network Format (`PNG`), Scalable Vector Graphic (`S

 `--binary`
 :   Treat input data as raw 8-bit binary data instead of the default UTF-8. Automatic code page translation to an ECI
-    page is disabled, and no validation of the data's encodation takes place.
+    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
@ -66,7 +66,7 @@ Paintbrush (`PCX`), Portable Network Format (`PNG`), Scalable Vector Graphic (`S

 `--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.
+    Expanded Stacked (DBAR_EXPSTK) and DotCode symbols.

 `--compliantheight`

@ -76,11 +76,11 @@ Paintbrush (`PCX`), Portable Network Format (`PNG`), Scalable Vector Graphic (`S
 `-d`, `--data=DATA`

 :   Specify the input *DATA* to encode. The `--esc` option may be used to enter non-printing characters using escape
-    sequences.
+    sequences. The *DATA* should be UTF-8, unless the `--binary` option is given, in which case it can be anything.

 `--direct`

-:   Send output to stdout, which in most cases should be re-directed via a pipe.
+:   Send output to stdout, which in most cases should be re-directed to a pipe or a file.

 `--dmre`

@ -89,7 +89,7 @@ Paintbrush (`PCX`), Portable Network Format (`PNG`), Scalable Vector Graphic (`S
 `--dotsize=NUMBER`

 :   Set the radius of the dots in dotty mode (`--dotty`). *NUMBER* is in multiples of the X-dimension, and may be
-    floating-point.
+    floating-point. The default is 0.8.

 `--dotty`

@ -173,7 +173,7 @@ Paintbrush (`PCX`), Portable Network Format (`PNG`), Scalable Vector Graphic (`S

 `--heightperrow`

-:   Treat height as per-row. Affects Codablock-F, Code16K, Code 49, GS1 DataBar Expanded Stacked (DBar_ExpStk),
+:   Treat height as per-row. Affects Codablock-F, Code16K, Code 49, GS1 DataBar Expanded Stacked (DBAR_EXPSTK),
    MicroPDF417 and PDF417.

 `-i`, `--input=FILE`
@ -236,7 +236,8 @@ Paintbrush (`PCX`), Portable Network Format (`PNG`), Scalable Vector Graphic (`S

 `--rows=INTEGER`

-:   Set the number of rows for Codablock-F or PDF417 to *INTEGER*.
+:   Set the number of rows for Codablock-F or PDF417 to *INTEGER*. It will also set the minimum number of rows for
+    Code 16k or Code 49, and the maximum number of rows for GS1 DataBar Expanded Stacked (DBAR_EXPSTK).

 `--scale=NUMBER`

@ -275,11 +276,13 @@ Paintbrush (`PCX`), Portable Network Format (`PNG`), Scalable Vector Graphic (`S

 `-t`, `--types`

-:   Display the table of barcode types (symbologies).
+:   Display the table of barcode types (symbologies). The numbers or names can be used with `-b` or `--barcode`.

 `--vers=INTEGER`

-:   Set the symbol version (size, check digits, other options) to *INTEGER*. The meaning is symbol-specific.
+:   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.

 `-v`, `--version`

@ -287,13 +290,13 @@ Paintbrush (`PCX`), Portable Network Format (`PNG`), Scalable Vector Graphic (`S

 `--vwhitesp=INTEGER`

-:   Set the height of vertical whitespace either side of the barcode, where *INTEGER* is in integral multiples of the
+:   Set the height of vertical whitespace above and below the barcode, where *INTEGER* is in integral multiples of the
    X-dimension.

 `-w`, `--whitesp=INTEGER`

-:   Set the width of horizontal whitespace above and below the barcode, where *INTEGER* is in integral multiples of
-    the X-dimension.
+:   Set the width of horizontal whitespace either side of the barcode, where *INTEGER* is in integral multiples of the
+    X-dimension.

 `--werror`

@ -320,7 +323,7 @@ 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.pmd.
+http://zint.org.uk/Manual.aspx, and at https://sourceforge.net/p/zint/docs/manual.txt.

 # STANDARDS

--- a/frontend/main.c
+++ b/frontend/main.c
@ -45,7 +45,8 @@ typedef int static_assert_int_at_least_32bits[CHAR_BIT != 8 || sizeof(int) < 4 ?

 /* Print list of supported symbologies */
 static void types(void) {
-    printf( " 1 CODE11      Code 11                  74 CODABLOCKF     Codablock-F\n"
+    printf( " # Name        Description               # Name           Description\n"
+            " 1 CODE11      Code 11                  74 CODABLOCKF     Codablock-F\n"
            " 2 C25STANDARD Standard 2 of 5          75 NVE18          NVE-18\n"
            " 3 C25INTER    Interleaved 2 of 5       76 JAPANPOST      Japanese Post\n"
            " 4 C25IATA     IATA 2 of 5              77 KOREAPOST      Korea Post\n"