diff options
Diffstat (limited to 'gnu/usr.bin/ptx/ptx.texinfo')
| -rw-r--r-- | gnu/usr.bin/ptx/ptx.texinfo | 554 |
1 files changed, 554 insertions, 0 deletions
diff --git a/gnu/usr.bin/ptx/ptx.texinfo b/gnu/usr.bin/ptx/ptx.texinfo new file mode 100644 index 0000000..e690c55 --- /dev/null +++ b/gnu/usr.bin/ptx/ptx.texinfo @@ -0,0 +1,554 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename ptx.info +@settitle GNU @code{ptx} reference manual +@finalout +@c %**end of header + +@ifinfo +This file documents the @code{ptx} command, which has the purpose of +generated permuted indices for group of files. + +Copyright (C) 1990, 1991, 1993 by the Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Foundation. +@end ifinfo + +@titlepage +@title ptx +@subtitle The GNU permuted indexer +@subtitle Edition 0.3, for ptx version 0.3 +@subtitle November 1993 +@author by Francois Pinard + +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1990, 1991, 1993 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Foundation. +@end titlepage + +@node Top, Invoking ptx, (dir), (dir) +@chapter Introduction + +This is the 0.3 beta release of @code{ptx}, the GNU version of a +permuted index generator. This software has the main goal of providing +a replacement for the traditional @code{ptx} as found on System V +machines, able to handle small files quickly, while providing a platform +for more development. + +This version reimplements and extends traditional @code{ptx}. Among +other things, it can produce a readable @dfn{KWIC} (keywords in their +context) without the need of @code{nroff}, there is also an option to +produce @TeX{} compatible output. This version does not handle huge +input files, that is, those files which do not fit in memory all at +once. + +@emph{Please note} that an overall renaming of all options is +foreseeable. In fact, GNU ptx specifications are not frozen yet. + +@menu +* Invoking ptx:: How to use this program +* Compatibility:: The GNU extensions to @code{ptx} + + --- The Detailed Node Listing --- + +How to use this program + +* General options:: Options which affect general program behaviour. +* Charset selection:: Underlying character set considerations. +* Input processing:: Input fields, contexts, and keyword selection. +* Output formatting:: Types of output format, and sizing the fields. +@end menu + +@node Invoking ptx, Compatibility, Top, Top +@chapter How to use this program + +This tool reads a text file and essentially produces a permuted index, with +each keyword in its context. The calling sketch is one of: + +@example +ptx [@var{option} @dots{}] [@var{file} @dots{}] +@end example + +or: + +@example +ptx -G [@var{option} @dots{}] [@var{input} [@var{output}]] +@end example + +The @samp{-G} (or its equivalent: @samp{--traditional}) option disables +all GNU extensions and revert to traditional mode, thus introducing some +limitations, and changes several of the program's default option values. +When @samp{-G} is not specified, GNU extensions are always enabled. GNU +extensions to @code{ptx} are documented wherever appropriate in this +document. See @xref{Compatibility} for an explicit list of them. + +Individual options are explained later in this document. + +When GNU extensions are enabled, there may be zero, one or several +@var{file} after the options. If there is no @var{file}, the program +reads the standard input. If there is one or several @var{file}, they +give the name of input files which are all read in turn, as if all the +input files were concatenated. However, there is a full contextual +break between each file and, when automatic referencing is requested, +file names and line numbers refer to individual text input files. In +all cases, the program produces the permuted index onto the standard +output. + +When GNU extensions are @emph{not} enabled, that is, when the program +operates in traditional mode, there may be zero, one or two parameters +besides the options. If there is no parameters, the program reads the +standard input and produces the permuted index onto the standard output. +If there is only one parameter, it names the text @var{input} to be read +instead of the standard input. If two parameters are given, they give +respectively the name of the @var{input} file to read and the name of +the @var{output} file to produce. @emph{Be very careful} to note that, +in this case, the contents of file given by the second parameter is +destroyed. This behaviour is dictated only by System V @code{ptx} +compatibility, because GNU Standards discourage output parameters not +introduced by an option. + +Note that for @emph{any} file named as the value of an option or as an +input text file, a single dash @kbd{-} may be used, in which case +standard input is assumed. However, it would not make sense to use this +convention more than once per program invocation. + +@menu +* General options:: Options which affect general program behaviour. +* Charset selection:: Underlying character set considerations. +* Input processing:: Input fields, contexts, and keyword selection. +* Output formatting:: Types of output format, and sizing the fields. +@end menu + +@node General options, Charset selection, Invoking ptx, Invoking ptx +@section General options + +@table @code + +@item -C +@itemx --copyright +Prints a short note about the Copyright and copying conditions, then +exit without further processing. + +@item -G +@itemx --traditional +As already explained, this option disables all GNU extensions to +@code{ptx} and switch to traditional mode. + +@item --help +Prints a short help on standard output, then exit without further +processing. + +@item --version +Prints the program verison on standard output, then exit without further +processing. + +@end table + +@node Charset selection, Input processing, General options, Invoking ptx +@section Charset selection + +As it is setup now, the program assumes that the input file is coded +using 8-bit ISO 8859-1 code, also known as Latin-1 character set, +@emph{unless} if it is compiled for MS-DOS, in which case it uses the +character set of the IBM-PC. (GNU @code{ptx} is not known to work on +smaller MS-DOS machines anymore.) Compared to 7-bit ASCII, the set of +characters which are letters is then different, this fact alters the +behaviour of regular expression matching. Thus, the default regular +expression for a keyword allows foreign or diacriticized letters. +Keyword sorting, however, is still crude; it obeys the underlying +character set ordering quite blindly. + +@table @code + +@item -f +@itemx --ignore-case +Fold lower case letters to upper case for sorting. + +@end table + +@node Input processing, Output formatting, Charset selection, Invoking ptx +@section Word selection + +@table @code + +@item -b @var{file} +@item --break-file=@var{file} + +This option is an alternative way to option @code{-W} for describing +which characters make up words. This option introduces the name of a +file which contains a list of characters which can@emph{not} be part of +one word, this file is called the @dfn{Break file}. Any character which +is not part of the Break file is a word constituent. If both options +@code{-b} and @code{-W} are specified, then @code{-W} has precedence and +@code{-b} is ignored. + +When GNU extensions are enabled, the only way to avoid newline as a +break character is to write all the break characters in the file with no +newline at all, not even at the end of the file. When GNU extensions +are disabled, spaces, tabs and newlines are always considered as break +characters even if not included in the Break file. + +@item -i @var{file} +@itemx --ignore-file=@var{file} + +The file associated with this option contains a list of words which will +never be taken as keywords in concordance output. It is called the +@dfn{Ignore file}. The file contains exactly one word in each line; the +end of line separation of words is not subject to the value of the +@code{-S} option. + +There is a default Ignore file used by @code{ptx} when this option is +not specified, usually found in @file{/usr/local/lib/eign} if this has +not been changed at installation time. If you want to deactivate the +default Ignore file, specify @code{/dev/null} instead. + +@item -o @var{file} +@itemx --only-file=@var{file} + +The file associated with this option contains a list of words which will +be retained in concordance output, any word not mentioned in this file +is ignored. The file is called the @dfn{Only file}. The file contains +exactly one word in each line; the end of line separation of words is +not subject to the value of the @code{-S} option. + +There is no default for the Only file. In the case there are both an +Only file and an Ignore file, a word will be subject to be a keyword +only if it is given in the Only file and not given in the Ignore file. + +@item -r +@itemx --references + +On each input line, the leading sequence of non white characters will be +taken to be a reference that has the purpose of identifying this input +line on the produced permuted index. See @xref{Output formatting} for +more information about reference production. Using this option change +the default value for option @code{-S}. + +Using this option, the program does not try very hard to remove +references from contexts in output, but it succeeds in doing so +@emph{when} the context ends exactly at the newline. If option +@code{-r} is used with @code{-S} default value, or when GNU extensions +are disabled, this condition is always met and references are completely +excluded from the output contexts. + +@item -S @var{regexp} +@itemx --sentence-regexp=@var{regexp} + +This option selects which regular expression will describe the end of a +line or the end of a sentence. In fact, there is other distinction +between end of lines or end of sentences than the effect of this regular +expression, and input line boundaries have no special significance +outside this option. By default, when GNU extensions are enabled and if +@code{-r} option is not used, end of sentences are used. In this +case, the precise @var{regex} is imported from GNU emacs: + +@example +[.?!][]\"')@}]*\\($\\|\t\\| \\)[ \t\n]* +@end example + +Whenever GNU extensions are disabled or if @code{-r} option is used, end +of lines are used; in this case, the default @var{regexp} is just: + +@example +\n +@end example + +Using an empty REGEXP is equivalent to completely disabling end of line or end +of sentence recognition. In this case, the whole file is considered to +be a single big line or sentence. The user might want to disallow all +truncation flag generation as well, through option @code{-F ""}. +@xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs +Manual}. + +When the keywords happen to be near the beginning of the input line or +sentence, this often creates an unused area at the beginning of the +output context line; when the keywords happen to be near the end of the +input line or sentence, this often creates an unused area at the end of +the output context line. The program tries to fill those unused areas +by wrapping around context in them; the tail of the input line or +sentence is used to fill the unused area on the left of the output line; +the head of the input line or sentence is used to fill the unused area +on the right of the output line. + +As a matter of convenience to the user, many usual backslashed escape +sequences, as found in the C language, are recognized and converted to +the corresponding characters by @code{ptx} itself. + +@item -W @var{regexp} +@itemx --word-regexp=@var{regexp} + +This option selects which regular expression will describe each keyword. +By default, if GNU extensions are enabled, a word is a sequence of +letters; the @var{regexp} used is @code{\w+}. When GNU extensions are +disabled, a word is by default anything which ends with a space, a tab +or a newline; the @var{regexp} used is @code{[^ \t\n]+}. + +An empty REGEXP is equivalent to not using this option, letting the +default dive in. @xref{Regexps, , Syntax of Regular Expressions, emacs, +The GNU Emacs Manual}. + +As a matter of convenience to the user, many usual backslashed escape +sequences, as found in the C language, are recognized and converted to +the corresponding characters by @code{ptx} itself. + +@end table + +@node Output formatting, , Input processing, Invoking ptx +@section Output formatting + +Output format is mainly controlled by @code{-O} and @code{-T} options, +described in the table below. When neither @code{-O} nor @code{-T} is +selected, and if GNU extensions are enabled, the program choose an +output format suited for a dumb terminal. Each keyword occurrence is +output to the center of one line, surrounded by its left and right +contexts. Each field is properly justified, so the concordance output +could readily be observed. As a special feature, if automatic +references are selected by option @code{-A} and are output before the +left context, that is, if option @code{-R} is @emph{not} selected, then +a colon is added after the reference; this nicely interfaces with GNU +Emacs @code{next-error} processing. In this default output format, each +white space character, like newline and tab, is merely changed to +exactly one space, with no special attempt to compress consecutive +spaces. This might change in the future. Except for those white space +characters, every other character of the underlying set of 256 +characters is transmitted verbatim. + +Output format is further controlled by the following options. + +@table @code + +@item -g @var{number} +@itemx --gap-size=@var{number} + +Select the size of the minimum white gap between the fields on the output +line. + +@item -w @var{number} +@itemx --width=@var{number} + +Select the output maximum width of each final line. If references are +used, they are included or excluded from the output maximum width +depending on the value of option @code{-R}. If this option is not +selected, that is, when references are output before the left context, +the output maximum width takes into account the maximum length of all +references. If this options is selected, that is, when references are +output after the right context, the output maximum width does not take +into account the space taken by references, nor the gap that precedes +them. + +@item -A +@itemx --auto-reference + +Select automatic references. Each input line will have an automatic +reference made up of the file name and the line ordinal, with a single +colon between them. However, the file name will be empty when standard +input is being read. If both @code{-A} and @code{-r} are selected, then +the input reference is still read and skipped, but the automatic +reference is used at output time, overriding the input reference. + +@item -R +@itemx --right-side-refs + +In default output format, when option @code{-R} is not used, any +reference produced by the effect of options @code{-r} or @code{-A} are +given to the far right of output lines, after the right context. In +default output format, when option @code{-R} is specified, references +are rather given to the beginning of each output line, before the left +context. For any other output format, option @code{-R} is almost +ignored, except for the fact that the width of references is @emph{not} +taken into account in total output width given by @code{-w} whenever +@code{-R} is selected. + +This option is automatically selected whenever GNU extensions are +disabled. + +@item -F @var{string} +@itemx --flac-truncation=@var{string} + +This option will request that any truncation in the output be reported +using the string @var{string}. Most output fields theoretically extend +towards the beginning or the end of the current line, or current +sentence, as selected with option @code{-S}. But there is a maximum +allowed output line width, changeable through option @code{-w}, which is +further divided into space for various output fields. When a field has +to be truncated because cannot extend until the beginning or the end of +the current line to fit in the, then a truncation occurs. By default, +the string used is a single slash, as in @code{-F /}. + +@var{string} may have more than one character, as in @code{-F ...}. +Also, in the particular case @var{string} is empty (@code{-F ""}), +truncation flagging is disabled, and no truncation marks are appended in +this case. + +As a matter of convenience to the user, many usual backslashed escape +sequences, as found in the C language, are recognized and converted to +the corresponding characters by @code{ptx} itself. + +@item -M @var{string} +@itemx --macro-name=@var{string} + +Select another @var{string} to be used instead of @samp{xx}, while +generating output suitable for @code{nroff}, @code{troff} or @TeX{}. + +@item -O +@itemx --format=roff + +Choose an output format suitable for @code{nroff} or @code{troff} +processing. Each output line will look like: + +@example +.xx "@var{tail}" "@var{before}" "@var{keyword_and_after}" "@var{head}" "@var{ref}" +@end example + +so it will be possible to write an @samp{.xx} roff macro to take care of +the output typesetting. This is the default output format when GNU +extensions are disabled. Option @samp{-M} might be used to change +@samp{xx} to another macro name. + +In this output format, each non-graphical character, like newline and +tab, is merely changed to exactly one space, with no special attempt to +compress consecutive spaces. Each quote character: @kbd{"} is doubled +so it will be correctly processed by @code{nroff} or @code{troff}. + +@item -T +@itemx --format=tex + +Choose an output format suitable for @TeX{} processing. Each output +line will look like: + +@example +\xx @{@var{tail}@}@{@var{before}@}@{@var{keyword}@}@{@var{after}@}@{@var{head}@}@{@var{ref}@} +@end example + +@noindent +so it will be possible to write write a @code{\xx} definition to take +care of the output typesetting. Note that when references are not being +produced, that is, neither option @code{-A} nor option @code{-r} is +selected, the last parameter of each @code{\xx} call is inhibited. +Option @samp{-M} might be used to change @samp{xx} to another macro +name. + +In this output format, some special characters, like @kbd{$}, @kbd{%}, +@kbd{&}, @kbd{#} and @kbd{_} are automatically protected with a +backslash. Curly brackets @kbd{@{}, @kbd{@}} are also protected with a +backslash, but also enclosed in a pair of dollar signs to force +mathematical mode. The backslash itself produces the sequence +@code{\backslash@{@}}. Circumflex and tilde diacritics produce the +sequence @code{^\@{ @}} and @code{~\@{ @}} respectively. Other +diacriticized characters of the underlying character set produce an +appropriate @TeX{} sequence as far as possible. The other non-graphical +characters, like newline and tab, and all others characters which are +not part of ASCII, are merely changed to exactly one space, with no +special attempt to compress consecutive spaces. Let me know how to +improve this special character processing for @TeX{}. + +@end table + +@node Compatibility, , Invoking ptx, Top +@chapter The GNU extensions to @code{ptx} + +This version of @code{ptx} contains a few features which do not exist in +System V @code{ptx}. These extra features are suppressed by using the +@samp{-G} command line option, unless overridden by other command line +options. Some GNU extensions cannot be recovered by overriding, so the +simple rule is to avoid @samp{-G} if you care about GNU extensions. +Here are the differences between this program and System V @code{ptx}. + +@itemize @bullet + +@item +This program can read many input files at once, it always writes the +resulting concordance on standard output. On the other end, System V +@code{ptx} reads only one file and produce the result on standard output +or, if a second @var{file} parameter is given on the command, to that +@var{file}. + +Having output parameters not introduced by options is a quite dangerous +practice which GNU avoids as far as possible. So, for using @code{ptx} +portably between GNU and System V, you should pay attention to always +use it with a single input file, and always expect the result on +standard output. You might also want to automatically configure in a +@samp{-G} option to @code{ptx} calls in products using @code{ptx}, if +the configurator finds that the installed @code{ptx} accepts @samp{-G}. + +@item +The only options available in System V @code{ptx} are options @samp{-b}, +@samp{-f}, @samp{-g}, @samp{-i}, @samp{-o}, @samp{-r}, @samp{-t} and +@samp{-w}. All other options are GNU extensions and are not repeated in +this enumeration. Moreover, some options have a slightly different +meaning when GNU extensions are enabled, as explained below. + +@item +By default, concordance output is not formatted for @code{troff} or +@code{nroff}. It is rather formatted for a dumb terminal. @code{troff} +or @code{nroff} output may still be selected through option @code{-O}. + +@item +Unless @code{-R} option is used, the maximum reference width is +subtracted from the total output line width. With GNU extensions +disabled, width of references is not taken into account in the output +line width computations. + +@item +All 256 characters, even @kbd{NUL}s, are always read and processed from +input file with no adverse effect, even if GNU extensions are disabled. +However, System V @code{ptx} does not accept 8-bit characters, a few +control characters are rejected, and the tilda @kbd{~} is condemned. + +@item +Input line length is only limited by available memory, even if GNU +extensions are disabled. However, System V @code{ptx} processes only +the first 200 characters in each line. + +@item +The break (non-word) characters default to be every character except all +letters of the underlying character set, diacriticized or not. When GNU +extensions are disabled, the break characters default to space, tab and +newline only. + +@item +The program makes better use of output line width. If GNU extensions +are disabled, the program rather tries to imitate System V @code{ptx}, +but still, there are some slight disposition glitches this program does +not completely reproduce. + +@item +The user can specify both an Ignore file and an Only file. This is not +allowed with System V @code{ptx}. + +@end itemize + +@bye |
