Migrate notes about input/output file descriptors and output function from tickit_term_set_* manpages into tickit_term_build.3; discourage the tickit_term_set_* mutators; point most manpages at tickit_term_build(3) instead

29 files changed, 50 insertions, 87 deletions

diff --git a/man/tickit_term.7 b/man/tickit_term.7
index 7e39ccb..761a66f 100644
--- a/man/tickit_term.7
+++ b/man/tickit_term.7
@@ -11,13 +11,11 @@ TickitTerm \- abstraction of an interactive terminal
 .SH DESCRIPTION
 A \fBTickitTerm\fP instance represents an interactive user terminal. It provides functions to draw content to the terminal, and to accept input and other events from it. It supports a variety of modes of operation; allowing both synchronous and asynchronous filehandle IO, and working abstractly via byte buffers.
 .SH FUNCTIONS
-A new \fBTickitTerm\fP instance is created using the \fBtickit_term_build\fP(3), \fBtickit_term_new\fP(3) or \fBtickit_term_new_for_termtype\fP(3) functions. A terminal instance stores a reference count to make it easier for applications to manage the lifetime of terminals. A new terminal starts with reference count of one, and it can be adjusted using \fBtickit_term_ref\fP(3) and \fBtickit_term_unref\fP(3). When the count reaches zero the instance is destroyed.
+A new \fBTickitTerm\fP instance is created using the \fBtickit_term_build\fP(3). A terminal instance stores a reference count to make it easier for applications to manage the lifetime of terminals. A new terminal starts with reference count of one, and it can be adjusted using \fBtickit_term_ref\fP(3) and \fBtickit_term_unref\fP(3). When the count reaches zero the instance is destroyed.
 .PP
 The \fBtickit_term_open_stdio\fP(3) function offers a convenient shortcut to creating a new instance set up to represent the standard input and output streams of the process.
 .PP
-A terminal instance will need either an output function or an output filehandle set before it can send output. This can be performed by either \fBtickit_term_set_output_func\fP(3) or \fBtickit_term_set_output_fd\fP(3). An output buffer can be defined by \fBtickit_term_set_output_buffer\fP(3). If output is via a filehandle, then the size of that will be queried if it is a
-.SM TTY.
-If output is via an output function only then the size must be set using \fBtickit_term_set_size\fP(3). An input filehandle can be set using \fBtickit_term_set_input_fd\fP(3), or input can be sent from a byte buffer using \fBtickit_term_input_push_bytes\fP(3). Once input and output methods are set the terminal startup actions are performed, and the \fBtickit_term_await_started_msec\fP(3) function can be used to wait until this is complete. A running instance can be paused using \fBtickit_term_pause\fP(3) and resumed using \fBtickit_term_resume\fP(3).
+Once built the terminal startup actions are performed, and the \fBtickit_term_await_started_msec\fP(3) function can be used to wait until this is complete. A running instance can be paused using \fBtickit_term_pause\fP(3) and resumed using \fBtickit_term_resume\fP(3).
 .PP
 It supports
 .SM UTF-8
@@ -27,7 +25,7 @@ locale, explicitly by calling \fBtickit_term_set_utf8\fP(3).
 .PP
 The size of the terminal can be queried using \fBtickit_term_get_size\fP(3), or forced to a given size by \fBtickit_term_set_size\fP(3). If the application is aware that the size of a terminal represented by a \fBtty\fP(7) filehandle has changed (for example due to receipt of a \fBSIGWINCH\fP signal), it can call \fBtickit_term_refresh_size\fP(3) to update it. The type of the terminal is set at construction time but can be queried later using \fBtickit_term_get_termtype\fP(3).
 .SH OUTPUT
-Once an output method is defined, a terminal instance can be used for outputting drawing and other commands. For drawing, the functions \fBtickit_term_print\fP(3), \fBtickit_term_goto\fP(3), \fBtickit_term_move\fP(3), \fBtickit_term_scrollrect\fP(3), \fBtickit_term_chpen\fP(3), \fBtickit_term_setpen\fP(3), \fBtickit_term_clear\fP(3) and \fBtickit_term_erasech\fP(3) can be used. Additionally for setting modes, the function \fBtickit_term_setctl_int\fP(3) can be used. If an output buffer is defined it will need to be flushed when drawing is complete by calling \fBtickit_term_flush\fP(3).
+A terminal instance can be used for outputting drawing and other commands. For drawing, the functions \fBtickit_term_print\fP(3), \fBtickit_term_goto\fP(3), \fBtickit_term_move\fP(3), \fBtickit_term_scrollrect\fP(3), \fBtickit_term_chpen\fP(3), \fBtickit_term_setpen\fP(3), \fBtickit_term_clear\fP(3) and \fBtickit_term_erasech\fP(3) can be used. Additionally for setting modes, the function \fBtickit_term_setctl_int\fP(3) can be used. If an output buffer is defined it will need to be flushed when drawing is complete by calling \fBtickit_term_flush\fP(3).
 .SH INPUT
 Input via a filehandle can be received either synchronously by calling \fBtickit_term_input_wait_msec\fP(3), or asynchronously by calling \fBtickit_term_input_readable\fP(3) and \fBtickit_term_input_check_timeout_msec\fP(3). Any of these functions may cause one or more events to be raised by invoking event handler functions.
 .SH EVENTS
diff --git a/man/tickit_term_await_started_msec.3 b/man/tickit_term_await_started_msec.3
index c85e107..5a5d03f 100644
--- a/man/tickit_term_await_started_msec.3
+++ b/man/tickit_term_await_started_msec.3
@@ -19,8 +19,6 @@ Under most terminal drivers it is not strictly required that it be completely pr
 .SH "RETURN VALUE"
 \fBtickit_term_await_started_msec\fP() and \fBtickit_term_await_started_tv\fP() return no value.
 .SH "SEE ALSO"
-.BR tickit_term_new (3),
-.BR tickit_term_set_output_func (3),
-.BR tickit_term_set_output_fd (3),
+.BR tickit_term_build (3),
 .BR tickit_term (7),
 .BR tickit (7)
diff --git a/man/tickit_term_bind_event.3 b/man/tickit_term_bind_event.3
index f5391b3..366d138 100644
--- a/man/tickit_term_bind_event.3
+++ b/man/tickit_term_bind_event.3
@@ -22,6 +22,6 @@ Link with \fI\-ltickit\fP.
 .SH "RETURN VALUE"
 \fBtickit_term_bind_event\fP() returns an identifier integer. \fBtickit_term_unbind_event_id\fP() returns no value.
 .SH "SEE ALSO"
-.BR tickit_term_new (3),
+.BR tickit_term_build (3),
 .BR tickit_term (7),
 .BR tickit (7)
diff --git a/man/tickit_term_build.3 b/man/tickit_term_build.3
index 6650d6e..7d1e792 100644
--- a/man/tickit_term_build.3
+++ b/man/tickit_term_build.3
@@ -5,6 +5,9 @@ tickit_term_build \- create a new terminal instance with arguments
 .EX
 .B #include <tickit.h>
 .sp
+.BI "typedef void " TickitTermOutputFunc "(TickitTerm *" tt ", const char *" bytes ,
+.BI "    size_t " len ", void *" user );
+.sp
 .BI "struct " TickitTermBuilder " {"
 .BI "  const char *" termtype ;
 .BI "  enum ... " open ;
@@ -42,11 +45,18 @@ The \fIoutput_func\fP and \fIoutput_func_user\fP fields provide an output functi
 .PP
 The \fIoutput_buffersize\fP field sets the initial size of the output buffer. It defaults to zero, meaning no buffer will be allocated.
 .PP
+The input file descriptor will be used by \fBtickit_term_input_readable\fP(3) to read more data from the terminal. The value -1 may be set to indicate an absence of a file descriptor, in which case input data may still be given by calling \fBtickit_term_input_push_bytes\fP(3).
+.PP
+If set to a non-NULL value, output function is used to output bytes of data to the terminal even if a file descriptor is also set. When invoked, it is passed the terminal instance, a byte buffer and size, and the user data pointer that it was configured with. This pointer may be NULL if not required.
+.PP
+The output file descriptor will be used by \fBtickit_term_refresh_size\fP(3) to query the size of the terminal, by issuing the \fBTIOCGWINSZ\fP \fBioctl\fP(2). It will also be used to write output to the terminal if no function has been set. The value -1 may be set to indicate no file descriptor, in which case the size must be set by \fBtickit_term_set_size\fP(3) and an output function must be set for output to occur.
+.PP
 The reference count of a newly-constructed terminal instance will be one. This can be incremented or decremented using \fBtickit_term_ref\fP(3) and \fBtickit_term_unref\fP(3). When its reference count reaches zero it is destroyed.
+.PP
+After construction it is recommended to call \fBtickit_term_await_started\fP(3) to wait for the terminal to be set up.
 .SH "RETURN VALUE"
 If successful, \fBtickit_term_build\fP() returns a pointer to the new instance. On failure, \fBNULL\fP is returned with \fIerrno\fP set to indicate the failure.
 .SH "SEE ALSO"
-.BR tickit_term_new (3),
 .BR tickit_term_open_stdio (3),
 .BR tickit_term_set_output_fd (3),
 .BR tickit_term_set_output_func (3),
diff --git a/man/tickit_term_chpen.3 b/man/tickit_term_chpen.3
index 21d8113..fdfc13e 100644
--- a/man/tickit_term_chpen.3
+++ b/man/tickit_term_chpen.3
@@ -19,9 +19,7 @@ If the foreground or background colour is set to an index higher than the termin
 .SH "RETURN VALUE"
 \fBtickit_term_chpen\fP() and \fBtickit_term_setpen\fP() return no value.
 .SH "SEE ALSO"
-.BR tickit_term_new (3),
-.BR tickit_term_set_output_fd (3),
-.BR tickit_term_set_output_func (3),
+.BR tickit_term_build (3),
 .BR tickit_term_goto (3),
 .BR tickit_term_print (3),
 .BR tickit_term (7),
diff --git a/man/tickit_term_clear.3 b/man/tickit_term_clear.3
index cfa10dd..543b861 100644
--- a/man/tickit_term_clear.3
+++ b/man/tickit_term_clear.3
@@ -14,9 +14,7 @@ Link with \fI\-ltickit\fP.
 .SH "RETURN VALUE"
 \fBtickit_term_clear\fP() returns no value.
 .SH "SEE ALSO"
-.BR tickit_term_new (3),
-.BR tickit_term_set_output_fd (3),
-.BR tickit_term_set_output_func (3),
+.BR tickit_term_build (3),
 .BR tickit_term_goto (3),
 .BR tickit_term_print (3),
 .BR tickit_term_erasech (3),
diff --git a/man/tickit_term_emit_key.3 b/man/tickit_term_emit_key.3
index 175c72f..b95b478 100644
--- a/man/tickit_term_emit_key.3
+++ b/man/tickit_term_emit_key.3
@@ -15,7 +15,7 @@ Link with \fI\-ltickit\fP.
 .PP
 In each case, the event handler chain runs with the usual semantics; each installed handler with the appropriate bit set in its event type mask will be invoked until one returns a true value. Any remaining handlers after this will not get to see the event.
 .SH "SEE ALSO"
-.BR tickit_term_new (3),
+.BR tickit_term_build (3),
 .BR tickit_term_bind_event (3),
 .BR tickit_term (7),
 .BR tickit (7)
diff --git a/man/tickit_term_erasech.3 b/man/tickit_term_erasech.3
index 2199126..386fd2e 100644
--- a/man/tickit_term_erasech.3
+++ b/man/tickit_term_erasech.3
@@ -16,9 +16,7 @@ Some terminals cannot erase using the background colour, so this operation may b
 .SH "RETURN VALUE"
 \fBtickit_term_erasech\fP() returns no value.
 .SH "SEE ALSO"
-.BR tickit_term_new (3),
-.BR tickit_term_set_output_fd (3),
-.BR tickit_term_set_output_func (3),
+.BR tickit_term_build (3),
 .BR tickit_term_goto (3),
 .BR tickit_term_print (3),
 .BR tickit_term_setpen (3),
diff --git a/man/tickit_term_flush.3 b/man/tickit_term_flush.3
index 1423ed6..15afa15 100644
--- a/man/tickit_term_flush.3
+++ b/man/tickit_term_flush.3
@@ -10,13 +10,11 @@ tickit_term_flush \- flush the terminal output buffer
 .sp
 Link with \fI\-ltickit\fP.
 .SH DESCRIPTION
-\fBtickit_term_flush\fP() flushes any data pending in the output buffer to the terminal, either by calling the output function if defined by \fBtickit_term_set_output_func\fP(3), or by \fBwrite\fP(3) on the output file descriptor defined by \fBtickit_term_set_output_fd\fP(3). If there is no pending data then this function does nothing.
+\fBtickit_term_flush\fP() flushes any data pending in the output buffer to the terminal, either by calling the output function by \fBwrite\fP(3) on the output file descriptor. If there is no pending data then this function does nothing.
 .SH "RETURN VALUE"
 \fBtickit_term_flush\fP() returns no value.
 .SH "SEE ALSO"
-.BR tickit_term_new (3),
-.BR tickit_term_set_output_fd (3),
-.BR tickit_term_set_output_func (3),
+.BR tickit_term_build (3),
 .BR tickit_term_set_output_buffer (3),
 .BR tickit_term_print (3),
 .BR tickit_term (7),
diff --git a/man/tickit_term_get_size.3 b/man/tickit_term_get_size.3
index cd96d6b..7c007c0 100644
--- a/man/tickit_term_get_size.3
+++ b/man/tickit_term_get_size.3
@@ -20,8 +20,7 @@ Link with \fI-ltickit\fP.
 .SH "RETURN VALUE"
 \fBtickit_term_get_size\fP, \fBtickit_term_set_size\fP and \fBtickit_term_refresh_size\fP return no value.
 .SH "SEE ALSO"
-.BR tickit_term_new (3),
-.BR tickit_term_set_output_fd (3),
+.BR tickit_term_build (3),
 .BR tickit_term_goto (3),
 .BR tickit_term_bind_event (3),
 .BR tickit_term (7),
diff --git a/man/tickit_term_get_termtype.3 b/man/tickit_term_get_termtype.3
index 3cd56fb..bf76198 100644
--- a/man/tickit_term_get_termtype.3
+++ b/man/tickit_term_get_termtype.3
@@ -10,10 +10,10 @@ tickit_term_get_termtype \- returns the terminal type
 .sp
 Link with \fI-ltickit\fP.
 .SH DESCRIPTION
-\fBtickit_term_get_termtype\fP() returns the string name of the type of the terminal. This is the string that was given to \fBtickit_term_new_for_termtype\fP(3), or was fetched from the \fBTERM\fP environment variable. The returned value points directly into the buffer allocated by the \fITickitTerm\fP instance itself; this buffer must not be modified or freed.
+\fBtickit_term_get_termtype\fP() returns the string name of the type of the terminal. This is the string that set in the \fBTickitTermBuilder\fP struct to \fBtickit_term_build\fP(3), or was fetched from the \fBTERM\fP environment variable. The returned value points directly into the buffer allocated by the \fITickitTerm\fP instance itself; this buffer must not be modified or freed.
 .SH "RETURN VALUE"
 \fBtickit_term_get_termtype\fP() returns a string buffer pointer.
 .SH "SEE ALSO"
-.BR tickit_term_new (3),
+.BR tickit_term_build (3),
 .BR tickit_term (7),
 .BR tickit (7)
diff --git a/man/tickit_term_goto.3 b/man/tickit_term_goto.3
index bf18324..6c701f1 100644
--- a/man/tickit_term_goto.3
+++ b/man/tickit_term_goto.3
@@ -17,7 +17,7 @@ Link with \fI\-ltickit\fP.
 .SH "RETURN VALUE"
 \fBtickit_term_goto\fP() returns a boolean value indicating whether it was able to support the requested movement. \fBtickit_term_move\fP() returns no value.
 .SH "SEE ALSO"
-.BR tickit_term_new (3),
+.BR tickit_term_build (3),
 .BR tickit_term_print (3),
 .BR tickit_term (7),
 .BR tickit (7)
diff --git a/man/tickit_term_input_check_timeout_msec.3 b/man/tickit_term_input_check_timeout_msec.3
index bbcaee0..9f27a9f 100644
--- a/man/tickit_term_input_check_timeout_msec.3
+++ b/man/tickit_term_input_check_timeout_msec.3
@@ -16,8 +16,7 @@ This function also invokes deferred \fBTICKIT_EV_RESIZE\fP events if enabled by
 .SH "RETURN VALUE"
 \fBtickit_term_input_check_timeout_msec\fP() returns a number indicating a timeout delay in miliseconds.
 .SH "SEE ALSO"
-.BR tickit_term_new (3),
-.BR tickit_term_set_input_fd (3),
+.BR tickit_term_build (3),
 .BR tickit_term_input_push_bytes (3),
 .BR tickit_term_bind_event (3),
 .BR tickit_term (7),
diff --git a/man/tickit_term_input_push_bytes.3 b/man/tickit_term_input_push_bytes.3
index 5ada61f..9b658b9 100644
--- a/man/tickit_term_input_push_bytes.3
+++ b/man/tickit_term_input_push_bytes.3
@@ -16,8 +16,7 @@ This function also invokes deferred \fBTICKIT_EV_RESIZE\fP events if enabled by
 .SH "RETURN VALUE"
 \fBtickit_term_input_push_bytes\fP() returns no value.
 .SH "SEE ALSO"
-.BR tickit_term_new (3),
-.BR tickit_term_set_input_fd (3),
+.BR tickit_term_build (3),
 .BR tickit_term_input_readable (3),
 .BR tickit_term_bind_event (3),
 .BR tickit_term (7),
diff --git a/man/tickit_term_input_readable.3 b/man/tickit_term_input_readable.3
index 9aaaaa1..dbfda67 100644
--- a/man/tickit_term_input_readable.3
+++ b/man/tickit_term_input_readable.3
@@ -10,14 +10,13 @@ tickit_term_input_readable \- read more data from the terminal
 .sp
 Link with \fI\-ltickit\fP.
 .SH DESCRIPTION
-\fBtickit_term_input_readable\fP() informs the terminal instance that more data is, or may be, available on the input file descriptor previously set with \fBtickit_term_set_input_fd\fP(), and reads it. Calling this function may block if the underlying file descriptor is in blocking mode. It may result in \fBTICKIT_EV_KEY\fP or \fBTICKIT_EV_MOUSE\fP events being invoked.
+\fBtickit_term_input_readable\fP() informs the terminal instance that more data is, or may be, available on the input file descriptor, and reads it. Calling this function may block if the underlying file descriptor is in blocking mode. It may result in \fBTICKIT_EV_KEY\fP or \fBTICKIT_EV_MOUSE\fP events being invoked.
 .PP
 This function also invokes deferred \fBTICKIT_EV_RESIZE\fP events if enabled by \fBtickit_term_observe_sigwinch\fP(3).
 .SH "RETURN VALUE"
 \fBtickit_term_input_readable\fP() returns no value.
 .SH "SEE ALSO"
-.BR tickit_term_new (3),
-.BR tickit_term_set_input_fd (3),
+.BR tickit_term_build (3),
 .BR tickit_term_input_push_bytes (3),
 .BR tickit_term_bind_event (3),
 .BR tickit_term (7),
diff --git a/man/tickit_term_input_wait_msec.3 b/man/tickit_term_input_wait_msec.3
index 900c2a9..6c90045 100644
--- a/man/tickit_term_input_wait_msec.3
+++ b/man/tickit_term_input_wait_msec.3
@@ -19,8 +19,7 @@ The functions differ in how the timeout is specified. \fBtickit_term_input_wait_
 .SH "RETURN VALUE"
 \fBtickit_term_input_wait_msec\fP() and \fBtickit_term_input_wait_tv\fP() return no value.
 .SH "SEE ALSO"
-.BR tickit_term_new (3),
-.BR tickit_term_set_input_fd (3),
+.BR tickit_term_build (3),
 .BR tickit_term_input_readable (3),
 .BR tickit_term_bind_event (3),
 .BR tickit_term (7),
diff --git a/man/tickit_term_new.3 b/man/tickit_term_new.3
index 71c5b49..4211a97 100644
--- a/man/tickit_term_new.3
+++ b/man/tickit_term_new.3
@@ -11,20 +11,8 @@ tickit_term_new \- create a new terminal instance
 .sp
 Link with \fI\-ltickit\fP.
 .SH DESCRIPTION
-\fBtickit_term_new\fP() creates a new \fBTickitTerm\fP instance for the terminal type given by the \fBTERM\fP environment variable.
-.PP
-\fBtickit_term_new_for_termtype\fP() creates a new \fBTickitTerm\fP instance for the given terminal type.
-.PP
-The reference count of a newly-constructed terminal instance will be one. This can be incremented or decremented using \fBtickit_term_ref\fP(3) and \fBtickit_term_unref\fP(3). When its reference count reaches zero it is destroyed.
-.SH "RETURN VALUE"
-If successful, \fBtickit_term_new\fP() and \fBtickit_term_new_for_termtype\fP() return a pointer to the new instance. On failure, \fBNULL\fP is returned with \fIerrno\fP set to indicate the failure.
+These functions are now discouraged. Applications should use \fBtickit_term_build\fP(3) instead.
 .SH "SEE ALSO"
 .BR tickit_term_build (3),
-.BR tickit_term_open_stdio (3),
-.BR tickit_term_set_output_fd (3),
-.BR tickit_term_set_output_func (3),
-.BR tickit_term_set_input_fd (3),
-.BR tickit_term_print (3),
-.BR tickit_term_bind_event (3),
 .BR tickit_term (7),
 .BR tickit (7)
diff --git a/man/tickit_term_observe_sigwinch.3 b/man/tickit_term_observe_sigwinch.3
index f9a74ce..0c18722 100644
--- a/man/tickit_term_observe_sigwinch.3
+++ b/man/tickit_term_observe_sigwinch.3
@@ -25,8 +25,7 @@ The \fBtickit_term_input_check_timeout_msec\fP(3) family
 .IP *
 The \fBtickit_term_input_wait_msec\fP(3) family
 .SH "SEE ALSO"
-.BR tickit_term_new (3),
-.BR tickit_term_set_input_fd (3),
+.BR tickit_term_build (3),
 .BR tickit_term_refresh_size (3),
 .BR tickit_term_bind_event (3),
 .BR tickit_term (7),
diff --git a/man/tickit_term_open_stdio.3 b/man/tickit_term_open_stdio.3
index a278691..ec3e7d5 100644
--- a/man/tickit_term_open_stdio.3
+++ b/man/tickit_term_open_stdio.3
@@ -10,11 +10,11 @@ tickit_term_open_stdio \- create a terminal instance on standard input/output
 .sp
 Link with \fI\-ltickit\fP.
 .SH DESCRIPTION
-\fBtickit_term_open_stdio\fP() creates a new \fBTickitTerm\fP instance to represent the standard input and output streams of the process. This function is a convenient shortcut around the common use-case of creating an instance using \fBtickit_term_new\fP(3), setting the input and output handles using \fBtickit_term_set_input_fd\fP(3) and \fBtickit_term_set_output_fd\fP(3), and enabling \fBSIGWINCH\fP support using \fBtickit_term_observe_sigwinch\fP(3).
+\fBtickit_term_open_stdio\fP() creates a new \fBTickitTerm\fP instance to represent the standard input and output streams of the process. This function is a convenient shortcut around the common use-case of creating an instance using \fBtickit_term_build\fP(3) with the \fIopen\fP field set to \fBTICKIT_OPEN_STDIO\fP, and enabling \fBSIGWINCH\fP support using \fBtickit_term_observe_sigwinch\fP(3).
 .SH "RETURN VALUE"
 If successful, \fBtickit_term_open_stdio\fP() returns a pointer to the new instance. On failure, \fBNULL\fP is returned with \fIerrno\fP set to indicate the failure.
 .SH "SEE ALSO"
-.BR tickit_term_new (3),
+.BR tickit_term_build (3),
 .BR tickit_term_print (3),
 .BR tickit_term_bind_event (3),
 .BR tickit_term (7),
diff --git a/man/tickit_term_pause.3 b/man/tickit_term_pause.3
index 3f022c2..dad3a3e 100644
--- a/man/tickit_term_pause.3
+++ b/man/tickit_term_pause.3
@@ -17,7 +17,7 @@ Link with \fI\-ltickit\fP.
 .PP
 It is intended these functions be used to create a program-wide suspend feature, where the terminal can be handed back over to the invoking shell while the process backgrounds itself. Typically this is done by the process sending itself a \fBSIGSTOP\fP signal via \fBraise\fP(3). After calling \fBtickit_term_pause\fP(), no other terminal-related functions should be called, nor other IO operations attempted, until after a subsequent \fBtickit_term_resume\fP(3).
 .SH "SEE ALSO"
-.BR tickit_term_new (3),
+.BR tickit_term_build (3),
 .BR tickit_term_setctl_int (3),
 .BR tickit_term (7),
 .BR tickit (7)
diff --git a/man/tickit_term_print.3 b/man/tickit_term_print.3
index 4564d69..72d62f4 100644
--- a/man/tickit_term_print.3
+++ b/man/tickit_term_print.3
@@ -20,9 +20,7 @@ Link with \fI\-ltickit\fP.
 .SH "RETURN VALUE"
 \fBtickit_term_print\fP(), \fBtickit_term_printf\fP() and \fBtickit_term_vprintf\fP() return no value.
 .SH "SEE ALSO"
-.BR tickit_term_new (3),
-.BR tickit_term_set_output_fd (3),
-.BR tickit_term_set_output_func (3),
+.BR tickit_term_build (3),
 .BR tickit_term_goto (3),
 .BR tickit_term_setpen (3),
 .BR tickit_term_chpen (3),
diff --git a/man/tickit_term_ref.3 b/man/tickit_term_ref.3
index 082867c..7de3b9f 100644
--- a/man/tickit_term_ref.3
+++ b/man/tickit_term_ref.3
@@ -17,6 +17,6 @@ Link with \fI\-ltickit\fP.
 .SH "RETURN VALUE"
 \fBtickit_term_ref\fP() returns a terminal instance pointer. \fBtickit_term_unref\fP() returns no value.
 .SH "SEE ALSO"
-.BR tickit_term_new (3),
+.BR tickit_term_build (3),
 .BR tickit_term (7),
 .BR tickit (7)
diff --git a/man/tickit_term_scrollrect.3 b/man/tickit_term_scrollrect.3
index c2e822e..1319089 100644
--- a/man/tickit_term_scrollrect.3
+++ b/man/tickit_term_scrollrect.3
@@ -15,7 +15,7 @@ Link with \fI\-ltickit\fP.
 .SH "RETURN VALUE"
 \fBtickit_term_scrollrect\fP() returns a boolean indicating if the scrolling operation was successful.
 .SH "SEE ALSO"
-.BR tickit_term_new (3),
+.BR tickit_term_build (3),
 .BR tickit_term_goto (3),
 .BR tickit_term_print (3),
 .BR tickit_term_setpen (3),
diff --git a/man/tickit_term_set_input_fd.3 b/man/tickit_term_set_input_fd.3
index 6cae17f..eb6dda2 100644
--- a/man/tickit_term_set_input_fd.3
+++ b/man/tickit_term_set_input_fd.3
@@ -11,16 +11,13 @@ tickit_term_set_input_fd, tickit_term_get_input_fd \- manage terminal input
 .sp
 Link with \fI\-ltickit\fP.
 .SH DESCRIPTION
-\fBtickit_term_set_input_fd\fP() associates an input file descriptor with the terminal instance. This file descriptor will be used by \fBtickit_term_input_readable\fP(3) to read more data from the terminal. The value -1 may be set to indicate an absence of a file descriptor. If no file descriptor is provided, input data may still be given by calling \fBtickit_term_input_push_bytes\fP(3).
+\fBtickit_term_set_input_fd\fP() is discouraged and should not be used by applications. See instead the \fIopen\fP and \fIinput_fd\fP fields of the \fBTickitTermBuilder\fP struct to \fBtickit_term_build\fP(3).
 .PP
 \fBtickit_term_get_input_fd\fP() returns the currently associated input file descriptor, or -1 if none has been set.
-.PP
-After both an input and output method have been defined, it is recommended to call \fBtickit_term_await_started\fP(3) to wait for the terminal to be set up.
 .SH "RETURN VALUE"
-\fBtickit_term_set_input_fd\fP() returns no value. \fBtickit_term_get_input_fd\fP() returns a file descriptor or -1.
+\fBtickit_term_get_input_fd\fP() returns a file descriptor or -1.
 .SH "SEE ALSO"
-.BR tickit_term_new (3),
-.BR tickit_term_await_started (3),
+.BR tickit_term_build (3),
 .BR tickit_term_bind_event (3),
 .BR tickit_term (7),
 .BR tickit (7)
diff --git a/man/tickit_term_set_output_buffer.3 b/man/tickit_term_set_output_buffer.3
index 916e362..8cbe87e 100644
--- a/man/tickit_term_set_output_buffer.3
+++ b/man/tickit_term_set_output_buffer.3
@@ -16,9 +16,7 @@ If a buffer is defined, then none of the drawing functions will immediately crea
 .SH "RETURN VALUE"
 \fBtickit_term_set_output_buffer\fP() returns no value.
 .SH "SEE ALSO"
-.BR tickit_term_new (3),
-.BR tickit_term_set_output_fd (3),
-.BR tickit_term_set_output_func (3),
+.BR tickit_term_build (3),
 .BR tickit_term_print (3),
 .BR tickit_term_flush (3),
 .BR tickit_term (7),
diff --git a/man/tickit_term_set_output_fd.3 b/man/tickit_term_set_output_fd.3
index d552091..89515b7 100644
--- a/man/tickit_term_set_output_fd.3
+++ b/man/tickit_term_set_output_fd.3
@@ -11,17 +11,13 @@ tickit_term_set_output_fd, tickit_term_get_output_fd \- manage terminal output
 .sp
 Link with \fI\-ltickit\fP.
 .SH DESCRIPTION
-\fBtickit_term_set_output_fd\fP() associates an output file descriptor with the terminal instance. If no output function has been set by \fBtickit_term_set_output_func\fP(3) then this file descriptor will be used to send bytes to the user's terminal. This file descriptor will also be used by \fBtickit_term_refresh_size\fP(3) to query the size of the terminal by issuing the \fBTIOCGWINSZ\fP \fBioctl\fP(2). The value -1 may be set to indicate an absence of a file descriptor.
+\fBtickit_term_set_output_fd\fP() is discouraged and should not be used by applications. See instead the \fIopen\fP and \fIoutput_fd\fP fields of the \fBTickitTermBuilder\fP struct to \fBtickit_term_build\fP(3).
 .PP
 \fBtickit_term_get_output_fd\fP() returns the currently associated output file descriptor, or -1 if none has been set.
-.PP
-After both an input and output method have been defined, it is recommended to call \fBtickit_term_await_started\fP(3) to wait for the terminal to be set up.
 .SH "RETURN VALUE"
-\fBtickit_term_set_output_fd\fP() returns no value. \fBtickit_term_get_output_fd\fP() returns a file descriptor or -1.
+\fBtickit_term_get_output_fd\fP() returns a file descriptor or -1.
 .SH "SEE ALSO"
-.BR tickit_term_new (3),
-.BR tickit_term_set_output_func (3),
-.BR tickit_term_await_started (3),
+.BR tickit_term_build (3),
 .BR tickit_term_print (3),
 .BR tickit_term (7),
 .BR tickit (7)
diff --git a/man/tickit_term_set_output_func.3 b/man/tickit_term_set_output_func.3
index b9a8e39..48ce32e 100644
--- a/man/tickit_term_set_output_func.3
+++ b/man/tickit_term_set_output_func.3
@@ -14,17 +14,11 @@ tickit_term_set_output_func \- manage terminal output via a callback function
 .sp
 Link with \fI\-ltickit\fP.
 .SH DESCRIPTION
-\fBtickit_term_set_output_func\fP() associates an output function with the terminal instance. If set, this function will be used to send bytes to the user's terminal even if an output file descriptor is also set. When the function is invoked, it will be passed the terminal instance, a byte buffer and size, and the user data pointer it was installed with.
-.PP
-When an output function is replaced by another or the terminal is destroyed, an existing function is invoked one final time to inform it. In this case, the \fIlen\fP argument will be 0 and \fIbytes\fP will be \fBNULL\fP.
-.PP
-After both an input and output method have been defined, it is recommended to call \fBtickit_term_await_started\fP(3) to wait for the terminal to be set up.
+This function is now discouraged. Applications should use \fBtickit_term_build\fP(3) instead.
 .SH "RETURN VALUE"
 \fBtickit_term_set_output_func\fP() returns no value.
 .SH "SEE ALSO"
-.BR tickit_term_new (3),
-.BR tickit_term_set_output_fd (3),
-.BR tickit_term_await_started (3),
+.BR tickit_term_build (3),
 .BR tickit_term_print (3),
 .BR tickit_term (7),
 .BR tickit (7)
diff --git a/man/tickit_term_set_utf8.3 b/man/tickit_term_set_utf8.3
index 5601961..859e6fe 100644
--- a/man/tickit_term_set_utf8.3
+++ b/man/tickit_term_set_utf8.3
@@ -23,6 +23,6 @@ support as \fBTICKIT_YES\fP or \fBTICKIT_NO\fP, or \fBTICKIT_MAYBE\fP if the val
 .SH "RETURN VALUE"
 \fBtickit_term_set_utf8\fP() returns no value. \fBtickit_term_get_utf8\fP() returns a \fITickitMaybeBool\fP tri-state boolean value.
 .SH "SEE ALSO"
-.BR tickit_term_new (3),
+.BR tickit_term_build (3),
 .BR tickit_term (7),
 .BR tickit (7)
diff --git a/man/tickit_term_setctl_int.3 b/man/tickit_term_setctl_int.3
index b33684b..ea28fdf 100644
--- a/man/tickit_term_setctl_int.3
+++ b/man/tickit_term_setctl_int.3
@@ -18,6 +18,6 @@ For the list of possible \fBTickitTermCtl\fP values and their meanings, see \fBt
 .SH "RETURN VALUE"
 \fBtickit_term_getctl_int\fP() returns a true value if it recognised the requested control and managed to return the current value of it; false if not. \fBtickit_term_setctl_int\fP() and \fBtickit_term_setctl_str\fP() return a true value if it recognised the requested control and managed to request the terminal to change it; false if not.
 .SH "SEE ALSO"
-.BR tickit_term_new (3),
+.BR tickit_term_build (3),
 .BR tickit_term (7),
 .BR tickit (7)