Actions Status MetaCPAN Release

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
--hi --highlight[=#]    syntax highlight of files (default: on)
     --no-highlight     disable syntax highlight (--no-hi)
     --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

Layout Options

Style Options

Text Conversion

Pager Options

PDF Output

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

-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:

app-nup of the tap has it inside, and nup of app-nup runs it. It is put apart from the commands of Homebrew, so the less of Homebrew itself stays as it is. To use it as less outside of nup, install it on its own; it cannot be installed together with the less of Homebrew, which has the same command name:

brew install tecolicom/tap/less

With either, 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

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:

-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

It comes with the build of less in the same tap, which nup runs; see "LESS INTEGRATION".

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