Support different help texts for normal and advanced users and restore legacy mode

[stweil]

These series partially reverts commit 173ad2b.

[stweil]

New help texts:

$ tesseract --help
Usage:
  tesseract --help | --help-extra | --version
  tesseract --list-langs
  tesseract imagename outputbase [options...] [configfile...]

OCR options:
  -l LANG[+LANG]        Specify language(s) used for OCR.
NOTE: These options must occur before any configfile.

Single options:
  --help                Show this help message.
  --help-extra          Show extra help for advanced users.
  --version             Show version information.
  --list-langs          List available languages for tesseract engine.


$ tesseract --help-extra
Usage:
  tesseract --help | --help-extra | --help-psm | --help-oem | --version
  tesseract --list-langs [--tessdata-dir PATH]
  tesseract --print-parameters [options...] [configfile...]
  tesseract imagename|imagelist|stdin outputbase|stdout [options...] [configfile...]

OCR options:
  --tessdata-dir PATH   Specify the location of tessdata path.
  --user-words PATH     Specify the location of user words file.
  --user-patterns PATH  Specify the location of user patterns file.
  -l LANG[+LANG]        Specify language(s) used for OCR.
  -c VAR=VALUE          Set value for config variables.
                        Multiple -c arguments are allowed.
  --psm NUM             Specify page segmentation mode.
  --oem NUM             Specify OCR Engine mode.
NOTE: These options must occur before any configfile.

Page segmentation modes:
  0    Orientation and script detection (OSD) only.
  1    Automatic page segmentation with OSD.
  2    Automatic page segmentation, but no OSD, or OCR.
  3    Fully automatic page segmentation, but no OSD. (Default)
  4    Assume a single column of text of variable sizes.
  5    Assume a single uniform block of vertically aligned text.
  6    Assume a single uniform block of text.
  7    Treat the image as a single text line.
  8    Treat the image as a single word.
  9    Treat the image as a single word in a circle.
 10    Treat the image as a single character.
 11    Sparse text. Find as much text as possible in no particular order.
 12    Sparse text with OSD.
 13    Raw line. Treat the image as a single text line,
       bypassing hacks that are Tesseract-specific.

OCR Engine modes:
  0    Legacy Tesseract only.
  1    Neural nets LSTM only.
  2    Legacy + LSTM Tesseract.
  3    Default, based on what is available.

Single options:
  -h, --help            Show minimal help message.
  --help-extra          Show extra help for advanced users.
  --help-psm            Show page segmentation modes.
  --help-oem            Show OCR Engine modes.
  -v, --version         Show version information.
  --list-langs          List available languages for tesseract engine.
  --print-parameters    Print tesseract parameters.

[zdenop]

My notes:

1. user still can easily run legacy engine that will cause a crash
2. legacy engine is not supported anymore and this is not indicated by help => users will continue open issues...

[stweil]

1. When I run the legacy engine, I don't get a crash. Which crash scenario are you referring to? You could add a tag "legacy" to issues related to the legacy engine.

2. Doesn't "legacy" already say that it is old? And I don't think that it is completely unsupported. As I already said, I'll try to fix issues which are reported. It should be easy to add some help text which clarifies the situation. What about this text:

   ...
   OCR Engine modes:
   0 Legacy Tesseract only.
   1 Neural nets LSTM only.
   2 Legacy + LSTM Tesseract.
   3 Default, based on what is available.

   Please note that the legacy engine is no longer supported by Google!
   ...

[stweil]

See issue #707 and also #1074 (comment) on the role of the legacy engine.

[Shreeshrii]

@stweil The crash scenario is because traineddata from tessdata_fast do not have legacy models in them (at least for some languages). For some languages such as Hindi, sanskrit etc it is intentional, as the accuracy is very much improved with LSTM engine and model. However, for other Latin script based languages, 'tesseract' may provide better results (as you have mentioned). I will test and post some specific crash scenarios for you. I am sure the crash can be avoided by checking for available models in the traineddata files. I will also add link to issues where I have commented about the same.

[amitdo]

0 Legacy Tesseract only.

2 Legacy + LSTM Tesseract.

Tesseract is (also) the name of the legacy engine.

What about:

OCR Engine modes:
0 Legacy engine only
1 Neural nets LSTM engine only
2 Legacy + LSTM engines
3 Default, based on what is available

?

[stweil]

Fine for me. Adding "engine" in the descriptions looks indeed better. Do you want to send a pull request, or should I prepare one?

[amitdo]

You.

[amitdo]

I think the periods are unnecessary.

[stweil]

PrintHelpForPSM also has periods, and so do the other help texts. I'd keep them for now, but yes, it would also be possible to have a good help text without those periods.

[Shreeshrii]

The crash scenario is because traineddata from tessdata_fast do not have
legacy models in them (at least for some languages).

@stweil

I checked and my earlier comment seems not to be correct. It is NOT a crash/assert. I will open a new issue with what I noticed.

edit: Added issue #1327

[amitdo]

'extra' => 'advanced'