Skip to Content
gnux

ptxx

Produce a permuted index of the words in a text.

Mirrors GNU ptx. Run it as ptxx, or as gnux ptxx.

Synopsis

ptxx [OPTION]... [INPUT]...   (without -G)
ptxx -G [OPTION]... [INPUT [OUTPUT]]

GNU reference

Description

ptxx lists every word of the INPUTs (standard input when there are none, or for -) in alphabetical order, each in the middle of a line with the text before it on the left and the text after it on the right: a keyword-in-context index. A word is a run of letters, or what -W's regular expression matches, or what is between -b's break characters; a context ends at the end of a sentence, or where -S says. -i leaves out the words of a file, one per line, and -o keeps only those. -A prefixes each line with FILE:LINE, and -r takes the first word of each input line as its reference; -R puts references on the right. -w sets the width (72), -g the gap between fields (3), -F the mark of a cut context ('/'). -O and -T write roff or TeX macro calls instead (-M names the macro), and -G behaves like System V ptx, with words between blanks, contexts that are lines, roff output, and an optional OUTPUT file. Regular expressions use the Emacs syntax GNU ptx uses, ( ) | for groups and alternatives, and \1 to \9 for back references.

Permissions

Needs read permission on each INPUT and on the -b, -i and -o files; with -G, write permission to create OUTPUT.

Use cases

  • Building a keyword-in-context index for a book or a manual.
  • Seeing every place a word is used in a set of notes, in context.
  • Producing an index for typesetting with roff or TeX.

Flags

  -A, --auto-reference           output automatically generated references
  -b, --break-file FILE          word break characters in this FILE
  -F, --flag-truncation STRING   use STRING for flagging line truncations. The default is '/'
      --format FORMAT            generate output as roff or TeX directives: FORMAT is roff or tex
  -g, --gap-size string          gap size in columns between output fields
      --help                     display this help and exit
  -f, --ignore-case              fold lower case to upper case for sorting
  -i, --ignore-file FILE         read ignore word list from FILE
  -M, --macro-name string        macro name to use instead of 'xx'
  -o, --only-file FILE           read only word list from this FILE
  -r, --references               first field of each line is a reference
  -R, --right-side-refs          put references at right, not counted in -w
  -O, --roff                     generate output as roff directives (--format=roff)
  -S, --sentence-regexp string   for end of lines or end of sentences
  -T, --tex                      generate output as TeX directives (--format=tex)
  -G, --traditional              behave more like System V 'ptx'
  -t, --typeset-mode             - not implemented -
      --version                  output version information and exit
  -w, --width string             output width in columns, reference excluded
  -W, --word-regexp REGEXP       use REGEXP to match each keyword

Examples

See every word of a text in context

ptxx notes.txt

Index a manual, skipping common words, with file and line references

ptxx -A -i stopwords.txt chapter*.txt

Index only the words that matter

ptxx -o terms.txt manual.txt

Produce TeX macro calls for typesetting

ptxx -T -M index book.txt > index.tex

Treat each line as its own context, ignoring case when sorting

ptxx -f -S '\n' titles.txt

Options

Each option has a page of its own, with its usage and examples.

Exit status

StatusMeaning
0success: every operand was processed
1failure: an operand could not be processed (diagnosed on standard error), or a command-line mistake

Help in the terminal

ptxx --help                # options, first examples, exit status
gnux help ptxx             # this page: the full manual
gnux help ptxx --OPTION    # one option in depth, with its examples

See also

On this page