coreutils: Output formatting in ptx
1
1 7.5.4 Output formatting
1 -----------------------
1
1 Output format is mainly controlled by the ‘-O’ and ‘-T’ options
1 described in the table below. When neither ‘-O’ nor ‘-T’ are selected,
1 and if GNU extensions are enabled, the program chooses an output format
1 suitable for a dumb terminal. Each keyword occurrence is output to the
1 center of one line, surrounded by its left and right contexts. Each
1 field is properly justified, so the concordance output can be readily
1 observed. As a special feature, if automatic references are selected by
1 option ‘-A’ and are output before the left context, that is, if option
1 ‘-R’ is _not_ selected, then a colon is added after the reference; this
1 nicely interfaces with GNU Emacs ‘next-error’ processing. In this
1 default output format, each white space character, like newline and tab,
1 is merely changed to exactly one space, with no special attempt to
1 compress consecutive spaces. This might change in the future. Except
1 for those white space characters, every other character of the
1 underlying set of 256 characters is transmitted verbatim.
1
1 Output format is further controlled by the following options.
1
1 ‘-g NUMBER’
1 ‘--gap-size=NUMBER’
1
1 Select the size of the minimum white space gap between the fields
1 on the output line.
1
1 ‘-w NUMBER’
1 ‘--width=NUMBER’
1
1 Select the maximum output width of each final line. If references
1 are used, they are included or excluded from the maximum output
1 width depending on the value of option ‘-R’. If this option is not
1 selected, that is, when references are output before the left
1 context, the maximum output width takes into account the maximum
1 length of all references. If this option is selected, that is,
1 when references are output after the right context, the maximum
1 output width does not take into account the space taken by
1 references, nor the gap that precedes them.
1
1 ‘-A’
1 ‘--auto-reference’
1
1 Select automatic references. Each input line will have an
1 automatic reference made up of the file name and the line ordinal,
1 with a single colon between them. However, the file name will be
1 empty when standard input is being read. If both ‘-A’ and ‘-r’ are
1 selected, then the input reference is still read and skipped, but
1 the automatic reference is used at output time, overriding the
1 input reference.
1
1 ‘-R’
1 ‘--right-side-refs’
1
1 In the default output format, when option ‘-R’ is not used, any
1 references produced by the effect of options ‘-r’ or ‘-A’ are
1 placed to the far right of output lines, after the right context.
1 With default output format, when the ‘-R’ option is specified,
1 references are rather placed at the beginning of each output line,
1 before the left context. For any other output format, option ‘-R’
1 is ignored, with one exception: with ‘-R’ the width of references
1 is _not_ taken into account in total output width given by ‘-w’.
1
1 This option is automatically selected whenever GNU extensions are
1 disabled.
1
1 ‘-F STRING’
1 ‘--flag-truncation=STRING’
1
1 This option will request that any truncation in the output be
1 reported using the string STRING. Most output fields theoretically
1 extend towards the beginning or the end of the current line, or
1 current sentence, as selected with option ‘-S’. But there is a
1 maximum allowed output line width, changeable through option ‘-w’,
1 which is further divided into space for various output fields.
1 When a field has to be truncated because it cannot extend beyond
1 the beginning or the end of the current line to fit in, then a
1 truncation occurs. By default, the string used is a single slash,
1 as in ‘-F /’.
1
1 STRING may have more than one character, as in ‘-F ...’. Also, in
1 the particular case when STRING is empty (‘-F ""’), truncation
1 flagging is disabled, and no truncation marks are appended in this
1 case.
1
1 As a matter of convenience to the user, many usual backslashed
1 escape sequences, as found in the C language, are recognized and
1 converted to the corresponding characters by ‘ptx’ itself.
1
1 ‘-M STRING’
1 ‘--macro-name=STRING’
1
1 Select another STRING to be used instead of ‘xx’, while generating
1 output suitable for ‘nroff’, ‘troff’ or TeX.
1
1 ‘-O’
1 ‘--format=roff’
1
1 Choose an output format suitable for ‘nroff’ or ‘troff’ processing.
1 Each output line will look like:
1
1 .xx "TAIL" "BEFORE" "KEYWORD_AND_AFTER" "HEAD" "REF"
1
1 so it will be possible to write a ‘.xx’ roff macro to take care of
1 the output typesetting. This is the default output format when GNU
1 extensions are disabled. Option ‘-M’ can be used to change ‘xx’ to
1 another macro name.
1
1 In this output format, each non-graphical character, like newline
1 and tab, is merely changed to exactly one space, with no special
1 attempt to compress consecutive spaces. Each quote character ‘"’
1 is doubled so it will be correctly processed by ‘nroff’ or ‘troff’.
1
1 ‘-T’
1 ‘--format=tex’
1
1 Choose an output format suitable for TeX processing. Each output
1 line will look like:
1
1 \xx {TAIL}{BEFORE}{KEYWORD}{AFTER}{HEAD}{REF}
1
1 so it will be possible to write a ‘\xx’ definition to take care of
1 the output typesetting. Note that when references are not being
1 produced, that is, neither option ‘-A’ nor option ‘-r’ is selected,
1 the last parameter of each ‘\xx’ call is inhibited. Option ‘-M’
1 can be used to change ‘xx’ to another macro name.
1
1 In this output format, some special characters, like ‘$’, ‘%’, ‘&’,
1 ‘#’ and ‘_’ are automatically protected with a backslash. Curly
1 brackets ‘{’, ‘}’ are protected with a backslash and a pair of
1 dollar signs (to force mathematical mode). The backslash itself
1 produces the sequence ‘\backslash{}’. Circumflex and tilde
1 diacritical marks produce the sequence ‘^\{ }’ and ‘~\{ }’
1 respectively. Other diacriticized characters of the underlying
1 character set produce an appropriate TeX sequence as far as
1 possible. The other non-graphical characters, like newline and
1 tab, and all other characters which are not part of ASCII, are
1 merely changed to exactly one space, with no special attempt to
1 compress consecutive spaces. Let me know how to improve this
1 special character processing for TeX.
1