| 1 | package App::nup; | ||
| 2 | |||
| 3 | 1 | our $VERSION = "1.20"; | |
| 4 | |||
| 5 | 1 | 1; | |
| 6 | =encoding utf-8 | ||
| 7 | |||
| 8 | =head1 NAME | ||
| 9 | |||
| 10 | nup - n-up, multi-column paged output for commands and files | ||
| 11 | |||
| 12 | =head1 SYNOPSIS | ||
| 13 | |||
| 14 | nup [ options ] file ... | ||
| 15 | nup -e [ options ] command ... | ||
| 16 | |||
| 17 | -h --help show help | ||
| 18 | --version show version | ||
| 19 | -d --debug debug mode | ||
| 20 | -n --dryrun dry-run mode | ||
| 21 | -e --exec execute command mode | ||
| 22 | --alias=CMD=OPTS set command alias | ||
| 23 | -V --parallel parallel view mode | ||
| 24 | -D --document document mode (default: on) | ||
| 25 | -F --no-paginate disable page mode | ||
| 26 | -A --auto-paginate auto disable page mode for single column | ||
| 27 | -L --lateral pages or files in one row, scrolled sideways | ||
| 28 | -H --filename show filename headers (default: on) | ||
| 29 | -C --pane=#[,#] number of columns, and rows (e.g., 2,2) | ||
| 30 | -P --page=# page height in lines | ||
| 31 | -S --pane-width=# pane width (default: 85) | ||
| 32 | --bs --border-style=# border style (default: heavy-box) | ||
| 33 | --ls --line-style=# line style (none/truncate/wrap/wordwrap) | ||
| 34 | --runin=# run-in width for line breaking | ||
| 35 | --runout=# run-out width for line breaking | ||
| 36 | --runlen=# set both run-in and run-out | ||
| 37 | --boundary=# fold boundary: word, space or none | ||
| 38 | --cm --colormap=# color mapping (LABEL=COLOR) | ||
| 39 | --[no-]page-number page number on border (default: on) | ||
| 40 | --textconv[=EXT] textconv for non-text files | ||
| 41 | --hi --highlight[=#] syntax highlight of files (default: on) | ||
| 42 | --no-highlight disable syntax highlight (--no-hi) | ||
| 43 | --pager=# pager command (empty to disable) | ||
| 44 | --no-pager disable pager | ||
| 45 | -T --device=# output device: tty, pdf, or a paper for PDF | ||
| 46 | (e.g., a4, a4p, a3l) | ||
| 47 | -o --output=FILE output file (PDF when it ends with .pdf) | ||
| 48 | --pdf-opts=# options for ansi2pdf (e.g., "-l 80") | ||
| 49 | --geometry print the size and the kind of the device | ||
| 50 | --white-board black on white board | ||
| 51 | --black-board white on black board | ||
| 52 | --green-board white on green board | ||
| 53 | --slate-board white on dark slate board | ||
| 54 | |||
| 55 | =head1 VERSION | ||
| 56 | |||
| 57 | Version 1.20 | ||
| 58 | |||
| 59 | =cut | ||
| 60 | =head1 DESCRIPTION | ||
| 61 | |||
| 62 | B<N-up> (command: C<nup>) is a multi-column paged output tool. | ||
| 63 | It provides a convenient way to view files or run commands in | ||
| 64 | n-up layout using the L<App::optex::up> module through C<optex>. | ||
| 65 | |||
| 66 | =begin html | ||
| 67 | |||
| 68 | <p><img width="750" src="https://raw.githubusercontent.com/tecolicom/App-nup/main/images/nup.png"></p> | ||
| 69 | |||
| 70 | =end html | ||
| 71 | |||
| 72 | C<nup> automatically detects the mode based on the first argument: | ||
| 73 | if it is an existing file, n-up file view mode is used; if it is an | ||
| 74 | executable command, n-up command mode is used. Use C<-e> option to | ||
| 75 | force command mode when needed. | ||
| 76 | |||
| 77 | In file view mode, C<nup> stops parsing its own options at the first | ||
| 78 | file name and hands the file names and everything after them to | ||
| 79 | L<ansicolumn> unchanged. Options of C<ansicolumn> that C<nup> does | ||
| 80 | not provide can therefore be given after the file names: | ||
| 81 | |||
| 82 | nup -C2 file1.txt file2.txt -w 170 | ||
| 83 | |||
| 84 | Here C<-w 170> sets the output width for C<ansicolumn>. To set the | ||
| 85 | width when no terminal is available, the C<COLUMNS> environment | ||
| 86 | variable works in both modes; see L</Terminal Size>. | ||
| 87 | |||
| 88 | =head1 OPTIONS | ||
| 89 | |||
| 90 | =head2 General Options | ||
| 91 | |||
| 92 | =over 4 | ||
| 93 | |||
| 94 | =item B<-h>, B<--help> | ||
| 95 | |||
| 96 | Show help message. | ||
| 97 | |||
| 98 | =item B<--version> | ||
| 99 | |||
| 100 | Show version. | ||
| 101 | |||
| 102 | =item B<-d>, B<--debug> | ||
| 103 | |||
| 104 | Enable debug mode. | ||
| 105 | |||
| 106 | =item B<-n>, B<--dryrun> | ||
| 107 | |||
| 108 | Dry-run mode. Show the command without executing. | ||
| 109 | |||
| 110 | =item B<-e>, B<--exec> | ||
| 111 | |||
| 112 | Force command execution mode. Normally the mode is auto-detected, | ||
| 113 | but use this option when you want to execute a file as a command. | ||
| 114 | |||
| 115 | =item B<--alias>=I<NAME>=I<CMD> I<OPTS>... | ||
| 116 | |||
| 117 | Define command alias. When a command matches I<NAME>, it is replaced | ||
| 118 | by I<CMD> with specified I<OPTS>. This can be used to add default | ||
| 119 | options or to substitute a different command. | ||
| 120 | Multiple C<--alias> options can be specified. | ||
| 121 | |||
| 122 | Default aliases: | ||
| 123 | |||
| 124 | bat bat --style=plain --color=always | ||
| 125 | batcat batcat --style=plain --color=always | ||
| 126 | mdcat mdcat --ansi | ||
| 127 | rg rg --color=always | ||
| 128 | tree tree -C | ||
| 129 | |||
| 130 | Example: | ||
| 131 | |||
| 132 | nup --alias='grep=ggrep --color=always' grep pattern file | ||
| 133 | |||
| 134 | =item B<-V>, B<--parallel> | ||
| 135 | |||
| 136 | Enable parallel view mode for ansicolumn. In this mode, each file | ||
| 137 | is displayed in its own column without pagination, similar to | ||
| 138 | C<--no-paginate>. Automatically enabled when multiple files are | ||
| 139 | specified. Single file or stdin input results in single column | ||
| 140 | output. | ||
| 141 | |||
| 142 | =item B<-D>, B<--document> | ||
| 143 | |||
| 144 | Enable document mode for ansicolumn. This mode is optimized for | ||
| 145 | viewing documents with n-up page-based layout. Enabled by default. | ||
| 146 | Use C<--no-document> to disable. | ||
| 147 | |||
| 148 | =for comment | ||
| 149 | --fold is accepted as an undocumented alias for backward compatibility | ||
| 150 | |||
| 151 | =item B<-F>, B<--no-paginate> | ||
| 152 | |||
| 153 | Disable page mode. Without pagination, the entire content is | ||
| 154 | split evenly across columns. Page mode is the default; use | ||
| 155 | B<--paginate> to re-enable if needed. | ||
| 156 | |||
| 157 | =item B<-A>, B<--auto-paginate> | ||
| 158 | |||
| 159 | Automatically disable page mode when only one column fits the | ||
| 160 | terminal. This is useful when using C<nup> as C<MANPAGER>, | ||
| 161 | where single-column page splitting wastes space. | ||
| 162 | |||
| 163 | =item B<-L>, B<--lateral> | ||
| 164 | |||
| 165 | Put all the pages in one row, however wide it becomes, instead of | ||
| 166 | filling the screen with as many panes as fit and going on below. | ||
| 167 | The row is as high as the screen, and it is seen by scrolling | ||
| 168 | sideways in the pager. | ||
| 169 | |||
| 170 | The screen shows the same number of panes as without this option: | ||
| 171 | as many as fit, or the number given by C<-C>. With C<-C4>, four | ||
| 172 | pages are on the screen at a time, each a quarter of it wide. | ||
| 173 | |||
| 174 | The page number has a triangle on each side, as C<◂ 2/12 ▸>, which | ||
| 175 | tells that the row can be scrolled in that direction: the triangle is | ||
| 176 | filled when there is a page there, and open at the end of the row | ||
| 177 | (C<◃ 1/12 ▸>). They are the C<%L> and C<%R> of the C<--label> option | ||
| 178 | of C<ansicolumn>; give other marks by C<--mark>, after the file names | ||
| 179 | (C<--mark RIGHT=E<gt>E<gt> --mark RIGHT_END=>). | ||
| 180 | |||
| 181 | When the pager is C<less>, C<nup> adds | ||
| 182 | C<< -S --shift=I<N> --rscroll=- >> to it, where I<N> is the width of | ||
| 183 | a pane: the lines are not wrapped, and the right and left arrow keys | ||
| 184 | move by one page. | ||
| 185 | |||
| 186 | C<nup> also puts the following keys in the C<LESSKEY_CONTENT> | ||
| 187 | environment variable, which C<less> 661 or later reads. With three panes on the | ||
| 188 | screen and a C<less> older than 710, they are: | ||
| 189 | |||
| 190 | h , left left-scroll one page to the left | ||
| 191 | l . right right-scroll one page to the right | ||
| 192 | H g < K no-scroll the left end of the row | ||
| 193 | L G > J end-scroll the right end of the row | ||
| 194 | space j down noaction ESC-) x 3 the panes on the screen to the right | ||
| 195 | d ^D return | ||
| 196 | b k up u ^U noaction ESC-( x 3 the panes on the screen to the left | ||
| 197 | |||
| 198 | The pages have the height of the screen, and there is nothing to | ||
| 199 | scroll down to: C<j> and C<k>, the down and up arrows, C<d> and C<u>, | ||
| 200 | C<^D> and C<^U>, and the return key go on to the | ||
| 201 | next and the previous screen, as space and C<b> do. | ||
| 202 | C<noaction> does nothing and then types the keys after it, here | ||
| 203 | ESC-) three times. It cannot type the arrow keys, so ESC-) and | ||
| 204 | ESC-( are given the same actions as the right and left arrow. In | ||
| 205 | C<LESSKEY_CONTENT>, they are in one line, joined by C<;>, as | ||
| 206 | C<h left-scroll;l right-scroll;...>, and space is written C<\ >, a | ||
| 207 | backslash and a space. | ||
| 208 | With C<less> 710 or later, C<l>, C<.>, the right arrow and ESC-) are | ||
| 209 | C<right-limit-scroll>, which stops at the right end. A count before | ||
| 210 | C<.> is taken for a decimal point of the number by C<less>; give it | ||
| 211 | to the right arrow instead, as C<3> and the right arrow. | ||
| 212 | |||
| 213 | The help of C<less> on C<h> and C<H> is then on no key, and C<g> and | ||
| 214 | C<G> no longer go to the first and the last line, which are on the | ||
| 215 | screen all the time anyway. | ||
| 216 | |||
| 217 | When C<LESSKEY_CONTENT> is set, the keys are added after it, in a | ||
| 218 | C<#command> section, so that they win over the same keys there and | ||
| 219 | in F<~/.lesskey>; the other keys stay as they are. | ||
| 220 | |||
| 221 | C<NUP_LESSKEY> gives the keys in place of those of C<nup>, in the | ||
| 222 | same way, and they do not change with the panes or the C<less>. Set | ||
| 223 | it empty not to add any keys, and C<LESSKEY_CONTENT> is left as it | ||
| 224 | is: | ||
| 225 | |||
| 226 | export NUP_LESSKEY= | ||
| 227 | |||
| 228 | The options are added to C<NUP_PAGER>, C<NUP_PAGE_PAGER> and | ||
| 229 | C<--pager> as well when the command is C<less>; another pager is used | ||
| 230 | as it is, and has to be told not to wrap the lines. | ||
| 231 | |||
| 232 | See L</"LESS INTEGRATION"> for what works with the versions of | ||
| 233 | C<less>, and for the build of C<less> in tecolicom/tap, with which | ||
| 234 | the screens are the same as without C<-L>. | ||
| 235 | |||
| 236 | nup -L man perlfunc | ||
| 237 | nup -L -C4 README.md | ||
| 238 | |||
| 239 | With more than one file, or C<-V>, the files side by side go on to | ||
| 240 | the right in the same way, instead of going on below: each file is a | ||
| 241 | column of its own, without pages, and as many columns as without this | ||
| 242 | option are on the screen. The lines move up and down as usual, and | ||
| 243 | only C<h>, C<l>, C<,>, C<.>, the arrow keys, ESC-( and ESC-), C<H>, | ||
| 244 | C<L>, C<E<lt>> and C<E<gt>> are put in C<LESSKEY_CONTENT>, to move by one column and to | ||
| 245 | the ends; C<g> and C<G> go to the first and the last line. | ||
| 246 | |||
| 247 | nup -L *.txt | ||
| 248 | |||
| 249 | With C<--no-paginate> and one input, which has nothing to put on the | ||
| 250 | right, this option is ignored. It cannot be used with rows (C<-R>, | ||
| 251 | C<-C2,2>, C<-G>) or PDF output (C<-T>, C<-o> with C<.pdf>). | ||
| 252 | C<--auto-paginate> is ignored. The pages are laid out once, for the | ||
| 253 | height of the terminal at that time. | ||
| 254 | |||
| 255 | =item B<-H>, B<--filename> | ||
| 256 | |||
| 257 | Show filename headers in file view mode. Enabled by default. | ||
| 258 | Use C<--no-filename> to disable. | ||
| 259 | |||
| 260 | =back | ||
| 261 | |||
| 262 | =head2 Layout Options | ||
| 263 | |||
| 264 | =over 4 | ||
| 265 | |||
| 266 | =item B<-C> I<C>[,I<R>], B<--pane>=I<C>[,I<R>] | ||
| 267 | |||
| 268 | Set the number of columns (panes), and the number of rows when it is | ||
| 269 | given after a comma. For example, C<-C2> creates 2 columns, and | ||
| 270 | C<-C2,3> creates 2 columns and 3 rows. | ||
| 271 | |||
| 272 | =item B<-R> I<N>, B<--row>=I<N> | ||
| 273 | |||
| 274 | Set the number of rows. | ||
| 275 | This option is kept for compatibility and may be removed in the | ||
| 276 | future. | ||
| 277 | |||
| 278 | =item B<-G> I<CxR>, B<--grid>=I<CxR> | ||
| 279 | |||
| 280 | Set grid layout. C<-G2x3> is equivalent to C<-C2,3>. | ||
| 281 | This option is kept for compatibility and may be removed in the | ||
| 282 | future. | ||
| 283 | |||
| 284 | =item B<-P> I<N>, B<--page>=I<N> | ||
| 285 | |||
| 286 | Set the page height in lines. | ||
| 287 | |||
| 288 | =item B<-S> I<N>, B<--pane-width>=I<N> | ||
| 289 | |||
| 290 | Set the pane width in characters. Default is 85. | ||
| 291 | |||
| 292 | =back | ||
| 293 | |||
| 294 | =head2 Style Options | ||
| 295 | |||
| 296 | =over 4 | ||
| 297 | |||
| 298 | =item B<--bs>=I<STYLE>, B<--border-style>=I<STYLE> | ||
| 299 | |||
| 300 | Set the border style. Default is C<heavy-box>. | ||
| 301 | |||
| 302 | =item B<--ls>=I<STYLE>, B<--line-style>=I<STYLE> | ||
| 303 | |||
| 304 | Set the line style. Available: C<none>, C<truncate>, C<wrap>, C<wordwrap>. | ||
| 305 | |||
| 306 | =item B<--runin>=I<N>, B<--runout>=I<N>, B<--runlen>=I<N> | ||
| 307 | |||
| 308 | Set the run-in and run-out widths that L<ansicolumn> uses for line | ||
| 309 | breaking (kinsoku) when it folds long lines. C<--runlen> sets both. | ||
| 310 | They are given to ansicolumn after the values in F<~/.ansicolumnrc>, | ||
| 311 | so they take precedence. Without them, ansicolumn uses the values in | ||
| 312 | F<~/.ansicolumnrc>, or 2. | ||
| 313 | |||
| 314 | =item B<--boundary>=C<word>|C<space>|C<none> | ||
| 315 | |||
| 316 | Set where L<ansicolumn> may break a line when it folds long lines, as | ||
| 317 | its C<--boundary> option: C<word> does not break inside an | ||
| 318 | alphanumeric word, C<space> not inside a sequence of non-space | ||
| 319 | characters, and C<none> breaks anywhere. Like C<--runin>, it is | ||
| 320 | given to ansicolumn after F<~/.ansicolumnrc>. Without it, ansicolumn | ||
| 321 | uses the value in the rc file, or C<word> in document mode. | ||
| 322 | |||
| 323 | =item B<--cm>=I<SPEC>, B<--colormap>=I<SPEC> | ||
| 324 | |||
| 325 | Set color mapping. Specify as C<LABEL=COLOR> (e.g., C<--cm=BORDER=R>). | ||
| 326 | Available labels: C<TEXT>, C<BORDER>. | ||
| 327 | |||
| 328 | =item B<-->[B<no->]B<page-number> | ||
| 329 | |||
| 330 | Show page number on the bottom border of each column, with the number | ||
| 331 | of all the pages, as C<3/12>. With the | ||
| 332 | files side by side (more than one file, or C<-V>), which can be long, | ||
| 333 | it is shown on the top border as well, at the left, under the file | ||
| 334 | name. Enabled by default. Use | ||
| 335 | C<--no-page-number> to disable. | ||
| 336 | |||
| 337 | =item B<--white-board>, B<--black-board>, B<--green-board>, B<--slate-board> | ||
| 338 | |||
| 339 | Predefined color schemes for board-style display. | ||
| 340 | |||
| 341 | =back | ||
| 342 | |||
| 343 | =head2 Text Conversion | ||
| 344 | |||
| 345 | =over 4 | ||
| 346 | |||
| 347 | =item B<--textconv>[=I<EXT,...>] | ||
| 348 | |||
| 349 | Enable text conversion for non-text files using | ||
| 350 | L<App::optex::textconv>. When any of the specified file extensions | ||
| 351 | are found in the arguments, the C<textconv> module is loaded to | ||
| 352 | convert them to text before display. | ||
| 353 | |||
| 354 | Default extensions: | ||
| 355 | C<pdf,docx,docm,pptx,pptm,xlsx,xlsm,jpg,jpeg>. | ||
| 356 | |||
| 357 | Use C<--textconv=none> to disable. | ||
| 358 | |||
| 359 | =item B<--hi>, B<--highlight>[=I<NAME>], B<--no-highlight> | ||
| 360 | |||
| 361 | Color the source files by their syntax in file view mode. Enabled | ||
| 362 | by default, and done when the command of the highlighter and | ||
| 363 | L<Text::ANSI::Highlight::IO> are installed; nothing changes without | ||
| 364 | them. | ||
| 365 | C<ansicolumn> reads each file through the highlighter, with the language | ||
| 366 | told from the name of the file, or from the first line of a script. | ||
| 367 | In a Markdown file, the code in a fence is colored by the language of | ||
| 368 | the fence. | ||
| 369 | A file whose language is not known is shown as it is, and so is a | ||
| 370 | file which has ANSI sequences already. The file names in the headers | ||
| 371 | are not changed. | ||
| 372 | |||
| 373 | I<NAME> is the highlighter: | ||
| 374 | |||
| 375 | pandoc pandoc, by its ansi writer (default) | ||
| 376 | sourcehighlight, gnu source-highlight of GNU Source-highlight, | ||
| 377 | the colors of less | ||
| 378 | skylighting, sky the skylighting command | ||
| 379 | |||
| 380 | brew install pandoc | ||
| 381 | brew install source-highlight | ||
| 382 | brew install skylighting | ||
| 383 | |||
| 384 | Set the one to use in C<NUP_OPTS>: | ||
| 385 | |||
| 386 | export NUP_OPTS=--highlight=sourcehighlight | ||
| 387 | |||
| 388 | Use C<--no-highlight> to disable. C<--hi> is the short name of the | ||
| 389 | option, and C<sky> and C<gnu> are those of the highlighters: | ||
| 390 | C<--hi=gnu>, C<--no-hi>. | ||
| 391 | |||
| 392 | =back | ||
| 393 | |||
| 394 | =head2 Pager Options | ||
| 395 | |||
| 396 | =over 4 | ||
| 397 | |||
| 398 | =item B<--pager>=I<COMMAND> | ||
| 399 | |||
| 400 | Set the pager command. Default is C<NUP_PAGER> or C<less -F +Gg>. | ||
| 401 | When page mode is active, C<NUP_PAGE_PAGER> takes precedence over | ||
| 402 | C<NUP_PAGER>. | ||
| 403 | Viewing multiple files (or C<-V> parallel view) produces parallel | ||
| 404 | layout which has no page structure, so C<nup> disables page mode | ||
| 405 | and C<NUP_PAGE_PAGER> is not used there. | ||
| 406 | The C<PAGER> variable is not used to avoid an infinite loop when | ||
| 407 | C<PAGER> is set to C<nup>. | ||
| 408 | C<+Gg> makes C<less> read all input before displaying, so that C<-F> | ||
| 409 | and the percentage work; see L</"LESS INTEGRATION"> for the settings | ||
| 410 | of C<less>. | ||
| 411 | |||
| 412 | Use C<--pager=> (empty) or C<--no-pager> to disable pager. | ||
| 413 | |||
| 414 | =item B<--no-pager> | ||
| 415 | |||
| 416 | Disable pager. | ||
| 417 | |||
| 418 | =back | ||
| 419 | |||
| 420 | =head2 PDF Output | ||
| 421 | |||
| 422 | =over 4 | ||
| 423 | |||
| 424 | =item B<-T> I<DEVICE>, B<--device>=I<DEVICE> | ||
| 425 | |||
| 426 | Set the device to show the output on. The default is C<tty>, the | ||
| 427 | terminal. Any other device is a paper, and the output is printed to | ||
| 428 | PDF by C<ansi2pdf>, instead of being shown on the terminal. | ||
| 429 | |||
| 430 | The name of a paper is the one for the C<-p> option of C<ansi2pdf>, | ||
| 431 | such as C<a4>, C<a3>, C<b5> or C<letter>. A paper is used in | ||
| 432 | landscape orientation. The letter C<p> or C<l> after the name gives | ||
| 433 | the orientation: C<a4p> is A4 in portrait, and C<a4l> is A4 in | ||
| 434 | landscape. The device C<pdf> is the default paper of C<ansi2pdf>, A4. | ||
| 435 | |||
| 436 | nup -T a4 man nup > nup.pdf # A4, landscape | ||
| 437 | nup -T a4p -C1 man nup | lpr # A4, portrait | ||
| 438 | |||
| 439 | A sheet of paper takes the place of the terminal, and C<ansi2pdf> | ||
| 440 | takes the place of the pager. The size of a sheet in columns and | ||
| 441 | lines is asked to C<ansi2pdf>, the output is formatted for that size | ||
| 442 | in the same way as for a terminal, and each screen is printed on a | ||
| 443 | sheet as it is. The default is a landscape A4 sheet of 60 lines, | ||
| 444 | which has room for two panes of the default width. | ||
| 445 | |||
| 446 | =item B<-o> I<FILE>, B<--output>=I<FILE> | ||
| 447 | |||
| 448 | Write the output to I<FILE>. When the name ends with C<.pdf>, the | ||
| 449 | output is PDF without C<-T> as well. | ||
| 450 | |||
| 451 | nup -o nup.pdf man nup # A4, landscape | ||
| 452 | nup -T a3 -o nup.pdf man nup # A3, landscape | ||
| 453 | |||
| 454 | Otherwise, what is shown on the terminal is written to the file as it | ||
| 455 | is, with the ANSI sequences and in the size of the terminal, and the | ||
| 456 | pager is not used. C<-T tty> does so for a name ending with C<.pdf> | ||
| 457 | as well. | ||
| 458 | |||
| 459 | nup -o nup.txt man nup # the same as --no-pager > nup.txt | ||
| 460 | |||
| 461 | =item B<--geometry> | ||
| 462 | |||
| 463 | Print the size of the device in columns and lines and its kind, | ||
| 464 | C<tty> or C<pdf>, and exit. No file is read and no command is run. | ||
| 465 | |||
| 466 | $ nup -T a4p --geometry | ||
| 467 | 100 60 pdf | ||
| 468 | $ nup -o nup.pdf -P 80 --geometry | ||
| 469 | 275 80 pdf | ||
| 470 | |||
| 471 | For a paper, the size is that of a sheet, which follows C<-T>, C<-o>, | ||
| 472 | C<-P>, the number of rows, C<--pdf-opts> and C<-w> of C<ansicolumn> | ||
| 473 | given after the file names. For the terminal, it is the size of the | ||
| 474 | terminal. This is for a program that formats text before giving it | ||
| 475 | to C<nup>, as L<mdee(1)|App::mdee> does. | ||
| 476 | |||
| 477 | =item B<--pdf-opts>=I<OPTIONS> | ||
| 478 | |||
| 479 | Give other options to C<ansi2pdf>, such as the number of lines on a | ||
| 480 | sheet, the margin and the fonts. They are given after the paper, so | ||
| 481 | they take precedence. | ||
| 482 | |||
| 483 | nup -o nup.pdf --pdf-opts='-l 80 -m 15' man nup | ||
| 484 | |||
| 485 | =back | ||
| 486 | |||
| 487 | The C<-P> option sets the number of lines of a page for PDF as well: | ||
| 488 | a sheet has that many lines for each row. The C<-w> option of | ||
| 489 | C<ansicolumn>, given after the files or the command, sets the number | ||
| 490 | of columns of a sheet. The font size follows them, and the one that | ||
| 491 | is not given is decided to fill the sheet. With neither of them, a | ||
| 492 | sheet has 60 lines. | ||
| 493 | |||
| 494 | nup -o nup.pdf -P 80 man nup # 80 lines on a sheet | ||
| 495 | nup -o nup.pdf -C2,2 -P 40 man nup # 2x2 pages of 40 lines | ||
| 496 | nup -o nup.pdf -C3 file -w 300 # 300 columns on a sheet | ||
| 497 | |||
| 498 | =head2 Terminal Size | ||
| 499 | |||
| 500 | The terminal size is taken from the controlling terminal | ||
| 501 | (C</dev/tty>). When it is not available, as when C<nup> is run | ||
| 502 | without a terminal, the C<COLUMNS> environment variable gives the | ||
| 503 | width (default 80), and C<LINES> gives the height (default 24) used | ||
| 504 | to split the screen when the number of rows is set, as in C<-C2,2>: | ||
| 505 | |||
| 506 | COLUMNS=170 nup -C2 file1.txt file2.txt | ||
| 507 | |||
| 508 | =head1 LESS INTEGRATION | ||
| 509 | |||
| 510 | C<nup> is made to be used with C<less>. It sets environment | ||
| 511 | variables for C<less> (see L</ENVIRONMENT>), and adds options to it | ||
| 512 | for C<-L>. Some of them need a recent version, and a patched build | ||
| 513 | of C<less> does more for the pages of C<nup>. | ||
| 514 | |||
| 515 | The pages fill the screen and go on below, and a line down would show | ||
| 516 | them cut in the middle. So C<j> and C<k>, the down and up arrows, | ||
| 517 | C<d> and C<u>, C<^D> and C<^U>, and the return key | ||
| 518 | move by the screen, as space and C<b> do, when the output has pages | ||
| 519 | and the pager is C<less> 661 or later, and C<J> and C<K> go to the | ||
| 520 | last and the first page, as C<G> and C<g>. The keys are put in | ||
| 521 | C<LESSKEY_CONTENT>, in the way C<-L> does, and not when C<NUP_LESSKEY> | ||
| 522 | is set. Without pages (C<-F>, or the files side by side), they move | ||
| 523 | by the line as usual. C<e> and C<y> are left to move by the line. | ||
| 524 | |||
| 525 | =head2 Versions | ||
| 526 | |||
| 527 | =over 4 | ||
| 528 | |||
| 529 | =item C<less> 590 | ||
| 530 | |||
| 531 | C<--file-size> makes C<less> read all input before displaying, as | ||
| 532 | C<+Gg> of the default pager does. The C<less> 581 of macOS does not | ||
| 533 | have it, so C<+Gg> is the default. Set C<NUP_PAGER> to use it: | ||
| 534 | |||
| 535 | export NUP_PAGER="less --file-size" | ||
| 536 | |||
| 537 | =item C<less> 661 | ||
| 538 | |||
| 539 | C<LESSKEY_CONTENT> is read, which C<-L> uses to put its keys: | ||
| 540 | C<h>, C<l>, C<,>, C<.>, the arrow keys, ESC-( and ESC-), C<H>, C<L>, C<g>, C<G>, | ||
| 541 | C<E<lt>>, C<E<gt>>, space, C<b>, C<j>, C<k>, C<d>, C<u>, C<^D>, C<^U>, | ||
| 542 | the return key, C<J> and C<K>. | ||
| 543 | Without C<-L>, the keys are C<j>, C<k>, the down and up arrows, C<d>, | ||
| 544 | C<u>, C<^D>, C<^U>, the return key, C<J> and C<K>. | ||
| 545 | An older C<less> ignores it. | ||
| 546 | |||
| 547 | =item C<less> 710 | ||
| 548 | |||
| 549 | C<right-limit-scroll> stops at the right end of the lines. C<-L> | ||
| 550 | puts it on C<l>, C<.>, the right arrow and ESC-), in place of C<right-scroll>, | ||
| 551 | which goes on past the end. | ||
| 552 | |||
| 553 | =back | ||
| 554 | |||
| 555 | C<-L> runs C<less --align-shift --version> to see the version of | ||
| 556 | C<less>, and whether it has the option below. | ||
| 557 | |||
| 558 | =head2 The Build in tecolicom/tap | ||
| 559 | |||
| 560 | L<tecolicom/tap|https://github.com/tecolicom/homebrew-tap> has a build | ||
| 561 | of C<less> with patches for the pages of C<nup> | ||
| 562 | (L<kaz-utashiro/less|https://github.com/kaz-utashiro/less>). It adds | ||
| 563 | two options: | ||
| 564 | |||
| 565 | =over 4 | ||
| 566 | |||
| 567 | =item B<--align-record>=I<N> | ||
| 568 | |||
| 569 | A search shows the whole record (page) that has the match from the | ||
| 570 | top of the screen, instead of the matching line, so that the pages | ||
| 571 | stay in place. I<N> is the lines of a record; C<-1> is the height | ||
| 572 | of the screen less the prompt line, which is the height of the pages | ||
| 573 | of C<nup>. A repeated search goes on from the next record. | ||
| 574 | |||
| 575 | =item B<--align-shift> | ||
| 576 | |||
| 577 | The horizontal shift stays at a multiple of the C<--shift> amount, the | ||
| 578 | width of a pane with C<-L>, so that the panes are always at the edge | ||
| 579 | of the screen. C<-L> adds this option when the C<less> has it, and | ||
| 580 | the screens are then the same as without C<-L>: space, C<b>, C<G> and | ||
| 581 | C<E<gt>> move by the screens, the last screen shows the last pages | ||
| 582 | and the rest of it is blank, and C<n> and C<N> skip the matches on | ||
| 583 | the screen and move by the screens to the next page that has one. | ||
| 584 | C<l>, C<.> and the right arrow go on until the last page is at the left | ||
| 585 | edge. For this, the keys of C<-L> are given a count instead of being repeated: | ||
| 586 | with three panes, space and C<b>, and the keys which do the same, are | ||
| 587 | C<3> ESC-) and C<3> ESC-(, and | ||
| 588 | C<G> and C<E<gt>> are C<3L>, while C<L> shows the end of the row at | ||
| 589 | the right edge of the screen. | ||
| 590 | |||
| 591 | =back | ||
| 592 | |||
| 593 | C<app-nup> of the tap has it inside, and C<nup> of C<app-nup> runs it. | ||
| 594 | It is put apart from the commands of Homebrew, so the C<less> of | ||
| 595 | Homebrew itself stays as it is. To use it as C<less> outside of | ||
| 596 | C<nup>, install it on its own; it cannot be installed together with | ||
| 597 | the C<less> of Homebrew, which has the same command name: | ||
| 598 | |||
| 599 | brew install tecolicom/tap/less | ||
| 600 | |||
| 601 | With either, use C<--align-record> for the pages: | ||
| 602 | |||
| 603 | export NUP_PAGER="less --file-size" | ||
| 604 | export NUP_PAGE_PAGER="less --file-size --align-record=-1" | ||
| 605 | |||
| 606 | =head1 ENVIRONMENT | ||
| 607 | |||
| 608 | =head2 Read by C<nup> | ||
| 609 | |||
| 610 | =over 4 | ||
| 611 | |||
| 612 | =item C<NUP_OPTS> | ||
| 613 | |||
| 614 | Options given before those on the command line, separated by spaces, | ||
| 615 | so that the options on the command line take precedence. This is | ||
| 616 | useful when C<nup> is called by another command, as C<MANPAGER>: | ||
| 617 | |||
| 618 | NUP_OPTS=-L man perlfunc | ||
| 619 | |||
| 620 | =item C<NUP_PAGER> | ||
| 621 | |||
| 622 | The pager command, used when C<--pager> is not given. Default: | ||
| 623 | C<less -F +Gg>. See C<--pager> in L</"Pager Options">. | ||
| 624 | |||
| 625 | =item C<NUP_PAGE_PAGER> | ||
| 626 | |||
| 627 | The pager command in page mode, used in place of C<NUP_PAGER>. See | ||
| 628 | C<--pager> in L</"Pager Options">. | ||
| 629 | |||
| 630 | =item C<NUP_LESSKEY> | ||
| 631 | |||
| 632 | The keys that C<-L> gives to C<less>, in place of those of C<nup>. | ||
| 633 | Empty for no keys. See C<-L> in L</"General Options">. When it is | ||
| 634 | set, the keys of the pages without C<-L> are not added either. | ||
| 635 | |||
| 636 | =item C<COLUMNS>, C<LINES> | ||
| 637 | |||
| 638 | The width and the height of the terminal when C</dev/tty> is not | ||
| 639 | available. See L</Terminal Size>. | ||
| 640 | |||
| 641 | =back | ||
| 642 | |||
| 643 | C<PAGER> is not read, so that it can be set to C<nup>. | ||
| 644 | |||
| 645 | =head2 Set by C<nup> | ||
| 646 | |||
| 647 | These are set for C<less>, when they are not set already: | ||
| 648 | |||
| 649 | =over 4 | ||
| 650 | |||
| 651 | =item C<LESS> | ||
| 652 | |||
| 653 | Default: C<-R>. Required for ANSI color sequences. | ||
| 654 | |||
| 655 | =item C<LESSANSIENDCHARS> | ||
| 656 | |||
| 657 | Default: C<mK>. Recognizes SGR (C<m>) and erase line (C<K>) | ||
| 658 | sequences. | ||
| 659 | |||
| 660 | =back | ||
| 661 | |||
| 662 | C<-L> adds its keys to C<LESSKEY_CONTENT>, after those already in | ||
| 663 | it. See C<-L> in L</"General Options">. | ||
| 664 | |||
| 665 | =head1 EXAMPLES | ||
| 666 | |||
| 667 | Typical n-up usage: | ||
| 668 | |||
| 669 | nup man nup # view manual in n-up layout | ||
| 670 | nup -C2 man perl # 2 columns | ||
| 671 | nup -C2,2 man perl # 2x2 grid (4-up layout) | ||
| 672 | nup -F man perl # no pagination | ||
| 673 | nup -L man perl # one row of pages, scrolled sideways | ||
| 674 | nup -L -C4 man perl # four pages on the screen at a time | ||
| 675 | nup -L *.txt # files side by side, scrolled sideways | ||
| 676 | nup file1.txt file2.txt # view files side by side | ||
| 677 | nup -C2 a.txt b.txt -w 170 # 2 columns, width 170 (ansicolumn -w) | ||
| 678 | nup -e ./script.sh # force command mode for a file | ||
| 679 | nup -o nup.pdf man nup # print to PDF (requires ansi2pdf) | ||
| 680 | nup -T a4p -C1 file | lpr # print on A4 in portrait | ||
| 681 | |||
| 682 | Using C<nup> as a C<MANPAGER>: | ||
| 683 | |||
| 684 | export MANPAGER="nup -A" | ||
| 685 | |||
| 686 | =head1 INSTALLATION | ||
| 687 | |||
| 688 | =head2 Homebrew | ||
| 689 | |||
| 690 | Use L<tecolicom/tap|https://github.com/tecolicom/homebrew-tap>: | ||
| 691 | |||
| 692 | brew tap tecolicom/tap | ||
| 693 | brew install app-nup | ||
| 694 | |||
| 695 | It comes with the build of C<less> in the same tap, which C<nup> runs; | ||
| 696 | see L</"LESS INTEGRATION">. | ||
| 697 | |||
| 698 | =head2 CPAN | ||
| 699 | |||
| 700 | Using L<cpanminus|https://metacpan.org/pod/App::cpanminus>: | ||
| 701 | |||
| 702 | cpanm -n App::nup | ||
| 703 | |||
| 704 | =head1 DIAGNOSTICS | ||
| 705 | |||
| 706 | Both stdout and stderr of the command are merged and passed through | ||
| 707 | the n-up output filter. Error messages will appear in the paged output. | ||
| 708 | |||
| 709 | =head1 EXIT STATUS | ||
| 710 | |||
| 711 | The exit status of the executed command is not preserved because | ||
| 712 | the output is passed through a filter pipeline. | ||
| 713 | |||
| 714 | =head1 SEE ALSO | ||
| 715 | |||
| 716 | L<App::optex::up> (bundled), L<optex> | ||
| 717 | |||
| 718 | =head1 AUTHOR | ||
| 719 | |||
| 720 | Kazumasa Utashiro | ||
| 721 | |||
| 722 | =head1 LICENSE | ||
| 723 | |||
| 724 | Copyright © 2025-2026 Kazumasa Utashiro. | ||
| 725 | |||
| 726 | This software is released under the MIT License. | ||
| 727 | L<https://opensource.org/licenses/MIT> | ||
| 728 | |||
| 729 | =cut |