NAME

nup - n-up, multi-column paged output for commands and files

SYNOPSIS

nup [ options ] file ...
nup -e [ options ] command ...

 -h  --help             show help
     --version          show version
 -d  --debug            debug mode
 -n  --dryrun           dry-run mode
 -e  --exec             execute command mode
     --alias=CMD=OPTS   set command alias
 -V  --parallel         parallel view mode
 -D  --document         document mode (default: on)
 -F  --no-paginate      disable page mode
 -A  --auto-paginate    auto disable page mode for single column
 -L  --lateral          pages or files in one row, scrolled sideways
 -H  --filename         show filename headers (default: on)
 -C  --pane=#[,#]       number of columns, and rows (e.g., 2,2)
 -P  --page=#           page height in lines
 -S  --pane-width=#     pane width (default: 85)
--bs --border-style=#   border style (default: heavy-box)
--ls --line-style=#     line style (none/truncate/wrap/wordwrap)
     --runin=#          run-in width for line breaking
     --runout=#         run-out width for line breaking
     --runlen=#         set both run-in and run-out
     --boundary=#       fold boundary: word, space or none
--cm --colormap=#       color mapping (LABEL=COLOR)
     --[no-]page-number page number on border (default: on)
     --textconv[=EXT]   textconv for non-text files
     --pager=#          pager command (empty to disable)
     --no-pager         disable pager
 -T  --device=#         output device: tty, pdf, or a paper for PDF
                        (e.g., a4, a4p, a3l)
 -o  --output=FILE      output file (PDF when it ends with .pdf)
     --pdf-opts=#       options for ansi2pdf (e.g., "-l 80")
     --geometry         print the size and the kind of the device
     --white-board      black on white board
     --black-board      white on black board
     --green-board      white on green board
     --slate-board      white on dark slate board

VERSION

Version 1.17

DESCRIPTION

N-up (command: nup) is a multi-column paged output tool. It provides a convenient way to view files or run commands in n-up layout using the App::optex::up module through optex.

nup automatically detects the mode based on the first argument: if it is an existing file, n-up file view mode is used; if it is an executable command, n-up command mode is used. Use -e option to force command mode when needed.

In file view mode, nup stops parsing its own options at the first file name and hands the file names and everything after them to ansicolumn unchanged. Options of ansicolumn that nup does not provide can therefore be given after the file names:

nup -C2 file1.txt file2.txt -w 170

Here -w 170 sets the output width for ansicolumn. To set the width when no terminal is available, the COLUMNS environment variable works in both modes; see "Terminal Size".

OPTIONS

General Options

-h, --help

Show help message.

--version

Show version.

-d, --debug

Enable debug mode.

-n, --dryrun

Dry-run mode. Show the command without executing.

-e, --exec

Force command execution mode. Normally the mode is auto-detected, but use this option when you want to execute a file as a command.

--alias=NAME=CMD OPTS...

Define command alias. When a command matches NAME, it is replaced by CMD with specified OPTS. This can be used to add default options or to substitute a different command. Multiple --alias options can be specified.

Default aliases:

bat     bat --style=plain --color=always
batcat  batcat --style=plain --color=always
mdcat   mdcat --ansi
rg      rg --color=always
tree    tree -C

Example:

nup --alias='grep=ggrep --color=always' grep pattern file
-V, --parallel

Enable parallel view mode for ansicolumn. In this mode, each file is displayed in its own column without pagination, similar to --no-paginate. Automatically enabled when multiple files are specified. Single file or stdin input results in single column output.

-D, --document

Enable document mode for ansicolumn. This mode is optimized for viewing documents with n-up page-based layout. Enabled by default. Use --no-document to disable.

-F, --no-paginate

Disable page mode. Without pagination, the entire content is split evenly across columns. Page mode is the default; use --paginate to re-enable if needed.

-A, --auto-paginate

Automatically disable page mode when only one column fits the terminal. This is useful when using nup as MANPAGER, where single-column page splitting wastes space.

-L, --lateral

Put all the pages in one row, however wide it becomes, instead of filling the screen with as many panes as fit and going on below. The row is as high as the screen, and it is seen by scrolling sideways in the pager.

The screen shows the same number of panes as without this option: as many as fit, or the number given by -C. With -C4, four pages are on the screen at a time, each a quarter of it wide.

When the pager is less, nup adds -S --shift=N --rscroll=- to it, where N is the width of a pane: the lines are not wrapped, and the right and left arrow keys move by one page.

nup also puts the following keys in the LESSKEY_CONTENT environment variable, which less 661 or later reads. With three panes on the screen and a less older than 710, they are:

h , left    left-scroll         one page to the left
l . right   right-scroll        one page to the right
H g <       no-scroll           the left end of the row
L G >       end-scroll          the right end of the row
space       noaction ESC-) x 3  the panes on the screen to the right
b           noaction ESC-( x 3  the panes on the screen to the left

noaction does nothing and then types the keys after it, here ESC-) three times. It cannot type the arrow keys, so ESC-) and ESC-( are given the same actions as the right and left arrow. In LESSKEY_CONTENT, they are in one line, joined by ;, as h left-scroll;l right-scroll;..., and space is written \ , a backslash and a space. With less 710 or later, l, ., the right arrow and ESC-) are right-limit-scroll, which stops at the right end. A count before . is taken for a decimal point of the number by less; give it to the right arrow instead, as 3 and the right arrow.

The help of less on h and H is then on no key, and g and G no longer go to the first and the last line, which are on the screen all the time anyway.

When LESSKEY_CONTENT is set, the keys are added after it, in a #command section, so that they win over the same keys there and in ~/.lesskey; the other keys stay as they are.

NUP_LESSKEY gives the keys in place of those of nup, in the same way, and they do not change with the panes or the less. Set it empty not to add any keys, and LESSKEY_CONTENT is left as it is:

export NUP_LESSKEY=

The options are added to NUP_PAGER, NUP_PAGE_PAGER and --pager as well when the command is less; another pager is used as it is, and has to be told not to wrap the lines.

See "LESS INTEGRATION" for what works with the versions of less, and for the build of less in tecolicom/tap, with which the screens are the same as without -L.

nup -L man perlfunc
nup -L -C4 README.md

With more than one file, or -V, the files side by side go on to the right in the same way, instead of going on below: each file is a column of its own, without pages, and as many columns as without this option are on the screen. The lines move up and down as usual, and only h, l, ,, ., the arrow keys, ESC-( and ESC-), H, L, < and > are put in LESSKEY_CONTENT, to move by one column and to the ends; g and G go to the first and the last line.

nup -L *.txt

With --no-paginate and one input, which has nothing to put on the right, this option is ignored. It cannot be used with rows (-R, -C2,2, -G) or PDF output (-T, -o with .pdf). --auto-paginate is ignored. The pages are laid out once, for the height of the terminal at that time.

-H, --filename

Show filename headers in file view mode. Enabled by default. Use --no-filename to disable.

Layout Options

-C C[,R], --pane=C[,R]

Set the number of columns (panes), and the number of rows when it is given after a comma. For example, -C2 creates 2 columns, and -C2,3 creates 2 columns and 3 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 grid layout. -G2x3 is equivalent to -C2,3. This option is kept for compatibility and may be removed in the future.

-P N, --page=N

Set the page height in lines.

-S N, --pane-width=N

Set the pane width in characters. Default is 85.

Style Options

--bs=STYLE, --border-style=STYLE

Set the border style. Default is heavy-box.

--ls=STYLE, --line-style=STYLE

Set the line style. Available: none, truncate, wrap, wordwrap.

--runin=N, --runout=N, --runlen=N

Set the run-in and run-out widths that ansicolumn uses for line breaking (kinsoku) when it folds long lines. --runlen sets both. They are given to ansicolumn after the values in ~/.ansicolumnrc, so they take precedence. Without them, ansicolumn uses the values in ~/.ansicolumnrc, or 2.

--boundary=word|space|none

Set where ansicolumn may break a line when it folds long lines, as its --boundary option: word does not break inside an alphanumeric word, space not inside a sequence of non-space characters, and none breaks anywhere. Like --runin, it is given to ansicolumn after ~/.ansicolumnrc. Without it, ansicolumn uses the value in the rc file, or word in document mode.

--cm=SPEC, --colormap=SPEC

Set color mapping. Specify as LABEL=COLOR (e.g., --cm=BORDER=R). Available labels: TEXT, BORDER.

--[no-]page-number

Show page number on the bottom border of each column. Enabled by default. Use --no-page-number to disable.

--white-board, --black-board, --green-board, --slate-board

Predefined color schemes for board-style display.

Text Conversion

--textconv[=EXT,...]

Enable text conversion for non-text files using App::optex::textconv. When any of the specified file extensions are found in the arguments, the textconv module is loaded to convert them to text before display.

Default extensions: pdf,docx,docm,pptx,pptm,xlsx,xlsm,jpg,jpeg.

Use --textconv=none to disable.

Pager Options

--pager=COMMAND

Set the pager command. Default is NUP_PAGER or less -F +Gg. When page mode is active, NUP_PAGE_PAGER takes precedence over NUP_PAGER. Viewing multiple files (or -V parallel view) produces parallel layout which has no page structure, so nup disables page mode and NUP_PAGE_PAGER is not used there. The PAGER variable is not used to avoid an infinite loop when PAGER is set to nup. +Gg makes less read all input before displaying, so that -F and the percentage work; see "LESS INTEGRATION" for the settings of less.

Use --pager= (empty) or --no-pager to disable pager.

--no-pager

Disable pager.

PDF Output

-T DEVICE, --device=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 by ansi2pdf, instead of being shown on the terminal.

The name of a paper is the one for the -p option of ansi2pdf, such as a4, a3, b5 or letter. A paper is used in landscape orientation. The letter p or l after the name gives the orientation: a4p is A4 in portrait, and a4l is A4 in landscape. The device pdf is the default paper of ansi2pdf, A4.

nup -T a4 man nup > nup.pdf     # A4, landscape
nup -T a4p -C1 man nup | lpr    # A4, portrait

A sheet of paper takes the place of the terminal, and ansi2pdf takes the place of the pager. The size of a sheet in columns and lines is asked to ansi2pdf, the output is formatted for that size in the same way as for a terminal, and each screen is printed on a sheet as it is. The default is a landscape A4 sheet of 60 lines, which has room for two panes of the default width.

-o FILE, --output=FILE

Write the output to FILE. When the name ends with .pdf, the output is PDF without -T as well.

nup -o nup.pdf man nup          # A4, landscape
nup -T a3 -o nup.pdf man nup    # A3, landscape

Otherwise, what is shown on the terminal is written to the file as it is, with the ANSI sequences and in the size of the terminal, and the pager is not used. -T tty does so for a name ending with .pdf as well.

nup -o nup.txt man nup          # the same as --no-pager > nup.txt
--geometry

Print the size of the device in columns and lines and its kind, tty or pdf, and exit. No file is read and no command is run.

$ nup -T a4p --geometry
100 60 pdf
$ nup -o nup.pdf -P 80 --geometry
275 80 pdf

For a paper, the size is that of a sheet, which follows -T, -o, -P, the number of rows, --pdf-opts and -w of ansicolumn given after the file names. For the terminal, it is the size of the terminal. This is for a program that formats text before giving it to nup, as mdee(1) does.

--pdf-opts=OPTIONS

Give other options to ansi2pdf, such as the number of lines on a sheet, the margin and the fonts. They are given after the paper, so they take precedence.

nup -o nup.pdf --pdf-opts='-l 80 -m 15' man nup

The -P option sets the number of lines of a page for PDF as well: a sheet has that many lines for each row. The -w option of ansicolumn, given after the files or the command, sets 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. With neither of them, a sheet has 60 lines.

nup -o nup.pdf -P 80 man nup         # 80 lines on a sheet
nup -o nup.pdf -C2,2 -P 40 man nup   # 2x2 pages of 40 lines
nup -o nup.pdf -C3 file -w 300       # 300 columns on a sheet

Terminal Size

The terminal size is taken from the controlling terminal (/dev/tty). When it is not available, as when nup is run without a terminal, the COLUMNS environment variable gives the width (default 80), and LINES gives the height (default 24) used to split the screen when the number of rows is set, as in -C2,2:

COLUMNS=170 nup -C2 file1.txt file2.txt

LESS INTEGRATION

nup is made to be used with less. It sets environment variables for less (see "ENVIRONMENT"), and adds options to it for -L. Some of them need a recent version, and a patched build of less does more for the pages of nup.

Versions

less 590

--file-size makes less read all input before displaying, as +Gg of the default pager does. The less 581 of macOS does not have it, so +Gg is the default. Set NUP_PAGER to use it:

export NUP_PAGER="less --file-size"
less 661

LESSKEY_CONTENT is read, which -L uses to put its keys: h, l, ,, ., the arrow keys, ESC-( and ESC-), H, L, g, G, <, >, space and b. An older less ignores it.

less 710

right-limit-scroll stops at the right end of the lines. -L puts it on l, ., the right arrow and ESC-), in place of right-scroll, which goes on past the end.

-L runs less --align-shift --version to see the version of less, and whether it has the option below.

The Build in tecolicom/tap

tecolicom/tap has a build of less with patches for the pages of nup (kaz-utashiro/less). It adds two options:

--align-record=N

A search shows the whole record (page) that has the match from the top of the screen, instead of the matching line, so that the pages stay in place. N is the lines of a record; -1 is the height of the screen less the prompt line, which is the height of the pages of nup. A repeated search goes on from the next record.

--align-shift

The horizontal shift stays at a multiple of the --shift amount, the width of a pane with -L, so that the panes are always at the edge of the screen. -L adds this option when the less has it, and the screens are then the same as without -L: space, b, G and > move by the screens, the last screen shows the last pages and the rest of it is blank, and n and N skip the matches on the screen and move by the screens to the next page that has one. l, . and the right arrow go on until the last page is at the left edge. For this, the keys of -L are given a count instead of being repeated: with three panes, space and b are 3 ESC-) and 3 ESC-(, and G and > are 3L, while L shows the end of the row at the right edge of the screen.

Install it with Homebrew. It cannot be installed together with the less of Homebrew itself, which has the same command name:

brew install tecolicom/tap/less

Then use --align-record for the pages:

export NUP_PAGER="less --file-size"
export NUP_PAGE_PAGER="less --file-size --align-record=-1"

ENVIRONMENT

Read by nup

NUP_OPTS

Options given before those on the command line, separated by spaces, so that the options on the command line take precedence. This is useful when nup is called by another command, as MANPAGER:

NUP_OPTS=-L man perlfunc
NUP_PAGER

The pager command, used when --pager is not given. Default: less -F +Gg. See --pager in "Pager Options".

NUP_PAGE_PAGER

The pager command in page mode, used in place of NUP_PAGER. See --pager in "Pager Options".

NUP_LESSKEY

The keys that -L gives to less, in place of those of nup. Empty for no keys. See -L in "General Options".

COLUMNS, LINES

The width and the height of the terminal when /dev/tty is not available. See "Terminal Size".

PAGER is not read, so that it can be set to nup.

Set by nup

These are set for less, when they are not set already:

LESS

Default: -R. Required for ANSI color sequences.

LESSANSIENDCHARS

Default: mK. Recognizes SGR (m) and erase line (K) sequences.

-L adds its keys to LESSKEY_CONTENT, after those already in it. See -L in "General Options".

EXAMPLES

Typical n-up usage:

nup man nup                # view manual in n-up layout
nup -C2 man perl           # 2 columns
nup -C2,2 man perl         # 2x2 grid (4-up layout)
nup -F man perl            # no pagination
nup -L man perl            # one row of pages, scrolled sideways
nup -L -C4 man perl        # four pages on the screen at a time
nup -L *.txt               # files side by side, scrolled sideways
nup file1.txt file2.txt    # view files side by side
nup -C2 a.txt b.txt -w 170 # 2 columns, width 170 (ansicolumn -w)
nup -e ./script.sh         # force command mode for a file
nup -o nup.pdf man nup     # print to PDF (requires ansi2pdf)
nup -T a4p -C1 file | lpr  # print on A4 in portrait

Using nup as a MANPAGER:

export MANPAGER="nup -A"

INSTALLATION

Homebrew

Use tecolicom/tap:

brew tap tecolicom/tap
brew install app-nup

See "LESS INTEGRATION" for the build of less in the same tap.

CPAN

Using cpanminus:

cpanm -n App::nup

DIAGNOSTICS

Both stdout and stderr of the command are merged and passed through the n-up output filter. Error messages will appear in the paged output.

EXIT STATUS

The exit status of the executed command is not preserved because the output is passed through a filter pipeline.

SEE ALSO

App::optex::up (bundled), optex

AUTHOR

Kazumasa Utashiro

LICENSE

Copyright 2025-2026 Kazumasa Utashiro.

This software is released under the MIT License. https://opensource.org/licenses/MIT