NAME

       textwrap - line-folding (text-wrapping) library with i18n support

SYNOPSIS

       #include <textwrap.h>

       void textwrap_init(textwrap_t *prop);
       void textwrap_columns(textwrap_t *prop, int columns);
       void textwrap_tab(textwrap_t *prop, int tab);
       void textwrap_head(textwrap_t *prop, const char *head1, const char *head2);
       char *textwrap(const textwrap_t *prop, const char *text);

DESCRIPTION

       textwrap  is  a library to wrap given text to fit the terminal with a certain width.  This
       is like Text::Wrap(3pm).

       Unlike other libraries or functions, this supports internationalization.

       At first, this automatically detects the current  LC_CTYPE  locale  and  follows  it.   To
       enable this, your application must call setlocale(3) in advance.

       Next, this supports multibyte encodings such as UTF-8 and EUC-JP.  In multibyte encodings,
       one character consists from one or more bytes.

       Third, this supports fullwidth characters such as CJK Ideogram,  Katakana,  Hiragana,  and
       Hangul.  These characters occupy two columns per one character on the terminal.

       Forth,  this  supports  combining  characters  such as Thai and accents for Latin scripts.
       These characters occupy zero columns per one character on the terminal.

       Fifth, this supports languages which do not  use  whitespaces  between  words.   In  these
       languages,  lines  can  be  folded  at  any places with small amount of exception (such as
       before commas).

USAGE

       At first, you will have to prepare a set of parameters as textwrap_t.  Prepare a  variable
       of textwrap_t and then call textwrap_init() with the pointer to the variable.

       Members  of  textwrap_t  may  change  in future.  Thus, please use API functions to modify
       values of these members.

       textwrap_columns()
              Specifies the number of columns or width of your terminal.  The result string  will
              not have longer line than this value.  The default value is 76.

       textwrap_tab()
              Specifies the number of columns for TAB code.  The default is 8.

       textwrap_head()
              Specifies  strings  which  will  be  added at the top of the top line and following
              lines.  The defaults are NULL for head1 and NULL for head2.

       The real text-wrapping is performed by textwrap().  The text to  be  folded  is  given  as
       text.   The  text  must  be  encoded  in  the current LC_CTYPE locale, i.e., ISO-8859-1 in
       ISO-8859-1 locales, KOI8-R in KOI8-R locales, EUC-JP in EUC-JP  locales,  UTF-8  in  UTF-8
       locales,  and so on.  Though you might not be very familiar with the term LC_CTYPE locale,
       this behavior is under what most of users use UNIX-like systems.  Thus, you do not have to
       convert the encoding of the string.

       The  text  can  contain tab code (0x09).  The tab is converted into proper number of space
       code (0x20) by textwrap.

RETURN VALUE

       textwrap() returns the line-folded text.  You can free(3) the given value.

       In case of any error while processing the string, the text <ERR> will be appended  to  the
       output and processing will be aborted.

EXAMPLE

       #include <stdio.h>
       #include <textwrap.h>

       main()
       {
           textwrap_t property;
           char *text = "This is a sample.\n";
           char *outtext;

           textwrap_init(&property);
           textwrap_columns(&property, 70);
           outtext = textwrap(&property, text);
           printf("%s\n",outtext);
           free(outtext);
       }

SEE ALSO

       Manual pages of dotextwrap(1), setlocale(3), locale(7), charsets(7), and UTF-8(7).

AUTHOR

       Tomohiro KUBOTA <kubota@debian.org>.

                                            2003-08-16                                textwrap(3)