rudimentary docs for libraries added to Teliva

3 files changed, 104 insertions, 3 deletions

diff --git a/doc/contents.html b/doc/contents.html
index e549044..52c78a8 100644
--- a/doc/contents.html
+++ b/doc/contents.html
@@ -107,9 +107,13 @@ Freely available under the terms of the
 </UL>
 <LI><A HREF="manual.html#5.5">5.5 &ndash; Table Manipulation</A>
 <LI><A HREF="manual.html#5.6">5.6 &ndash; Mathematical Functions</A>
-<LI><A HREF="manual.html#5.7">5.7 &ndash; Input and Output Facilities</A>
+<LI><A HREF="manual.html#5.7">5.7 &ndash; File Input and Output Facilities</A>
 <LI><A HREF="manual.html#5.8">5.8 &ndash; Operating System Facilities</A>
 <LI><A HREF="manual.html#5.9">5.9 &ndash; The Debug Library</A>
+<LI><span class='teliva'><A HREF="manual.html#5.10">5.10 &ndash; Curses Window Facilities</A></span>
+<LI><span class='teliva'><A HREF="manual.html#5.11">5.11 &ndash; Networking Facilities</A></span>
+<LI><span class='teliva'><A HREF="manual.html#5.12">5.12 &ndash; JSON Facilities</A></span>
+<LI><span class='teliva'><A HREF="manual.html#5.13">5.13 &ndash; Tasks and Channels</A></span>
 </UL>
 <P>
 <LI><A HREF="manual.html#8">8 &ndash; The Complete Syntax of Lua</A>
diff --git a/doc/lua.css b/doc/lua.css
index 7fafbb1..97c5bc7 100644
--- a/doc/lua.css
+++ b/doc/lua.css
@@ -81,3 +81,10 @@ input[type=text] {
 	height: 2em ;
 }
 
+.teliva {
+	background-color: #f1a7fe;
+	padding-left: 2px;
+	padding-right: 2px;
+	padding-top: 5px;
+	padding-bottom: 2px;
+}
diff --git a/doc/manual.html b/doc/manual.html
index 5ece5c0..c2910f4 100644
--- a/doc/manual.html
+++ b/doc/manual.html
@@ -3590,12 +3590,58 @@ Returns the hyperbolic tangent of <code>x</code>.
 
 
 
-<h2>5.7 - <a name="5.7">Input and Output Facilities</a></h2>
+<h2>5.7 - <a name="5.7">File Input and Output Facilities</a></h2>
+
+<div class='teliva'>
+While Teliva supports the standard Lua primitives for managing files,
+idiomatic Teliva uses some slightly different primitives.
+
+<p>
+<hr><h3><a name="pdf-start_reading"><code>start_reading (fs, filename)</code></a></h3>
+
+<p>
+This function opens a file exclusively for reading, and returns a
+<tt>channel</tt> (NOT a file as regular Lua) or <b>nil</b> on error.
+<tt>recv()</tt> from the channel to read a line at a time from the file.
+
+<p>
+(The <tt>fs</tt> parameter is currently unused. It will be used to pass in
+fake file systems for tests.)
+
+<p>
+<hr><h3><a name="pdf-character_by_character"><code>character_by_character(chanin, chanout)</code></a></h3>
+
+<p>
+This function converts a channel that can <tt>recv()</tt> a line at a time
+from a file into a channel that can <tt>recv()</tt> a character at a time.
+Don't try to mix by-line reads with by-character reads. Once a channel is
+passed into <tt>character_by_character</tt>, calling code should stop trying
+to use it.
+
+
+<p>
+<hr><h3><a name="pdf-start_writing"><code>start_writing(fs, filename)</code></a></h3>
+
+<p>
+This function opens a file exclusively for writing, and returns a
+<tt>channel</tt> (NOT a file as regular Lua) or <b>nil</b> on error.
+<tt>send()</tt> to the channel will write to the file. <tt>close()</tt> on the
+channel will persist the changes and make them externally visible. All writes
+are hidden until <tt>close()</tt>.
+
+<p>
+(The <tt>fs</tt> parameter is currently unused. It will be used to pass in
+fake file systems for tests.)
+
+
+<hr>
+The rest of this section describes Lua's standard primitives for File I/O.
+</div>
 
 
 <p>
 Unless otherwise stated,
-all I/O functions return <b>nil</b> on failure
+all File I/O functions return <b>nil</b> on failure
 (plus an error message as a second result and
 a system-dependent error code as a third result)
 and some value different from <b>nil</b> on success.
@@ -4341,8 +4387,52 @@ to start the traceback
 (default is 1, the function calling <code>traceback</code>).
 
 
+<div class='teliva'>
+<h2>5.10 - <a name="5.10">Curses Window Facilities</a></h2>
+
+Teliva includes curses facilities identical to Lua's <a href='http://lcurses.github.io/lcurses/'>lcurses</a>
+library. As there, the top-level module is called <tt>curses</tt>. All apps
+start with the terminal window initialized using <tt>curses.initscr()</tt>.
+Look at the sample apps for example usage.
+
+</div>
 
+<div class='teliva'>
+<h2>5.11 - <a name="5.11">Networking Facilities</a></h2>
+
+Teliva includes the following well-known Lua libraries for networking:
+
+<li><a href='https://w3.impa.br/~diego/software/luasocket/reference.html'>LuaSocket</a>,
+consisting of modules <tt>socket</tt>, <tt>http</tt>, <tt>url</tt>,
+<tt>headers</tt>, <tt>mime</tt> and <tt>ltn12</tt>.
+
+<li><a href='https://github.com/brunoos/luasec/wiki'>LuaSec</a>,
+consisting of modules <tt>https</tt> and <tt>ssl</tt>.
+
+</div>
 
+<div class='teliva'>
+<h2>5.12 - <a name="5.12">JSON Facilities</a></h2>
+
+Teliva includes the well-known
+<a href='https://github.com/rxi/json.lua'>json.lua</a> library (module
+<tt>json</tt>). It also includes a variant in module <tt>jsonf</tt> that can
+read or write JSON from channels opened by
+<a href='#pdf-start_reading'>start_reading</a>
+and
+<a href='#pdf-start_writing'>start_writing</a>.
+
+</div>
+
+<div class='teliva'>
+<h2>5.13 - <a name="5.13">Tasks and Channels</a></h2>
+
+Teliva includes the well-known
+<a href='https://github.com/majek/lua-channels#readme'>lua-channels</a>
+library in module <tt>task</tt>. It also transparently starts up
+<tt>task.scheduler</tt> for all apps.
+
+</div>