# Command-Line Usage: `sphobjinv-textconv`

`sphobjinv-textconv` is intentionally implemented with very narrow functionality, focused on simplifying use of sphobjinv as a Git “textconv”, which is a mechanism for rendering binary files in a diff-able text format. There are many examples of clever application of textconv in the wild.

Ultimately, a textconv requires three things:

1. A utility that takes in a file path as a single positional argument and emits a plaintext representation to stdout, such as sphobjinv-textconv.

2. An entry somewhere in Git config (system, user-global, per-repo, etc.) declaring a “diff driver” set up to use that utility as its textconv. Example:

       [diff "objects_inv"]
               textconv = sphobjinv-textconv

   Note that the utility must be on path in all contexts where you wish to use it as a textconv.

3. An entry somewhere in .gitattributes (system, user-global, per-repo, etc.) that associates a particular file or glob pattern with the diff driver. Example:

       *.inv diff=objects_inv

With sphobjinv-textconv configured in this fashion as a textconv for Sphinx inventory files, the following should all yield nearly the same output.

Using `sphobjinv convert`:

    $ sphobjinv convert plain objects_pdfminer.inv -

    # Sphinx inventory version 2
    # Project: pdfminer-docs
    # Version: 0
    # The remainder of this file is compressed using zlib.
    genindex std:label -1 genindex.html Index
    index std:doc -1 index.html pdfminer docs
    modindex std:label -1 py-modindex.html Module Index
    pdfminer_index std:doc -1 pdfminer_index.html PDFMiner
    programming std:doc -1 programming.html Programming with PDFMiner
    search std:label -1 search.html Search Page

Using `sphobjinv-textconv` (note the absence of blank lines between the shell invocation and the inventory contents):

    $ sphobjinv-textconv objects_pdfminer.inv
    # Sphinx inventory version 2
    # Project: pdfminer-docs
    # Version: 0
    # The remainder of this file is compressed using zlib.
    genindex std:label -1 genindex.html Index
    index std:doc -1 index.html pdfminer docs
    modindex std:label -1 py-modindex.html Module Index
    pdfminer_index std:doc -1 pdfminer_index.html PDFMiner
    programming std:doc -1 programming.html Programming with PDFMiner
    search std:label -1 search.html Search Page

Using `git show --textconv` (with the textconv set on-the-fly so that it will render correctly in ReadTheDocs builds):

System Message: ERROR/6 (/build/python-sphobjinv-ZwwGyp/python-sphobjinv-2.4/doc/source/cli/textconv.rst, line 57)

Command ['git', '-c', 'diff.objects_inv.textconv=sphobjinv-textconv', 'show', '--textconv', 'HEAD:tests/resource/objects_pdfminer.inv'] failed: [Errno 2] No such file or directory: 'git'

Usage

    $ sphobjinv-textconv --help
    usage: sphobjinv-textconv [-h] [-v] infile

    Emit the plaintext of the local Sphinx inventory at 'infile' to stdout.

    ...

Positional Arguments

infile

  Path to file to be emitted to stdout in plaintext.

Flags

-h, --help

  Display help message and exit.

-v, --version

  Display brief package version information and exit.

Added in version 2.4.