info > ptx(1)

man perldoc info pydoc3 ri search

📛 NAME

ptx reads a text file and essentially produces a permuted index, with each keyword in its context. The calling sketch is either one of:

ptx [OPTION ...] [FILE ...]
ptx -G [OPTION ...] [INPUT [OUTPUT]]

The -G (or --traditional) option disables all GNU extensions and reverts to traditional mode, introducing some limitations and changing default option values.

🚀 Quick Reference

Use Case	Command	Description
🧩 Generate a permuted index (GNU)	ptx file.txt	Reads file.txt and outputs permuted index to stdout
🔄 Use traditional System V mode	ptx -G input.txt output.txt	Disables GNU extensions; output written to file (destroys existing content)
📄 Process multiple input files	ptx file1.txt file2.txt	Concatenates files with contextual breaks
🔤 Ignore case for keyword sorting	ptx -f file.txt	Fold lower case letters to upper case for sorting
📝 Define break characters from file	ptx -b breakfile file.txt	Characters in breakfile are NOT part of words
🚫 Specify ignore file (words never keywords)	ptx -i ignorefile file.txt	Words in ignorefile are excluded from concordance
✅ Specify only file (only listed words)	ptx -o onlyfile file.txt	Only words in onlyfile are retained as keywords
🔖 Use reference fields from input lines	ptx -r file.txt	Leading non-whitespace sequence treated as line reference
📏 Set output line width	ptx -w 80 file.txt	Set maximum output width to 80 characters
📄 Output in roff format	ptx -O file.txt	Generate output suitable for nroff/troff
📄 Output in TeX format	ptx -T file.txt	Generate output suitable for TeX processing

📋 Menu

• General options in ptx – Options which affect general program behavior.
• Charset selection in ptx – Underlying character set considerations.
• Input processing in ptx – Input fields, contexts, and keyword selection.
• Output formatting in ptx – Types of output format, and sizing the fields.
• Compatibility in ptx

⚙️ General options

-G / --traditional 🚫 Disables all GNU extensions to ptx and switches to traditional mode. --help ❓ Print a short help on standard output, then exit without further processing. --version ℹ️ Print the program version on standard output, then exit without further processing.

✅ An exit status of zero indicates success, and a nonzero value indicates failure.

🔤 Charset selection

Currently, the program assumes the input file is coded using 8-bit ISO 8859-1 (Latin-1) unless compiled for MS-DOS (IBM-PC charset). This affects regular expression matching – the default keyword regex allows foreign/diacriticized letters. Keyword sorting obeys the underlying character set ordering.

-f / --ignore-case 🔠 Fold lower case letters to upper case for sorting.

📝 Word selection and input processing

-b FILE / --break-file=FILE 🔧 Alternative to -W for describing word constituents. FILE contains characters that cannot be part of a word (Break file). If both -b and -W are specified, -W takes precedence. When GNU extensions are enabled, newline is a break character unless omitted from the file entirely. When disabled, spaces, tabs and newlines are always break characters. -i FILE / --ignore-file=FILE 🚫 FILE contains words never taken as keywords (Ignore file). One word per line; line separation not affected by -S. -o FILE / --only-file=FILE ✅ FILE contains words retained in concordance output (Only file). Any word not in this file is ignored. One word per line. When both Only and Ignore files are specified, a word is a keyword only if listed in the Only file and not in the Ignore file. -r / --references 🔖 On each input line, the leading non-whitespace sequence is taken as a reference identifying the line. Changes default for -S. References are excluded from contexts when the context ends exactly at the newline (always true with -r and default -S or when GNU extensions disabled). -S REGEXP / --sentence-regexp=REGEXP 🔬 Selects the regular expression describing end-of-line or end-of-sentence. Default (GNU enabled, no -r): end-of-sentence regex from GNU Emacs: [.?!][\]"')}]*\\($\\|\t\\| \\)[ \t\n]*. When GNU disabled or -r used: end-of-line regex \n. Empty REGEXP disables recognition entirely (whole file is one line/sentence). Many C backslash escape sequences are recognized. -W REGEXP / --word-regexp=REGEXP 🔤 Selects regex describing each keyword. Default (GNU enabled): \w+ (sequence of letters). Default (GNU disabled): [^ \t\n]+ (anything ending with space/tab/newline). Empty REGEXP equivalent to not using this option. C backslash escape sequences are recognized.

📄 Output formatting

Output format is mainly controlled by -O and -T. When neither selected and GNU extensions enabled, output is suitable for a dumb terminal: each keyword centered, surrounded by left/right contexts, properly justified. If automatic references (-A) are output before left context (no -R), a colon is added after the reference (works with Emacs next-error). White space becomes one space; other characters transmitted verbatim.

-g NUMBER / --gap-size=NUMBER 📏 Minimum white space gap between output fields. -w NUMBER / --width=NUMBER 📐 Maximum output width per line. If references are used, they are included/excluded depending on -R. Without -R, max width considers max reference length. With -R, references and preceding gap are not counted. -A / --auto-reference 🏷️ Automatic references: each input line gets a reference of filename:line (empty filename for stdin). If both -A and -r are selected, the input reference is skipped and the automatic reference is used. -R / --right-side-refs 🔀 By default, references are placed to the far right. With -R, references are placed before the left context. Ignored for other output formats, except that with -R the width of references is not taken into account in total output width. Automatically selected when GNU extensions are disabled. -F STRING / --flag-truncation=STRING 🚩 Report truncation using STRING. Default: -F /. Empty STRING (-F "") disables truncation marking. C backslash escape sequences are recognized. -M STRING / --macro-name=STRING 🏷️ Use STRING instead of xx in roff/TeX output formats. -O / --format=roff 📰 Output suitable for nroff/troff. Each line: .xx "TAIL" "BEFORE" "KEYWORD_AND_AFTER" "HEAD" "REF". Default when GNU extensions disabled. Non-graphical characters become one space; quotes doubled. -T / --format=tex 📐 Output suitable for TeX. Each line: \xx {TAIL}{BEFORE}{KEYWORD}{AFTER}{HEAD}{REF}. Special characters ($, %, &, #, _) are backslash-protected; curly braces with dollar signs; backslash becomes \backslash{}; diacritics produce appropriate TeX sequences. Non-graphical characters become one space.

🔄 The GNU extensions to 'ptx'

This version of ptx contains features not in System V ptx, suppressed by -G unless overridden. Some extensions cannot be recovered by overriding, so avoid -G if you care about GNU extensions. Differences:

• 📁 This program can read many input files at once and always writes to stdout. System V ptx reads only one file; with a second FILE parameter, output is written to that FILE (dangerous). For portability, use a single input file and expect stdout.
• 🏷️ System V options: -b, -f, -g, -i, -o, -r, -t, -w. All other options are GNU extensions.
• 📄 By default, concordance output is formatted for a dumb terminal, not troff/nroff. Use -O for roff output.
• 📏 Unless -R is used, maximum reference width is subtracted from total output line width. With GNU extensions disabled, reference width is not considered.
• 🔢 All 256 bytes (including NUL) are read and processed. System V ptx rejects 8-bit characters, some control characters, and tilde ~.
• 📏 Input line length is limited only by memory. System V ptx processes only the first 200 characters per line.
• 🔤 Break (non-word) characters default to every character except letters (including diacritics). When GNU extensions disabled, break characters default to space, tab, and newline only.
• 📐 Better use of output line width. When GNU extensions disabled, program tries to imitate System V but with slight disposition glitches.
• 📋 Both an Ignore file and an Only file can be specified (not allowed in System V).

📛 NAME 🚀 Quick Reference 📋 Menu ⚙️ General options 🔤 Charset selection 📝 Word selection and input processing 📄 Output formatting 🔄 The GNU extensions to 'ptx'