diff-numerics.1

.TH diff-numerics 1 "June 2025" "diff-numerics"
.SH NAME
diff-numerics \- compare numerical data files with tolerance
.SH SYNOPSIS
.B diff-numerics
[options] file1 file2
.SH DESCRIPTION
A command-line tool for comparing numerical data files with configurable tolerance, threshold, and output formatting. Designed for scientific and engineering workflows where small floating-point differences are expected.

The program returns 0 if the files are equal within tolerance, a positive integer equal to the number of differing lines if files differ, and -1 if an error occurred (such as file not found or invalid arguments). This makes it suitable for use in scripts and automated pipelines.

.SH OPTIONS
.TP
.B -y, --side-by-side
Print lines side by side.
.TP
.B -ys, --suppress-common-lines
Suppress lines within tolerance in side-by-side mode (implies -y).
.TP
.B -t, --tolerance <value>
Tolerance for percentage difference (default: 1E-2).
.TP
.B -T, --threshold <value>
Ignore if both values are under threshold (default: 1E-6).
.TP
.B -c, --comment-string <str>
String to start a comment (default: #).
.TP
.B -w, --single-column-width <n>
Set column width for side-by-side output (default: 60).
.TP
.B -s, --report-identical-files
Print only if files are equal within tolerance, otherwise print summary.
.TP
.B -q, --quiet
Suppress all output if files are equal within tolerance.
.TP
.B -C, --columns <list>
Comma-separated list of 1-based column indices to compare (e.g., 1,2,4).
.TP
.B -d, --color-diff-digits
Highlight only differing digits in output using ANSI colors.
.TP
.B -v, --version
Show program version and exit.
.TP
.B -h, --help
Show help message and exit.

.SH RETURN VALUE
Returns 0 if files are equal within tolerance.
Returns a positive integer equal to the number of differing lines if files differ.
Returns -1 if an error occurred (e.g., file not found or invalid arguments).

.SH EXAMPLES
.TP
Compare two files with default settings:
.B diff-numerics file1.dat file2.dat
.TP
Side-by-side comparison with custom tolerance:
.B diff-numerics -y -t 0.01 file1.dat file2.dat
.TP
Compare only columns 1, 2, and 4:
.B diff-numerics -C 1,2,4 file1.dat file2.dat
.TP
Highlight differing digits in color:
.B diff-numerics -d file1.dat file2.dat
.TP
Show only lines that are equal within tolerance:
.B diff-numerics --only-equal file1.dat file2.dat

.SH AUTHOR
Written by Alessandro Grassi (2025).

.SH LICENSE
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.