blib/lib/App/mdee.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/Greple/md/widen.pm ↑ Summary
1 package App::mdee;
2  
3 # DO NOT EDIT this file manually.
4 # POD documentation is appended from script/mdee at release time.
5 # See minil.toml for details.
6  
7 1 our $VERSION = "1.21";
8  
9 1 1;
10 =encoding utf-8
11  
12 =head1 NAME
13  
14 mdee - em·dee, Markdown Easy on the Eyes
15  
16 =head1 SYNOPSIS
17  
18 mdee [ options ] file ...
19  
20 -h --help show help
21 --version show version
22 -d --debug debug level (repeatable)
23 -x --[no-]trace trace mode (set -x)
24 -n --dryrun dry-run mode
25 -s --style=# output style (nup/pager/cat/filter/raw)
26 -f --filter shortcut for --style=filter
27 -p --plain shortcut for --style=pager
28 --[no-]fold line folding (default: on)
29 -r --[no-]refill join paragraph lines (default: off)
30 --[no-]table table formatting (default: on)
31 --[no-]trim trim cell spaces (default: on)
32 --[no-]nup nup paged output (default: on)
33 -V --parallel show files side by side
34 -L --[no-]lateral all pages in one row, scrolled sideways
35 --[no-]rule use Unicode rules for tables (default: on)
36 --ts --table-style=# table style: lattice, 3line or simple (default: lattice)
37 --cat-v visualize whitespace via cat-v
38 -w --width=# output width (default: terminal width)
39 --fold-width=# fold width (default: pane width - 3 - run-in)
40 --runin=# run-in width for line breaking (default: 4)
41 --runout=# run-out width for line breaking (default: 4)
42 --runlen=# set both run-in and run-out
43 --boundary=# fold boundary: word, space or none (default: word)
44 -t --theme=#[,#,...] color theme(s) (default: hashed,nomark,markcell,doubleline)
45 -m --mode=# light or dark (default: light)
46 -B --base-color=# override base color of theme
47 (e.g., Ivory, #780043, (120,0,67))
48 --config=KEY=VALUE set config parameter (e.g., h1=RD, FILE=...)
49 --cm --colormap=L=SPEC override color for element (e.g., h1=RD)
50 --hm --heading-markup=# enable markup in headings (all/bold/...)
51 --show=# set field visibility (e.g., italic=1)
52 -C --pane=#[,#] number of columns, and rows
53 -R --row=# number of rows
54 -G --grid=# grid layout (e.g., 2x3)
55 -P --page=# page height in lines
56 -S --pane-width=# pane width (default: 85)
57 --bs --border-style=# border style
58 --[no-]page-number page number on border (default: on)
59 --[no-]filename file name label (default: on)
60 --[no-]pager[=#] pager command
61 -T --device=# output device: tty, pdf, or a paper for PDF
62 (e.g., a4, a4p, a3l)
63 -o --output=FILE output file (PDF when it ends with .pdf)
64  
65 =head1 VERSION
66  
67 Version 1.21
68  
69 =cut
70 =head1 DESCRIPTION
71  
72 B<em·dee> (command: C<mdee>) is a terminal-based multi-column
73 Markdown text viewer with syntax highlighting, particularly
74 useful for reading documents generated by LLMs.
75  
76 =begin html
77  
78 <p><img width="1000" src="https://raw.githubusercontent.com/tecolicom/App-mdee/main/images/3-column.png">
79  
80 =end html
81  
82 It presents Markdown content in a clean, readable form: syntax
83 highlighting distinguishes document structure, line folding wraps
84 long list items, and tables are aligned with proper column
85 formatting. By default, markup characters (C<**>, C<`>,
86 C<[>...C<]>, etc.) are hidden so that the text reads naturally,
87 while color and styling preserve the structural information.
88 Closing hashes are appended to h3-h6 headers to make heading
89 levels visually distinct. On terminals supporting OSC 8, links
90 remain clickable.
91  
92 Use C<--no-theme> to display the original Markdown source with
93 markup characters intact.
94  
95 The same view is printed to PDF with C<-o file.pdf>. See
96 L</Printing to PDF>.
97  
98 =head2 Concept
99  
100 B<em·dee> began as a viewer for Markdown I<text>, not as a Markdown
101 renderer. The idea was to show a C<.md> file as it is written, line
102 for line, only made easier on the eyes with color: the Markdown is
103 not interpreted or reformatted. Some formatting has been added since
104 because it made the text more readable: tables are aligned, long
105 list items are folded, the default themes hide markup characters,
106 and closing hashes are appended to lower-level headings. With
107 C<--refill>, the lines that a Markdown parser has found to be
108 one paragraph are joined as well. Everything else is still the
109 source text. This is why backslash escapes such as C<\*> are shown
110 as written, and why C<--no-theme> gives back the original file, in
111 color.
112  
113 For full Markdown rendering, many other viewers are available, such
114 as C<glow> and C<mdcat>. Combine them with L<nup(1)|App::nup> for
115 similar paged output (e.g., C<nup glow README.md>, C<nup mdcat README.md>).
116  
117 The pipeline combines L<greple(1)|App::Greple> for colorization and
118 L<nup(1)|App::nup> for multi-column paged output.
119  
120 The following elements are highlighted. Elements marked with
121 C<--show> can be individually disabled via the C<--show> option.
122 Others are always processed for structural integrity.
123  
124 --show bold (**bold**, __bold__)
125 --show italic (*italic*, _italic_)
126 --show strike (~~strike~~)
127 --show code_inline (`code`)
128 --show header, h1-h6 (# heading)
129 --show horizontal_rule (---, ***, ___)
130 --show blockquote (> quote)
131 always code_mark (``` or ~~~)
132 code_block
133 code_info
134 always meta_mark (--- or +++ at the top)
135 meta_block
136 always comment (<!-- ... -->)
137 always link ([text](url))
138 image (![text])
139 image_link (![text](url))
140  
141 Tables and list item folding are controlled by C<--table> and
142 C<--fold> options, not by C<--show>.
143  
144 The code in a fenced code block is shown in the colors of its
145 language (C<```perl>), when L<Text::ANSI::Highlight> and the command
146 of its highlighter, C<pandoc> by default, are installed.
147 C<--config highlight=gnu> uses C<source-highlight>, and
148 C<--config highlight=0> turns it off. See
149 L<App::Greple::md/"Syntax Highlight of Code">.
150  
151 =head2 Multi-column Layout and Pagination
152  
153 By default, B<mdee> calculates the number of display columns by
154 dividing the output width (the terminal width unless C<--width>
155 is given) by the pane width (default 85 characters). This determines how the output is laid out and
156 paginated.
157  
158 When two or more columns fit, L<nup(1)|App::nup> arranges output
159 in multi-column layout with page-by-page pagination — content is
160 split into terminal-height pages viewed through a pager.
161  
162 When only one column fits, B<mdee> still uses nup for formatting
163 (borders, document layout) but disables page-by-page splitting,
164 so the content scrolls continuously in the pager. This avoids
165 wasted space from page breaks on narrow terminals while
166 maintaining the same visual appearance.
167  
168 To force page-by-page pagination even in single-column layout,
169 specify C<--nup> explicitly. The C<--pane-width> (C<-S>) option
170 adjusts the column width used for this calculation, and
171 C<--pane> (C<-C>) sets the number of columns directly. The
172 C<--width> (C<-w>) option replaces the terminal width in this
173 calculation and limits the output to that width.
174  
175 With two or more files, C<--parallel> shows the files side by side,
176 one pane per file, instead of one after another. Each file is
177 folded to its pane width, and the panes scroll together in the
178 pager. The screen shows as many files as fit, as many as the pages
179 of a single file, and the files that do not fit in one row continue
180 on the next, or on the right with C<--lateral>; C<--pane> (C<-C>)
181 sets the number of panes.
182  
183 Use C<-p> (C<--style=pager>) for a simpler view without nup
184 formatting — highlighted output is piped directly through a
185 pager. Use C<-f> (C<--style=filter>) to write highlighted
186 output to stdout without a pager, suitable for piping into
187 other commands.
188  
189 =head2 Printing to PDF
190  
191 B<mdee> prints the document to PDF when the output file ends with
192 C<.pdf>, or when a paper is given as the device with C<-T>.
193  
194 mdee -o README.pdf README.md # A4 in landscape
195 mdee -T a4p -o README.pdf README.md # A4 in portrait
196 mdee -T a3 README.md > README.pdf # A3, to the standard output
197  
198 The paper takes the place of the terminal. The number of columns is
199 the width of the paper in characters divided by the pane width, and
200 the text is folded for it, in the same way as on the terminal: A4 in
201 landscape is 206 characters wide and has two panes, and A4 in
202 portrait is 100 characters wide and has one. C<-C> and C<-S> work
203 as on the terminal. The mode is C<light> unless C<--mode> is given,
204 because the paper is white.
205  
206 A paper is given by its name, with the letter C<p> or C<l> for
207 portrait or landscape, and the margin in millimeters after C<:m>.
208 The default is landscape with a margin of 5 mm.
209  
210 mdee -T a4p:m10 -o README.pdf README.md
211  
212 A sheet has 60 lines. The rows of C<-C> divide the sheet, and the
213 size of the characters is kept: C<-C2,2> gives four pages of 30
214 lines on a sheet. C<-P> sets the lines of a page instead, and the
215 characters become smaller or larger to put the pages on the sheet:
216 C<-C2,2 -P60> prints four pages of 60 lines on a sheet in half the
217 size, as a printer does for 4-up.
218  
219 mdee -C2,2 -o README.pdf README.md
220 mdee -C2,2 -P60 -o README.pdf README.md
221  
222 L<nup(1)|App::nup> and
223 L<ansi2pdf(1)|https://github.com/tecolicom/App-ansi2pdf> make the
224 PDF, so C<ansi2pdf> has to be installed, and the output style has to
225 be C<nup>, which is the default. See C<-T> and C<-o> in
226 L</Output Options>.
227  
228 =head1 INSTALLATION
229  
230 =head2 Homebrew
231  
232 Use L<tecolicom/tap|https://github.com/tecolicom/homebrew-tap>:
233  
234 brew tap tecolicom/tap
235 brew install app-mdee
236  
237 =head2 CPAN
238  
239 cpanm -n App::mdee
240  
241 =head1 OPTIONS
242  
243 =head2 General Options
244  
245 =over 4
246  
247 =item B<-h>, B<--help>
248  
249 Show help message.
250  
251 =item B<--version>
252  
253 Show version.
254  
255 =item B<-d>, B<--debug>
256  
257 Set debug level. Can be repeated for increasing verbosity.
258  
259 =over 4
260  
261 =item C<-d>
262  
263 Show theme values (C<theme_light[]>/C<theme_dark[]>, C<md_config[]>)
264 and pipeline stage names.
265  
266 =item C<-dd>
267  
268 Above, plus full command lines for each pipeline stage.
269  
270 =back
271  
272 =item B<-x>, B<--trace>, B<--no-trace>
273  
274 Enable or disable shell trace mode (C<set -x>). Useful for
275 debugging script execution. Can be toggled: C<-x --no-x> enables
276 then disables tracing.
277  
278 =item B<-n>, B<--dryrun>
279  
280 Dry-run mode. Print the commands that would be run, one pipeline
281 stage per line joined with C<|>, without running them. Arguments
282 are quoted so that the output can be pasted into a shell. The
283 environment that B<mdee> sets (C<LESS>, C<LESSANSIENDCHARS>) is not
284 shown. With C<-d>, the stage names are printed to stderr as well.
285  
286 =back
287  
288 =head2 Processing Options
289  
290 =over 4
291  
292 =item B<-s> I<STYLE>, B<--style>=I<STYLE>
293  
294 Set the output style. Default is C<nup>. Available styles:
295  
296 =over 4
297  
298 =item C<nup> - Full pipeline: fold + table + nup paged output (default)
299  
300 =item C<pager> - Fold + table, output to pager (C<$PAGER> or C<less>)
301  
302 =item C<cat> - Fold + table, output to stdout
303  
304 =item C<filter> - Table only (no fold, no nup), suitable for piping
305  
306 =item C<raw> - Highlight only (no fold, no table, no nup)
307  
308 =back
309  
310 The style sets the initial state of C<--fold>, C<--table>, and
311 C<--nup> options. Subsequent options can override individual
312 settings:
313  
314 mdee -s filter --fold file.md # filter + fold
315 mdee -p --no-fold file.md # pager without fold
316  
317 =item B<-f>, B<--filter>
318  
319 Shortcut for C<--style=filter>. Reads from stdin (or files) and
320 outputs highlighted Markdown to stdout. Disables line folding and
321 nup paged output, but keeps table formatting enabled. Useful for
322 piping Markdown content through mdee for syntax highlighting.
323  
324 =item B<-p>, B<--plain>
325  
326 Shortcut for C<--style=pager>. Enables fold and table formatting,
327 outputs through a pager (C<$PAGER> or C<less>) instead of nup.
328  
329 =item B<--[no-]fold>
330  
331 Enable or disable line folding for list items, definition lists,
332 block quotes and, with C<--refill>, paragraphs. When enabled, long
333 lines are wrapped with proper indentation using
334 L<ansifold(1)|App::ansifold>: the continuation lines of a list item
335 are indented under its text, those of a block quote start with the
336 quote marker again. Default is enabled.
337  
338 Supported list markers: C<*>, C<+>, C<->, C<1.>, C<1)>, C<#.>, C<#)>.
339 The C<#.> and C<#)> forms are the auto-numbered lists of Pandoc's
340 Markdown.
341  
342 =item B<-r>, B<--[no-]refill>
343  
344 Join the lines of each paragraph into one line. Default is disabled;
345 C<default[refill]=1> in the configuration file enables it.
346  
347 What a paragraph is, a Markdown parser decides: a run of lines at the
348 top level, in a block quote, in a list item or in a definition body.
349 Those lines are joined in the original text. Headings, tables, code
350 blocks, front matter and everything else stay as written. A hard
351 line break (two or more spaces or a backslash at the end of a line)
352 is kept.
353  
354 Lines are joined with one space, or with nothing after a fullwidth
355 punctuation character and between two characters of a script that is
356 written without spaces, as L<ansifold(1)|App::ansifold> does. When
357 fold is enabled, the joined paragraphs are folded to the fold width
358 like list items; otherwise each is one long line.
359  
360 The parser is L<Markdown::Perl>, which is installed with B<mdee>, or
361 the L<CommonMark> module (an interface to libcmark) when it is there,
362 which is faster. C<--config refill_parser=pandoc> uses pandoc 2.11.3
363 or later instead.
364  
365 Front matter at the top of the file, TOML between C<+++> lines or
366 YAML between C<---> lines (or ended by C<...>), is left as it is
367 and shown as a code block; C<--config front_matter=0> takes its lines
368 as Markdown.
369  
370 =item B<--[no-]table>
371  
372 Enable or disable table formatting. When enabled, Markdown tables
373 are formatted using L<ansicolumn(1)|App::ansicolumn> for aligned column display.
374 Column alignment specified in the separator line (C<:---> for left,
375 C<:---:> for center, C<---:> for right) is respected.
376 Default is enabled.
377  
378 When folding is enabled, a table wider than the fold width is fit into
379 that width: columns that fit keep their width, and the cells of
380 over-wide columns are wrapped. A table that already fits is not
381 changed. Use C<--config table_width=0> to disable wrapping, or
382 C<--config table_width=N> to use a different width. Per-column
383 widths can be given with C<--config table_cell=SPEC>, where SPEC
384 is a colon-separated list passed to ansicolumn's C<--cell> option
385 (for example C<0:10> fixes the second column at 10 columns, and
386 C<< '<30' >> caps every column at 30). Marks can be put at the
387 start of cell lines, in place of the cell's leading space so that
388 column widths do not change. C<--config table_cell_mark=STRING>
389 marks the first line of every body cell in a column that has a
390 wrapped cell; the header row and columns that fit are left alone.
391 The default theme C<markcell> sets it to C<‣> (U+2023).
392 C<--config table_wrap_mark=STRING> marks the second and later
393 lines of a wrapped cell, so that they are not read as new rows;
394 the theme C<markwrap> sets it to C<›> (U+203A). Without these
395 themes no mark is used.
396  
397 =item B<--[no-]trim>
398  
399 Trim whitespace from table cell content before formatting.
400 This is useful when the source table is pre-formatted with
401 aligned spacing, which would otherwise prevent column alignment
402 directives from working correctly. Default is enabled.
403  
404 =item B<--[no-]nup>
405  
406 Enable or disable L<nup(1)|App::nup> for multi-column paged output.
407 When disabled, output goes directly to stdout without formatting.
408 Default is enabled. When explicitly specified, forces nup's
409 native pagination even in single-column layout (which normally
410 uses the pager instead).
411  
412 =item B<--[no-]rule>
413  
414 Enable or disable Unicode rule characters for table borders.
415 When enabled, ASCII pipe characters (C<|>) are replaced with
416 Unicode box-drawing characters (C<│>, C<├>, C<┤>, C<┼>) and
417 dashes (C<->) in separator lines are replaced with horizontal
418 rules (C<─>). Default is enabled.
419  
420 =item B<--table-style>=I<STYLE>, B<--ts> I<STYLE>
421  
422 Select how tables are drawn. C<lattice> (default) keeps a separator
423 between the columns, C<│> or C<|> depending on C<--rule>. C<pipe> is
424 another name of it, kept for compatibility:
425  
426 Left │ Center │ Right │ Default
427 ──────┼────────┼───────┼─────────
428 a │ b │ c │ d
429  
430 C<3line> separates the columns by spaces only and draws three rules: a
431 rule the width of the table above and below it, and a rule per column
432 below the header.
433  
434 ─────────────────────────────────
435 Left Center Right Default
436 ────── ──────── ─────── ─────────
437 a b c d
438 ─────────────────────────────────
439  
440 C<simple> also separates the columns by spaces only, and draws the
441 rule per column below the header and below the table.
442  
443 Left Center Right Default
444 ────── ──────── ─────── ─────────
445 a b c d
446 ────── ──────── ─────── ─────────
447  
448 The rules are drawn with C<-> with C<--no-rule>.
449  
450 =item B<--cat-v>
451  
452 Pass the output through L<cat-v(1)|App::cat::v> to visualize
453 whitespace and special characters. Spaces are shown as C<·>
454 and other invisible characters are made visible. Newline
455 visualization is disabled by default.
456  
457 =item B<-w> I<N>, B<--width>=I<N>
458  
459 Set the output width in characters. Default is the terminal
460 width. With nup, this width is used in place of the terminal
461 width to calculate the number of columns, and it is passed to
462 L<ansicolumn(1)|App::ansicolumn> so that the panes fit into it:
463  
464 mdee -w 170 file.md # two 85-column panes on a wide terminal
465 mdee -V -w 170 a.md b.md # two files in 85 columns each
466  
467 Without nup (C<--style=cat>, C<pager>, C<filter>, or C<--no-nup>),
468 the text itself is the output, so this is the fold width.
469  
470 =item B<--fold-width>=I<N>
471  
472 Set the fold width for text wrapping directly. Default is the
473 pane width (output width divided by the number of columns) minus
474 3 for borders and padding and the run-in width (see C<--runin>),
475 which gives 78 when pane-width is 85.
476 Only effective when C<--fold> is enabled. The same width is used
477 to fit tables (see C<--table>).
478  
479 =item B<--runin>=I<N>, B<--runout>=I<N>, B<--runlen>=I<N>
480  
481 Set the run-in and run-out widths that L<ansicolumn(1)|App::ansicolumn>
482 uses for line breaking (kinsoku) when nup folds the panes.
483 C<--runlen> sets both; options given later override earlier ones.
484 Default is 4. A run-in character may go past the fold width, so
485 ansicolumn keeps the run-in width free at the end of the pane, and
486 the default fold width is made narrower by the same amount. These
487 values are given to nup, and they take precedence over the values
488 in F<~/.ansicolumnrc>. The same values are given to the md module
489 as C<fold_runin> and C<fold_runout>, so that the lines it folds run
490 in by the width kept free, not more.
491  
492 =item B<--boundary>=C<word>|C<space>|C<none>
493  
494 Set where L<ansicolumn(1)|App::ansicolumn> may break a line when nup
495 folds the panes, as its C<--boundary> option: C<word> (default) does
496 not break inside an alphanumeric word, C<space> not inside a sequence
497 of non-space characters, and C<none> breaks anywhere. Lists, tables
498 and the paragraphs joined by C<--refill> are folded by the md module
499 at word boundaries, and this option keeps the other paragraphs, which
500 are folded by nup, in step with them. The value is given to nup,
501 which gives it to ansicolumn after F<~/.ansicolumnrc>, so it takes
502 precedence over the value there.
503  
504 =back
505  
506 =head2 Theme Options
507  
508 B<em·dee> supports color themes for customizing syntax highlighting.
509 Themes define colors for various Markdown elements (headers, code blocks,
510 bold text, etc.).
511  
512 =over 4
513  
514 =item B<-t> I<NAME>, B<--theme>=I<NAME>[,I<NAME>,...]
515  
516 Select color themes. The default is C<hashed,nomark,markcell,doubleline>,
517 which appends closing hashes to h3-h6 headers, hides markup
518 characters for a clean reading experience, marks the rows of
519 tables whose cells are wrapped, and gives h4 a double underline.
520  
521 Themes specified with C<--theme> are added to the default, not
522 replacing it (C<default[theme]> in the configuration file replaces
523 it). Multiple themes can be specified as comma-separated names or
524 by repeating the option. Each theme is applied in order as a
525 transformation, and when two themes set the same value the later
526 one wins:
527  
528 mdee --theme=warm file.md # the default themes + warm
529 mdee --no-theme --theme=warm # warm only (clear default first)
530 mdee --no-theme file.md # no theme (show all markup)
531  
532 Use C<--no-theme> to clear the default theme. It can be combined
533 with C<--theme> to start fresh.
534  
535 See L</THEMES> for the themes that come with B<mdee> and how to
536 write one.
537  
538 Use C<-d> to dump current theme values in sourceable format.
539  
540 =item B<-m> I<MODE>, B<--mode>=I<MODE>
541  
542 Select light or dark mode. Default is C<light>.
543  
544 If the terminal supports background color detection (via
545 L<Getopt::EX::termcolor>), the mode is automatically selected based on
546 terminal luminance.
547 When the environment variable C<TERM_LUMINANCE> is set (0 to 100, as
548 L<Getopt::EX::termcolor> uses it), its value is taken instead and the
549 terminal is not asked; below 50 is dark.
550  
551 Each theme has light and dark variants optimized for different terminal
552 backgrounds. The built-in C<default> theme uses RoyalBlue as the base
553 color with automatic luminance adjustment:
554  
555 =over 4
556  
557 =item C<light> - RoyalBlue with luminance 25 (dark text for light backgrounds)
558  
559 =item C<dark> - RoyalBlue with luminance 80 (bright text for dark backgrounds)
560  
561 =back
562  
563 =item B<-B> I<COLOR>, B<--base-color>=I<COLOR>
564  
565 Override the theme's base color. The base color determines the overall
566 color scheme because all heading colors (h1, h2, h3, etc.) are derived
567 from it by adjusting luminance. For example, h2 might be C<${base}+y20>
568 (base color with luminance increased by 20).
569  
570 B<Simple color name> - luminance is adjusted automatically:
571  
572 When you specify just a color name (without C<E<lt>E<gt>> brackets or
573 other syntax), the default luminance adjustment is applied based on
574 the current mode:
575  
576 -B RoyalBlue # becomes <RoyalBlue>=y25 in light mode
577 # becomes <RoyalBlue>=y80 in dark mode
578  
579 This makes it easy to try different colors without worrying about
580 luminance values. The default adjustments (C<=y25> for light, C<=y80>
581 for dark) are designed to provide good contrast against typical terminal
582 backgrounds.
583  
584 B<Full color specification> - used exactly as specified:
585  
586 If you include C<E<lt>E<gt>> brackets, luminance modifiers, or use RGB
587 notation, the value is used as-is without any automatic adjustment:
588  
589 -B '<Ivory>' # original color, no adjustment
590 -B '<Ivory>=y50' # explicit luminance 50
591 -B '#780043' # burgundy in hex
592 -B '(120,0,67)' # same color in RGB decimal
593  
594 B<Customizing the default adjustment>:
595  
596 The automatic luminance adjustment values can be customized with the
597 C<--adjust> option:
598  
599 --adjust light='=y30' # use =y30 instead of =y25 for light mode
600 --adjust dark='=y70' # use =y70 instead of =y80 for dark mode
601  
602 B<Note>: Basic ANSI color codes (C<R>, C<G>, C<B>, etc.) cannot be used
603 because heading variations require luminance adjustment, which only works
604 with full color specifications (X11 names, RGB hex, or RGB decimal).
605  
606 =item B<--config>=I<KEY>=I<VALUE>
607  
608 Set config parameters from the command line. Parameters are
609 passed to the L<App::Greple::md> module via
610 L<Getopt::EX::Config>. Theme keys recognized by mdee (C<base>,
611 C<FILE>, C<FILE_FORMAT>) are consumed locally and applied to both
612 light and dark themes; all other parameters are forwarded to the
613 md module.
614  
615 Color labels (C<h1>, C<bold>, C<italic>, etc.) are accepted as
616 config parameters and override default colors. The C<${base}>
617 placeholder can be used and will be expanded at runtime.
618  
619 mdee --config h1=RD # red h1
620 mdee --config bold=GD --config italic=YI # green bold, yellow italic
621 mdee --config h1='L25D/R;E' # custom h1 with background
622 mdee --config FILE='L25D/R;E' # red file label
623 mdee --config FILE_FORMAT=%s: # simple format
624 mdee --config hashed.h3=1 # enable h3 closing hashes
625 mdee --config cjk_friendly=1 # see LIMITATIONS, Emphasis
626  
627 Theme keys consumed by mdee:
628  
629 =over 4
630  
631 =item C<base> - Base color (equivalent to C<--base-color>)
632  
633 =item C<FILE> - Color spec for file label (default: C<L25D/${base};E> for light, C<L00D/${base};E> for dark). This is passed to greple's C<FILE> label and cannot be set via C<--cm>.
634  
635 =item C<FILE_FORMAT> - Format string for file label passed to greple's C<--format FILE=> (default: C<\n %s\n\n>). Cannot be set via C<--cm>.
636  
637 =back
638  
639 All other keys are passed to the md module as config parameters.
640 See L</Highlight Options> for the list of available color labels.
641 The md module also accepts operational parameters such as
642 C<table_trim>, C<table_width>, C<table_cell>, C<rule>, C<osc8>,
643 C<tick_open>, C<tick_close>, etc.
644  
645 =back
646  
647 =head2 Highlight Options
648  
649 =over 4
650  
651 =item B<--colormap>=I<LABEL>=I<SPEC>, B<--cm> I<LABEL>=I<SPEC>
652  
653 Override the color for a specific element. I<LABEL> is one of the
654 color labels listed below. I<SPEC> follows
655 L<Term::ANSIColor::Concise> format.
656  
657 --colormap h1=RD # red bold headings
658 --colormap code_block=/L20;E # dark background for code blocks
659 --colormap bold='${base}D' # base color bold
660  
661 This option is passed to the L<App::Greple::md> module, as a module
662 option before C<--> in the B<greple> command line (see it with C<-n>).
663 It is not the C<--cm> option of B<greple>, so C<FILE> and C<FILE_FORMAT>
664 are set by C<--config> instead.
665  
666 Available labels:
667  
668 h1 - h6 Heading levels 1 through 6
669 bold Bold (**text** or __text__)
670 italic Italic (*text* or _text_)
671 strike Strikethrough (~~text~~)
672 emphasis_mark Emphasis markers (**, *, __, _, ~~)
673 bold_mark Bold markers only (overrides emphasis_mark)
674 italic_mark Italic markers only (overrides emphasis_mark)
675 strike_mark Strike markers only (overrides emphasis_mark)
676 link Inline links [text](url)
677 image Images ![alt](url)
678 image_link Image links [![alt](img)](url)
679 link_mark Link/image brackets (overrides emphasis_mark)
680 blockquote Blockquote marker (>)
681 horizontal_rule Horizontal rules (---, ***, ___)
682 comment HTML comments (<!-- ... -->)
683 code_mark Code block delimiters (``` and ~~~)
684 code_tick Inline code backtick markers
685 code_info Fenced code block info string
686 code_block Fenced code block body
687 code_inline Inline code body
688 meta_mark Front matter delimiter lines
689 meta_block Front matter body
690  
691 This option can be specified multiple times. Color labels can
692 also be set via C<--config>. When both are
693 specified, C<--cm> takes priority over C<--config>.
694  
695 =item B<--heading-markup>=I<STEPS>, B<--hm> I<STEPS>
696  
697 Control inline markup processing inside headings. By default,
698 headings are rendered with uniform heading color without processing
699 bold, italic, strikethrough, or inline code inside them. Links
700 are always processed as OSC 8 hyperlinks regardless of this option.
701  
702 Use C<all> or C<1> to enable all inline formatting within headings
703 using cumulative coloring. To select specific steps, list them
704 separated by colons.
705  
706 Available steps: C<inline_code>, C<horizontal_rules>, C<bold>,
707 C<italic>, C<strike>.
708  
709 mdee --hm all file.md # all markup
710 mdee --hm bold file.md # bold only
711 mdee --hm bold:italic file.md # bold and italic
712  
713 =item B<--show>=I<FIELD>[=I<VALUE>],...
714  
715 Control field visibility for highlighting. Empty value or C<0> disables
716 the field; any other value (including C<1>) enables it.
717  
718 --show italic # enable italic
719 --show bold=0 # disable bold
720 --show all # enable all fields
721 --show all= --show bold # disable all, then enable only bold
722  
723 Multiple fields can be specified with commas or by repeating the option.
724 The special field C<all> affects all fields and is processed first.
725  
726 See L</DESCRIPTION> for the list of available fields and
727 elements that are always active.
728 All controllable fields are enabled by default.
729  
730 =back
731  
732 =head2 Layout Options (passed to nup)
733  
734 =over 4
735  
736 =item B<-V>, B<--parallel>
737  
738 Show two or more files side by side, one pane per file, instead of
739 one after another. The screen shows as many files as fit, as many
740 as the pages of a single file, but not more than there are, and the
741 rest continue below; C<--pane> gives the number. Ignored with a
742 single file.
743  
744 With C<--lateral>, the rest go on to the right in one row instead,
745 and are scrolled sideways, a file at a time:
746  
747 mdee -LV *.md
748 mdee -LVC3 *.md
749  
750 =item B<-L>, B<--[no-]lateral>
751  
752 Put all the pages in one row, given to L<nup(1)|App::nup> as its
753 C<--lateral>. The screen shows as many pages as without it, and
754 space and C<b> of C<less> move by the screen as usual, while C<h> and
755 C<l> move by one page; see L<nup(1)|App::nup> for the keys and the
756 build of C<less> that keeps the pages at the edge of the screen. A
757 single pane goes to nup as well, so that the pages can be shifted one
758 by one. It cannot be used with C<--width>,
759 and nup refuses it with rows (C<-C2,2>, C<-R>, C<-G>) and PDF output.
760 With C<--parallel>, the files go on to the right in the same way,
761 each file a column scrolled up and down as usual; see C<--parallel>.
762 C<default[lateral]=1> in the configuration file makes it the default;
763 the default is left out where the option cannot be used, and
764 C<default[width]> is not used with it.
765  
766 =item B<-C> I<C>[,I<R>], B<--pane>=I<C>[,I<R>]
767  
768 Set the number of columns (panes). The number of rows may follow
769 after a comma: C<-C2,2> is 2 columns and 2 rows on a page, the same
770 as C<-C2 -R2>. When not specified (or 0),
771 the number of columns is calculated from the output width
772 (C<--width>, default terminal width) and C<--pane-width>. If only 1 column fits, nup formatting (borders
773 etc.) is preserved but pagination is handled by the pager instead.
774 Use C<--nup> to force nup's native pagination even in single column.
775  
776 =item B<-R> I<N>, B<--row>=I<N>
777  
778 Set the number of rows. C<-C> takes it as well, as C<-C2,2>.
779  
780 =item B<-G> I<CxR>, B<--grid>=I<CxR>
781  
782 Set grid layout. For example, C<-G2x3> creates 2 columns and 3 rows.
783 The text is folded for the number of columns of C<-C>, which this
784 option does not tell to mdee, so C<-C2,3> is better.
785  
786 =item B<-P> I<N>, B<--page>=I<N>
787  
788 Set the page height in lines.
789  
790 =item B<-S> I<N>, B<--pane-width>=I<N>
791  
792 Set the pane width in characters. Default is 85. This value is
793 used to calculate the number of columns from the output width,
794 and the default fold width. It has no effect when the number of
795 columns is given by C<--pane> or C<--parallel>.
796  
797 =item B<--bs>=I<STYLE>, B<--border-style>=I<STYLE>
798  
799 Set the border style.
800  
801 =item B<-->[B<no->]B<page-number>
802  
803 Show page number on the bottom border of each column. Enabled by
804 default. Use C<--no-page-number> to disable.
805  
806 =item B<-->[B<no->]B<filename>
807  
808 Show the file name label at the top of each file. Enabled by
809 default. Use C<--no-filename> to hide it, for example when files are
810 shown side by side with C<--parallel> and the panes should start with
811 the text. The label format and color are set by the C<FILE_FORMAT>
812 and C<FILE> theme keys (see C<--config>).
813  
814 =back
815  
816 =head2 Output Options
817  
818 =over 4
819  
820 =item B<--[no-]pager>[=I<COMMAND>]
821  
822 Set the pager command. Use C<--pager=less> to specify a pager,
823 or C<--no-pager> to disable paging.
824  
825 =item B<-T> I<DEVICE>, B<--device>=I<DEVICE>
826  
827 Set the device to show the output on, which is given to
828 L<nup(1)|App::nup>. The default is C<tty>, the terminal. Any other
829 device is a paper, and the output is printed to PDF by
830 L<ansi2pdf(1)|https://github.com/tecolicom/App-ansi2pdf>: C<a4> is A4
831 in landscape, C<a4p> is A4 in portrait and C<a3l> is A3 in landscape.
832 The device C<pdf> is the default paper, A4.
833  
834 mdee -T a4 README.md > README.pdf
835 mdee -T a4p -o README.pdf README.md
836  
837 The paper takes the place of the terminal, as described in
838 L</Printing to PDF>, and the pager is not used.
839  
840 This requires the nup style, and C<ansi2pdf>
841 0.1.3 or later for PDF (0.1.4 or later for the margin).
842  
843 =item B<-o> I<FILE>, B<--output>=I<FILE>
844  
845 Write the output to I<FILE>, which is given to L<nup(1)|App::nup>.
846 When the name ends with C<.pdf>, the output is PDF without C<-T> as
847 well. Otherwise, what is shown on the terminal is written to the
848 file as it is.
849  
850 mdee -o README.pdf README.md
851  
852 =back
853  
854 =head1 THEMES
855  
856 A theme changes how the document looks: the colors, the marks that
857 are shown or hidden, and the decoration of headings and tables.
858 Themes are chosen with C<--theme> (see L</Theme Options>), and each
859 is applied in order as a transformation of the default.
860  
861 =head2 Built-in Themes
862  
863 =over 4
864  
865 =item C<hashed> (default)
866  
867 Append closing hashes to h3-h6 headers.
868  
869 =item C<nomark> (default)
870  
871 Hide emphasis markers (C<**>, C<*>, C<__>, C<_>, C<~~>),
872 inline code backticks, and link brackets (C<[>, C<]>).
873 Content text keeps its formatting (bold, italic,
874 strikethrough, code, clickable links) but the surrounding
875 markers are not displayed. Table marks (C<markcell>,
876 C<markwrap>) are independent of this theme.
877  
878 =item C<doubleline> (default)
879  
880 Give h4 headers a double underline, which is C<ESC[4:2m>, in the
881 terminals known to take it, decided by environment variables: iTerm2,
882 Ghostty, cmux, VS Code, WezTerm, kitty, Alacritty, Konsole, Windows
883 Terminal and terminals based on VTE 0.52 or later. Elsewhere, inside
884 B<tmux> and B<screen>, and where the variables do not reach, as through
885 B<ssh>, this theme does nothing and h4 has a single underline, the same
886 as h5. Many terminals do not take the sequence: it becomes a background color in Terminal.app and
887 rxvt-unicode, and the Linux console and mosh drop the whole sequence
888 with its color.
889  
890 =item C<warm>
891  
892 Change base color to Coral.
893  
894 =item C<fatchap>
895  
896 Add decorative border lines (C<#>) above and below h1 headings,
897 using C<=+> to append a text transformation while preserving the
898 original heading color.
899  
900 With C<--refill>, the added lines are not counted, so paragraphs below
901 the h1 headings may not be folded properly by this module. The text
902 itself does not change. For this reason, this theme turns off
903 C<default[refill]> in the configuration file; C<--refill> given on the
904 command line still works.
905  
906 =item C<widen>
907  
908 Give circled digits and the wastebasket (U+1F5D1) a column of their
909 own, by adding a no-break space after them, for terminals that draw
910 them over two columns on top of the next character, as on macOS.
911 This gives the function of L<App::Greple::md::widen> to the C<--begin>
912 option of the md module.
913  
914 The characters are listed in the array C<widen_chars> of the theme, as
915 code points and ranges in hexadecimal. Add more in F<config.sh>:
916  
917 widen_chars+=(3248-324F) # circled numbers on black squares
918  
919 =item C<markcell> (default)
920  
921 In a table that has wrapped cells, mark the first line of every
922 body cell in the wrapped columns with C<‣> (U+2023), so that the
923 rows read like a bulleted list and the continuation lines stand
924 apart. The header row, columns that fit, and tables that fit are
925 not marked. Sets C<table_cell_mark>; C<nomark> does not affect it.
926 To use another character, set it in the configuration file or in a
927 theme of your own:
928  
929 md_config+=(table_cell_mark=∙) # U+2219
930  
931 =item C<markwrap>
932  
933 Mark the second and later lines of a wrapped table cell with C<›>
934 (U+203A). Sets C<table_wrap_mark>. It can be combined with
935 C<markcell>.
936  
937 =back
938  
939 =head2 Theme Files
940  
941 Theme files are searched in the following order:
942  
943 =over 4
944  
945 =item 1. User theme directory: C<${XDG_CONFIG_HOME:-~/.config}/mdee/theme/NAME.sh>
946  
947 =item 2. Share theme directory: installed with the distribution under C<auto/share/dist/App-mdee/theme/>
948  
949 =back
950  
951 Theme files are Bash scripts that can modify C<theme_light[]>,
952 C<theme_dark[]>, C<md_config[]>, and/or C<pass_md[]>:
953  
954 # theme/warm.sh — change base color
955 theme_light[base]='<Coral>=y25'
956 theme_dark[base]='<Coral>=y80'
957  
958 # theme/hashed.sh — enable closing hashes on h3-h6
959 md_config+=(hashed.h3=1 hashed.h4=1 hashed.h5=1 hashed.h6=1)
960  
961 # theme/nomark.sh — hide markers and brackets
962 pass_md+=(--cm 'emphasis_mark=sub{""}')
963 pass_md+=(--cm 'code_tick=sub{""}')
964 pass_md+=(--cm 'link_mark=sub{""}')
965  
966 =head1 CONFIGURATION
967  
968 User configuration is loaded from:
969  
970 ${XDG_CONFIG_HOME:-~/.config}/mdee/config.sh
971  
972 This is a shell script that can set defaults and override colors:
973  
974 # ~/.config/mdee/config.sh
975 default[mode]='dark' # set default mode
976 default[theme]='warm' # set default theme(s)
977 default[style]='pager' # set default style
978 default[width]=170 # set default output width
979 default[fold_width]=80 # set default fold width
980 default[refill]=1 # join paragraph lines
981 default[lateral]=1 # all pages in one row
982 default[base_color]='DarkCyan' # set default base color
983  
984 The C<default> associative array supports the following keys:
985  
986 =over 4
987  
988 =item C<default[mode]> - Corresponds to C<--mode> (e.g., C<dark>, C<light>)
989  
990 =item C<default[theme]> - Corresponds to C<--theme> (e.g., C<warm>, C<warm,hashed>)
991  
992 =item C<default[style]> - Corresponds to C<--style> (e.g., C<pager>, C<cat>)
993  
994 =item C<default[width]> - Corresponds to C<--width> (e.g., C<170>)
995  
996 =item C<default[fold_width]> - Corresponds to C<--fold-width> (e.g., C<80>)
997  
998 =item C<default[refill]> - Corresponds to C<--refill> (C<1> to enable)
999  
1000 =item C<default[lateral]> - Corresponds to C<--lateral> (C<1> to enable)
1001  
1002 =item C<default[pane_width]> - Corresponds to C<--pane-width> (e.g., C<100>)
1003  
1004 =item C<default[pane]> - Corresponds to C<--pane> (e.g., C<2> or C<2,2>)
1005  
1006 =item C<default[base_color]> - Corresponds to C<--base-color> (e.g., C<DarkCyan>)
1007  
1008 =back
1009  
1010 B<Overriding theme colors>
1011  
1012 Config.sh can modify theme variables directly, using the same
1013 mechanism as theme files:
1014  
1015 # Change base color for both modes
1016 theme_light[base]='<DarkCyan>=y25'
1017 theme_dark[base]='<DarkCyan>=y80'
1018  
1019 # Enable md module features
1020 md_config+=(hashed.h3=1 hashed.h4=1 hashed.h5=1 hashed.h6=1)
1021  
1022 # Use another character for the table cell mark
1023 md_config+=(table_cell_mark=∙)
1024  
1025 These settings take precedence over the default themes.
1026  
1027 Changing the base color automatically affects all derived colors
1028 (h1, h2, bold, etc.) because the md module expands C<${base}>
1029 references.
1030  
1031 Use C<-d> to dump current theme values in sourceable format.
1032  
1033 B<Color specification format>
1034  
1035 Color specifications use L<Term::ANSIColor::Concise> format.
1036 The C<FG/BG> notation specifies foreground and background colors
1037 (e.g., C<L25D/${base};E> means gray foreground on base-colored background).
1038 The C<${base}> string is expanded to the base color value after loading.
1039  
1040 To change the text before it is formatted, give a function to the
1041 C<--begin> option of the md module:
1042  
1043 pass_md+=(--begin 'sub{ s/\(C\)/\x{A9}/g }')
1044  
1045 =head1 EXAMPLES
1046  
1047 mdee README.md # view markdown file
1048 mdee -C2 document.md # 2-column view
1049 mdee -C2,2 manual.md # 2x2 grid (4-up)
1050 mdee -w170 file.md # two 85-column panes on a wide terminal
1051 mdee -V -w170 a.md b.md # two files in 85 columns each
1052 mdee --fold-width=60 a.md # narrower text within the pane
1053 mdee --no-pager file.md # without pager
1054 mdee --no-nup file.md # output to stdout without nup
1055 mdee --no-fold file.md # disable line folding
1056 mdee --no-table file.md # disable table formatting
1057 mdee -r file.md # join paragraph lines
1058  
1059 # PDF
1060 mdee -o file.pdf file.md # A4 in landscape
1061 mdee -T a4p -o file.pdf file.md # A4 in portrait
1062 mdee -T a4p -C1,2 -o file.pdf file.md # two pages on a sheet
1063  
1064 # Output styles
1065 mdee -s pager file.md # fold + table, output to pager
1066 mdee -s cat file.md # fold + table, output to stdout
1067 mdee -s filter file.md # table only, no fold/nup
1068 mdee -s raw file.md # highlight only
1069  
1070 # Style shortcuts
1071 mdee -p file.md # same as --style=pager
1072 cat file.md | mdee -f # highlight stdin (filter mode)
1073 mdee -f file.md # highlighted output to stdout
1074  
1075 # Override individual settings
1076 mdee -f --fold file.md # filter + fold
1077 mdee -p --no-fold file.md # pager without fold
1078  
1079 # Theme examples
1080 mdee --mode=dark file.md # use dark mode
1081 mdee --mode=light file.md # use light mode
1082 mdee -B Ivory file.md # override base color
1083 mdee --mode=dark -B '#780043' file.md # dark mode with burgundy
1084 mdee --theme=warm file.md # warm (Coral) base color
1085 mdee --no-theme file.md # show all markup characters
1086  
1087 =head1 DEPENDENCIES
1088  
1089 This command requires the following:
1090  
1091 =over 4
1092  
1093 =item * L<App::Greple> - pattern matching and highlighting
1094  
1095 =item * L<App::Greple::tee> - filter integration
1096  
1097 =item * L<App::ansifold> - ANSI-aware text folding
1098  
1099 =item * L<App::ansicolumn> - ANSI-aware column formatting
1100  
1101 =item * L<App::nup> - N-up multi-column paged output
1102  
1103 =item * L<App::ansiecho> - ANSI color output
1104  
1105 =item * L<Getopt::Long::Bash> - bash option parsing
1106  
1107 =item * L<Getopt::EX::termcolor> - terminal background detection
1108  
1109 =back
1110  
1111 The code in fenced code blocks is colored by
1112 L<Text::ANSI::Highlight>, with C<pandoc> 3.4 or later
1113 (C<brew install pandoc>), or with C<source-highlight> or
1114 C<skylighting>. Without the command, the code is shown as it is.
1115  
1116 C<--refill> finds the paragraphs with L<Markdown::Perl> (pure Perl,
1117 installed with this distribution). The L<CommonMark> module, which
1118 needs the libcmark C library (C<brew install cmark>, C<apt-get install
1119 libcmark-dev>) and is only recommended, is used when it is there
1120 because it is faster; L<pandoc|https://pandoc.org> 2.11.3 or later is
1121 a third choice.
1122  
1123 =head1 LIMITATIONS
1124  
1125 =head2 HTML Comments
1126  
1127 Only HTML comments starting at the beginning of a line are highlighted.
1128 Inline comments are not matched to avoid conflicts with inline code
1129 containing comment-like text (e.g., C<< `<!-->` >>).
1130  
1131 =head2 Emphasis
1132  
1133 Emphasis patterns (bold and italic) do not span multiple lines.
1134 Multi-line emphasis text is not supported.
1135  
1136 C<***bold italic***> and C<___bold italic___> are supported.
1137 Other nested forms (e.g., C<< **bold _italic_** >>) are not.
1138  
1139 C<*> and C<**> start and end emphasis as in CommonMark: a delimiter
1140 with a letter on one side and punctuation on the other does not
1141 count, so C<L*=50, a*=68> is not italic. CommonMark counts Unicode
1142 punctuation, and this rejects some emphasis in Japanese text,
1143 such as C<日本語の*「強調」*です> and C<日本語の**強調。**です>. mdee
1144 shows them as the commonmark and gfm readers of pandoc and zenn.dev
1145 do, with the markers and without emphasis, so that such text can be
1146 found before it is published.
1147  
1148 With C<cjk_friendly=1> (C<--config cjk_friendly=1>, or
1149 C<md_config+=(cjk_friendly=1)> in F<config.sh>), the rules of
1150 L<markdown-cjk-friendly|https://github.com/tats-u/markdown-cjk-friendly>
1151 are used instead: CJK punctuation does not count, and a CJK character
1152 on the other side is as good as a space, so these are emphasis. This
1153 is a proposal, not part of CommonMark; use it for text that is
1154 processed by an implementation of it.
1155  
1156 =head2 Block Quotes
1157  
1158 A block quote is recognized by its C<E<gt>> markers at the start of a
1159 line, after up to three spaces. Only the markers are colored, not the
1160 quoted text. Headings, lists and code blocks inside a quote are not
1161 recognized, so they get no color of their own, and a code block in a
1162 quote does not protect its contents from inline highlighting.
1163  
1164 A line without a marker that continues a quoted paragraph (a lazy
1165 continuation in CommonMark) is shown as an ordinary line, unless
1166 C<--refill> joins it to the quote.
1167  
1168 =head2 Links
1169  
1170 Link patterns do not span multiple lines. The link text and URL must
1171 be on the same line.
1172  
1173 Reference-style links (C<[text][ref]> with C<[ref]: url> elsewhere)
1174 are not supported.
1175  
1176 =head2 Paragraph Refill
1177  
1178 C<--refill> joins lines by the rules of Markdown, as the parser
1179 reads them. Lines of verse, addresses or lyrics that rely on the line
1180 breaks without a hard line break (two spaces or a backslash at the
1181 end of the line) are joined as well, and so are the lines of a
1182 display math block between C<$$> lines. Do not use C<--refill>
1183 for such documents.
1184  
1185 =head2 Table Alignment
1186  
1187 Column alignment assumes that cell content in the source is not
1188 pre-padded. If the source table is already formatted with aligned
1189 spacing (e.g., C<| c |>), the embedded spaces become part of
1190 the cell content and alignment directives in the separator line
1191 will not produce the expected result. This is by design: pre-formatted
1192 tables are assumed to be correctly aligned as-is.
1193  
1194 =head2 OSC 8 Hyperlinks
1195  
1196 Links are converted to OSC 8 terminal hyperlinks for clickable URLs:
1197  
1198 =over 4
1199  
1200 =item C<[text](url)> - C<[text]> links to url
1201  
1202 =item C<![alt](url)> - C<![alt]> links to url (image)
1203  
1204 =item C<[![alt](img)](url)> - C<!> links to img, C<[alt]> links to url
1205  
1206 =back
1207  
1208 This requires terminal support. Compatible terminals include iTerm2,
1209 Kitty, WezTerm, Ghostty, and recent versions of GNOME Terminal.
1210 Apple's default Terminal.app does not support OSC 8.
1211  
1212 When using C<less> as pager, version 566 or later is required with
1213 C<-R> option.
1214  
1215 For OSC 8 specification, see:
1216 L<https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda>
1217  
1218 =head2 Terminal Luminance
1219  
1220 Without C<--mode> or C<default[mode]>, B<mdee> asks the terminal for
1221 its background color (OSC 11) through L<Getopt::EX::termcolor> to
1222 choose between light and dark mode. Set C<TERM_LUMINANCE> to a value
1223 from 0 to 100 to give the answer yourself and skip the query, for
1224 example in scripts or tests, where a reply that arrives late would
1225 show up as terminal input.
1226  
1227 =head2 Less Environment Variables
1228  
1229 When C<less> is used as pager (either directly via C<--style=pager> or
1230 through C<nup>), the following environment variables affect behavior.
1231 B<mdee> sets defaults for these when they are not already defined:
1232  
1233 =over 4
1234  
1235 =item C<LESS>
1236  
1237 Default: C<-R>. The C<-R> option is required for ANSI color
1238 sequences to be displayed correctly.
1239  
1240 =item C<LESSANSIENDCHARS>
1241  
1242 Default: C<mK>. This tells C<less> to recognize ANSI sequences
1243 ending with C<m> (SGR color) and C<K> (erase line). The erase line
1244 sequence is used for background color rendering.
1245  
1246 =back
1247  
1248 If you already have these variables set in your environment, B<mdee>
1249 does not override them.
1250  
1251 =head1 SEE ALSO
1252  
1253 =over 4
1254  
1255 =item L<Implementation of em·dee|https://github.com/tecolicom/App-mdee/blob/main/IMPLEMENTATION.md>
1256  
1257 How the pipeline, the themes and the colors work inside.
1258  
1259 =item L<App::Greple::md>
1260  
1261 Greple module for Markdown syntax highlighting, table formatting,
1262 and text folding. Bundled with this distribution.
1263  
1264 =item L<greple>
1265  
1266 General-purpose extensible grep tool used for pattern matching.
1267  
1268 =item L<nup>
1269  
1270 Multi-column paged output formatter.
1271  
1272 =item L<ansi2pdf|https://github.com/tecolicom/App-ansi2pdf>
1273  
1274 Renders the output to PDF.
1275  
1276 =item L<ansifold|https://metacpan.org/dist/App-ansifold/view/script/ansifold>
1277  
1278 ANSI-aware text folding for line wrapping.
1279  
1280 =item L<ansicolumn>
1281  
1282 ANSI-aware column formatting for table alignment.
1283  
1284 =item L<CommonMark>, L<Markdown::Perl>, L<pandoc|https://pandoc.org>
1285  
1286 One of them finds the paragraphs for C<--refill>.
1287  
1288 =item L<CommonMark Spec 0.31.2, Emphasis and strong emphasis|https://spec.commonmark.org/0.31.2/#emphasis-and-strong-emphasis>
1289  
1290 The rules that C<*> and C<**> follow by default (see L</Emphasis>).
1291  
1292 =item L<CommonMark CJK-friendly Amendments|https://github.com/tats-u/markdown-cjk-friendly/blob/main/specification.md>
1293  
1294 The rules that C<cjk_friendly=1> follows. The proposal comes from
1295 L<commonmark-spec issue #650, Emphasis with CJK punctuation|https://github.com/commonmark/commonmark-spec/issues/650>,
1296 open since 2020.
1297  
1298 =item L<https://github.com/tecolicom/App-mdee>
1299  
1300 Repository and bug tracker.
1301  
1302 =back
1303  
1304 =head1 AUTHOR
1305  
1306 Kazumasa Utashiro
1307  
1308 =head1 LICENSE
1309  
1310 Copyright © 2026 Kazumasa Utashiro.
1311  
1312 This software is released under the MIT License.
1313 L<https://opensource.org/licenses/MIT>
1314  
1315 =cut
« blib/lib/App/Greple/md/widen.pm ↑ Summary