Usage information doesn't match required usage

[sixtyfive]

According to kraken --help, the binary should be called like so:

kraken [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...

For options, four (version, input, verbose, help) are offered. For commands, six (binarize, get, list, ocr, segment, show) are offered.

Choosing to binarize and requesting help on how to do so, the following format is explained:

kraken binarize [OPTIONS]

This time, for options, nine (threshold, zoom, escale, border, perc, range, low, high, help) are offered.

That leads to the expectation that a command like kraken -i image.jpg binarize will generate some sort of output, presumably on stdout. Instead, the result is an error message:

Error: Missing command.

Only by looking at the example in the README can the correct version of the command be understood: kraken -i image.jpg output.png binarize.

Would it be possible to either change the usage information (for example to something like kraken [OPTIONS] OUTPUT COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...) or the way kraken works (for example so that it outputs to stdout if no output is specified)?

Edit:

The README is also wrong in naming the output file for the binarize command .tiff as it is "PNG image data, [...], 8-bit grayscale, non-interlaced" (according to file(1)) and would thus better be named .png. In the segment example, the output is JSON, so the file would be more aptly name .json (as it already is in the Quickstart section of kraken.re).

[mittagessen]

If you look at the help screen for the main command you can see the format for input definitions:

Options:
  --version                   Show the version and exit.
  -i, --input <PATH PATH>...
  -v, --verbose               [default: 0]
  -d, --device TEXT           Select device to use (cpu, cuda:0, cuda:1, ...)
                              [default: cpu]
  --help                      Show this message and exit

which is -i <PATH PATH> i.e. -i $input $output, mapping one input file to one output file. The second argument to the option is always interpreted as the output. There is no way to default to something like stdout and it wouldn't really make sense as the output of some subcommands is binary. I've added a short help text to the option to make its usage more clear.

For the PNG output that is mostly a way to keep people from shooting themselves in the foot. Not all image formats support 1bpp B/W, chiefly JPEG, and people have complained in the past that their binarized output is in fact not binary because of that. Is there a specific reason you want TIFF output? As far as I know no image processing library actually cares about extensions.

[sixtyfive]

If you look at the help screen for the main command you can see the format for input definitions: -i, --input ... which is -i <PATH PATH> i.e. -i $input $output, mapping one input file to one output file

I saw both PATH was written twice, but thought it to be a typo. In that case, would it be possible to change the wording just slightly, i.e. to something like -i <IN_PATH OUT_PATH>? I do understand that it seems clear to someone who knows, unfortunately, that's not necessarily the case for someone who doesn't, yet.

For the PNG output that is mostly a way to keep people from shooting themselves in the foot. Not all image formats support 1bpp B/W, chiefly JPEG, and people have complained in the past that their binarized output is in fact not binary because of that. Is there a specific reason you want TIFF output? As far as I know no image processing library actually cares about extensions.

Sorry, misunderstanding. I'm really happy that it's PNG. I just think the README shouldn't name the file .tif when it's not actually a TIFF file (especially since the other docs do properly name it .png). (Edit: nah, no library will ... but I was trying to inspect what I'd gotten by saying eog file.tif - which then complained "not a valid TIFF file", which led me to run file on the file, only to find out it was a PNG, which made me wonder why the README had named it .tif, which must have historical reasons I'm guessing?)

[mittagessen]

i.e. to something like -i ?

Unfortunately, that part of the help message is procedurally generated. The new help text makes it more explicit but realistically I can only hope that people read at least the Quick Start before running random commands.

I'd gotten by saying eog file.tif...

Ah so there is some software that does rely on the extension. I'll add a check and warning message only forcing to PNG when the output format is JPEG.