From 9dd697bb8d6f33cce8dd00d6e75cd5d9ada38926 Mon Sep 17 00:00:00 2001 From: H2Swine <100731704+H2Swine@users.noreply.github.com> Date: Wed, 26 Jun 2024 13:03:00 +0200 Subject: [PATCH] Improve flac executable built-in help text (#708) Co-authored-by: Martijn van Beurden --- src/flac/main.c | 116 ++++++++++++++++++++++++++---------------------- 1 file changed, 63 insertions(+), 53 deletions(-) diff --git a/src/flac/main.c b/src/flac/main.c index 81e21ff8..597e24b3 100644 --- a/src/flac/main.c +++ b/src/flac/main.c @@ -1280,50 +1280,37 @@ void show_help(void) { usage_header(); usage_summary(); - printf("general options:\n"); + printf("\n"); + printf("General options:\n"); printf(" -v, --version Show the flac version number\n"); printf(" -h, --help Show this screen\n"); printf(" -H, --explain Show detailed explanation of usage and options\n"); printf(" -d, --decode Decode (the default behavior is to encode)\n"); - printf(" -t, --test Same as -d except no decoded file is written,\n"); - printf(" with some additional checks.\n"); - printf(" -a, --analyze Same as -d except an analysis file is written\n"); + printf(" -t, --test As -d except no decoded file is written,\n"); + printf(" and with some additional checks.\n"); + printf(" -a, --analyze As -d except an analysis file is written\n"); printf(" -c, --stdout Write output to stdout\n"); - printf(" -s, --silent Do not write runtime encode/decode statistics\n"); - printf(" --totally-silent Do not print anything, including errors\n"); - printf(" --no-utf8-convert Do not convert tags from local charset to UTF-8\n"); - printf(" -w, --warnings-as-errors Treat all warnings as errors\n"); printf(" -f, --force Force overwriting of output files\n"); + printf(" --delete-input-file Deletes after a successful encode/decode\n"); printf(" -o, --output-name=FILENAME Force the output file name\n"); printf(" --output-prefix=STRING Prepend STRING to output names\n"); - printf(" --delete-input-file Deletes after a successful encode/decode\n"); - printf(" --preserve-modtime Output files keep timestamp of input (default)\n"); + printf(" --preserve-modtime (default) Output files keep timestamp of input\n"); printf(" --keep-foreign-metadata Save/restore WAVE or AIFF non-audio chunks\n"); - printf(" --keep-foreign-metadata-if-present Save/restore WAVE or AIFF non-audio\n"); - printf(" but not return an error when no such chunks are found\n"); + printf(" --keep-foreign-metadata-if-present Save/restore WAVE or AIFF non-audio\n"); + printf(" but not return an error when no such chunks are found\n"); printf(" --skip={#|mm:ss.ss} Skip the given initial samples for each input\n"); - printf(" --until={#|[+|-]mm:ss.ss} Stop at the given sample for each input file\n"); -#if FLAC__HAS_OGG - printf(" --ogg Use Ogg as transport layer\n"); - printf(" --serial-number Serial number to use for the FLAC stream\n"); -#endif - printf("analysis options:\n"); - printf(" --residual-text Include residual signal in text output\n"); - printf(" --residual-gnuplot Generate gnuplot files of residual distribution\n"); - printf("decoding options:\n"); + printf(" --until={#|[+|-]mm:ss.ss} Stop at the given sample for each input file\n"); + printf(" --no-utf8-convert Do not convert tags from local charset to UTF-8\n"); + printf(" -s, --silent Do not write runtime encode/decode statistics\n"); + printf(" --totally-silent Do not print anything, including errors\n"); + printf(" -w, --warnings-as-errors Treat all warnings as errors\n"); + printf("\n"); + printf("Decoding options:\n"); printf(" -F, --decode-through-errors Continue decoding through stream errors\n"); printf(" --cue=[#.#][-[#.#]] Set the beginning and ending cuepoints to decode\n"); - printf("encoding options:\n"); - printf(" -V, --verify Verify a correct encoding\n"); - printf(" --lax Allow encoder to generate non-Subset files\n"); - printf(" --ignore-chunk-sizes Ignore data chunk sizes in WAVE/AIFF files\n"); - printf(" --replay-gain Calculate ReplayGain & store in FLAC tags\n"); - printf(" --cuesheet=FILENAME Import cuesheet and store in CUESHEET block\n"); - printf(" --picture=SPECIFICATION Import picture and store in PICTURE block\n"); - printf(" -T, --tag=FIELD=VALUE Add a FLAC tag; may appear multiple times\n"); - printf(" --tag-from-file=FIELD=FILENAME Like --tag but gets value from file\n"); - printf(" -S, --seekpoint={#|X|#x|#s} Add seek point(s)\n"); - printf(" -P, --padding=# Write a PADDING block of length #\n"); + printf("\n"); + printf("Encoding options, defaulting to -5, -A \"tukey(5e-1)\" and one CPU thread:\n"); + printf(" -V, --verify Verify a correct encoding\n"); printf(" -0, --compression-level-0, --fast Synonymous with -l 0 -b 1152 -r 3\n"); printf(" -1, --compression-level-1 Synonymous with -l 0 -b 1152 -M -r 3\n"); printf(" -2, --compression-level-2 Synonymous with -l 0 -b 1152 -m -r 3\n"); @@ -1331,24 +1318,40 @@ void show_help(void) printf(" -4, --compression-level-4 Synonymous with -l 8 -b 4096 -M -r 4\n"); printf(" -5, --compression-level-5 Synonymous with -l 8 -b 4096 -m -r 5\n"); printf(" -6, --compression-level-6 Synonymous with -l 8 -b 4096 -m -r 6\n"); - printf(" -A subdivide_tukey(2)\n"); + printf(" -A \"subdivide_tukey(2)\"\n"); printf(" -7, --compression-level-7 Synonymous with -l 12 -b 4096 -m -r 6\n"); - printf(" -A subdivide_tukey(2)\n"); + printf(" -A \"subdivide_tukey(2)\"\n"); printf(" -8, --compression-level-8, --best Synonymous with -l 12 -b 4096 -m -r 6\n"); - printf(" -A subdivide_tukey(3)\n"); + printf(" -A \"subdivide_tukey(3)\"\n"); + printf(" -l, --max-lpc-order=# Max LPC order; 0 => only fixed predictors\n"); printf(" -b, --blocksize=# Specify blocksize in samples\n"); printf(" -m, --mid-side Try mid-side coding for each frame\n"); - printf(" -M, --adaptive-mid-side Adaptive mid-side coding for all frames\n"); - printf(" -e, --exhaustive-model-search Do exhaustive model search (expensive!)\n"); - printf(" -A, --apodization=\"function\" Window audio data with given the function\n"); - printf(" -l, --max-lpc-order=# Max LPC order; 0 => only fixed predictors\n"); - printf(" -p, --qlp-coeff-precision-search Exhaustively search LP coeff quantization\n"); - printf(" -q, --qlp-coeff-precision=# Specify precision in bits\n"); + printf(" -M, --adaptive-mid-side Adaptive choice of mid-side coding\n"); printf(" -r, --rice-partition-order=[#,]# Set [min,]max residual partition order\n"); + printf(" -A, --apodization=\"function\" Window audio data with given function(s)\n"); + printf(" -e, --exhaustive-model-search Do exhaustive model search (expensive!)\n"); + printf(" -q, --qlp-coeff-precision=# Specify quantization precision in bits\n"); + printf(" (default: let encoder decide)\n"); + printf(" -p, --qlp-coeff-precision-search Exhaustively search LP coeff quantization\n"); + printf(" --lax Allow encoder to generate non-Subset files\n"); printf(" --limit-min-bitrate Limit minimum bitrate (for streaming)\n"); printf(" -j, --threads=# Set number of encoding threads\n"); - printf("format options:\n"); - printf(" --force-raw-format Treat input or output as raw samples\n"); + printf(" --ignore-chunk-sizes Ignore data chunk sizes in WAVE/AIFF files\n"); + printf(" --replay-gain Calculate ReplayGain & store in FLAC tags\n"); + printf(" --cuesheet=FILENAME Import cuesheet & store in CUESHEET block\n"); + printf(" --picture=SPECIFICATION Import picture & store in PICTURE block\n"); + printf(" -T, --tag=FIELD=VALUE Add a FLAC tag; may appear multiple times\n"); + printf(" --tag-from-file=FIELD=FILENAME Like --tag but gets value from file\n"); + printf(" -S, --seekpoint={#|X|#x|#s} Add seek point(s)\n"); + printf(" -P, --padding=# Write a PADDING block of length # bytes\n"); + printf("\n"); + printf("Format options (encoding defaults to FLAC not OGG; decoding defaults to WAVE, \n"); + printf(" chunks found by --keep-foreign-metadata-if-present will override):\n"); +#if FLAC__HAS_OGG + printf(" --ogg Use Ogg transport layer, output .oga\n"); + printf(" --serial-number Ogg serial number to assign (encoding)\n"); + printf(" or to select for decoding\n"); +#endif printf(" --force-aiff-format Decode to AIFF format\n"); printf(" --force-rf64-format Decode to RF64 format\n"); printf(" --force-wave64-format Decode to Wave64 format\n"); @@ -1356,22 +1359,31 @@ void show_help(void) printf(" --force-extensible-wave-format Decode to extensible wave format\n"); printf(" --force-aiff-c-none-format Decode to AIFF-C NONE format\n"); printf(" --force-aiff-c-sowt-format Decode to AIFF-C sowt format\n"); - printf("raw format options:\n"); - printf(" --endian={big|little} Set byte order for samples\n"); - printf(" --channels=# Number of channels\n"); - printf(" --bps=# Number of bits per sample\n"); - printf(" --sample-rate=# Sample rate in Hz\n"); - printf(" --sign={signed|unsigned} Sign of samples\n"); - printf(" --input-size=# Size of the raw input in bytes\n"); - printf("negative options:\n"); + printf(" --force-raw-format Treat input or output as raw samples\n"); + printf("raw format options: (all options mandatory for encoding from raw input,\n"); + printf(" --sign and --endian are mandatory for decoding to raw output)\n"); + printf(" --sign={signed|unsigned} Sign of samples\n"); + printf(" --endian={big|little} Byte order for samples\n"); + printf(" --channels=# Number of channels in raw input\n"); + printf(" --bps=# Number of bits per sample in raw input\n"); + printf(" --sample-rate=# Sample rate in Hz in raw input\n"); + printf(" --input-size=# Size of the raw input in bytes\n"); + printf("\n"); + printf("Analysis options:\n"); + printf(" --residual-text Include residual signal in text output\n"); + printf(" --residual-gnuplot Generate gnuplot files of residual distribution\n"); + printf("\n"); + printf("Negative options (rightmost applied takes precedence):\n"); printf(" --no-adaptive-mid-side\n"); printf(" --no-cued-seekpoints\n"); printf(" --no-decode-through-errors\n"); printf(" --no-delete-input-file\n"); printf(" --no-error-on-compression-fail\n"); + printf(" --no-force\n"); printf(" --no-preserve-modtime\n"); printf(" --no-keep-foreign-metadata\n"); printf(" --no-exhaustive-model-search\n"); + printf(" --no-ignore-chunk-sizes\n"); printf(" --no-lax\n"); printf(" --no-mid-side\n"); #if FLAC__HAS_OGG @@ -1382,10 +1394,8 @@ void show_help(void) printf(" --no-replay-gain\n"); printf(" --no-residual-gnuplot\n"); printf(" --no-residual-text\n"); - printf(" --no-ignore-chunk-sizes\n"); printf(" --no-seektable\n"); printf(" --no-silent\n"); - printf(" --no-force\n"); printf(" --no-verify\n"); printf(" --no-warnings-as-errors\n"); }