NAME
up - optex module for multi-column paged output
SYNOPSIS
optex -Mup command ...
optex -Mup -C2 -- command ...
optex -Mup -C2,2 -- command ...
DESCRIPTION
up is a module for the optex command that pipes the output through App::ansicolumn for multi-column formatting and a pager. The name comes from the printing term "n-up" (2-up, 3-up, etc.) which refers to printing multiple pages on a single sheet.
The module automatically calculates the number of columns based on the terminal width divided by the pane width (default 85 characters). The terminal size is taken from the controlling terminal (/dev/tty); when it is not available, the COLUMNS environment variable gives the width (default 80), and LINES gives the height (default 24) used when the number of rows is set, as in -C2,2.
Both stdout and stderr are merged and passed through the filter, so error messages are also displayed in the multi-column paged output.
The pager command is taken from the NUP_PAGER environment variable if set, otherwise defaults to less -F +Gg. When page mode is active, the NUP_PAGE_PAGER environment variable is consulted first. The environment variables are named after the nup command, a wrapper for this module. The PAGER variable is not used to avoid an infinite loop when PAGER is set to nup. Use the --pager option to specify a different pager on the command line.
The -F option causes less to exit immediately if the output fits on one screen. +Gg causes less to read all input before displaying, which may take time for large output, but prevents empty trailing pages from being shown. The --file-size option of less 590 (June 2021) and later does the same as +Gg; it is not the default because older versions, such as the less 581 that comes with macOS, do not have it and print an error message for it. Set NUP_PAGER to use it:
export NUP_PAGER="less --file-size"
OPTIONS
Module options must be specified before -- separator.
- -C C[,R], --pane=C[,R]
-
Set the number of columns (panes) directly, and the number of rows when it is given after a comma. For example,
-C2creates 2 columns, and-C2,3creates a 2-column, 3-row layout (6-up). The page height is calculated by dividing the terminal height by the number of rows. - -R N, --row=N
-
Set the number of rows. This option is kept for compatibility and may be removed in the future.
- -G CxR, --grid=CxR
-
Set the grid layout.
--grid=2x3or--grid=2,3is equivalent to-C2,3. This option is kept for compatibility and may be removed in the future. - -S N, --pane-width=N
-
Set the pane width in characters. Default is 85. When --pane is not specified, the number of panes is calculated by dividing the terminal width by this value.
- --bs=STYLE, --border-style=STYLE
-
Set the border style for ansicolumn. Default is
heavy-box. See App::ansicolumn for available styles. - --no-paginate
-
Disable page mode. Without pagination, the entire content is split evenly across columns. Page mode is the default.
Note that App::ansicolumn uses parallel layout when multiple files are given, which has no page structure. Specify this option in such cases so that
NUP_PAGE_PAGERis not used (the nup command does this automatically). - -A, --auto-paginate
-
Automatically disable page mode when only one column fits the terminal.
- --pager=COMMAND
-
Set the pager command, overriding the environment variables. Default is
NUP_PAGE_PAGER(page mode only),NUP_PAGER, orless -F +Gg. - --no-pager
-
Disable pager. Output goes directly to stdout.
- --pdf[=FILE]
-
Print the output to a PDF file by
ansi2pdf. Without FILE, the PDF is written to the standard output. The size of a sheet of paper in columns and lines, whichansi2pdf --geometrytells, is used in place of the terminal size, andansi2pdfis used in place of the pager. Each screen is printed on a landscape sheet as it is.The page height given by
-P(--page) is the number of lines of a page here too: a sheet has that many lines for each row. The width given by-w(--width) is the number of columns of a sheet. The font size follows them, and the one that is not given is decided to fill the sheet. The default is 60 lines on a sheet. - --pdf-opts=OPTIONS
-
Give options to
ansi2pdf, such as-p a3for the paper size,-Pfor portrait and-l 80for the number of lines on a sheet. - Other options
-
Any unrecognized options are passed through to App::ansicolumn. For example,
--cmoption can be used to set colormap:optex -Mup --cm=BORDER=R -- commandSee App::ansicolumn for available options.
EXAMPLES
Display perldoc output in multiple columns:
optex -Mup perldoc App::optex::up
List files in multiple columns with pager:
optex -Mup ls -l
Use 2 columns:
optex -Mup -C2 -- ls -l
Set pane width to 100:
optex -Mup -S100 -- ls -l
Use 2x2 grid (4-up):
optex -Mup -C2,2 -- ls -l
No pagination:
optex -Mup --no-paginate -- man perl
Use a different border style:
optex -Mup --bs=round-box -- ls -l
Output without pager (useful for piping):
optex -Mup --no-pager -C2 -- ls -l | head
Truncate long lines:
optex -Mup --ls=truncate -- ps aux
INSTALL
Homebrew
Use tecolicom/tap:
brew tap tecolicom/tap
brew install app-nup
CPANMINUS
cpanm App::nup
SEE ALSO
App::nup, https://github.com/tecolicom/App-nup
App::optex, https://github.com/kaz-utashiro/optex
AUTHOR
Kazumasa Utashiro
LICENSE
Copyright 2025 Kazumasa Utashiro.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.