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.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
« blib/lib/App/optex/up.pm ↑ Summary