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

[Samuel Thibault]

Hello,

Thanks for your contributions! Here are a few comments for the last bit.

Samuel

Joshua Branson, le jeu. 21 sept. 2023 12:48:22 -0400, a ecrit:
> 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

I'd say use a less hurdish example,

ls | grep -i report

for instance.

> +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?

Yes, it would be useful. We don't really want to borrow text, a simple
example can be:

mkfifo /tmp/foo
echo Hello > /tmp/foo

and in another term,

cat /tmp/foo


>  @node null
>  @section null
>  
> +The null translator represents an endless stream of zeros.

No, see cat /dev/null which returns immediately. It's the zero
translator that returns zeroes.

> 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
>  



> @@ -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

I'd say call the gz file foo.txt.gz

An other interesting example is accessing partitions of a disk image:

settrans -ca disk1 /hurd/storeio -T typed part:1:file:disk.img

then you can access partition 1 through disk1. Which nicely brings to:

> +@code{libdiskfs} uses storeio:

+also

> +@example
> +@verbatim
> +$ fsysopts / | awk '{ print $5 " " $6}'
> +  --store-type=typed part:1:device:hd0
> +@end verbatim
> +@end example
>  

> @@ -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

That isn't really explaining how it works. Additionally show:

$ showtrans /ftp:/ftp.gnu.org
/hurd/ftpfs / ftp.gnu.org

and explain that hostmux simply added the host string at the end of the
translator invocation.

> @@ -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.

pfinet

> 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. 

replacement

> 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.

I don't think such comments should be added to the documentation, only
to the wiki.

> +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

You also need to pass the -6 option and setup /servers/socket/26 as
well, just like for pfinet.

> +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,

It's not really a Mach device: as the example shows it can be a mere
unix path.

> 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).

The qemu part is not really meaningful here.

Samuel