1[manpage_begin textutil::adjust n 0.7]
2[moddesc   {Text and string utilities, macro processing}]
3[titledesc {Procedures to adjust, indent, and undent paragraphs}]
4[category  {Text processing}]
5[require Tcl 8.2]
6[require textutil::adjust [opt 0.7]]
7[description]
8
9The package [package textutil::adjust] provides commands that manipulate
10strings or texts (a.k.a. long strings or string with embedded newlines
11or paragraphs), adjusting, or indenting them.
12
13[para]
14
15The complete set of procedures is described below.
16
17[list_begin definitions]
18
19[call [cmd ::textutil::adjust::adjust] [arg string] [opt [arg "option value..."]]]
20
21Do a justification on the [arg string] according to the options.  The
22string is taken as one big paragraph, ignoring any newlines.  Then the
23line is formatted according to the options used, and the command
24returns a new string with enough lines to contain all the printable
25chars in the input string. A line is a set of characters between the
26beginning of the string and a newline, or between 2 newlines, or
27between a newline and the end of the string. If the input string is
28small enough, the returned string won't contain any newlines.
29
30[para]
31
32Together with [cmd ::textutil::adjust::indent] it is possible to
33create properly wrapped paragraphs with arbitrary indentations.
34
35[para]
36
37By default, any occurrence of space or tabulation characters are
38replaced by a single space so that each word in a line is separated
39from the next one by exactly one space character, and this forms a
40[emph real] line.
41
42Each [emph real] line is placed in a [emph logical] line, which has
43exactly a given length (see the option [option -length] below).
44
45The [emph real] line may be shorter. Again by default, trailing spaces
46are ignored before returning the string (see the option [option -full]
47below).
48
49[para]
50
51The following options may be used after the [arg string] parameter,
52and change the way the command places a [emph real] line in a
53[emph logical] line.
54
55
56[list_begin options]
57
58[opt_def -full [arg boolean]]
59
60If set to [const false] (default), trailing space characters are
61deleted before returning the string. If set to [const true], any
62trailing space characters are left in the string.
63
64[opt_def -hyphenate [arg boolean]]
65
66If set to [const false] (default), no hyphenation will be done. If set
67to [const true], the command will try to hyphenate the last word of a
68line. [emph Note]: Hyphenation patterns must be loaded prior, using
69the command [cmd ::textutil::adjust::readPatterns].
70
71
72[opt_def -justify [const center|left|plain|right]]
73
74Sets the justification of the returned string to either [const left]
75(default), [const center], [const plain] or [const right]. The
76justification means that any line in the returned string but the last
77one is build according to the value.
78
79If the justification is set to [const plain] and the number of
80printable chars in the last line is less than 90% of the length of a
81line (see the option [option -length]), then this line is justified
82with the [const left] value, avoiding the expansion of this line when
83it is too small. The meaning of each value is:
84
85[list_begin definitions]
86
87[def [const center]]
88
89The real line is centered in the logical line. If needed, a set of
90space characters are added at the beginning (half of the needed set)
91and at the end (half of the needed set) of the line if required (see
92the option [option -full]).
93
94[def [const left]]
95
96The real line is set on the left of the logical line. It means that
97there are no space chars at the beginning of this line. If required,
98all needed space chars are added at the end of the line (see the
99option [option -full]).
100
101[def [const plain]]
102
103The real line is exactly set in the logical line. It means that there
104are no leading or trailing space chars. All the needed space chars are
105added in the [emph real] line, between 2 (or more) words.
106
107[def [const right]]
108
109The real line is set on the right of the logical line. It means that
110there are no space chars at the end of this line, and there may be
111some space chars at the beginning, despite of the [option -full] option.
112
113[list_end]
114
115[opt_def  -length [arg integer]]
116
117Set the length of the [emph logical] line in the string to
118[arg integer].  [arg integer] must be a positive integer
119value. Defaults to [const 72].
120
121
122[opt_def -strictlength] [arg boolean]]
123
124If set to [const false] (default), a line can exceed the specified
125[option -length] if a single word is longer than [option -length]. If
126set to [const true], words that are longer than [option -length] are
127split so that no line exceeds the specified [option -length].
128
129[list_end]
130
131
132[call [cmd ::textutil::adjust::readPatterns] [arg filename]]
133
134Loads the internal storage for hyphenation patterns with the contents
135of the file [arg filename]. This has to be done prior to calling
136command [cmd ::textutil::adjust::adjust] with "[option -hyphenate]
137[const true]", or the hyphenation process will not work correctly.
138
139[para]
140
141The package comes with a number of predefined pattern files, and the
142command [cmd ::textutil::adjust::listPredefined] can be used to find
143out their names.
144
145[call [cmd ::textutil::adjust::listPredefined]]
146
147This command returns a list containing the names of the hyphenation
148files coming with this package.
149
150[call [cmd ::textutil::adjust::getPredefined] [arg filename]]
151
152Use this command to query the package for the full path name of the
153hyphenation file [arg filename] coming with the package. Only the
154filenames found in the list returned by
155
156[cmd ::textutil::adjust::listPredefined] are legal arguments for this
157command.
158
159
160[call [cmd ::textutil::adjust::indent] [arg string] [arg prefix] [opt [arg skip]]]
161
162Each line in the [arg string] is indented by adding the string
163[arg prefix] at its beginning. The modified string is returned
164as the result of the command.
165
166[para]
167
168If [arg skip] is specified the first [arg skip] lines are left
169untouched. The default for [arg skip] is [const 0], causing the
170modification of all lines. Negative values for [arg skip] are treated
171like [const 0]. In other words, [arg skip] > [const 0] creates a
172hanging indentation.
173
174[para]
175
176Together with [cmd ::textutil::adjust::adjust] it is possible to
177create properly wrapped paragraphs with arbitrary indentations.
178
179
180[call [cmd ::textutil::adjust::undent] [arg string]]
181
182The command computes the common prefix for all lines in [arg string]
183consisting solely out of whitespace, removes this from each line and
184returns the modified string.
185
186[para]
187
188Lines containing only whitespace are always reduced to completely
189empty lines. They and empty lines are also ignored when computing the
190prefix to remove.
191
192[para]
193
194Together with [cmd ::textutil::adjust::adjust] it is possible to
195create properly wrapped paragraphs with arbitrary indentations.
196
197[list_end]
198
199
200[section {BUGS, IDEAS, FEEDBACK}]
201
202This document, and the package it describes, will undoubtedly contain
203bugs and other problems.
204
205Please report such in the category [emph textutil] of the
206[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}].
207
208Please also report any ideas for enhancements you may have for either
209package and/or documentation.
210
211
212[see_also regexp(n) split(n) string(n)]
213[keywords string justification formatting TeX hyphenation]
214[keywords indenting undenting paragraph adjusting]
215[manpage_end]
216