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

[jbranso]

January 22, 2024 at 6:49 PM, "Samuel Thibault" <samuel.thibault@gnu.org> wrote:



> 
> Hello,
> 
> Thanks for your contributions! Here are a few comments for the last bit.
> 
> Samuel

If you are ok with an the Hurd manual being converted to org-mode,
then we could use the org-mode manual as a reference:

https://git.savannah.gnu.org/cgit/emacs/org-mode.git/tree/doc/org-manual.org

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