blib/lib/App/nup.pm

filter: Statementstmt 100% 2 / 2 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub n/a Podpod n/a totaltotal 100% 2 / 2 CC 0 SCAR 0
CC
0
Cov
0%
CRAP 0
« blib/lib/App/optex/up.pm ↑ Summary
1 package App::nup;
2  
3 1 our $VERSION = "1.21";
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.21
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 A style of the highlighter can be given after the name and a colon,
385 a name of its own or a file: C<--highlight=pandoc:breezedark> for a
386 dark screen, C<--hi=gnu:esc256>. See L<Text::ANSI::Highlight/STYLES>.
387  
388 Set the one to use in C<NUP_OPTS>:
389  
390 export NUP_OPTS=--highlight=sourcehighlight
391  
392 Use C<--no-highlight> to disable. C<--hi> is the short name of the
393 option, and C<sky> and C<gnu> are those of the highlighters:
394 C<--hi=gnu>, C<--no-hi>.
395  
396 =back
397  
398 =head2 Pager Options
399  
400 =over 4
401  
402 =item B<--pager>=I<COMMAND>
403  
404 Set the pager command. Default is C<NUP_PAGER> or C<less -F +Gg>.
405 When page mode is active, C<NUP_PAGE_PAGER> takes precedence over
406 C<NUP_PAGER>.
407 Viewing multiple files (or C<-V> parallel view) produces parallel
408 layout which has no page structure, so C<nup> disables page mode
409 and C<NUP_PAGE_PAGER> is not used there.
410 The C<PAGER> variable is not used to avoid an infinite loop when
411 C<PAGER> is set to C<nup>.
412 C<+Gg> makes C<less> read all input before displaying, so that C<-F>
413 and the percentage work; see L</"LESS INTEGRATION"> for the settings
414 of C<less>.
415  
416 Use C<--pager=> (empty) or C<--no-pager> to disable pager.
417  
418 =item B<--no-pager>
419  
420 Disable pager.
421  
422 =back
423  
424 =head2 PDF Output
425  
426 =over 4
427  
428 =item B<-T> I<DEVICE>, B<--device>=I<DEVICE>
429  
430 Set the device to show the output on. The default is C<tty>, the
431 terminal. Any other device is a paper, and the output is printed to
432 PDF by C<ansi2pdf>, instead of being shown on the terminal.
433  
434 The name of a paper is the one for the C<-p> option of C<ansi2pdf>,
435 such as C<a4>, C<a3>, C<b5> or C<letter>. A paper is used in
436 landscape orientation. The letter C<p> or C<l> after the name gives
437 the orientation: C<a4p> is A4 in portrait, and C<a4l> is A4 in
438 landscape. The device C<pdf> is the default paper of C<ansi2pdf>, A4.
439  
440 nup -T a4 man nup > nup.pdf # A4, landscape
441 nup -T a4p -C1 man nup | lpr # A4, portrait
442  
443 A sheet of paper takes the place of the terminal, and C<ansi2pdf>
444 takes the place of the pager. The size of a sheet in columns and
445 lines is asked to C<ansi2pdf>, the output is formatted for that size
446 in the same way as for a terminal, and each screen is printed on a
447 sheet as it is. The default is a landscape A4 sheet of 60 lines,
448 which has room for two panes of the default width.
449  
450 =item B<-o> I<FILE>, B<--output>=I<FILE>
451  
452 Write the output to I<FILE>. When the name ends with C<.pdf>, the
453 output is PDF without C<-T> as well.
454  
455 nup -o nup.pdf man nup # A4, landscape
456 nup -T a3 -o nup.pdf man nup # A3, landscape
457  
458 Otherwise, what is shown on the terminal is written to the file as it
459 is, with the ANSI sequences and in the size of the terminal, and the
460 pager is not used. C<-T tty> does so for a name ending with C<.pdf>
461 as well.
462  
463 nup -o nup.txt man nup # the same as --no-pager > nup.txt
464  
465 =item B<--geometry>
466  
467 Print the size of the device in columns and lines and its kind,
468 C<tty> or C<pdf>, and exit. No file is read and no command is run.
469  
470 $ nup -T a4p --geometry
471 100 60 pdf
472 $ nup -o nup.pdf -P 80 --geometry
473 275 80 pdf
474  
475 For a paper, the size is that of a sheet, which follows C<-T>, C<-o>,
476 C<-P>, the number of rows, C<--pdf-opts> and C<-w> of C<ansicolumn>
477 given after the file names. For the terminal, it is the size of the
478 terminal. This is for a program that formats text before giving it
479 to C<nup>, as L<mdee(1)|App::mdee> does.
480  
481 =item B<--pdf-opts>=I<OPTIONS>
482  
483 Give other options to C<ansi2pdf>, such as the number of lines on a
484 sheet, the margin and the fonts. They are given after the paper, so
485 they take precedence.
486  
487 nup -o nup.pdf --pdf-opts='-l 80 -m 15' man nup
488  
489 =back
490  
491 The C<-P> option sets the number of lines of a page for PDF as well:
492 a sheet has that many lines for each row. The C<-w> option of
493 C<ansicolumn>, given after the files or the command, sets the number
494 of columns of a sheet. The font size follows them, and the one that
495 is not given is decided to fill the sheet. With neither of them, a
496 sheet has 60 lines.
497  
498 nup -o nup.pdf -P 80 man nup # 80 lines on a sheet
499 nup -o nup.pdf -C2,2 -P 40 man nup # 2x2 pages of 40 lines
500 nup -o nup.pdf -C3 file -w 300 # 300 columns on a sheet
501  
502 =head2 Terminal Size
503  
504 The terminal size is taken from the controlling terminal
505 (C</dev/tty>). When it is not available, as when C<nup> is run
506 without a terminal, the C<COLUMNS> environment variable gives the
507 width (default 80), and C<LINES> gives the height (default 24) used
508 to split the screen when the number of rows is set, as in C<-C2,2>:
509  
510 COLUMNS=170 nup -C2 file1.txt file2.txt
511  
512 =head1 LESS INTEGRATION
513  
514 C<nup> is made to be used with C<less>. It sets environment
515 variables for C<less> (see L</ENVIRONMENT>), and adds options to it
516 for C<-L>. Some of them need a recent version, and a patched build
517 of C<less> does more for the pages of C<nup>.
518  
519 The pages fill the screen and go on below, and a line down would show
520 them cut in the middle. So C<j> and C<k>, the down and up arrows,
521 C<d> and C<u>, C<^D> and C<^U>, and the return key
522 move by the screen, as space and C<b> do, when the output has pages
523 and the pager is C<less> 661 or later, and C<J> and C<K> go to the
524 last and the first page, as C<G> and C<g>. The keys are put in
525 C<LESSKEY_CONTENT>, in the way C<-L> does, and not when C<NUP_LESSKEY>
526 is set. Without pages (C<-F>, or the files side by side), they move
527 by the line as usual. C<e> and C<y> are left to move by the line.
528  
529 =head2 Versions
530  
531 =over 4
532  
533 =item C<less> 590
534  
535 C<--file-size> makes C<less> read all input before displaying, as
536 C<+Gg> of the default pager does. The C<less> 581 of macOS does not
537 have it, so C<+Gg> is the default. Set C<NUP_PAGER> to use it:
538  
539 export NUP_PAGER="less --file-size"
540  
541 =item C<less> 661
542  
543 C<LESSKEY_CONTENT> is read, which C<-L> uses to put its keys:
544 C<h>, C<l>, C<,>, C<.>, the arrow keys, ESC-( and ESC-), C<H>, C<L>, C<g>, C<G>,
545 C<E<lt>>, C<E<gt>>, space, C<b>, C<j>, C<k>, C<d>, C<u>, C<^D>, C<^U>,
546 the return key, C<J> and C<K>.
547 Without C<-L>, the keys are C<j>, C<k>, the down and up arrows, C<d>,
548 C<u>, C<^D>, C<^U>, the return key, C<J> and C<K>.
549 An older C<less> ignores it.
550  
551 =item C<less> 710
552  
553 C<right-limit-scroll> stops at the right end of the lines. C<-L>
554 puts it on C<l>, C<.>, the right arrow and ESC-), in place of C<right-scroll>,
555 which goes on past the end.
556  
557 =back
558  
559 C<-L> runs C<less --align-shift --version> to see the version of
560 C<less>, and whether it has the option below.
561  
562 =head2 The Build in tecolicom/tap
563  
564 L<tecolicom/tap|https://github.com/tecolicom/homebrew-tap> has a build
565 of C<less> with patches for the pages of C<nup>
566 (L<kaz-utashiro/less|https://github.com/kaz-utashiro/less>). It adds
567 two options:
568  
569 =over 4
570  
571 =item B<--align-record>=I<N>
572  
573 A search shows the whole record (page) that has the match from the
574 top of the screen, instead of the matching line, so that the pages
575 stay in place. I<N> is the lines of a record; C<-1> is the height
576 of the screen less the prompt line, which is the height of the pages
577 of C<nup>. A repeated search goes on from the next record.
578  
579 =item B<--align-shift>
580  
581 The horizontal shift stays at a multiple of the C<--shift> amount, the
582 width of a pane with C<-L>, so that the panes are always at the edge
583 of the screen. C<-L> adds this option when the C<less> has it, and
584 the screens are then the same as without C<-L>: space, C<b>, C<G> and
585 C<E<gt>> move by the screens, the last screen shows the last pages
586 and the rest of it is blank, and C<n> and C<N> skip the matches on
587 the screen and move by the screens to the next page that has one.
588 C<l>, C<.> and the right arrow go on until the last page is at the left
589 edge. For this, the keys of C<-L> are given a count instead of being repeated:
590 with three panes, space and C<b>, and the keys which do the same, are
591 C<3> ESC-) and C<3> ESC-(, and
592 C<G> and C<E<gt>> are C<3L>, while C<L> shows the end of the row at
593 the right edge of the screen.
594  
595 =back
596  
597 C<app-nup> of the tap has it inside, and C<nup> of C<app-nup> runs it.
598 It is put apart from the commands of Homebrew, so the C<less> of
599 Homebrew itself stays as it is. To use it as C<less> outside of
600 C<nup>, install it on its own; it cannot be installed together with
601 the C<less> of Homebrew, which has the same command name:
602  
603 brew install tecolicom/tap/less
604  
605 With either, use C<--align-record> for the pages:
606  
607 export NUP_PAGER="less --file-size"
608 export NUP_PAGE_PAGER="less --file-size --align-record=-1"
609  
610 =head1 ENVIRONMENT
611  
612 =head2 Read by C<nup>
613  
614 =over 4
615  
616 =item C<NUP_OPTS>
617  
618 Options given before those on the command line, separated by spaces,
619 so that the options on the command line take precedence. This is
620 useful when C<nup> is called by another command, as C<MANPAGER>:
621  
622 NUP_OPTS=-L man perlfunc
623  
624 =item C<NUP_PAGER>
625  
626 The pager command, used when C<--pager> is not given. Default:
627 C<less -F +Gg>. See C<--pager> in L</"Pager Options">.
628  
629 =item C<NUP_PAGE_PAGER>
630  
631 The pager command in page mode, used in place of C<NUP_PAGER>. See
632 C<--pager> in L</"Pager Options">.
633  
634 =item C<NUP_LESSKEY>
635  
636 The keys that C<-L> gives to C<less>, in place of those of C<nup>.
637 Empty for no keys. See C<-L> in L</"General Options">. When it is
638 set, the keys of the pages without C<-L> are not added either.
639  
640 =item C<COLUMNS>, C<LINES>
641  
642 The width and the height of the terminal when C</dev/tty> is not
643 available. See L</Terminal Size>.
644  
645 =back
646  
647 C<PAGER> is not read, so that it can be set to C<nup>.
648  
649 =head2 Set by C<nup>
650  
651 These are set for C<less>, when they are not set already:
652  
653 =over 4
654  
655 =item C<LESS>
656  
657 Default: C<-R>. Required for ANSI color sequences.
658  
659 =item C<LESSANSIENDCHARS>
660  
661 Default: C<mK>. Recognizes SGR (C<m>) and erase line (C<K>)
662 sequences.
663  
664 =back
665  
666 C<-L> adds its keys to C<LESSKEY_CONTENT>, after those already in
667 it. See C<-L> in L</"General Options">.
668  
669 =head1 EXAMPLES
670  
671 Typical n-up usage:
672  
673 nup man nup # view manual in n-up layout
674 nup -C2 man perl # 2 columns
675 nup -C2,2 man perl # 2x2 grid (4-up layout)
676 nup -F man perl # no pagination
677 nup -L man perl # one row of pages, scrolled sideways
678 nup -L -C4 man perl # four pages on the screen at a time
679 nup -L *.txt # files side by side, scrolled sideways
680 nup file1.txt file2.txt # view files side by side
681 nup -C2 a.txt b.txt -w 170 # 2 columns, width 170 (ansicolumn -w)
682 nup -e ./script.sh # force command mode for a file
683 nup -o nup.pdf man nup # print to PDF (requires ansi2pdf)
684 nup -T a4p -C1 file | lpr # print on A4 in portrait
685  
686 Using C<nup> as a C<MANPAGER>:
687  
688 export MANPAGER="nup -A"
689  
690 =head1 INSTALLATION
691  
692 =head2 Homebrew
693  
694 Use L<tecolicom/tap|https://github.com/tecolicom/homebrew-tap>:
695  
696 brew tap tecolicom/tap
697 brew install app-nup
698  
699 It comes with the build of C<less> in the same tap, which C<nup> runs;
700 see L</"LESS INTEGRATION">.
701  
702 =head2 CPAN
703  
704 Using L<cpanminus|https://metacpan.org/pod/App::cpanminus>:
705  
706 cpanm -n App::nup
707  
708 =head1 DIAGNOSTICS
709  
710 Both stdout and stderr of the command are merged and passed through
711 the n-up output filter. Error messages will appear in the paged output.
712  
713 =head1 EXIT STATUS
714  
715 The exit status of the executed command is not preserved because
716 the output is passed through a filter pipeline.
717  
718 =head1 SEE ALSO
719  
720 L<App::optex::up> (bundled), L<optex>
721  
722 =head1 AUTHOR
723  
724 Kazumasa Utashiro
725  
726 =head1 LICENSE
727  
728 Copyright © 2025-2026 Kazumasa Utashiro.
729  
730 This software is released under the MIT License.
731 L<https://opensource.org/licenses/MIT>
732  
733 =cut
« blib/lib/App/optex/up.pm ↑ Summary