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.
- -L, --[no-]lateral
-
Put all the pages in one row, however wide it becomes. The screen shows as many panes as without this option, as many as fit or the number given by
-C, and the row goes on to the right: the panes are given toansicolumnby their width (-S), the width of the screen divided by that number, in a very large output width.When the pager is
less,-S --shift=N --rscroll=-is added to it, where N is the width of a pane, so that the lines are not wrapped and the arrow keys move by one page. Keys are added toLESSKEY_CONTENT(less 661 or later), after the keys of the user, or those ofNUP_LESSKEYin their place, none when it is empty:handl,,and., and ESC-( and ESC-), move by one page as the arrow keys,HandLgo to the left and the right end, and so dogandG,<and>, and space andbmove to the right and to the left by the panes on the screen. With less 710 or later,l,., the right arrow and ESC-) stop at the right end. The build of less in tecolicom/tap does more; see "LESS INTEGRATION" in nup.With
--no-paginate, it is for the files side by side, as the nup command gives it for more than one file: each file is a column of its own, the columns go on to the right, and onlyh,l,,,., the arrow keys, ESC-( and ESC-),H,L,<and>are put inLESSKEY_CONTENT. One input without pages makes a column of each line.It cannot be used with rows (
-R,-C2,2,-G) or PDF output, and--auto-paginateis ignored. - --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.
- --device=DEVICE, -T DEVICE
-
Set the device to show the output on. The default is
tty, the terminal. Any other device is a paper, and the output is printed to PDF byansi2pdf. The name of a paper is the one for the-poption ofansi2pdf, asa4ora3, andporlafter it gives the orientation, asa4pfor A4 in portrait. A paper without it is used in landscape. The devicepdfis the default paper ofansi2pdf.The size of a sheet of paper in columns and lines, which
ansi2pdf --geometrytells, is used in place of the terminal size, andansi2pdfis used in place of the pager. Each screen is printed on a sheet as it is. - --output=FILE, -o FILE
-
Write the output to FILE. When the name ends with
.pdf, the output is PDF without--deviceas well. Otherwise, what is shown on the terminal is written to the file as it is, with the ANSI sequences, and the pager is not used.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. - --geometry
-
Print the size of the device in columns and lines and its kind,
ttyorpdf, as206 60 pdf, and exit without running the command. For a paper, the size is that of a sheet, which follows--device,--output,--page,--width, the number of rows and--pdf-opts. For the terminal, it is the size of the terminal. - --pdf-opts=OPTIONS
-
Give other options to
ansi2pdf, such as-l 80for the number of lines on a sheet and-m 15for the margin. They are given after the paper, so they take precedence. - 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.