CLI: tidy

[casperdcl]

• tidy --help to match argparse style (follow-up to #46 <- fixes #43)
• ~~add --print-completion using shtab~~

/CC @gagb

[casperdcl]

@microsoft-github-policy-service agree

[afourney]

Looks interesting. Can you say more about shtab? What shell are you using that isn't already doing tab completion?

[casperdcl]

Ah @afourney your question(s) imply a fundamental misunderstanding. Clearly some docs are missing here. Unsure about how much detail you'd prefer to see in the GitHub flavoured markdown README, though.

For example/comparison, DVC details its end-user completion usage in separate per-OS/shell tabs at https://dvc.org/doc/install/completion

[gagb]

With this PR:

main:

@casperdcl thank you for the PR. This is what I see. I am not sure if the --print-completion is helpful? I am open to simplifying the help instructions but not sure if adding another dependency is a good idea -- the syntax is already simple and helps keep the package lightweight? cc @afourney @jackgerrits

[casperdcl]

ok rebased & removed shtab now

[casperdcl]

@gagb if I rebase this will you merge?

[gagb]

Sure. Can you share new (post rebase) before and after screenshots?

[casperdcl]

New:

usage: markitdown [-h] [-v] [-o OUTFILENAME] [-d] [-e ENDPOINT] [-p] [--list-plugins] [FILENAME]

Convert various file formats to markdown.

positional arguments:
  FILENAME              if unspecified, defaults to stdin

options:
  -h, --help            show this help message and exit
  -v, --version         show the version number and exit
  -o OUTFILENAME, --output OUTFILENAME
                        if unspecified, defaults to stdout
  -d, --use-docintel    use online Document Intelligence to extract text (requires a valid `--endpoint`)
  -e ENDPOINT, --endpoint ENDPOINT
                        required for `--use-docintel`
  -p, --use-plugins     use 3rd-party plugins to convert files (see `--list-plugins`)
  --list-plugins        list installed 3rd-party plugins (loaded with `--use-plugin`)

examples:
  markitdown example.pdf
  markitdown -o example.md example.pdf
  cat example.pdf | markitdown > example.md

Old:

usage: SYNTAX:

    markitdown <OPTIONAL: FILENAME>
    If FILENAME is empty, markitdown reads from stdin.

EXAMPLE:

    markitdown example.pdf

    OR

    cat example.pdf | markitdown

    OR

    markitdown < example.pdf

    OR to save to a file use

    markitdown example.pdf -o example.md

    OR

    markitdown example.pdf > example.md

Convert various file formats to markdown.

positional arguments:
  filename

options:
  -h, --help            show this help message and exit
  -v, --version         show the version number and exit
  -o OUTPUT, --output OUTPUT
                        Output file name. If not provided, output is written to stdout.
  -d, --use-docintel    Use Document Intelligence to extract text instead of offline conversion. Requires a valid Document Intelligence Endpoint.
  -e ENDPOINT, --endpoint ENDPOINT
                        Document Intelligence Endpoint. Required if using Document Intelligence.
  -p, --use-plugins     Use 3rd-party plugins to convert files. Use --list-plugins to see installed plugins.
  --list-plugins        List installed 3rd-party plugins. Plugins are loaded when using the -p or --use-plugin option.