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.18";
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.18
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 When the pager is C<less>, C<nup> adds
175 C<< -S --shift=I<N> --rscroll=- >> to it, where I<N> is the width of
176 a pane: the lines are not wrapped, and the right and left arrow keys
177 move by one page.
178  
179 C<nup> also puts the following keys in the C<LESSKEY_CONTENT>
180 environment variable, which C<less> 661 or later reads. With three panes on the
181 screen and a C<less> older than 710, they are:
182  
183 h , left left-scroll one page to the left
184 l . right right-scroll one page to the right
185 H g < no-scroll the left end of the row
186 L G > end-scroll the right end of the row
187 space j down noaction ESC-) x 3 the panes on the screen to the right
188 b k up noaction ESC-( x 3 the panes on the screen to the left
189  
190 The pages have the height of the screen, and there is nothing to
191 scroll down to: C<j> and C<k> and the down and up arrows go on to the
192 next and the previous screen, as space and C<b> do.
193 C<noaction> does nothing and then types the keys after it, here
194 ESC-) three times. It cannot type the arrow keys, so ESC-) and
195 ESC-( are given the same actions as the right and left arrow. In
196 C<LESSKEY_CONTENT>, they are in one line, joined by C<;>, as
197 C<h left-scroll;l right-scroll;...>, and space is written C<\ >, a
198 backslash and a space.
199 With C<less> 710 or later, C<l>, C<.>, the right arrow and ESC-) are
200 C<right-limit-scroll>, which stops at the right end. A count before
201 C<.> is taken for a decimal point of the number by C<less>; give it
202 to the right arrow instead, as C<3> and the right arrow.
203  
204 The help of C<less> on C<h> and C<H> is then on no key, and C<g> and
205 C<G> no longer go to the first and the last line, which are on the
206 screen all the time anyway.
207  
208 When C<LESSKEY_CONTENT> is set, the keys are added after it, in a
209 C<#command> section, so that they win over the same keys there and
210 in F<~/.lesskey>; the other keys stay as they are.
211  
212 C<NUP_LESSKEY> gives the keys in place of those of C<nup>, in the
213 same way, and they do not change with the panes or the C<less>. Set
214 it empty not to add any keys, and C<LESSKEY_CONTENT> is left as it
215 is:
216  
217 export NUP_LESSKEY=
218  
219 The options are added to C<NUP_PAGER>, C<NUP_PAGE_PAGER> and
220 C<--pager> as well when the command is C<less>; another pager is used
221 as it is, and has to be told not to wrap the lines.
222  
223 See L</"LESS INTEGRATION"> for what works with the versions of
224 C<less>, and for the build of C<less> in tecolicom/tap, with which
225 the screens are the same as without C<-L>.
226  
227 nup -L man perlfunc
228 nup -L -C4 README.md
229  
230 With more than one file, or C<-V>, the files side by side go on to
231 the right in the same way, instead of going on below: each file is a
232 column of its own, without pages, and as many columns as without this
233 option are on the screen. The lines move up and down as usual, and
234 only C<h>, C<l>, C<,>, C<.>, the arrow keys, ESC-( and ESC-), C<H>,
235 C<L>, C<E<lt>> and C<E<gt>> are put in C<LESSKEY_CONTENT>, to move by one column and to
236 the ends; C<g> and C<G> go to the first and the last line.
237  
238 nup -L *.txt
239  
240 With C<--no-paginate> and one input, which has nothing to put on the
241 right, this option is ignored. It cannot be used with rows (C<-R>,
242 C<-C2,2>, C<-G>) or PDF output (C<-T>, C<-o> with C<.pdf>).
243 C<--auto-paginate> is ignored. The pages are laid out once, for the
244 height of the terminal at that time.
245  
246 =item B<-H>, B<--filename>
247  
248 Show filename headers in file view mode. Enabled by default.
249 Use C<--no-filename> to disable.
250  
251 =back
252  
253 =head2 Layout Options
254  
255 =over 4
256  
257 =item B<-C> I<C>[,I<R>], B<--pane>=I<C>[,I<R>]
258  
259 Set the number of columns (panes), and the number of rows when it is
260 given after a comma. For example, C<-C2> creates 2 columns, and
261 C<-C2,3> creates 2 columns and 3 rows.
262  
263 =item B<-R> I<N>, B<--row>=I<N>
264  
265 Set the number of rows.
266 This option is kept for compatibility and may be removed in the
267 future.
268  
269 =item B<-G> I<CxR>, B<--grid>=I<CxR>
270  
271 Set grid layout. C<-G2x3> is equivalent to C<-C2,3>.
272 This option is kept for compatibility and may be removed in the
273 future.
274  
275 =item B<-P> I<N>, B<--page>=I<N>
276  
277 Set the page height in lines.
278  
279 =item B<-S> I<N>, B<--pane-width>=I<N>
280  
281 Set the pane width in characters. Default is 85.
282  
283 =back
284  
285 =head2 Style Options
286  
287 =over 4
288  
289 =item B<--bs>=I<STYLE>, B<--border-style>=I<STYLE>
290  
291 Set the border style. Default is C<heavy-box>.
292  
293 =item B<--ls>=I<STYLE>, B<--line-style>=I<STYLE>
294  
295 Set the line style. Available: C<none>, C<truncate>, C<wrap>, C<wordwrap>.
296  
297 =item B<--runin>=I<N>, B<--runout>=I<N>, B<--runlen>=I<N>
298  
299 Set the run-in and run-out widths that L<ansicolumn> uses for line
300 breaking (kinsoku) when it folds long lines. C<--runlen> sets both.
301 They are given to ansicolumn after the values in F<~/.ansicolumnrc>,
302 so they take precedence. Without them, ansicolumn uses the values in
303 F<~/.ansicolumnrc>, or 2.
304  
305 =item B<--boundary>=C<word>|C<space>|C<none>
306  
307 Set where L<ansicolumn> may break a line when it folds long lines, as
308 its C<--boundary> option: C<word> does not break inside an
309 alphanumeric word, C<space> not inside a sequence of non-space
310 characters, and C<none> breaks anywhere. Like C<--runin>, it is
311 given to ansicolumn after F<~/.ansicolumnrc>. Without it, ansicolumn
312 uses the value in the rc file, or C<word> in document mode.
313  
314 =item B<--cm>=I<SPEC>, B<--colormap>=I<SPEC>
315  
316 Set color mapping. Specify as C<LABEL=COLOR> (e.g., C<--cm=BORDER=R>).
317 Available labels: C<TEXT>, C<BORDER>.
318  
319 =item B<-->[B<no->]B<page-number>
320  
321 Show page number on the bottom border of each column. With the
322 files side by side (more than one file, or C<-V>), which can be long,
323 it is shown on the top border as well, at the left, under the file
324 name. Enabled by default. Use
325 C<--no-page-number> to disable.
326  
327 =item B<--white-board>, B<--black-board>, B<--green-board>, B<--slate-board>
328  
329 Predefined color schemes for board-style display.
330  
331 =back
332  
333 =head2 Text Conversion
334  
335 =over 4
336  
337 =item B<--textconv>[=I<EXT,...>]
338  
339 Enable text conversion for non-text files using
340 L<App::optex::textconv>. When any of the specified file extensions
341 are found in the arguments, the C<textconv> module is loaded to
342 convert them to text before display.
343  
344 Default extensions:
345 C<pdf,docx,docm,pptx,pptm,xlsx,xlsm,jpg,jpeg>.
346  
347 Use C<--textconv=none> to disable.
348  
349 =item B<--hi>, B<--highlight>[=I<NAME>], B<--no-highlight>
350  
351 Color the source files by their syntax in file view mode. Enabled
352 by default, and done when the command of the highlighter and
353 L<IO::Factotum> are installed; nothing changes without them.
354 C<ansicolumn> reads each file through the command, with the language
355 told from the name of the file, or from the first line of a script.
356 A file whose language is not known is shown as it is, and so is a
357 file which has ANSI sequences already. The file names in the headers
358 are not changed.
359  
360 I<NAME> is the highlighter:
361  
362 skylighting, sky skylighting, the highlighter of pandoc (default)
363 sourcehighlight, gnu source-highlight of GNU Source-highlight
364  
365 brew install skylighting
366 brew install source-highlight
367  
368 Set the one to use in C<NUP_OPTS>:
369  
370 export NUP_OPTS=--highlight=sourcehighlight
371  
372 Use C<--no-highlight> to disable. C<--hi> is the short name of the
373 option, and C<sky> and C<gnu> are those of the highlighters:
374 C<--hi=gnu>, C<--no-hi>.
375  
376 =back
377  
378 =head2 Pager Options
379  
380 =over 4
381  
382 =item B<--pager>=I<COMMAND>
383  
384 Set the pager command. Default is C<NUP_PAGER> or C<less -F +Gg>.
385 When page mode is active, C<NUP_PAGE_PAGER> takes precedence over
386 C<NUP_PAGER>.
387 Viewing multiple files (or C<-V> parallel view) produces parallel
388 layout which has no page structure, so C<nup> disables page mode
389 and C<NUP_PAGE_PAGER> is not used there.
390 The C<PAGER> variable is not used to avoid an infinite loop when
391 C<PAGER> is set to C<nup>.
392 C<+Gg> makes C<less> read all input before displaying, so that C<-F>
393 and the percentage work; see L</"LESS INTEGRATION"> for the settings
394 of C<less>.
395  
396 Use C<--pager=> (empty) or C<--no-pager> to disable pager.
397  
398 =item B<--no-pager>
399  
400 Disable pager.
401  
402 =back
403  
404 =head2 PDF Output
405  
406 =over 4
407  
408 =item B<-T> I<DEVICE>, B<--device>=I<DEVICE>
409  
410 Set the device to show the output on. The default is C<tty>, the
411 terminal. Any other device is a paper, and the output is printed to
412 PDF by C<ansi2pdf>, instead of being shown on the terminal.
413  
414 The name of a paper is the one for the C<-p> option of C<ansi2pdf>,
415 such as C<a4>, C<a3>, C<b5> or C<letter>. A paper is used in
416 landscape orientation. The letter C<p> or C<l> after the name gives
417 the orientation: C<a4p> is A4 in portrait, and C<a4l> is A4 in
418 landscape. The device C<pdf> is the default paper of C<ansi2pdf>, A4.
419  
420 nup -T a4 man nup > nup.pdf # A4, landscape
421 nup -T a4p -C1 man nup | lpr # A4, portrait
422  
423 A sheet of paper takes the place of the terminal, and C<ansi2pdf>
424 takes the place of the pager. The size of a sheet in columns and
425 lines is asked to C<ansi2pdf>, the output is formatted for that size
426 in the same way as for a terminal, and each screen is printed on a
427 sheet as it is. The default is a landscape A4 sheet of 60 lines,
428 which has room for two panes of the default width.
429  
430 =item B<-o> I<FILE>, B<--output>=I<FILE>
431  
432 Write the output to I<FILE>. When the name ends with C<.pdf>, the
433 output is PDF without C<-T> as well.
434  
435 nup -o nup.pdf man nup # A4, landscape
436 nup -T a3 -o nup.pdf man nup # A3, landscape
437  
438 Otherwise, what is shown on the terminal is written to the file as it
439 is, with the ANSI sequences and in the size of the terminal, and the
440 pager is not used. C<-T tty> does so for a name ending with C<.pdf>
441 as well.
442  
443 nup -o nup.txt man nup # the same as --no-pager > nup.txt
444  
445 =item B<--geometry>
446  
447 Print the size of the device in columns and lines and its kind,
448 C<tty> or C<pdf>, and exit. No file is read and no command is run.
449  
450 $ nup -T a4p --geometry
451 100 60 pdf
452 $ nup -o nup.pdf -P 80 --geometry
453 275 80 pdf
454  
455 For a paper, the size is that of a sheet, which follows C<-T>, C<-o>,
456 C<-P>, the number of rows, C<--pdf-opts> and C<-w> of C<ansicolumn>
457 given after the file names. For the terminal, it is the size of the
458 terminal. This is for a program that formats text before giving it
459 to C<nup>, as L<mdee(1)|App::mdee> does.
460  
461 =item B<--pdf-opts>=I<OPTIONS>
462  
463 Give other options to C<ansi2pdf>, such as the number of lines on a
464 sheet, the margin and the fonts. They are given after the paper, so
465 they take precedence.
466  
467 nup -o nup.pdf --pdf-opts='-l 80 -m 15' man nup
468  
469 =back
470  
471 The C<-P> option sets the number of lines of a page for PDF as well:
472 a sheet has that many lines for each row. The C<-w> option of
473 C<ansicolumn>, given after the files or the command, sets the number
474 of columns of a sheet. The font size follows them, and the one that
475 is not given is decided to fill the sheet. With neither of them, a
476 sheet has 60 lines.
477  
478 nup -o nup.pdf -P 80 man nup # 80 lines on a sheet
479 nup -o nup.pdf -C2,2 -P 40 man nup # 2x2 pages of 40 lines
480 nup -o nup.pdf -C3 file -w 300 # 300 columns on a sheet
481  
482 =head2 Terminal Size
483  
484 The terminal size is taken from the controlling terminal
485 (C</dev/tty>). When it is not available, as when C<nup> is run
486 without a terminal, the C<COLUMNS> environment variable gives the
487 width (default 80), and C<LINES> gives the height (default 24) used
488 to split the screen when the number of rows is set, as in C<-C2,2>:
489  
490 COLUMNS=170 nup -C2 file1.txt file2.txt
491  
492 =head1 LESS INTEGRATION
493  
494 C<nup> is made to be used with C<less>. It sets environment
495 variables for C<less> (see L</ENVIRONMENT>), and adds options to it
496 for C<-L>. Some of them need a recent version, and a patched build
497 of C<less> does more for the pages of C<nup>.
498  
499 =head2 Versions
500  
501 =over 4
502  
503 =item C<less> 590
504  
505 C<--file-size> makes C<less> read all input before displaying, as
506 C<+Gg> of the default pager does. The C<less> 581 of macOS does not
507 have it, so C<+Gg> is the default. Set C<NUP_PAGER> to use it:
508  
509 export NUP_PAGER="less --file-size"
510  
511 =item C<less> 661
512  
513 C<LESSKEY_CONTENT> is read, which C<-L> uses to put its keys:
514 C<h>, C<l>, C<,>, C<.>, the arrow keys, ESC-( and ESC-), C<H>, C<L>, C<g>, C<G>,
515 C<E<lt>>, C<E<gt>>, space, C<b>, C<j> and C<k>.
516 An older C<less> ignores it.
517  
518 =item C<less> 710
519  
520 C<right-limit-scroll> stops at the right end of the lines. C<-L>
521 puts it on C<l>, C<.>, the right arrow and ESC-), in place of C<right-scroll>,
522 which goes on past the end.
523  
524 =back
525  
526 C<-L> runs C<less --align-shift --version> to see the version of
527 C<less>, and whether it has the option below.
528  
529 =head2 The Build in tecolicom/tap
530  
531 L<tecolicom/tap|https://github.com/tecolicom/homebrew-tap> has a build
532 of C<less> with patches for the pages of C<nup>
533 (L<kaz-utashiro/less|https://github.com/kaz-utashiro/less>). It adds
534 two options:
535  
536 =over 4
537  
538 =item B<--align-record>=I<N>
539  
540 A search shows the whole record (page) that has the match from the
541 top of the screen, instead of the matching line, so that the pages
542 stay in place. I<N> is the lines of a record; C<-1> is the height
543 of the screen less the prompt line, which is the height of the pages
544 of C<nup>. A repeated search goes on from the next record.
545  
546 =item B<--align-shift>
547  
548 The horizontal shift stays at a multiple of the C<--shift> amount, the
549 width of a pane with C<-L>, so that the panes are always at the edge
550 of the screen. C<-L> adds this option when the C<less> has it, and
551 the screens are then the same as without C<-L>: space, C<b>, C<G> and
552 C<E<gt>> move by the screens, the last screen shows the last pages
553 and the rest of it is blank, and C<n> and C<N> skip the matches on
554 the screen and move by the screens to the next page that has one.
555 C<l>, C<.> and the right arrow go on until the last page is at the left
556 edge. For this, the keys of C<-L> are given a count instead of being repeated:
557 with three panes, space and C<b>, and the keys which do the same, are
558 C<3> ESC-) and C<3> ESC-(, and
559 C<G> and C<E<gt>> are C<3L>, while C<L> shows the end of the row at
560 the right edge of the screen.
561  
562 =back
563  
564 C<app-nup> of the tap has it inside, and C<nup> of C<app-nup> runs it.
565 It is put apart from the commands of Homebrew, so the C<less> of
566 Homebrew itself stays as it is. To use it as C<less> outside of
567 C<nup>, install it on its own; it cannot be installed together with
568 the C<less> of Homebrew, which has the same command name:
569  
570 brew install tecolicom/tap/less
571  
572 With either, use C<--align-record> for the pages:
573  
574 export NUP_PAGER="less --file-size"
575 export NUP_PAGE_PAGER="less --file-size --align-record=-1"
576  
577 =head1 ENVIRONMENT
578  
579 =head2 Read by C<nup>
580  
581 =over 4
582  
583 =item C<NUP_OPTS>
584  
585 Options given before those on the command line, separated by spaces,
586 so that the options on the command line take precedence. This is
587 useful when C<nup> is called by another command, as C<MANPAGER>:
588  
589 NUP_OPTS=-L man perlfunc
590  
591 =item C<NUP_PAGER>
592  
593 The pager command, used when C<--pager> is not given. Default:
594 C<less -F +Gg>. See C<--pager> in L</"Pager Options">.
595  
596 =item C<NUP_PAGE_PAGER>
597  
598 The pager command in page mode, used in place of C<NUP_PAGER>. See
599 C<--pager> in L</"Pager Options">.
600  
601 =item C<NUP_LESSKEY>
602  
603 The keys that C<-L> gives to C<less>, in place of those of C<nup>.
604 Empty for no keys. See C<-L> in L</"General Options">.
605  
606 =item C<COLUMNS>, C<LINES>
607  
608 The width and the height of the terminal when C</dev/tty> is not
609 available. See L</Terminal Size>.
610  
611 =back
612  
613 C<PAGER> is not read, so that it can be set to C<nup>.
614  
615 =head2 Set by C<nup>
616  
617 These are set for C<less>, when they are not set already:
618  
619 =over 4
620  
621 =item C<LESS>
622  
623 Default: C<-R>. Required for ANSI color sequences.
624  
625 =item C<LESSANSIENDCHARS>
626  
627 Default: C<mK>. Recognizes SGR (C<m>) and erase line (C<K>)
628 sequences.
629  
630 =back
631  
632 C<-L> adds its keys to C<LESSKEY_CONTENT>, after those already in
633 it. See C<-L> in L</"General Options">.
634  
635 =head1 EXAMPLES
636  
637 Typical n-up usage:
638  
639 nup man nup # view manual in n-up layout
640 nup -C2 man perl # 2 columns
641 nup -C2,2 man perl # 2x2 grid (4-up layout)
642 nup -F man perl # no pagination
643 nup -L man perl # one row of pages, scrolled sideways
644 nup -L -C4 man perl # four pages on the screen at a time
645 nup -L *.txt # files side by side, scrolled sideways
646 nup file1.txt file2.txt # view files side by side
647 nup -C2 a.txt b.txt -w 170 # 2 columns, width 170 (ansicolumn -w)
648 nup -e ./script.sh # force command mode for a file
649 nup -o nup.pdf man nup # print to PDF (requires ansi2pdf)
650 nup -T a4p -C1 file | lpr # print on A4 in portrait
651  
652 Using C<nup> as a C<MANPAGER>:
653  
654 export MANPAGER="nup -A"
655  
656 =head1 INSTALLATION
657  
658 =head2 Homebrew
659  
660 Use L<tecolicom/tap|https://github.com/tecolicom/homebrew-tap>:
661  
662 brew tap tecolicom/tap
663 brew install app-nup
664  
665 It comes with the build of C<less> in the same tap, which C<nup> runs;
666 see L</"LESS INTEGRATION">.
667  
668 =head2 CPAN
669  
670 Using L<cpanminus|https://metacpan.org/pod/App::cpanminus>:
671  
672 cpanm -n App::nup
673  
674 =head1 DIAGNOSTICS
675  
676 Both stdout and stderr of the command are merged and passed through
677 the n-up output filter. Error messages will appear in the paged output.
678  
679 =head1 EXIT STATUS
680  
681 The exit status of the executed command is not preserved because
682 the output is passed through a filter pipeline.
683  
684 =head1 SEE ALSO
685  
686 L<App::optex::up> (bundled), L<optex>
687  
688 =head1 AUTHOR
689  
690 Kazumasa Utashiro
691  
692 =head1 LICENSE
693  
694 Copyright 2025-2026 Kazumasa Utashiro.
695  
696 This software is released under the MIT License.
697 L<https://opensource.org/licenses/MIT>
698  
699 =cut
« blib/lib/App/optex/up.pm ↑ Summary