# ptx

_Peios / Using Peios / Peiosutils / Transforming text_

> Produce a permuted index of the words in a file.

`ptx` produces a **permuted index** — a concordance. For each significant word in the input, it prints a line showing that word together with the text around it, so the same passage appears once per keyword it contains.

```
ptx [options] [input...]
```

```
$ ptx manual.txt
```

A permuted index is the kind of index found at the back of a reference book: every keyword, in alphabetical order, each shown in its context. `ptx` builds one from plain text. With no file, it reads standard input.

## Choosing the keywords

| Option | Effect |
|---|---|
| `-W`, `--word-regexp=REGEXP` | Treat anything matching `REGEXP` as a keyword. |
| `-b`, `--break-file=FILE` | Take the set of word-break characters from `FILE`. |
| `-i`, `--ignore-file=FILE` | Read a list of words to *exclude* from `FILE`. |
| `-o`, `--only-file=FILE` | Index *only* the words listed in `FILE`. |
| `-f`, `--ignore-case` | Fold case together when sorting. |

## Output format

| Option | Effect |
|---|---|
| `-w`, `--width=N` | Set the output width, in columns. |
| `-g`, `--gap-size=N` | Set the gap, in columns, between the output fields. |
| `-A`, `--auto-reference` | Generate a reference (file name and line number) for each entry automatically. |
| `-r`, `--references` | Treat the first field of each input line as a reference for that line. |
| `-R`, `--right-side-refs` | Put references on the right, and exclude them from the width count. |
| `-F`, `--flag-truncation=STRING` | Use `STRING` to mark where a line was truncated. |
| `-O`, `--format=roff` | Emit the index as `roff` typesetting directives. |
| `-T`, `--format=tex` | Emit the index as TeX typesetting directives. |
| `-M`, `--macro-name=NAME` | Use `NAME` as the macro name in `roff`/TeX output. |
| `-G`, `--traditional` | Behave like the older System V `ptx`, without the extended features. |

## Exit status

| Code | Meaning |
|---|---|
| `0` | Success. |
| `1` | A file could not be read, or an option value was invalid. |

Related content:

- [Transforming text](/peios/using-peios/peiosutils/transforming-text/overview.md)