manual/gnumaniak/original/man1/ptx.1

   1 .\" You may copy, distribute and modify under the terms of the LDP General
   2 .\" Public License as specified in the LICENSE file that comes with the
   3 .\" gnumaniak distribution
   4 .\"
   5 .\" The author kindly requests that no comments regarding the "better"
   6 .\" suitability or up-to-date notices of any info documentation alternative
   7 .\" is added without contacting him first.
   8 .\"
   9 .\" (C) 2002 Ragnar Hojland Espinosa <ragnar@ragnar-hojland.com>
  10 .\"
  11 .\"     GNU ptx man page
  12 .\"     man pages are NOT obsolete!
  13 .\"     <ragnar@ragnar-hojland.com>
  14 .TH PTX 1 "7 October 2002" "GNU textutils 2.1"
  15 .SH NAME
  16 \fBptx\fR \- produce permuted indexes
  17 .SH SYNOPSIS
  18 .B ptx
  19 .RI [ OPTION... "] [" FILE... ]
  20
  21 .B ptx
  22 .RB [ \-G ]
  23 .RB [ \-\-traditional ]
  24 .RI [ OPTION... "] [" IN\-FILE " [" OUT\-FILE ]]
  25 .SS Options:
  26 .RB [ \-frAORT ]
  27 .RB [ "\-b \fIFILE" ]
  28 .RB [ "\-g \fINUMBER" ]
  29 .RB [ "\-i \fIFILE" ]
  30 .RB [ "\-o \fIFILE" ]
  31 .RB [ "\-w \fINUMBER" ]
  32 .RB [ "\-F \fISTRING" ]
  33 .RB [ "\-M \fISTRING" ]
  34 .RB [ "\-S \fIREGEXP" ]
  35 .RB [ "\-W \fIREGEXP" ]
  36 .RB [ \-\-auto\-reference ]
  37 .RB [ \-\-break\-file=\fIFILE ]
  38 .RB [ \-\-flac\-truncation=\fISTRING ]
  39 .RB [ \-\-format=\fR{\fBnroff,tex }]
  40 .RB [ \-\-gap\-size=\fINUMBER ]
  41 .RB [ \-\-ignore\-case ]
  42 .RB [ \-\-ignore\-file=\fIFILE ]
  43 .RB [ \-\-macro\-name=\fISTRING ]
  44 .RB [ \-\-only\-file=\fIFILE ]
  45 .RB [ \-\-references ]
  46 .RB [ \-\-right\-side\-refs ]
  47 .RB [ \-\-sentence\-regexp=\fIREGEXP ]
  48 .RB [ \-\-word\-regexp=\fIREGEXP ]
  49 .RI [ FILE... ]
  50
  51 .BR ptx " [" \-C "] [" \-\-copyright "]  [" \-\-help "] [" \-\-version ]
  52 .SH DESCRIPTION
  53 .B ptx
  54 with GNU extensions (by default) writes to standard output a
  55 permutated index for each
  56 .I FILE
  57 given.
  58 If
  59 .I FILE
  60 is omitted or if is a
  61 .RB ` \- ',
  62 standard input is used.  Even if the result is concatenated together, each
  63 .I FILE
  64 has it's own context and is referrenced separately when using automatic
  65 references.
  66
  67 If \fB\-\-traditional\fR mode is used, \fBptx\fR reads \fIIN\-FILE\fR for
  68 input and writes to \fIOUT\-FILE\fR, or standard output if omitted.
  69
  70 The default output format is the keyword in the center of the line and the
  71 context of the keyword to the left and right if any, or
  72 \fB\-\-format\-nroff\fR in \fB\-\-traditional\fR mode.
  73 .SH OPTIONS
  74 .TP
  75 .B \-b \fIFILE\fB, \-\-break\-file=\fIFILE
  76 Obtain characters that can't be part of a word from \fIFILE\fR, also known
  77 as the \fBbreak file\fR.  In default
  78 mode any character in \fIFILE\fR is considered, including newlines.  In
  79 traditional mode spaces, tabs and newlines  are always discarded from
  80 \fIFILE\fR.
  81 .TP
  82 .B \-f, \-\-ignore\-case
  83 Ignores case when sorting strings.
  84 .TP
  85 .B \-g \fINUMBER\fB, \-\-gap\-size=\fINUMBER
  86 Set the minimum spacing between the fields to \fINUMBER\fR (default is 3).
  87 .TP
  88 .B \-i \fIFILE\fB, \-\-ignore\-file=\fIFILE
  89 Obtain a list of keywords that are to be ignored from \fIFILE\fR, also known
  90 as the \fBignore file\fR  (default is /usr/local/lib/eign)  Each line should
  91 only contain one word.  Words in the \fBignore file\fR override the ones in the
  92 \fBonly file\fR.
  93 .TP
  94 .B \-o \fIFILE\fB, \-\-only\-file=\fIFILE
  95 Obtain a list of keywords from\fIFILE\fR, also known as the \fBonly file\fR,
  96 and when generating the index ignore any keyword which isn't present in the
  97 list.  Each line should only contain one word.
  98 .TP
  99 .B \-r, \-\-references
 100 Precede each line with a string that will identify the context. \fBptx\fR
 101 will attempt to remove the references from context, and will always
 102 succeed when the context ends at the newline.  If it is used with \fB\-S\fR
 103 (and it's default), or when using \fB\-\-traditional\fR mode, references are
 104 always removed from context.
 105 .TP
 106 .B \-w \fINUMBER\fB, \-\-width=\fINUMBER
 107 Truncate output lines which exceed \fINUMBER\fR width.  Note that the length
 108 of \fB\-\-right\-side\-refs\fR isn't taken into account, and width may be
 109 exceeded if they are used.
 110 .TP
 111 .B \-A, \-\-auto\-reference
 112 Precede each line with the filename (or empty when reading from standard
 113 input), the line number, and a colon.  Overrides \fB\-\-references\fR.
 114 .TP
 115 .B \-F \fISTRING\fB, \-\-flac\-truncation=\fISTRING
 116 Output \fISTRING\fR (default is `\fB\e\fR') when truncating a line by
 117 effect of \fR\-\-width\fR or because it extends towards the beginning of the
 118 line.
 119
 120 Many usual backslashed escape sequences, as found in C programs, are
 121 recognized and converted to the corresponding characters by \fBptx\fR when
 122 specifying the \fISTRING\fR.
 123 .TP
 124 .B \-M \fISTRING\fB, \-\-macro\-name=\fISTRING
 125 Use \fISTRING\fR as the macro name when outputing in nroff or TeX format
 126 (default is `\fB.xx\fR')
 127 .TP
 128 .B \-O, \-\-format=nroff
 129 Output in nroff format, in the format.  Non printable characters are
 130 converted to spaces, and quote characters are doubled so they can ben
 131 correctly processed.  The format of each line is:
 132 .sp
 133 .nf
 134  .xx "TAIL" "BEFORE" "KEYWORD_AND_AFTER" "HEAD" "REF"
 135 .fi
 136 .TP
 137 .B \-R, \-\-right\-side\-refs
 138 Like \fB\-\-references\fR, but print output references to the right.
 139 .TP
 140 .B \-S \fIREGEXP\fB, \-\-sentence\-regexp=\fIREGEXP
 141 Use \fIREGEXP\fR to describe the end of a line or sentence.  In GNU mode
 142 when \fB\-\-references\fR are not used, the default is
 143 .sp
 144 .RS
 145 .RS
 146 .nf
 147 [.?!][]\e"')}]*\e\e($\e\e|\et\e\e|  \e\e)[ \et\en]*
 148 .fi
 149 .RE
 150 .sp
 151 In \fB\-\-traditional\fR mode, or in GNU mode when \fB\-\-references\fR are
 152 used the default is
 153 .sp
 154 .RS
 155 .nf
 156 \en
 157 .fi
 158 .RE
 159 .sp
 160 As with \fB\-\-F\fR, backslashed sequences are recognized and converted.
 161 .RE
 162 .TP
 163 .B \-T, \-\-format=tex
 164 Output in TeX format.  Non printable characters are converted to spaces,
 165 some special characters (such as `$', `%', `&', `#' and `_') are protected
 166 with a backslash,  backslashes are convert to `\ebackslash{}', circumflex
 167 to `^\e{ }', tildes to `~\e{ }', and other diacritics to the most possible
 168 appropiate TeX sequence.  The format of each line is:
 169 .sp
 170 .RS
 171 .RS
 172 .nf
 173 \exx {TAIL}{BEFORE}{KEYWORD}{AFTER}{HEAD}{REF}
 174 .fi
 175 .RE
 176 .RE
 177 .TP
 178 .B \-W \fIREGEXP\fB, \-\-word\-regexp=\fIREGEXP
 179 Use \fIREGEXP\fR to describe a keyword, overriding \fB\-\-break\-file\fR if
 180 it has been also specified.  In GNU mode the default is
 181 .sp
 182 .RS
 183 .RS
 184 .nf
 185 .B \ew+
 186 .fi
 187 .RE
 188 .sp
 189 and in \fB\-\-traditional\fR mode it is
 190 .sp
 191 .nf
 192 .RS
 193 .B [^ \et\en]+
 194 .fi
 195 .RE
 196 .sp
 197 An empty \fIREGEXP\fR is the equivalent of using the default.  As with
 198 \fB\-\-F\fR, backslashed sequences are recognized and converted.
 199 .RE
 200 .TP
 201 .B "\-C, \-\-copyright"
 202 Print a brief copyright message on standard output and exit successfully.
 203 .TP
 204 .B "\-\-help"
 205 Print a usage message on standard output and exit successfully.
 206 .TP
 207 .B "\-\-version"
 208 Print version information on standard output then exit successfully.
 209 .SH EXAMPLES
 210 No complete examples are given here because output tends to be rather
 211 bulky.
 212 .SS Plain text
 213
 214 Francois Pinard, author of \fBptx\fR, run through it an email I had sent him
 215 and this is what he says (*** denotes manual truncation to fit into the man
 216 page)
 217 .sp
 218 .nf
 219 >>    /I've had a look at the source,   and I still   ***
 220 >>    /or what is a permutated index,   and what it   ***
 221
 222 > ptx merely produces a sorted list of the vocabulary you
 223 > used, with some context for each, so I can study your
 224 > writing style, for example.  Whenever you use the word
 225 > "and", it is preceded by a comma :-).
 226 .fi
 227 .SS Bang Paths
 228 We have a collection of news posts or email messages, and grep the bang
 229 paths from them.  For example with
 230 .sp
 231 .RS
 232 .nf
 233 lightside~% grep posts "^Path: " |cut -b 7- > paths.txt
 234 .fi
 235 .RE
 236 .sp
 237 and ending up with paths.txt containing:
 238 .sp
 239 .RS
 240 .nf
 241 lightside!host2!host3!host4!host5!news
 242 lightside!host2!host3!host4!host6!news
 243 lightside!host7!host8!host9|host10|host4|host5!news
 244 lightside!host4!host5!news
 245 lightside!host11!news
 246 .fi
 247 .RE
 248 .sp
 249 Now we run \fBptx\fR on it, properly escaping the regexps
 250 .sp
 251 .RS
 252 .nf
 253 lightside~% ptx \-\-sentence\-regexp="\en" \e
 254                 \-\-word\-regexp"[^\e!]+."
 255 .fi
 256 .RE
 257 .sp
 258 This will produce output suitable for analyzing the the routes of the posts
 259 which is specially useful when having more than just the 5 lines we had here.
 260 .SH COMPATIBILITY
 261 System V \fBptx\fR compatibility is available by specifying
 262 \fB\-\-traditional\fR.  GNU \fBptx\fR also tries to imitate System V output,
 263 with occassional glitches due the better usage of line width by GNU
 264 \fBptx\fR. Other changes in \fB\-\-traditional\fR mode are:
 265 .RS
 266 .sp
 267 \fB\(bu\fR\ Argument behaviour changes as in \fBDESCRIPTION\fR.
 268 .sp
 269 \fB\(bu\fR\ The only available options are
 270 .BR \-b ", " \-f ", " \-g ", " \-i ", " \-o ", "\-r ", " \-t ", and " \-w .
 271 .sp
 272 \fB\(bu\fR\ Default format is \fB\-\-format=nroff\fR.
 273 .sp
 274 \fB\(bu\fR\ Width of references isn't taken into account when truncating to
 275 \fB\-\-width\fR.
 276 .sp
 277 \fB\(bu\fR\ 8-bit and tilde (`\fB~\fR') characters are rejected, as well as
 278 some control characters.
 279 .sp
 280 \fB\(bu\fR\ Input lines are silently truncated to 200 characters.
 281 .sp
 282 \fB\(bu\fR\ It's not possible to specify both an \fBignore file\fR and an
 283 \fBonly file\fR.
 284 .sp
 285 \fB\(bu\fR\ The defaults of some options change as described in \fBOPTIONS\fR.
 286 .RE
 287 .SH NOTES
 288 Report bugs to bug-textutils@gnu.org.  Enhancement suggestions on
 289 \fB\-\-format=tex\fR is encouraged.
 290 .sp
 291 Man page by Ragnar Hojland Espinosa <ragnar@ragnar-hojland.com>