.\" BSD Zero Clause License
.\"
.\" Copyright (c) 2022 Thomas Voss
.\"
.\" Permission to use, copy, modify, and/or distribute this software for any
.\" purpose with or without fee is hereby granted.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
.\" AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
.\" OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
.\" PERFORMANCE OF THIS SOFTWARE.
.Dd $Mdocdate: November 16 2022 $
.Dt CENTER 1
.Os
.Sh NAME
.Nm center
.Nd center align text
.Sh SYNOPSIS
.Nm
.Op Fl elr
.Op Fl t Ar width
.Op Fl w Ar width
.Op Ar
.Sh DESCRIPTION
The
.Nm
utility reads files sequentially, writing each line center aligned to the
standard output.
The
.Ar file
operands are processed in command-line order.
If
.Ar file
is a single dash
.Pq Sq -
or absent,
.Nm
reads from the standard input.
When run without arguments, the width on which the output should be centered is
automatically determined.
When the output device is a TTY, this is done via the
.Fn isatty
function.
When the output device isn't a terminal then the user is required to pass a
width via the
.Fl w
flag.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl e , Fl Fl ignore\-ansi
Do not take ANSI color escape sequences into account when centering input.
This will cause input containing ANSI color escape sequences to fail to be
visually centered.
.It Fl l , Fl Fl longest
Center the file as a whole instead of centering each line individually.
In otherwords each line is centered as if it has the length of the longest line.
This is useful for tasks like centering source code.
.It Fl r , Fl Fl spaces
Display tabs using spaces.
By default
.Nm
displays tabs using a literal tab character, however this can cause the output
to not appear as intended.
This is because tabs align to the next column that is a multiple of 8 instead of
always displaying as 8 columns.
This flag ensures that every tab character will display as 8 columns or the
amount of columns specified by the
.Fl t
flag.
.It Fl t Ar width , Fl Fl tabsize Ns = Ns Ar width
Treat tab characters as if they have a width of
.Ar width .
If this option is not specified, tabs are assumed to have a tab width of 8
columns.
.It Fl w Ar width , Fl Fl width Ns = Ns Ar width
Center align the input as if the output device has a width of
.Ar width .
This option is required when the output device is not a terminal.
.El
.Sh EXIT STATUS
.Ex -std
.Sh EXAMPLES
Center align the contents of
.Pa file1
and
.Pa file2
to the standard output:
.Pp
.Dl $ center file1 file2
.Pp
Center align a calendar and then follow it with the contents of the file
.Ar file1 ,
writing the output to the file
.Ar file2 .
Align the calendar as if the output device has a width of 80 columns.
.Pp
.Dl $ cal | center -w 80 | cat - file1 > file2
.Pp
Center align the contents of
.Pa file1
and write the output to
.Pa file2
as if the output device had the same width as the current TTY.
This requires non\-standard extensions, and you should refer to the
.Xr tput 1
manual page.
.Pp
.Dl $ center -w `tput cols` file1 > file2
.Pp
Center align the C source code file
.Pa main.c
assuming a tab width of 4 and view it in
.Xr less 3 .
.Pp
.Dl $ center -lr -t 4 center.c | less
.Sh SEE ALSO
.Xr cal 1 ,
.Xr cat 1 ,
.Xr less 1 ,
.Xr tput 1 ,
.Xr isatty 3
.Sh AUTHORS
.An Thomas Voss Aq Mt mail@thomasvoss.com