1Reflow(3) User Contributed Perl Documentation Reflow(3)
2
6 Text::Reflow - Perl module for reflowing text files using Knuth's
7 paragraphing algorithm.
8
10 use Text::Reflow qw(reflow_file reflow_string reflow_array);
11 reflow_file($infile, $outfile, key => value, ...);
13 $output = reflow_string($input, key => value, ...);
15 $output = reflow_array(\@input, key => value, ...);
17
19 These routines will reflow the paragraphs in the given file,
20 filehandle, string or array using Knuth's paragraphing algorithm (as
21 used in TeX) to pick "good" places to break the lines.
22 Each routine takes ascii text data with paragraphs separated by blank
24 lines and reflows the paragraphs. If two or more lines in a row are
25 "indented" then they are assumed to be a quoted poem and are passed
26 through unchanged (but see below)
27 The reflow algorithm tries to keep the lines the same length but also
29 tries to break at punctuation, and avoid breaking within a proper name
30 or after certain connectives ("a", "the", etc.). The result is a file
31 with a more "ragged" right margin than is produced by "fmt" or
32 "Text::Wrap" but it is easier to read since fewer phrases are broken
33 across line breaks.
34 For "reflow_file", if $infile is the empty string, then the input is
36 taken from STDIN and if $outfile is the empty string, the output is
37 written to STDOUT. Otherwise, $infile and $outfile may be a string, a
38 FileHandle reference or a FileHandle glob.
39 A typical invocation is:
41 reflow_file("myfile", "");
43 which reflows the whole of myfile and prints the result to STDOUT.
45 KEYWORD OPTIONS
47 The behaviour of Reflow can be adjusted by setting various keyword
48 options. These can be set globally by referencing the appropriate
49 variable in the Text::Reflow package, for example:
50 $Text::Reflow::maximum = 80;
52 $Text::Reflow::optimum = 75;
53 will set the maximum line length to 80 characters and the optimum line
55 length to 75 characters for all subsequent reflow operations. Or they
56 can be passed to a reflow_ function as a keyword parameter, for
57 example:
58 $out = reflow_string($in, maximum => 80, optimum => 75);
60 in which case the new options only apply to this call.
62 The following options are currently implemented, with their default
64 values:
65 optimum => [65]
67 The optimum line length in characters. This can be either a number
68 or a reference to an array of numbers: in the latter case, each
69 optimal line length is tried in turn for each paragraph, and the
70 one which leads to the best overall paragraph is chosen. This
71 results in less ragged paragraphs, but some paragraphs will be
72 wider or narrower overall than others.
73 maximum => 75
75 The maximum allowed line length.
76 indent => ""
78 Each line of output has this string prepended. "indent => string"
79 is equivalent to "indent1 => string, indent2 => string".
80 indent1 => ""
82 A string which is used to indent the first line in any paragraph.
83 indent2 => ""
85 A string which is used to indent the second and subsequent line in
86 any paragraph.
87 quote => ""
89 Characters to strip from the beginning of a line before processing.
90 To reflow a quoted email message and then restore the quotes you
91 might want to use
92 quote => "> ", indent => "> "
94 skipto => ""
96 Skip to the first line starting with the given pattern before
97 starting to reflow. This is useful for skipping Project Gutenberg
98 headers or contents tables.
99 skipindented => 2
101 If "skipindented" = 0 then all indented lines are flowed in with
102 the surrounding paragraph. If "skipindented" = 1 then any indented
103 line will not be reflowed. If "skipindented" = 2 then any two or
104 more adjacent indented lines will not be reflowed. The purpose of
105 the default value is to allow poetry to pass through unchanged, but
106 not to allow a paragraph indentation from preventing the first line
107 of the paragraph from being reflowed.
108 noreflow => ""
110 A pattern to indicate that certain lines should not be reflowed.
111 For example, a table of contents might have a line of dots. The
112 option:
113 noreflow => '(\.\s*){4}\.'
115 will not reflow any lines containing five or more consecutive dots.
117 frenchspacing => 'n'
119 Normally two spaces are put at the end of a sentence or a clause.
120 The "frenchspacing" option (taken from the TeX macro of the same
121 name) disables this feature.
122 oneparagraph => 'n'
124 Set this to 'y' if you want the whole input to be flowed into a
125 single paragraph, ignoring blank lines in the input.
126 semantic => 30
128 This parameter indicates the extent to which semantic factors
129 matter (breaking on punctuation, avoiding a break within a clause
130 etc.). Set this to zero to minimise the raggedness of the right
131 margin, at the expense of readability.
132 namebreak => 10
134 Penalty for splitting up a name
135 sentence => 20
137 Penalty for sentence widows and orphans (ie splitting a line
138 immediately after the first word in a sentence, or before the last
139 word in a sentence)
140 independent => 10
142 Penalty for independent clause widows and orphans.
143 dependent => 6
145 Penalty for dependent clause widows and orphans.
146 shortlast => 5
148 Penalty for a short last line in a paragraph (one or two words).
149 connpenalty => 1
151 Multiplier for the "negative penalty" for breaking at a connective.
152 In other words, increasing this value makes connectives an even
153 more attractive place to break a line.
154 EXPORT
156 None by default.
157
159 Original "reflow" perl script written by Michael Larsen,
160 larsen@edu.upenn.math.
161 Modified, enhanced and converted to a perl module with XSUB by Martin
163 Ward, martin@gkc.org.uk
164
166 perl(1).
167 See "TeX the Program" by Donald Knuth for a description of the
169 algorithm used.
170perl v5.36.0 2023-01-20 Reflow(3)