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
 -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")
     --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.11

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 Environment Variables

nup sets the following environment variables when they are not already defined, to ensure proper display with less:

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

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