1Reflow(3)             User Contributed Perl Documentation            Reflow(3)
2
3
4

NAME

6       Text::Reflow - Perl module for reflowing text files using Knuth's
7       paragraphing algorithm.
8

SYNOPSIS

10               use Text::Reflow qw(reflow_file reflow_string reflow_array);
11
12               reflow_file($infile, $outfile, key => value, ...);
13
14               $output = reflow_string($input, key => value, ...);
15
16               $output = reflow_array(\@input, key => value, ...);
17

DESCRIPTION

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
23       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
28       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
35       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
40       A typical invocation is:
41
42               reflow_file("myfile", "");
43
44       which reflows the whole of myfile and prints the result to STDOUT.
45
46   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
51               $Text::Reflow::maximum = 80;
52               $Text::Reflow::optimum = 75;
53
54       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
59               $out = reflow_string($in, maximum => 80, optimum => 75);
60
61       in which case the new options only apply to this call.
62
63       The following options are currently implemented, with their default
64       values:
65
66       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
74       maximum => 75
75           The maximum allowed line length.
76
77       indent => ""
78           Each line of output has this string prepended. "indent => string"
79           is equivalent to "indent1 => string, indent2 => string".
80
81       indent1 => ""
82           A string which is used to indent the first line in any paragraph.
83
84       indent2 => ""
85           A string which is used to indent the second and subsequent line in
86           any paragraph.
87
88       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
93                   quote => "> ", indent => "> "
94
95       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
100       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
109       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
114                   noreflow => '(\.\s*){4}\.'
115
116           will not reflow any lines containing five or more consecutive dots.
117
118       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
123       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
127       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
133       namebreak => 10
134           Penalty for splitting up a name
135
136       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
141       independent => 10
142           Penalty for independent clause widows and orphans.
143
144       dependent => 6
145           Penalty for dependent clause widows and orphans.
146
147       shortlast => 5
148           Penalty for a short last line in a paragraph (one or two words).
149
150       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
155   EXPORT
156       None by default.
157

AUTHOR

159       Original "reflow" perl script written by Michael Larsen,
160       larsen@edu.upenn.math.
161
162       Modified, enhanced and converted to a perl module with XSUB by Martin
163       Ward, martin@gkc.org.uk
164

SEE ALSO

166       perl(1).
167
168       See "TeX the Program" by Donald Knuth for a description of the
169       algorithm used.
170
171
172
173perl v5.32.1                      2021-01-27                         Reflow(3)
Impressum