12212 typos in some section 3tecla man pages

@@ -23,11 +23,11 @@
 .\" Except as contained in this notice, the name of a copyright holder
 .\" shall not be used in advertising or otherwise to promote the sale, use
 .\" or other dealings in this Software without prior written authorization
 .\" of the copyright holder.
 .\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
-.TH GL_GET_LINE 3TECLA "April 9, 2016"
+.TH GL_GET_LINE 3TECLA "January 18, 2020"
 .SH NAME
 gl_get_line, new_GetLine, del_GetLine, gl_customize_completion,
 gl_change_terminal, gl_configure_getline, gl_load_history, gl_save_history,
 gl_group_history, gl_show_history, gl_watch_fd, gl_inactivity_timeout,
 gl_terminal_size, gl_set_term_size, gl_resize_history, gl_limit_history,

@@ -37,11 +37,10 @@
 gl_completion_action, gl_register_action, gl_display_text, gl_return_status,
 gl_error_message, gl_catch_blocked, gl_list_signals, gl_bind_keyseq,
 gl_erase_terminal, gl_automatic_history, gl_append_history, gl_query_char,
 gl_read_char \- allow the user to compose an input line
 .SH SYNOPSIS
-.LP
 .nf
 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ltecla\fR [ \fIlibrary\fR\&.\|.\|. ]
 #include <stdio.h>
 #include <libtecla.h>
 

@@ -265,21 +264,19 @@
 .nf
 \fBint\fR \fBgl_erase_terminal\fR(\fBGetLine *\fR\fIgl\fR);
 .fi
 
 .SH DESCRIPTION
-.LP
 The \fBgl_get_line()\fR function is part of the \fBlibtecla\fR(3LIB) library.
 If the user is typing at a terminal, each call prompts them for a line of
 input, then provides interactive editing facilities, similar to those of the
 UNIX \fBtcsh\fR shell. In addition to simple command-line editing, it supports
 recall of previously entered command lines, TAB completion of file names, and
 in-line wild-card expansion of filenames. Documentation of both the user-level
 command-line editing features and all user configuration options can be found
 on the \fBtecla\fR(5) manual page.
 .SS "An Example"
-.LP
 The following shows a complete example of how to use the \fBgl_get_line()\fR
 function to get input from the user:
 .sp
 .in +2
 .nf

@@ -320,11 +317,10 @@
 return value of \fBdel_GetLine()\fR to make \fIgl\fR \fINULL\fR. This is a
 safety precaution. If the program subsequently attempts to pass \fIgl\fR to
 \fBgl_get_line()\fR, said function will complain, and return an error, instead
 of attempting to use the deleted resource object.
 .SS "The Functions Used In The Example"
-.LP
 The \fBnew_GetLine()\fR function creates the resources used by the
 \fBgl_get_line()\fR function and returns an opaque pointer to the object that
 contains them. The maximum length of an input line is specified by the
 \fIlinelen\fR argument, and the number of bytes to allocate for storing history
 lines is set by the \fIhistlen\fR argument. History lines are stored

@@ -373,11 +369,10 @@
 store in the internal buffer. In the latter case you should call
 \fBgl_get_line()\fR again to read the rest of the line. Note that this behavior
 makes \fBgl_get_line()\fR similar to \fBfgets\fR(3C). When \fBstdin\fR is not
 connected to a terminal, \fBgl_get_line()\fR simply calls \fBfgets()\fR.
 .SS "The Return Status Of \fBgl_get_line()\fR"
-.LP
 The \fBgl_get_line()\fR function has two possible return values: a pointer to
 the completed input line, or \fINULL\fR. Additional information about what
 caused \fBgl_get_line()\fR to return is available both by inspecting
 \fBerrno\fR and by calling the \fBgl_return_status()\fR function.
 .sp

@@ -431,11 +426,11 @@
 .ne 2
 .na
 \fB\fBGLR_FDABORT\fR\fR
 .ad
 .RS 15n
-An application I/O callback returned \fBGLFD_ABORT\fR. Ssee
+An application I/O callback returned \fBGLFD_ABORT\fR. See
 \fBgl_watch_fd()\fR.
 .RE
 
 .sp
 .ne 2

@@ -473,11 +468,10 @@
 \fIbuff\fR argument is provided, the error message, including a '\e0'
 terminator, will be written within the first \fIn\fR elements of this buffer,
 and the return value will be a pointer to the first element of this buffer. If
 the message will not fit in the provided buffer, it will be truncated to fit.
 .SS "Optional Prompt Formatting"
-.LP
 Whereas by default the prompt string that you specify is displayed literally
 without any special interpretation of the characters within it, the
 \fBgl_prompt_style()\fR function can be used to enable optional formatting
 directives within the prompt.
 .sp

@@ -630,11 +624,10 @@
 In this style, the prompt string is printed literally. This is the default
 style.
 .RE
 
 .SS "Alternate Configuration Sources"
-.LP
 By default users have the option of configuring the behavior of
 \fBgl_get_line()\fR with a configuration file called \fB\&.teclarc\fR in their
 home directories. The fact that all applications share this same configuration
 file is both an advantage and a disadvantage. In most cases it is an advantage,
 since it encourages uniformity, and frees the user from having to configure

@@ -679,11 +672,11 @@
 the use of the terminal bell by the library. It then attempts to read
 system-wide configuration commands from an optional file called
 \fB/usr/share/myapp/teclarc\fR, then finally reads user-specific configuration
 commands from an optional \fB\&.teclarc\fR file in the user's home directory.
 Note that the arguments are listed in ascending order of priority, with the
-contents of \fIapp_string\fR being potentially over riden by commands in
+contents of \fIapp_string\fR being potentially overridden by commands in
 \fIapp_file\fR, and commands in \fIapp_file\fR potentially being overridden by
 commands in \fIuser_file\fR.
 .sp
 .LP
 You can call this function as many times as needed, the results being

@@ -729,11 +722,10 @@
 and is expressed in the same way as in a \fB~/.teclarc\fR configuration file.
 The \fIaction\fR argument must either be a string containing the name of the
 action to bind the key sequence to, or it must be \fINULL\fR or \fB""\fR to
 unbind the key sequence.
 .SS "Customized Word Completion"
-.LP
 If in your application you would like to have TAB completion complete other
 things in addition to or instead of filenames, you can arrange this by
 registering an alternate completion callback function with a call to the
 \fBgl_customize_completion()\fR function.
 .sp

@@ -754,29 +746,28 @@
 being completed. It then must lookup possible completions of this word, and
 record them one by one in the \fBWordCompletion\fR object that is passed to it
 as an argument, by calling the \fBcpl_add_completion()\fR function. If the
 callback function wants to provide filename completion in addition to its own
 specific completions, it has the option of itself calling the builtin filename
-completion callback. This also is documented on the
+completion callback. This is also documented in the
 \fBcpl_complete_word\fR(3TECLA) manual page.
 .sp
 .LP
 If you would like \fBgl_get_line()\fR to return the current input line when a
-successful completion is been made, you can arrange this when you call
+successful completion has been made, you can arrange this when you call
 \fBcpl_add_completion()\fR by making the last character of the continuation
 suffix a newline character. The input line will be updated to display the
-completion, together with any contiuation suffix up to the newline character,
+completion, together with any continuation suffix up to the newline character,
 and \fBgl_get_line()\fR will return this input line.
 .sp
 .LP
 If your callback function needs to write something to the terminal, it must
 call \fBgl_normal_io()\fR before doing so. This will start a new line after the
 input line that is currently being edited, reinstate normal terminal I/O, and
 notify \fBgl_get_line()\fR that the input line will need to be redrawn when the
 callback returns.
 .SS "Adding Completion Actions"
-.LP
 In the previous section the ability to customize the behavior of the only
 default completion action, complete-word, was described. In this section the
 ability to install additional action functions, so that different types of word
 completion can be bound to different key sequences, is described. This is
 achieved by using the \fBgl_completion_action()\fR function.

@@ -797,11 +788,11 @@
 default key sequence to bind the action to. If this is \fINULL\fR, no new key
 sequence will be bound to the action.
 .sp
 .LP
 Beware that in order for the user to be able to change the key sequence that is
-bound to actions that are installed in this manner, you shouldcall
+bound to actions that are installed in this manner, you should call
 \fBgl_completion_action()\fR to install a given action for the first time
 between calling \fBnew_GetLine()\fR and the first call to \fBgl_get_line()\fR.
 Otherwise, when the user's configuration file is read on the first call to
 \fBgl_get_line()\fR, the name of the your additional action will not be known,
 and any reference to it in the configuration file will generate an error.

@@ -809,11 +800,10 @@
 .LP
 As discussed for \fBgl_customize_completion()\fR, if your callback function
 needs to write anything to the terminal, it must call \fBgl_normal_io()\fR
 before doing so.
 .SS "Defining Custom Actions"
-.LP
 Although the built-in key-binding actions are sufficient for the needs of most
 applications, occasionally a specialized application may need to define one or
 more custom actions, bound to application-specific key sequences. For example,
 a sales application would benefit from having a key sequence that displayed the
 part name that corresponded to a part number preceding the cursor. Such a

@@ -935,11 +925,10 @@
 name by which a user can refer to the action in their configuration file. This
 allows them to re-bind the action to an alternate key-sequence. In order for
 this to work, it is necessary to call \fBgl_register_action()\fR between
 calling \fBnew_GetLine()\fR and the first call to \fBgl_get_line()\fR.
 .SS "History Files"
-.LP
 To save the contents of the history buffer before quitting your application and
 subsequently restore them when you next start the application, the
 \fBgl_save_history()\fR and \fBgl_load_history()\fR functions are provided.
 .sp
 .LP

@@ -964,15 +953,14 @@
 The \fImax_lines\fR argument must be either -1 to specify that all lines in the
 history list be saved, or a positive number specifying a ceiling on how many of
 the most recent lines should be saved.
 .sp
 .LP
-Both fuctions return non-zero on error, after writing an error message to
+Both functions return non-zero on error, after writing an error message to
 \fBstderr\fR. Note that \fBgl_load_history()\fR does not consider the
 non-existence of a file to be an error.
 .SS "Multiple History Lists"
-.LP
 If your application uses a single \fBGetLine\fR object for entering many
 different types of input lines, you might want \fBgl_get_line()\fR to
 distinguish the different types of lines in the history list, and only recall
 lines that match the current type of line. To support this requirement,
 \fBgl_get_line()\fR marks lines being recorded in the history list with an

@@ -991,11 +979,10 @@
 Whenever \fBgl_get_line()\fR appends a new input line to the history list, the
 current history identifier is recorded with it, and when it is asked to recall
 a historical input line, it only recalls lines that are marked with the current
 identifier.
 .SS "Displaying History"
-.LP
 The history list can be displayed by calling \fBgl_show_history()\fR. This
 function displays the current contents of the history list to the \fBstdio\fR
 output stream \fIfp\fR. If the \fImax_lines\fR argument is greater than or
 equal to zero, then no more than this number of  the most recent lines will be
 displayed. If the \fIall_groups\fR argument is non-zero, lines from all history

@@ -1069,11 +1056,10 @@
 
 .sp
 .LP
 Note the inclusion of an explicit newline character in the format string.
 .SS "Looking Up History"
-.LP
 The \fBgl_lookup_history()\fR function allows the calling application to look
 up lines in the history list.
 .sp
 .LP
 The \fIid\fR argument indicates which line to look up, where the first line

@@ -1090,11 +1076,10 @@
 Beware that the string returned in \fIhline\fR->\fIline\fR is part of the
 history buffer, so it must not be modified by the caller, and will be recycled
 on the next call to any function that takes \fIgl\fR as its argument. Therefore
 you should make a private copy of this string if you need to keep it.
 .SS "Manual History Archival"
-.LP
 By default, whenever a line is entered by the user, it is automatically
 appended to the history list, just before \fBgl_get_line()\fR returns the line
 to the caller. This is convenient for the majority of applications, but there
 are also applications that need finer-grained control over what gets added to
 the history list. In such cases, the automatic addition of entered lines to the

@@ -1145,11 +1130,10 @@
 A textual description of the error can optionally be obtained by calling
 \fBgl_error_message()\fR. Note that after such an error, the history list
 remains in a valid state to receive new history lines, so there is little harm
 in simply ignoring the return status of \fBgl_append_history()\fR.
 .SS "Miscellaneous History Configuration"
-.LP
 If you wish to change the size of the history buffer that was originally
 specified in the call to \fBnew_GetLine()\fR, you can do so with the
 \fBgl_resize_history()\fR function.
 .sp
 .LP

@@ -1190,11 +1174,10 @@
 Setting the \fIenable\fR argument to 0 turns off the history mechanism, and
 setting it to 1 turns it back on. When history is turned off, no new lines will
 be added to the history list, and history lookup key-bindings will act as
 though there is nothing in the history buffer.
 .SS "Querying History Information"
-.LP
 The configured state of the history list can be queried with the
 \fBgl_history_state()\fR function. On return, the status information is
 recorded in the variable pointed to by the \fIstate\fR argument.
 .sp
 .LP

@@ -1211,11 +1194,10 @@
 .sp
 .LP
 On return, the size information is recorded in the variable pointed to by the
 \fIsize\fR argument.
 .SS "Changing Terminals"
-.LP
 The \fBnew_GetLine()\fR constructor function assumes that input is to be read
 from \fBstdin\fR and output written to \fBstdout\fR. The following function
 allows you to switch to different input and output streams.
 .sp
 .LP

@@ -1237,11 +1219,10 @@
 .LP
 Note that if you want to pass file descriptors to \fBgl_change_terminal()\fR,
 you can do this by creating \fBstdio\fR stream wrappers using the POSIX
 \fBfdopen\fR(3C) function.
 .SS "External Event Handling"
-.LP
 By default, \fBgl_get_line()\fR does not return until either a complete input
 line has been entered by the user, or an error occurs. In programs that need to
 watch for I/O from other sources than the terminal, there are two options.
 .RS +4
 .TP

@@ -1378,11 +1359,10 @@
 To remove a callback function that you previously registered for a given file
 descriptor and event, simply call \fBgl_watch_fd()\fR with the same \fIfd\fR
 and \fIevent\fR arguments, but with a \fIcallback\fR argument of 0. The
 \fIdata\fR argument is ignored in this case.
 .SS "Setting An Inactivity Timeout"
-.LP
 The \fBgl_inactivity_timeout()\fR function can be used to set or cancel an
 inactivity timeout. Inactivity in this case refers both to keyboard input, and
 to I/O on any file descriptors registered by prior and subsequent calls to
 \fBgl_watch_fd()\fR.
 .sp

@@ -1472,11 +1452,10 @@
 .sp
 .LP
 To turn off timeouts, simply call \fBgl_inactivity_timeout()\fR with a
 \fIcallback\fR argument of 0. The \fIdata\fR argument is ignored in this case.
 .SS "Signal Handling Defaults"
-.LP
 By default, the \fBgl_get_line()\fR function intercepts a number of signals.
 This is particularly important for signals that would by default terminate the
 process, since the terminal needs to be restored to a usable state before this
 happens. This section describes the signals that are trapped by default and how
 \fBgl_get_line()\fR responds to them. Changing these defaults is the topic of

@@ -1710,11 +1689,10 @@
 terminated without the terminal having been restored to a usable state. In
 practice, job-control shells usually reset the terminal settings when a process
 relinquishes the controlling terminal, so this is only a problem with older
 shells.
 .SS "Customized Signal Handling"
-.LP
 The previous section listed the signals that \fBgl_get_line()\fR traps by
 default, and described how it responds to them. This section describes how to
 both add and remove signals from the list of trapped signals, and how to
 specify how \fBgl_get_line()\fR should respond to a given signal.
 .sp

@@ -1863,11 +1841,11 @@
 entering a line that only occupies a signal terminal line, or if the cursor is
 on the last terminal line of a longer input line, this will have the same
 effect as \fBGL_SUSPEND_INPUT\fR. Otherwise it will start writing on a line
 that already contains part of the displayed input line. This does not do any
 harm, but it looks a bit ugly, which is why the \fBGL_SUSPEND_INPUT\fR
-combination is better if you know that you are always going to be writting to
+combination is better if you know that you are always going to be writing to
 the terminal.
 .sp
 .LP
 The \fIafter\fR argument, which determines what \fBgl_get_line()\fR does after
 the application's signal handler returns (if  it returns), can take any one of

@@ -1911,11 +1889,10 @@
 \fBerrno\fR variable to before returning \fINULL\fR to the calling program. It
 can also, however, be used with the \fBGL_RETURN\fR option, in case you want to
 have a way to distinguish between an input line that was entered using the
 return key, and one that was entered by the receipt of a signal.
 .SS "Reliable Signal Handling"
-.LP
 Signal handling is surprisingly hard to do reliably without race conditions. In
 \fBgl_get_line()\fR a lot of care has been taken to allow applications to
 perform reliable signal handling around \fBgl_get_line()\fR. This section
 explains how to make use of this.
 .sp

@@ -2125,11 +2102,10 @@
 .LP
 What the above steps do in essence is to take asynchronously delivered signals
 and handle them synchronously, one at a time, at a point in the code where
 \fBgl_get_line()\fR has complete control over its environment.
 .SS "The Terminal Size"
-.LP
 On most systems the combination of the \fBTIOCGWINSZ\fR ioctl and the
 \fBSIGWINCH\fR signal is used to maintain an accurate idea of the terminal
 size. The terminal size is newly queried every time that \fBgl_get_line()\fR is
 called and whenever a \fBSIGWINCH\fR signal is received.
 .sp

@@ -2176,11 +2152,10 @@
 .LP
 The \fIdef_ncolumn\fR and \fIdef_nline\fR arguments specify the default number
 of terminal columns and lines to use if the terminal size cannot be determined
 by ioctl(\fBTIOCGWINSZ\fR) or environment variables.
 .SS "Hiding What You Type"
-.LP
 When entering sensitive information, such as passwords, it is best not to have
 the text that you are entering echoed on the terminal. Furthermore, such text
 should not be recorded in the history list, since somebody finding your
 terminal unattended could then recall it, or somebody snooping through your
 directories could see it in your history file. With this in mind, the

@@ -2203,11 +2178,10 @@
 .LP
 When echoing is turned off, note that although tab completion will invisibly
 complete your prefix as far as possible, ambiguous completions will not be
 displayed.
 .SS "Single Character Queries"
-.LP
 Using \fBgl_get_line()\fR to query the user for a single character reply, is
 inconvenient for the user, since they must hit the enter or return key before
 the character that they typed is returned to the program. Thus the
 \fBgl_query_char()\fR function has been provided for single character queries
 like this.

@@ -2251,11 +2225,10 @@
 process of being read when \fBgl_query_char()\fR is called, the partial input
 line is discarded, and erased from the terminal, before the new prompt is
 displayed. The next call to \fBgl_get_line()\fR will thus start editing a new
 line.
 .SS "Reading Raw Characters"
-.LP
 Whereas the \fBgl_query_char()\fR function visibly prompts the user for a
 character, and displays what they typed, the \fBgl_read_char()\fR function
 reads a signal character from the user, without writing anything to the
 terminal, or perturbing any incompletely entered input line. This means that it
 can be called not only from between calls to \fBgl_get_line()\fR, but also from

@@ -2273,17 +2246,15 @@
 .LP
 Beware that certain keyboard keys, such as function keys, and cursor keys,
 usually generate at least three characters each, so a single call to
 \fBgl_read_char()\fR will not be enough to identify such keystrokes.
 .SS "Clearing The Terminal"
-.LP
 The calling program can clear the terminal by calling
 \fBgl_erase_terminal()\fR. In non-blocking server-I/O mode, this function also
 arranges for the current input line to be redrawn from scratch when
 \fBgl_get_line()\fR is next called.
 .SS "Displaying Text Dynamically"
-.LP
 Between calls to \fBgl_get_line()\fR, the \fBgl_display_text()\fR function
 provides a convenient way to display paragraphs of text, left-justified and
 split over one or more terminal lines according to the constraints of the
 current width of the terminal. Examples of the use of this function may be
 found in the demo programs, where it is used to display introductions. In those

@@ -2322,11 +2293,10 @@
 to force a new line to be started.
 .sp
 .LP
 On error, \fBgl_display_text()\fR returns -1.
 .SS "Callback Function Facilities"
-.LP
 Unless otherwise stated, callback functions such as tab completion callbacks
 and event callbacks should not call any functions in this module. The following
 functions, however, are designed specifically to be used by callback functions.
 .sp
 .LP

@@ -2336,11 +2306,10 @@
 \fBgl_get_line()\fR. In non-blocking server mode, when used between two calls
 to \fBgl_get_line()\fR that are operating on the same input line, the current
 input line will be re-drawn with the new prompt on the following call to
 \fBgl_get_line()\fR.
 .SS "International Character Sets"
-.LP
 Since \fBlibtecla\fR(3LIB) version 1.4.0, \fBgl_get_line()\fR has been 8-bit
 clean. This means that all 8-bit characters that are printable in the user's
 current locale are now displayed verbatim and included in the returned input
 line. Assuming that the calling program correctly contains a call like the
 following,

@@ -2370,21 +2339,19 @@
 .sp
 .LP
 at the shell prompt. Further documentation on how the user can make use of this
 to enter international characters can be found in the \fBtecla\fR(5) man page.
 .SS "Thread Safety"
-.LP
 Unfortunately neither \fBterminfo\fR nor \fBtermcap\fR were designed to be
 reentrant, so you cannot safely use the functions of the getline module in
 multiple threads (you can use the separate file-expansion and word-completion
 modules in multiple threads, see the corresponding man pages for details).
 However due to the use of POSIX reentrant functions for looking up home
 directories, it is safe to use this module from a single thread of a
 multi-threaded program, provided that your other threads do not use any
 \fBtermcap\fR or \fBterminfo\fR functions.
 .SH ATTRIBUTES
-.LP
 See \fBattributes\fR(5) for descriptions of the following attributes:
 .sp
 
 .sp
 .TS

@@ -2397,9 +2364,8 @@
 _
 MT-Level        MT-Safe
 .TE
 
 .SH SEE ALSO
-.LP
 \fBcpl_complete_word\fR(3TECLA), \fBef_expand_file\fR(3TECLA),
 \fBgl_io_mode\fR(3TECLA), \fBlibtecla\fR(3LIB), \fBpca_lookup_file\fR(3TECLA),
 \fBattributes\fR(5), \fBtecla\fR(5)