[PATCH 6/6] added short documentation for some translators.

[Joshua Branson]

From: "jbranso@dismail.de" <jbranso@dismail.de>

* doc/hurd.texi (fifo): added a short explanation.
* doc/hurd.texi (ifsock): added a really short explanation.
* doc/hurd.texi (null): added a short explanation.
* doc/hurd.texi (devnode): tiny grammer fix.
* doc/hurd.texi (Storeio): short explanation.
* doc/hurd.texi (Store Library): @code -> @file{<hurd/store.h>
* doc/hurd.texi (Networking): short description of pfinit and lwip.
---
 doc/hurd.texi | 145 ++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 141 insertions(+), 4 deletions(-)

diff --git a/doc/hurd.texi b/doc/hurd.texi
index 4a89cbec..7bad2976 100644
--- a/doc/hurd.texi
+++ b/doc/hurd.texi
@@ -2968,16 +2968,68 @@ FIXME: finish
 
 @node fifo
 @section fifo
+@cindex fifo
+
+The fifo translator implements named pipes, which is a simple and
+portable inter-process communication.  Usually pipes die when the
+command is completed like so (the ``|'' is the anonymous pipe):
+
+@example
+@verbatim
+$ fsysopts /home | awk '{ print $2 }'
+  --writable
+@end verbatim
+@end example
+
+Alternatively one can @emph{name} a pipe with the command
+@command{mkfifo <name>}, which will persist until you remove it with
+the command @command{rm <name>}.  This lets you use commands that
+interact with the pipe from many different terminals.
+
+FIXME: should we add an example?  Can I borrow what's on wikipedia?
 
 @node ifsock
 @section ifsock
 
+The @code{ifsock} translator acts as a hook to provide Unix domain
+sockets.  The @code{pflocal} translator on @file{/servers/socket/1}
+implements the sockets.
+
 @node magic
 @section magic
+@cindex magic
+
+The magic translator returns magic retry results, which are then
+resolved by glibc's name lookup routines.  This translator runs on the
+mount points @file{/dev/fd} and @file{/dev/tty}.
+
+@example
+$ showtrans /dev/fd
+  /hurd/magic --directory fd
+@end example
+
+The @file{/dev/fd} directory holds the open file descriptors for your
+current process. You can't see them individually with:
+
+@example
+$ ls /dev/fd
+  -rw-rw-rw- 1 root root 0 Apr 10 11:47 /dev/fd
+@end example
+
+But you can see them with:
+
+@example
+$ ls -l /dev/fd
+crw--w---- 1 joshua tty 0, 0 Sep 19 17:58 /dev/fd/0
+@end example
 
 @node null
 @section null
 
+The null translator represents an endless stream of zeros.  When you
+read from @file{/dev/null}, you are sure to get lots of zeros.  When you
+write to @file{/dev/null}, no data is stored.
+
 @node devnode
 @section devnode
 
@@ -2989,7 +3041,7 @@ FIXME: finish
 which provides another way for other programs to open the device.
 
 Clients need to get the port to the @dfn{devnode} translator by calling
-@dfn{file_name_lookup}() and uses this port as a master device port to open
+@dfn{file_name_lookup}() and use this port as a master device port to open
 the device by calling @dfn{device_open}(). The device name used in
 @dfn{device_open}() is specified by @option{--name} of @dfn{devnode}.
 
@@ -3034,15 +3086,33 @@ filtered in various ways.
 
 @section storeinfo, storecat, storeread
 @section storeio
+@cindex storeio
 
-FIXME: finish
+@code{storeio} is a translator for devices and other stores.  It
+heavily uses @code{libstore}.
+
+You can @code{ungzip} files on the fly with @code{storeio}
+(@code{bunzip2} is available as well.):
+
+@example
+$ settrans -ca foo.txt /hurd/storeio -T gunzip foo.gz
+@end example
+
+@code{libdiskfs} uses storeio:
+
+@example
+@verbatim
+$ fsysopts / | awk '{ print $5 " " $6}'
+  --store-type=typed part:1:device:hd0
+@end verbatim
+@end example
 
 @node Store Library
 @section Store Library
 @scindex libstore
 @scindex store.h
 
-The store library (which is declared in @code{<hurd/store.h>})
+The store library (which is declared in @file{<hurd/store.h>})
 implements many different backends which support the store abstraction.
 Hurd programs use @code{libstore} so that new storage types can be
 implemented with minimum impact.
@@ -4645,6 +4715,23 @@ FIXME: finish
 
 @section symlink, firmlink
 @section hostmux, usermux
+@cindex hostmux, usermux
+
+@code{hostmux} multiplexes arbitrary host names, which makes accessing
+to many different hosts fast and easy.  That is a terse and abstract
+definition.  Let's explain with an example:
+
+@example
+$ settrans -fgap ~/ftp: /hurd/hostmux /hurd/ftpfs /
+@end example
+
+Now any programs can access the files from open ftp servers as easy
+as:
+
+@example
+ls ~/ftp:/ftp.gnu.org/
+@end example
+
 @section shadowfs
 
 
@@ -4701,7 +4788,8 @@ FIXME: finish
 FIXME: this subsystem is in flux @c Thomas, 26-03-1998
 
 @menu
-* pfinet::                     TCP/IP stack.
+* pfinet::                     Default TCP/IP stack.
+* lwip::                        Alternative TCP/IP stack.
 * pflocal::
 * libpipe::
 * Socket Interface::            Network communication I/O protocol.
@@ -4710,6 +4798,55 @@ FIXME: this subsystem is in flux @c Thomas, 26-03-1998
 
 @node pfinet
 @section pfinet
+@cindex pfinet
+
+Hurd developers ripped out an old Linux TCP/IP stack and called it
+pfinit.  It is the hurd's current default TCP/IP stack.  We hope to
+one day replace it with the @code{lwip} or @code{rump} TCP/IP stack.
+Lwip exists and works as a full replacment for pfinit.  The rump
+TCP/IP stack will most likely be a better option, but no one has
+started on it yet.
+
+@node lwip
+@section lwip
+@cindex lwip
+
+Developers created the @code{lwip} TCP/IP library with the design
+goals of minimalism and portability.  @code{lwip} is meant to be used
+on embedded devices.  While it is an alternative for the pfinet TCP/IP
+stack, a rump TCP/IP stack may be a better option.
+
+The lwip translator provides all of the following:
+
+@itemize @bullet
+@item
+Support for IPv4 and IPv6
+@item
+Support for TCP and UDP
+@item
+Support for multiple Ethernet devices
+@item
+Support for fsysopts and command-line parameters configuration
+@item
+Support to create an IP tunnel which may be used by an OpenVPN client
+@end itemize
+
+To configure lwip for internet connectivity, use the settrans command:
+
+@example
+settrans -fgap /servers/socket/2 /hurd/lwip \
+    -i /dev/eth0 -a 192.168.0.50 -g 192.168.0.1 -m 255.255.255.0
+@end example
+
+The argument @file{/server/socket/2} is the node that the translator
+is to be attached to. This is followed by the translator program to
+run and any arguments to give it.
+
+There, ``-i'', ``-a'', ``-g'' and ``-m'' are, quite obviously, the
+(Mach) device to use, the IP address, the gateway and netmask. You can
+discover these values via the @command{ifconfig} command (You need to
+run the @command{ifconfig} command on the host system and NOT in the
+qemu environment).
 
 @node pflocal
 @section pflocal
-- 
2.40.1