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