665 of a user-specific configuration file, such as \fB~/.teclarc\fR. For example,
 666 in the call
 667 .sp
 668 .in +2
 669 .nf
 670 gl_configure_getline(gl, "edit-mode vi \en nobeep",
 671                      "/usr/share/myapp/teclarc", "~/.teclarc");
 672 .fi
 673 .in -2
 674 
 675 .sp
 676 .LP
 677 The \fIapp_string\fR argument causes the calling application to start in
 678 \fBvi\fR(1) edit-mode, instead of the default \fBemacs\fR mode, and turns off
 679 the use of the terminal bell by the library. It then attempts to read
 680 system-wide configuration commands from an optional file called
 681 \fB/usr/share/myapp/teclarc\fR, then finally reads user-specific configuration
 682 commands from an optional \fB\&.teclarc\fR file in the user's home directory.
 683 Note that the arguments are listed in ascending order of priority, with the
 684 contents of \fIapp_string\fR being potentially over riden by commands in
 685 \fIapp_file\fR, and commands in \fIapp_file\fR potentially being overriden by
 686 commands in \fIuser_file\fR.
 687 .sp
 688 .LP
 689 You can call this function as many times as needed, the results being
 690 cumulative, but note that copies of any file names specified with the
 691 \fIapp_file\fR and \fIuser_file\fR arguments are recorded internally for
 692 subsequent use by the read-init-files key-binding function, so if you plan to
 693 call this function multiple times, be sure that the last call specifies the
 694 filenames that you want re-read when the user requests that the configuration
 695 files be re-read.
 696 .sp
 697 .LP
 698 Individual key sequences can also be bound and unbound using the
 699 \fBgl_bind_keyseq()\fR function. The \fIorigin\fR argument specifies the
 700 priority of the binding, according to whom it is being established for, and
 701 must be one of the following two values.
 702 .sp
 703 .ne 2
 704 .na
 705 \fB\fBGL_USER_KEY\fR\fR

2281 arranges for the current input line to be redrawn from scratch when
2282 \fBgl_get_line()\fR is next called.
2283 .SS "Displaying Text Dynamically"
2284 .LP
2285 Between calls to \fBgl_get_line()\fR, the \fBgl_display_text()\fR function
2286 provides a convenient way to display paragraphs of text, left-justified and
2287 split over one or more terminal lines according to the constraints of the
2288 current width of the terminal. Examples of the use of this function may be
2289 found in the demo programs, where it is used to display introductions. In those
2290 examples the advanced use  of optional prefixes, suffixes and filled lines to
2291 draw a box around the text is also illustrated.
2292 .sp
2293 .LP
2294 If \fIgl\fR is not currently connected to a terminal, for example if the output
2295 of a program that uses \fBgl_get_line()\fR is being piped to another program or
2296 redirected to a file, then the value of the \fIdef_width\fR parameter is used
2297 as the terminal width.
2298 .sp
2299 .LP
2300 The \fIindentation\fR argument specifies the number of characters to use to
2301 indent each line of ouput. The \fIfill_char\fR argument specifies the character
2302 that will be used to perform this indentation.
2303 .sp
2304 .LP
2305 The \fIprefix\fR argument can be either \fINULL\fR or a string to place at the
2306 beginning of each new line (after any indentation). Similarly, the \fIsuffix\fR
2307 argument can be either \fINULL\fR or a string to place at the end of each line.
2308 The suffix is placed flush against the right edge of the terminal, and any
2309 space between its first character and the last word on that line is filled with
2310 the character specified by the \fIfill_char\fR argument. Normally the
2311 fill-character is a space.
2312 .sp
2313 .LP
2314 The \fIstart\fR argument tells \fBgl_display_text()\fR how many characters have
2315 already been written to the current terminal line, and thus tells it the
2316 starting column index of the cursor. Since the return value of
2317 \fBgl_display_text()\fR is the ending column index of the cursor, by passing
2318 the return value of one call to the start argument of the next call, a
2319 paragraph that is broken between more than one string can be composed by
2320 calling \fBgl_display_text()\fR for each successive portion of the paragraph.
2321 Note that literal newline characters are necessary at the end of each paragraph

 665 of a user-specific configuration file, such as \fB~/.teclarc\fR. For example,
 666 in the call
 667 .sp
 668 .in +2
 669 .nf
 670 gl_configure_getline(gl, "edit-mode vi \en nobeep",
 671                      "/usr/share/myapp/teclarc", "~/.teclarc");
 672 .fi
 673 .in -2
 674 
 675 .sp
 676 .LP
 677 The \fIapp_string\fR argument causes the calling application to start in
 678 \fBvi\fR(1) edit-mode, instead of the default \fBemacs\fR mode, and turns off
 679 the use of the terminal bell by the library. It then attempts to read
 680 system-wide configuration commands from an optional file called
 681 \fB/usr/share/myapp/teclarc\fR, then finally reads user-specific configuration
 682 commands from an optional \fB\&.teclarc\fR file in the user's home directory.
 683 Note that the arguments are listed in ascending order of priority, with the
 684 contents of \fIapp_string\fR being potentially over riden by commands in
 685 \fIapp_file\fR, and commands in \fIapp_file\fR potentially being overridden by
 686 commands in \fIuser_file\fR.
 687 .sp
 688 .LP
 689 You can call this function as many times as needed, the results being
 690 cumulative, but note that copies of any file names specified with the
 691 \fIapp_file\fR and \fIuser_file\fR arguments are recorded internally for
 692 subsequent use by the read-init-files key-binding function, so if you plan to
 693 call this function multiple times, be sure that the last call specifies the
 694 filenames that you want re-read when the user requests that the configuration
 695 files be re-read.
 696 .sp
 697 .LP
 698 Individual key sequences can also be bound and unbound using the
 699 \fBgl_bind_keyseq()\fR function. The \fIorigin\fR argument specifies the
 700 priority of the binding, according to whom it is being established for, and
 701 must be one of the following two values.
 702 .sp
 703 .ne 2
 704 .na
 705 \fB\fBGL_USER_KEY\fR\fR

2281 arranges for the current input line to be redrawn from scratch when
2282 \fBgl_get_line()\fR is next called.
2283 .SS "Displaying Text Dynamically"
2284 .LP
2285 Between calls to \fBgl_get_line()\fR, the \fBgl_display_text()\fR function
2286 provides a convenient way to display paragraphs of text, left-justified and
2287 split over one or more terminal lines according to the constraints of the
2288 current width of the terminal. Examples of the use of this function may be
2289 found in the demo programs, where it is used to display introductions. In those
2290 examples the advanced use  of optional prefixes, suffixes and filled lines to
2291 draw a box around the text is also illustrated.
2292 .sp
2293 .LP
2294 If \fIgl\fR is not currently connected to a terminal, for example if the output
2295 of a program that uses \fBgl_get_line()\fR is being piped to another program or
2296 redirected to a file, then the value of the \fIdef_width\fR parameter is used
2297 as the terminal width.
2298 .sp
2299 .LP
2300 The \fIindentation\fR argument specifies the number of characters to use to
2301 indent each line of output. The \fIfill_char\fR argument specifies the character
2302 that will be used to perform this indentation.
2303 .sp
2304 .LP
2305 The \fIprefix\fR argument can be either \fINULL\fR or a string to place at the
2306 beginning of each new line (after any indentation). Similarly, the \fIsuffix\fR
2307 argument can be either \fINULL\fR or a string to place at the end of each line.
2308 The suffix is placed flush against the right edge of the terminal, and any
2309 space between its first character and the last word on that line is filled with
2310 the character specified by the \fIfill_char\fR argument. Normally the
2311 fill-character is a space.
2312 .sp
2313 .LP
2314 The \fIstart\fR argument tells \fBgl_display_text()\fR how many characters have
2315 already been written to the current terminal line, and thus tells it the
2316 starting column index of the cursor. Since the return value of
2317 \fBgl_display_text()\fR is the ending column index of the cursor, by passing
2318 the return value of one call to the start argument of the next call, a
2319 paragraph that is broken between more than one string can be composed by
2320 calling \fBgl_display_text()\fR for each successive portion of the paragraph.
2321 Note that literal newline characters are necessary at the end of each paragraph