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

I just wanted to verify that I did get this email, and it's awesome 
that I can now work on the Hurd manual!  And I'll tweak this last
commits based on your comments.

Weirdly enough.  Would you be ok with me converting the Hurd manual
to org-mode?  Or is that a massive can of worms?

Thanks,

Joshua


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