Add Lua API tio.twrite's documentation and example

README.md

@@ -424,9 +424,15 @@ line may be returned as a second return value.
 
 #### `tio.write(string)`
 
-Write string to serial device.
+Write string to serial device without any of input-editing, output-mapping or output-delay.
 
-Returns the `tio` table.
+Returns the tio table on success or nil on error.
+
+#### `tio.twrite(string)`
+
+Write string to serial device with input-editing, output-mapping and output-delay.
+
+Returns the tio table on success or nil on error.
 
 #### `tio.send(file, protocol)`
 

examples/lua/twrite.lua

@@ -0,0 +1,22 @@
+--
+-- tio.twrite() uses output-mapping, output-delay and input-mode.
+--
+-- Input-mode HEX is very slow, so it has limited use.
+--
+-- This script sends
+--   Hello.
+--   This is Hex mode.
+--   Bye.
+--
+
+tio.set_input_mode(tio.C.IM_NORMAL)
+tio.twrite("Hello.\r\n")
+
+tio.set_input_mode(tio.C.IM_HEX)
+tio.twrite("5468697320697320486578206d6f64652e0d0a") -- "This is Hex mode."
+
+tio.set_input_mode(tio.C.IM_LINE)
+tio.twrite("Bye.\r\n")
+
+tio.set_input_mode(tio.C.IM_NORMAL)
+

man/tio.1.in

@@ -469,9 +469,14 @@ Returns a string on success and nil on timeout.  On timeout a partially read
 line may be returned as a second return value.
 
 .IP "\fBtio.write(string)"
-Write string to serial device.
+Write string to serial device without Input-editing, Output-mapping nor Output-delay.
 
-Returns the tio table.
+Returns the tio table on success or nil on error.
+
+.IP "\fBtio.twrite(string)"
+Write string to serial device with Input-editing, Output-mapping and Output-delay.
+
+Returns tio table on success or nil on error.
 
 .IP "\fBtio.send(file, protocol)"
 Send file using x/y-modem protocol.

man/tio.1.txt

@@ -381,9 +381,14 @@ SCRIPT API
              On success, returns the string that was read as second return value.  Also emits a single timestamp to stdout and log file per options.timestamp and options.log.
 
        write(string)
-             Write string to serial device.
+             Write string to serial device without Input-editing, Output-mapping nor Output-delay.
 
-             Returns number of bytes written on success or -1 on error.
+             Returns the tio table on success or nil on error.
+
+       twrite(string)
+             Write string to serial device with Input-editing, Output-mapping and Output-delay.
+
+             Returns the tio table on success or nil on error.
 
        send(file, protocol)
              Send file using x/y-modem protocol.