[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH 6/6] added short documentation for some translators.
From: |
Samuel Thibault |
Subject: |
Re: [PATCH 6/6] added short documentation for some translators. |
Date: |
Tue, 23 Jan 2024 00:49:32 +0100 |
User-agent: |
NeoMutt/20170609 (1.8.3) |
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
- Re: [PATCH 6/6] added short documentation for some translators.,
Samuel Thibault <=