Covert to mdoc; from FreeBSD, with some modifications by me.

1 files changed, 143 insertions, 99 deletions

diff --git a/usr.bin/rs/rs.1 b/usr.bin/rs/rs.1
index 1b9f955f19f..63240b08a06 100644
--- a/usr.bin/rs/rs.1
+++ b/usr.bin/rs/rs.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: rs.1,v 1.4 1999/10/17 20:24:35 aaron Exp $
+.\"	$OpenBSD: rs.1,v 1.5 2000/03/06 12:23:41 aaron Exp $
 .\"
 .\" Copyright (c) 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -32,170 +32,214 @@
 .\" SUCH DAMAGE.
 .\"
 .\"	@(#)rs.1	8.2 (Berkeley) 12/30/93
+.\" $FreeBSD: src/usr.bin/rs/rs.1,v 1.4 1999/08/28 01:05:21 peter Exp $
 .\"
-.TH RS 1 "December 30, 1993"
-.UC 4
-.SH NAME
-rs \- reshape a data array
-.SH SYNOPSIS
-\fBrs [ \-[csCS][\fRx\fB][kKgGw][\fRN\fB]tTeEnyjhHm ] [ \fRrows\fB [ \fRcols\fB ] ]\fR
-.SH DESCRIPTION
-.I Rs
+.Dd December 30, 1993
+.Dt RS 1
+.Os
+.Sh NAME
+.Nm rs
+.Nd reshape a data array
+.Sh SYNOPSIS
+.Nm rs
+.Oo
+.Sm off
+.Xo Fl Oo Cm Op Cm csCS
+.Op Ar x
+.Op Cm kKgGw
+.Op Ar N
+.Cm tTeEnyjhHmz Oc
+.Xc
+.Oc
+.Sm on
+.Op Ar rows Op Ar cols
+.Sh DESCRIPTION
+.Nm
 reads the standard input, interpreting each line as a row
 of blank-separated entries in an array,
 transforms the array according to the options,
 and writes it on the standard output.
 With no arguments it transforms stream input into a columnar
 format convenient for terminal viewing.
-.PP
+.Pp
 The shape of the input array is deduced from the number of lines
 and the number of columns on the first line.
 If that shape is inconvenient, a more useful one might be
-obtained by skipping some of the input with the \fB\-k\fP option.
+obtained by skipping some of the input with the
+.Fl k
+option.
 Other options control interpretation of the input columns.
-.PP
+.Pp
 The shape of the output array is influenced by the
-.I rows
+.Ar rows
 and
-.I cols
+.Ar cols
 specifications, which should be positive integers.
 If only one of them is a positive integer,
-.I rs
+.Nm
 computes a value for the other which will accommodate
 all of the data.
 When necessary, missing data are supplied in a manner
 specified by the options and surplus data are deleted.
 There are options to control presentation of the output columns,
 including transposition of the rows and columns.
-.PP
+.Pp
 The options are as follows:
-.IP \fB\-c\fRx
-Input columns are delimited by the single character \fIx\fP.
-A missing \fIx\fP is taken to be `^I'.
-.IP \fB\-s\fRx
-Like \fB\-c\fR, but maximal strings of \fIx\fP are delimiters.
-.IP \fB\-C\fRx
-Output columns are delimited by the single character \fIx\fP.
-A missing \fIx\fP is taken to be `^I'.
-.IP \fB\-S\fRx
-Like \fB\-C\fR, but padded strings of \fIx\fP are delimiters.
-.IP \fB\-t\fR
+.Bl -tag -width indent
+.It Fl c Ns Ar x
+Input columns are delimited by the single character
+.Ar x .
+A missing
+.Ar x
+is taken to be
+.Ql ^I .
+.It Fl s Ns Ar x
+Like
+.Fl c ,
+but maximal strings of
+.Ar x
+are delimiters.
+.It Fl C Ns Ar x
+Output columns are delimited by the single character
+.Ar x .
+A missing
+.Ar x
+is taken to be
+.Ql ^I .
+.It Fl S Ns Ar x
+Like
+.Fl C ,
+but padded strings of
+.Ar x
+are delimiters.
+.It Fl t
 Fill in the rows of the output array using the columns of the
 input array, that is, transpose the input while honoring any
-.I rows
+.Ar rows
 and
-.I cols
+.Ar cols
 specifications.
-.IP \fB\-T\fR
+.It Fl T
 Print the pure transpose of the input, ignoring any
-.I rows
+.Ar rows
 or
-.I cols
+.Ar cols
 specification.
-.IP \fB\-k\fRN
-Ignore the first \fIN\fR lines of input.
-.IP \fB\-K\fRN
-Like \fB\-k\fR, but print the ignored lines.
-.IP \fB\-g\fRN
-The gutter width (inter-column space), normally 2, is taken to be \fIN\fR.
-.IP \fB\-G\fRN
-The gutter width has \fIN\fR percent of the maximum
-column width added to it.
-.IP \fB\-e\fR
+.It Fl k Ns Ar N
+Ignore the first
+.Ar N
+lines of input.
+.It Fl K Ns Ar N
+Like
+.Fl k ,
+but print the ignored lines.
+.It Fl g Ns Ar N
+The gutter width (inter-column space), normally 2, is taken to be
+.Ar N .
+.It Fl G Ns Ar N
+The gutter width has
+.Ar N
+percent of the maximum column width added to it.
+.It Fl e
 Consider each line of input as an array entry.
-.IP \fB\-n\fR
+.It Fl E
+Consider each character of input as an array entry.
+.It Fl n
 On lines having fewer entries than the first line,
 use null entries to pad out the line.
 Normally, missing entries are taken from the next line of input.
-.IP \fB\-y\fR
+.It Fl y
 If there are too few entries to make up the output dimensions,
 pad the output by recycling the input from the beginning.
 Normally, the output is padded with blanks.
-.IP \fB\-h\fR
+.It Fl h
 Print the shape of the input array and do nothing else.
 The shape is just the number of lines and the number of
 entries on the first line.
-.IP \fB\-H\fR
-Like \fB\-h\fR, but also print the length of each line.
-.IP \fB\-j\fR
+.It Fl H
+Like
+.Fl h ,
+but also print the length of each line.
+.It Fl j
 Right adjust entries within columns.
-.IP \fB\-w\fRN
+.It Fl w Ns Ar N
 The width of the display, normally 80, is taken to be the positive
-integer \fIN\fP.
-.IP \fB\-m\fR
+integer
+.Ar N .
+.It Fl m
 Do not trim excess delimiters from the ends of the output array.
-.IP \fB\-z\fR
+.It Fl z
 Adapt column widths to fit the largest entries appearing in them.
-.PP
+.El
+.Pp
 With no arguments,
-.I rs
+.Nm
 transposes its input, and assumes one array entry per input line
 unless the first non-ignored line is longer than the display width.
 Option letters which take numerical arguments interpret a missing
 number as zero unless otherwise indicated.
-.SH EXAMPLES
-.de IC
-.IP
-.ss 36
-.ft B
-..
-.de NC
-.br
-.ss 12
-.PP
-..
-.I Rs
+.Sh EXAMPLES
+.Nm
 can be used as a filter to convert the stream output
 of certain programs (e.g.,
-.IR spell ,
-.IR du ,
-.IR file ,
-.IR look ,
-.IR nm ,
-.IR who ,
+.Xr spell ,
+.Xr du ,
+.Xr file ,
+.Xr look ,
+.Xr nm ,
+.Xr who ,
 and
-.IR wc (1))
-into a convenient ``window'' format, as in
-.IC
-who | rs
-.NC
+.Xr wc 1 )
+into a convenient
+.Dq window
+format, as in
+.Bd -literal -offset indent
+% who | rs
+.Ed
+.Pp
 This function has been incorporated into the
-.IR ls (1)
+.Xr ls 1
 program, though for most programs with similar output
-.I rs
+.Nm
 suffices.
-.PP
+.Pp
 To convert stream input into vector output and back again, use
-.IC
-rs 1 0 | rs 0 1
-.NC
+.Bd -literal -offset indent
+% rs 1 0 | rs 0 1
+.Ed
+.Pp
 A 10 by 10 array of random numbers from 1 to 100 and
 its transpose can be generated with
-.IC
-jot \-r 100 | rs 10 10 | tee array | rs \-T > tarray
-.NC
+.Bd -literal -offset indent
+% jot \-r 100 | rs 10 10 | tee array | rs \-T > tarray
+.Ed
+.Pp
 In the editor
-.IR vi (1),
+.Xr vi 1 ,
 a file consisting of a multi-line vector with 9 elements per line
 can undergo insertions and deletions,
 and then be neatly reshaped into 9 columns with
-.IC
+.Bd -literal -offset indent
 :1,$!rs 0 9
-.NC
+.Ed
+.Pp
 Finally, to sort a database by the first line of each 4-line field, try
-.IC
-rs \-eC 0 4 | sort | rs \-c 0 1
-.NC
-.SH SEE ALSO
-jot(1), vi(1), sort(1), pr(1)
-.SH BUGS
+.Bd -literal -offset indent
+% rs \-eC 0 4 | sort | rs \-c 0 1
+.Ed
+.Sh SEE ALSO
+.Xr jot 1 ,
+.Xr pr 1 ,
+.Xr sort 1 ,
+.Xr vi 1
+.Sh BUGS
 Handles only two dimensional arrays.
-
+.Pp
 The algorithm currently reads the whole file into memory,
 so files that do not fit in memory will not be reshaped.
-
+.Pp
 Fields cannot be defined yet on character positions.
-
+.Pp
 Re-ordering of columns is not yet possible.
-
+.Pp
 There are too many options.