


textutil::aTexttand string utilities, macro prtextutil::adjust(n)


______________________________________________________________________________

NAME
       textutil::adjust - Procedures to adjust, indent, and undent paragraphs

SYNOPSIS
       package require Tcl  8.2

       package require textutil::adjust  ?0.7?

       ::textutil::adjust::adjust string ?option value...?

       ::textutil::adjust::readPatterns filename

       ::textutil::adjust::listPredefined

       ::textutil::adjust::getPredefined filename

       ::textutil::adjust::indent string prefix ?skip?

       ::textutil::adjust::undent string

_________________________________________________________________

DESCRIPTION
       The  package textutil::adjust provides commands that manipulate strings
       or texts (a.k.a. long strings or string with embedded newlines or para-
       graphs), adjusting, or indenting them.

       The complete set of procedures is described below.

       ::textutil::adjust::adjust string ?option value...?
              Do  a justification on the string according to the options.  The
              string is taken as one big  paragraph,  ignoring  any  newlines.
              Then  the  line  is formatted according to the options used, and
              the command returns a new string with enough  lines  to  contain
              all  the printable chars in the input string. A line is a set of
              characters between the beginning of the string and a newline, or
              between  2  newlines,  or  between  a newline and the end of the
              string. If the input string is small enough, the returned string
              won't contain any newlines.

              Together  with ::textutil::adjust::indent it is possible to cre-
              ate properly wrapped paragraphs with arbitrary indentations.

              By default, any occurrence of space or tabulation characters are
              replaced  by a single space so that each word in a line is sepa-
              rated from the next one by exactly one space character, and this
              forms  a real line.  Each real line is placed in a logical line,
              which has exactly a given length (see the option -length below).
              The  real line may be shorter. Again by default, trailing spaces
              are ignored before returning the string (see  the  option  -full
              below).




textutil                       0.7                              1





textutil::aTexttand string utilities, macro prtextutil::adjust(n)


              The  following  options  may be used after the string parameter,
              and change the way the command places a real line in  a  logical
              line.

              -full boolean
                     If  set to false (default), trailing space characters are
                     deleted before returning the string. If set to true,  any
                     trailing space characters are left in the string.

              -hyphenate boolean
                     If  set  to false (default), no hyphenation will be done.
                     If set to true, the command will  try  to  hyphenate  the
                     last  word  of a line. Note: Hyphenation patterns must be
                     loaded prior, using the command ::textutil::adjust::read-
                     Patterns.

              -justify center|left|plain|right
                     Sets  the  justification of the returned string to either
                     left (default), center, plain or right. The justification
                     means  that  any line in the returned string but the last
                     one is build according to the value.  If  the  justifica-
                     tion is set to plain and the number of printable chars in
                     the last line is less than 90% of the length  of  a  line
                     (see  the  option  -length),  then this line is justified
                     with the left value, avoiding the expansion of this  line
                     when it is too small. The meaning of each value is:

                      center The real line is centered in the logical line. If
                             needed, a set of space characters  are  added  at
                             the beginning (half of the needed set) and at the
                             end (half of the  needed  set)  of  the  line  if
                             required (see the option -full).

                      left   The  real  line is set on the left of the logical
                             line. It means that there are no space  chars  at
                             the  beginning  of  this  line.  If required, all
                             needed space chars are added at the  end  of  the
                             line (see the option -full).

                      plain  The real line is exactly set in the logical line.
                             It means that there are no  leading  or  trailing
                             space chars. All the needed space chars are added
                             in the real line, between 2 (or more) words.

                      right  The real line is set on the right of the  logical
                             line.  It  means that there are no space chars at
                             the end of this line, and there may be some space
                             chars  at  the  beginning,  despite  of the -full
                             option.

              -length integer
                     Set the length of the logical line in the string to inte-
                     ger.   integer must be a positive integer value. Defaults
                     to 72.



textutil                       0.7                              2





textutil::aTexttand string utilities, macro prtextutil::adjust(n)


              -strictlength
                     boolean] If set to false (default), a line can exceed the
                     specified  -length  if  a  single  word  is  longer  than
                     -length. If set to  true,  words  that  are  longer  than
                     -length  are  split so that no line exceeds the specified
                     -length.

       ::textutil::adjust::readPatterns filename
              Loads the internal storage for  hyphenation  patterns  with  the
              contents  of  the  file  filename.  This has to be done prior to
              calling  command  ::textutil::adjust::adjust  with   "-hyphenate
              true", or the hyphenation process will not work correctly.

              The package comes with a number of predefined pattern files, and
              the command ::textutil::adjust::listPredefined can  be  used  to
              find out their names.

       ::textutil::adjust::listPredefined
              This  command returns a list containing the names of the hyphen-
              ation files coming with this package.

       ::textutil::adjust::getPredefined filename
              Use this command to query the package for the full path name  of
              the  hyphenation file filename coming with the package. Only the
              filenames   found   in   the   list   returned    by    ::textu-
              til::adjust::listPredefined  are  legal  arguments for this com-
              mand.

       ::textutil::adjust::indent string prefix ?skip?
              Each line in the string is indented by adding the string  prefix
              at  its beginning. The modified string is returned as the result
              of the command.

              If skip is specified the first skip lines  are  left  untouched.
              The  default  for  skip  is  0,  causing the modification of all
              lines. Negative values for skip are treated  like  0.  In  other
              words, skip > 0 creates a hanging indentation.

              Together  with ::textutil::adjust::adjust it is possible to cre-
              ate properly wrapped paragraphs with arbitrary indentations.

       ::textutil::adjust::undent string
              The command computes the common prefix for all lines  in  string
              consisting solely out of whitespace, removes this from each line
              and returns the modified string.

              Lines containing only whitespace  are  always  reduced  to  com-
              pletely  empty lines. They and empty lines are also ignored when
              computing the prefix to remove.

              Together with ::textutil::adjust::adjust it is possible to  cre-
              ate properly wrapped paragraphs with arbitrary indentations.





textutil                       0.7                              3





textutil::aTexttand string utilities, macro prtextutil::adjust(n)


BUGS, IDEAS, FEEDBACK
       This  document,  and the package it describes, will undoubtedly contain
       bugs and other problems.  Please report such in the  category  textutil
       of       the       Tcllib       SF       Trackers       [http://source-
       forge.net/tracker/?group_id=12883].  Please also report any  ideas  for
       enhancements you may have for either package and/or documentation.

SEE ALSO
       regexp(n), split(n), string(n)

KEYWORDS
       TeX,  adjusting,  formatting,  hyphenation,  indenting,  justification,
       paragraph, string, undenting

CATEGORY
       Text processing









































textutil                       0.7                              4


