Merge branch 'master' of flubber:~hurd-web/hurd-web

20 files changed, 441 insertions, 67 deletions

diff --git a/hurd/debugging/rpctrace.mdwn b/hurd/debugging/rpctrace.mdwn
index 63b72ee0..46f40508 100644
--- a/hurd/debugging/rpctrace.mdwn
+++ b/hurd/debugging/rpctrace.mdwn
@@ -1,4 +1,5 @@
-[[!meta copyright="Copyright © 2007, 2008 Free Software Foundation, Inc."]]
+[[!meta copyright="Copyright © 2007, 2008, 2009 Free Software Foundation,
+Inc."]]
 
 [[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
 id="license" text="Permission is granted to copy, distribute and/or modify this
@@ -24,7 +25,6 @@ See `rpctrace --help` about how to use it.
   * <http://savannah.gnu.org/patch/?1633> -- terminated with `C-c` `rpctrace`d
     programs hang
 * <http://savannah.gnu.org/patch/?5580> -- more readable output
-* <http://savannah.gnu.org/bugs/?20612> -- heisenbug
 
 
 # TODO
diff --git a/hurd/faq/still_useful.mdwn b/hurd/faq/still_useful.mdwn
new file mode 100644
index 00000000..bffeaebd
--- /dev/null
+++ b/hurd/faq/still_useful.mdwn
@@ -0,0 +1,46 @@
+[[!meta copyright="Copyright © 2009 Free Software Foundation, Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled [[GNU Free Documentation
+License|/fdl]]."]]"""]]
+
+what are the advantages with the Hurd over Linux, in general of course, nothing
+in depth
+
+> Flexibility for the user:
+> 
+> transparent ftp
+> 
+>     $ cd /ftp://ftp.debian.org/debian
+>     $ ls
+> 
+> personnal filesystem
+> 
+>     $ dd < /dev/zero > myspace.img bs=1M count=1024
+>     $ mke2fs myspace.img
+>     $ settrans myspace /hurd/ext2fs myspace.img
+>     $ cd myspace
+
+>> Just curious, but I keep seeing these (and other similar) concepts being
+>> brought up as the amazing selling points of the Hurd, but all of this is
+>> entirely doable now in Linux with FUSE or things like it.
+
+>>> Nowadays, at LAST, yes, partly.
+
+>> I'm not sure if an ftp filesystem has been implemented for FUSE yet, but its
+>> definately doable; and loopback filesystems like in your second example have
+>> been supported for years.
+
+>>> As a normal user?  And establish a tap interface connected through ppp over
+>>> ssh or whatever you could want to imagine?
+
+>>  What, then, are the major selling points or benefits?
+
+>>> These were just examples, Linux is trying to catch up in ugly ways indeed
+>>> (yes, have a look at the details of fuse, it's deemed to be inefficient).
+>>> In the Hurd, it's that way from the _ground_ and there is no limitation
+>>> like having to be root or ask for root to add magic lines, etc.
diff --git a/hurd/faq/top.mdwn b/hurd/faq/top.mdwn
new file mode 100644
index 00000000..9e385c0f
--- /dev/null
+++ b/hurd/faq/top.mdwn
@@ -0,0 +1,16 @@
+[[!meta copyright="Copyright © 2009 Free Software Foundation, Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled [[GNU Free Documentation
+License|/fdl]]."]]"""]]
+
+[[!meta title="What is a replacement for procps' top?"]]
+
+Here is a replacement to use, until the real `top` works, which depends on
+[[hurd/translator/procfs]] and some [[!taglink porting|open_issue_porting]].
+
+    $ while :; do ps -e -v -s CPU --top=22 -r; sleep 5; done
diff --git a/hurd/glibc.mdwn b/hurd/glibc.mdwn
index e975a239..bdfed833 100644
--- a/hurd/glibc.mdwn
+++ b/hurd/glibc.mdwn
@@ -1,4 +1,5 @@
-[[!meta copyright="Copyright © 2007, 2008 Free Software Foundation, Inc."]]
+[[!meta copyright="Copyright © 2007, 2008, 2009 Free Software Foundation,
+Inc."]]
 
 [[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
 id="license" text="Permission is granted to copy, distribute and/or modify this
@@ -16,3 +17,5 @@ For information about how the glibc integrates into the system, see sections
 [[Hurd-specific_API]].
 
 [[Debugging_glibc|debugging/glibc]].
+
+[[Internals]].
diff --git a/hurd/glibc/internals.mdwn b/hurd/glibc/internals.mdwn
new file mode 100644
index 00000000..897da92e
--- /dev/null
+++ b/hurd/glibc/internals.mdwn
@@ -0,0 +1,35 @@
+[[!meta copyright="Copyright © 2009 Free Software Foundation, Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled [[GNU Free Documentation
+License|/fdl]]."]]"""]]
+
+Some bits about this, some bits about that.
+
+# Controlling TTY
+
+Hurd controlling tty behavior is generally consistent with BSD's, including
+`TIOCSCTTY`.  Linux also has `TIOCSCTTY` and it is harmless to use it there.
+But BSD and Hurd never do an implicit `TIOCSCTTY` (hence our `O_NOCTTY` is
+zero).
+
+C.f. <http://lists.gnu.org/archive/html/bug-hurd/2009-10/msg00030.html> and the
+following messages.
+
+# Sinals
+
+[[Unix]] signals are implemented in glibc.
+
+In every process, signals are handled in a separate signal thread.
+
+    [Why does kill hang sometimes?]
+    <youpi> kill send the signal to the process
+    <youpi> if the process is hung, killing waits
+    <youpi> signals should be just asynchronous, but apparently for some reason
+      Roland & co wanted some syunchronization
+
+[[!taglink open_issue_glibc]]
diff --git a/hurd/ng/discussion.mdwn b/hurd/ng/discussion.mdwn
new file mode 100644
index 00000000..d4632bd5
--- /dev/null
+++ b/hurd/ng/discussion.mdwn
@@ -0,0 +1,13 @@
+[[!meta copyright="Copyright © 2009 Free Software Foundation, Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled [[GNU Free Documentation
+License|/fdl]]."]]"""]]
+
+To go beyond research project Hurd have to support thousands of various programs running on GNU/Linux nowadays.
+It looks like ExoKernel approach http://pdos.csail.mit.edu/exo.html might be useful here.
+Does somebody tried to look into something like Hurd exokernel + liblinux?
diff --git a/hurd/running.mdwn b/hurd/running.mdwn
index 470b5f0b..f0058625 100644
--- a/hurd/running.mdwn
+++ b/hurd/running.mdwn
@@ -1,4 +1,5 @@
-[[!meta copyright="Copyright © 2007, 2008 Free Software Foundation, Inc."]]
+[[!meta copyright="Copyright © 2007, 2008, 2009 Free Software Foundation,
+Inc."]]
 
 [[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
 id="license" text="Permission is granted to copy, distribute and/or modify this
@@ -17,4 +18,6 @@ There are several different ways to run a GNU/Hurd system:
 * [[vmware]] (**non-free!**)
 * [[FlashHurd]] - From a flash stick
 
+* [[FAQ]]
+
 * [[Public_hurd_boxen]]
diff --git a/hurd/running/debian/faq.mdwn b/hurd/running/debian/faq.mdwn
index 4966456a..b3bd230d 100644
--- a/hurd/running/debian/faq.mdwn
+++ b/hurd/running/debian/faq.mdwn
@@ -1,4 +1,4 @@
-[[!meta copyright="Copyright © 2007 Free Software Foundation, Inc."]]
+[[!meta copyright="Copyright © 2007, 2009 Free Software Foundation, Inc."]]
 
 [[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
 id="license" text="Permission is granted to copy, distribute and/or modify this
@@ -10,7 +10,8 @@ is included in the section entitled
 
 [[!meta title="Debian GNU/Hurd FAQ"]]
 
-See also the [[Hurd_FAQ|hurd/FAQ]] and [[after_install]].
+See also the [[Hurd_FAQ|/hurd/FAQ]], [[after_install]], and the [[General FAQ
+About Running GNU/Hurd|/hurd/running/faq]].
 
 [[!inline
 pages="hurd/running/debian/faq/* and !*/discussion"
diff --git a/hurd/running/debian/faq/apt_umount.mdwn b/hurd/running/debian/faq/apt_umount.mdwn
index f2889f3e..db0dbfd1 100644
--- a/hurd/running/debian/faq/apt_umount.mdwn
+++ b/hurd/running/debian/faq/apt_umount.mdwn
@@ -22,4 +22,4 @@ Give executable permission to the script.
     # chmod +x /usr/bin/umount
 
 In `/etc/fstab` add a trailing `/` after cdrom like `/cdrom/` since apt uses a
-traing `/`.
+trailing `/`.
diff --git a/hurd/running/faq.mdwn b/hurd/running/faq.mdwn
new file mode 100644
index 00000000..a59bce7e
--- /dev/null
+++ b/hurd/running/faq.mdwn
@@ -0,0 +1,20 @@
+[[!meta copyright="Copyright © 2009 Free Software Foundation, Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled [[GNU Free Documentation
+License|/fdl]]."]]"""]]
+
+[[!meta title="General FAQ About Running GNU/Hurd"]]
+
+See also the [[Hurd FAQ|hurd/FAQ]], and the [[Debian GNU/Hurd FAQ|debian/faq]].
+
+[[!inline
+pages="hurd/running/faq/* and !*/discussion"
+show=0
+feeds=no
+actions=yes
+rootpage="hurd/running/faq" postformtext="Add a new item titled:"]]
diff --git a/hurd/running/faq/native-install_doesnt_finish.mdwn b/hurd/running/faq/native-install_doesnt_finish.mdwn
new file mode 100644
index 00000000..a852e1dd
--- /dev/null
+++ b/hurd/running/faq/native-install_doesnt_finish.mdwn
@@ -0,0 +1,24 @@
+[[!meta copyright="Copyright © 2009 Free Software Foundation, Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled [[GNU Free Documentation
+License|/fdl]]."]]"""]]
+
+Copying baseGNU to the virtual disk works. Even booting got through but when I
+try to run native-install it never gets to the very end. First time it froze on
+*sed* package, the other time on *sysv-rc*.
+
+> How much memory did you configure for the [[QEMU]] system?  It may simply be
+> -- I've seen this myself -- that the system runs out of memory, as at the
+> native-install stage (I think at least) swap is not yet configured and
+> enabled.  What I've been doing is: boot (with -s), MAKEDEV hdWHATEVER in
+> /dev/ for the swap device, run /hurd/mach-defpager, followed by swapon
+> /dev/hdWHATEVER.  Does this help?
+
+>> Thank You very much, more memory solved the freezing.
+
+[[!tag open_issue_hurd]]
diff --git a/hurd/running/gnu/create_an_image.mdwn b/hurd/running/gnu/create_an_image.mdwn
index 2cdb8e27..c7a97a4e 100644
--- a/hurd/running/gnu/create_an_image.mdwn
+++ b/hurd/running/gnu/create_an_image.mdwn
@@ -27,7 +27,7 @@ Creating a bootable qemu image from a root filesystem and bootloader
     create the necessary partitions (root and swap partitions boot, home ... if
     required)
 
-4. Create a file syatem for the root partiotion
+4. Create a file system for the root partition
 
         mke2fs /dev/hda1
 
@@ -39,7 +39,7 @@ Creating a bootable qemu image from a root filesystem and bootloader
 6. Copy the file system from the host machine to the mounted directory (use a
     compressed file system to make the copying faster)
 
-    Grab the GNU spapshot from ams' site
+    Grab the GNU snapshot from ams' site
     <http://www.update.uu.se/~ams/home/slask/GNU/>
 
         scp <user>@<host>:<path to the compressed file system> disk
@@ -58,7 +58,7 @@ Creating a bootable qemu image from a root filesystem and bootloader
 
         poweroff
 
-10. To make the file syatem bootable download a grub floppy image
+10. To make the file system bootable download a grub floppy image
 
         <http://hurd.in/pub/Hurd/HurdOnVMware/grub.img>
 
diff --git a/hurd/running/gnu/setup.mdwn b/hurd/running/gnu/setup.mdwn
index 57a19054..2fb30c7b 100644
--- a/hurd/running/gnu/setup.mdwn
+++ b/hurd/running/gnu/setup.mdwn
@@ -8,7 +8,7 @@ Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
 is included in the section entitled
 [[GNU Free Documentation License|/fdl]]."]]"""]]
 
-Setup is very easy (You need a GNU/Linux system to install GNU, we are developing an installer for GNU and if you want to help us join us on [[http://lists.gnu.org/mailman/listinfo/gnu-system-discuss][gnu-system-discuss]]), just follow these steps ...
+Setup is very easy (You need a GNU/Linux system to install GNU, we are developing an installer for GNU and if you want to help us join us on [gnu-system-discuss](http://lists.gnu.org/mailman/listinfo/gnu-system-discuss)), just follow these steps ...
 
 ## Step 1: Find a home for GNU 
 
diff --git a/hurd/running/gnu/universal_package_manager.mdwn b/hurd/running/gnu/universal_package_manager.mdwn
index ecac8e21..74c1ac8b 100644
--- a/hurd/running/gnu/universal_package_manager.mdwn
+++ b/hurd/running/gnu/universal_package_manager.mdwn
@@ -153,3 +153,4 @@ To join the project just list your name below.
    6. Ajish.B
    7. Ambili.B
    8. Abhradip Mukherjee
+   9. Ermenegildo Fiorito
diff --git a/hurd/status.mdwn b/hurd/status.mdwn
index 3ee8ddcf..cd2256e3 100644
--- a/hurd/status.mdwn
+++ b/hurd/status.mdwn
@@ -16,13 +16,19 @@ for production use, as there are still many bugs and missing features.
 However, it should be a good base for further development and
 non-critical application usage.
 
-The GNU system (also called GNU/Hurd) is completely self-contained
+[[!img hurd-fvwm-screenshot-2009-11-12.png size=300x
+alt="FVWM and Gnumeric running on GNU/Hurd"
+title="FVWM and Gnumeric running on GNU/Hurd"
+align="right"
+
+]] The GNU system (also called GNU/Hurd) is completely self-contained
 (you can compile all parts of it using GNU itself).  You can run
 several instances of the Hurd in parallel, and debug even critical
 servers in one Hurd instance with gdb running on another Hurd
 instance.  You can run the X window system, applications that use it,
 and advanced server applications like the Apache webserver.
 
+
 On the negative side, the support for character devices (like sound
 cards) and other hardware is mostly missing.  Although the POSIX
 interface is provided, some additional interfaces like POSIX shared
diff --git a/hurd/status/hurd-fvwm-screenshot-2009-11-12.png b/hurd/status/hurd-fvwm-screenshot-2009-11-12.png
new file mode 100644
index 00000000..445abf32
--- /dev/null
+++ b/hurd/status/hurd-fvwm-screenshot-2009-11-12.png
diff --git a/hurd/translator.mdwn b/hurd/translator.mdwn
index 4995a005..e567938f 100644
--- a/hurd/translator.mdwn
+++ b/hurd/translator.mdwn
@@ -33,6 +33,17 @@ kernel and thus have absolute access to the machine.
 As the protocols do not require any special privilege
 to implement, this is not an issue on the Hurd.
 
+In Mach parlance, a *translator* is what they name a *server*: a process that
+participates in [[RPC]] interactions.  In the Hurd, a translator is a server
+that is additionally attached to a filesystem node.  Thus, it is quite common,
+even in the Hurd context, to speak about *server*s if you're stressing the RPC
+part, and on the other hand about *translator*s if you're stressing the
+filesystem part: a translator implements the [[interface/fs]] and
+[[interface/io]] interfaces.  For example: *the [[pfinet]] server implements
+the socket API calls (which are mapped by [[glibc]] to equivalent RPC calls)*,
+compared to *a [[libdiskfs]]-based translator implements a filesystem, based on
+a backing store*.
+
 To learn how to write a translator, read the code!
 It is well documented, in particular, the header files.
 The [[Hurd_Hacking_Guide]] also has a tutorial.
@@ -73,7 +84,7 @@ Read about translator [[short-circuiting]].
 * [[cvsfs]]
 * [[tmpfs]]
 * [[procfs]]
-* [[unionmount]]
+* [[nsmux]]
 * ...
 
 
diff --git a/hurd/translator/nsmux.mdwn b/hurd/translator/nsmux.mdwn
new file mode 100644
index 00000000..d156772b
--- /dev/null
+++ b/hurd/translator/nsmux.mdwn
@@ -0,0 +1,121 @@
+[[!meta copyright="Copyright © 2009 Free Software Foundation, Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled
+[[GNU Free Documentation License|/fdl]]."]]"""]]
+
+# nsmux
+
+`nsmux` implements the simplest use-case of namespace-based translator
+selection (see below).
+
+To use `nsmux` do the following:
+
+    $ settrans -a <node> nsmux <directory>
+
+After this operation `<node>` will be a mirror of `<directory>` with
+namespace-based translator selection functionality enabled.
+
+Please note that due to some details `nsmux` may complain a lot when
+run as a normal user.  This matter is the most urgent on the TODO
+list.
+
+## Source
+
+`nsmux` translator can be obtained with the following series of
+commands:
+
+	$ git clone git://git.sv.gnu.org/hurd/incubator.git nsmux
+	$ cd nsmux/
+	$ git checkout -b nsmux origin/nsmux
+
+`filter` translator can be obtained with the following series of
+commands:
+
+	$ git clone git://git.sv.gnu.org/hurd/incubator.git filter
+	$ cd filter/
+	$ git checkout -b filter origin/filter
+
+The filter is not yet working.
+
+## Namespace-based Translator Selection
+
+Namespace-based translator selection is the special technique of using
+"magic" filenames for both accessing the file and setting translators
+on it.
+
+A "magic" filename is a filename which contains an unescaped sequence
+of two commas: ",,".  This sequence can be escaped by adding another
+comma: ",,,".  In the magic filename the part up to the first double
+commas is interpreted as the filename itself; the remaining segments
+into which the string is split by occurrences of ",," are treated as
+names of translators located under `/hurd/`.
+
+The simplest advantage before traditional way of setting
+translators is shown in the following examples.  Compare this
+
+    $ settrans -a file translator1
+    $ settrans -a file translator2
+    $ cat file
+
+to this:
+    
+    $ cat file,,translator1,,translator2
+   
+One simple command versus three more lengthy ones is an obvious
+improvement.  However, this advantage is not the only one and,
+probably, not even the most important.
+
+What is a good candidate for the most important advantage is that
+translators requested via "magic" filenames are session-bound.  In
+other words, by running `cat file,,translator` we set a translator
+visible *only* to `cat`, while the original file remains untranslated.
+Such session-specific translators are called **dynamic** and there is
+no (theoretical) way for a client to get a port to a dynamic
+translator requested by another client.
+
+Obviously, dynamic translators can be stacked, similarly to static
+translators.  Also, dynamic translator stacks may reside on top of
+static translator stacks.
+
+An important operation of namespace-based translator selection is
+*filtering*.  Filtering basically consists in looking up a translator
+by name in the stack and ignoring translators located on top of it.
+Note that filtering does not mean dropping some translators: in the
+current implementation a filter is expected to be a normal dynamic
+translator, included in the dynamic translator stack similarly to
+other translators.
+
+An important detail is that filtering is not limited to dynamic
+translator stacks: a filter should be able to descend into static
+translator stacks as well.
+
+Although the concept of filtering may seem purely abstract in the
+simplest use-case of setting dynamic translators on top of files, the
+situation changes greatly when dynamic translator stacks on top of
+directories are considered.  In this case, the implementation of
+namespace-based translator selection is expected to be able to
+propagate the dynamic translators associated with the directory down
+the directory structure.  That is, all files located under a directory
+opened with magic syntax, are expected to be translated by the same
+set of translators.  In this case having the possibility to
+specifically discard some of the translators set up on top of certain
+files is very useful.
+
+Note that the implementation of propagation of dynamic translators
+down directories is not fully conceived at the moment.  The
+fundamental problem is distinguishing between situations when the
+dynamic translators are to be set on the underlying files of the
+directory or on the directory itself.
+
+## Currently Implemented
+
+Currently there a working (though not heavily tested) implementation
+of the simplest use-case of namespace-based translator selection in
+the form of translator `nsmux`.  The filter is partially implemented
+and this is the immediate goal.  Propagating translators down
+directories is the next objective.
diff --git a/hurd/translator/unionfs.mdwn b/hurd/translator/unionfs.mdwn
index b177b874..331ad19f 100644
--- a/hurd/translator/unionfs.mdwn
+++ b/hurd/translator/unionfs.mdwn
@@ -8,17 +8,140 @@ Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
 is included in the section entitled
 [[GNU Free Documentation License|/fdl]]."]]"""]]
 
+# `unionfs`
+
+*Unionfs allows you to simply union one directory or translator into another one, so you see the files of both of them side by side.*
+
 Source repository: <http://git.savannah.gnu.org/cgit/hurd/unionfs.git/>
 
+Right now there are some problems with syncing, so please be aware
+that it might not work as expected.
 
-<a name="stowfs"></a>
-# `stowfs`
+<a name="unionmount"></a>
+# `unionmount`
 
 ... is a special mode of `unionfs`.
 
-# See Also
+## Project Idea
+
+When setting a translator on Hurd -- similar to mounting a file system on UNIX
+-- the new node(s) exported by the translator are obscuring the original node
+where the translator is set, and any nodes below it in the directory tree. The
+translator itself can access the underlying node (which is a very nice feature,
+as it allows translators presenting the contents of the node in a different
+format); but it's no longer accessible from the "outside".
+
+Plan9 has a feature where a file system can be mounted in union mode: the new
+file system doesn't obscure the mount point in this case, but instead the
+contents are combined. (This feature has also been under discussion in Linux
+for a couple of years now, under the label "VFS-based union mounts".)
+
+This kind of union mounts is generally useful, as it's sometimes more
+convenient than unioning existing filesystem locations with unionfs -- it's not
+necessary to mount a file system that is to be unioned at some external
+location first: just union-mount it directly at the target location.
+
+But union mounts also allow creating passive translator hierarchies: If there
+is a passive translator on a parent node, and further passive translators on
+child nodes, the union mount allows the child nodes with the further translator
+settings still to be visible after the parent translator has started.
+
+This could be useful for device nodes for example: let's say we have an
+ethernet multiplexer at /dev/veth. Now the virtual subnodes could all be
+directly under /dev, i.e. /dev/veth0, /dev/veth1 etc., and explicitely refer to
+the main /dev/veth node in the translator command line. It would be more
+elegant however to store the virtual nodes direcly below the main multiplexer
+node -- /dev/veth/0, /dev/veth/1 etc.
+
+There are two possible approaches how union mounts could be implemented in the
+Hurd. The first one is to let the various translators handle union mounts
+internally, i.e. let them present the underlying nodes to the clients in
+addition to the actual nodes they export themselfs. This probably can be
+implemented as some kind of extension to the existing netfs and diskfs
+libraries.
+
+The other possible apporach is less efficient and probably more tricky, but
+probably also more generic: create a special unionmount translator, which
+serves as a kind of proxy: setting the union-mounted translator on some
+internal node; and at the actual mount location, presenting a union of the
+nodes exported by this translator, and the nodes from the underlying file
+system.
+
+The goal of this project is implementing union mounts using either of the
+approaches described above. (Though it might be useful initially to prototype
+both for comparision.) The ethernet multiplexer shall serve as an example use
+case -- any changes necessary to allow using it with the union mount
+functionality are also to be considered part of the task.
+
+## Implementation
+
+### Source
+
+Union mounts are currently implemented as two additional command line
+options of the `unionfs` translator.  This implementation resides in
+the master-unionmount branch of the unionfs git repository.  To
+checkout the code, do the following:
+
+    $ git clone git://git.sv.gnu.org/hurd/unionfs.git
+    $ cd unionfs
+    $ git checkout -b master-unionmount
+    $ git pull origin master-unionmount
+
+You can skip the checkout step if you don't mind that the
+`master-unionmount` branch gets merged into the `master` branch.
+
+### Short Documentation
 
-  * [[unionmount]]
+The `unionmount` project adds options "--mount" and "--no-mount" to
+`unionfs` (short versions: "-t" and "-n" correspondingly).  Both
+options are used to implement union-mounting, but the first option
+will create a *transparent* union mount, while the second option will
+create a *nontransparent* union mount.
+
+One can create a transparent union mount with the following command:
+
+    $ settrans -a <node> unionfs --underlying --mount=<translator>
+
+When running
+
+    $ fsysopts <node>
+
+one will see the information about the `<translator>`, not the
+`unionfs` translator.  Although this might seem the only natural way
+to do union mounts, one must keep in mind that such transparency
+deprives one of the possibility to modify the unioned virtual
+filesystem exported by `unionfs` at run-time (via `fsysopts`).
+
+One can create a nontransparent union mount with the following command:
+
+    $ settrans -a <node> unionfs --underlying --no-mount=<translator>
+
+When running
+
+    $ fsysopts <node>
+
+one will see the information about the `unionfs` translator.  Although
+this way allows modifying the contents of the unioned filesystem
+exported by `unionfs` at runtime, the access to `<translator>` is
+blocked.
+
+The filesystem exported by the *mountee* (`<translator>`) is actually
+treated like a normal filesystem within `unionfs`, which means that
+one can assign priorities to the *mountee* to achieve the desired
+order of layering of the unioned directories.  The following will make
+`unionfs` query the underlying filesystem first and then the
+*mountee*:
+
+    $ settrans -a <node> unionfs --priority=2 --underlying --priority=1 --mount=<translator>
+
+Note that the same functionality can also be achieved by assigning
+priority 1 to the underlying filesystem and keeping the priority of
+the *mountee* at 0.
+
+<a name="stowfs"></a>
+# `stowfs`
+
+... is a special mode of `unionfs`.
 
 # External Links
 
diff --git a/hurd/translator/unionmount.mdwn b/hurd/translator/unionmount.mdwn
index 47a3d85d..7384afc7 100644
--- a/hurd/translator/unionmount.mdwn
+++ b/hurd/translator/unionmount.mdwn
@@ -8,53 +8,4 @@ Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
 is included in the section entitled
 [[GNU Free Documentation License|/fdl]]."]]"""]]
 
-[[!meta title="Union Mounts"]]
-
-When setting a translator on Hurd -- similar to mounting a file system on UNIX
--- the new node(s) exported by the translator are obscuring the original node
-where the translator is set, and any nodes below it in the directory tree. The
-translator itself can access the underlying node (which is a very nice feature,
-as it allows translators presenting the contents of the node in a different
-format); but it's no longer accessible from the "outside".
-
-Plan9 has a feature where a file system can be mounted in union mode: the new
-file system doesn't obscure the mount point in this case, but instead the
-contents are combined. (This feature has also been under discussion in Linux
-for a couple of years now, under the label "VFS-based union mounts".)
-
-This kind of union mounts is generally useful, as it's sometimes more
-convenient than unioning existing filesystem locations with unionfs -- it's not
-necessary to mount a file system that is to be unioned at some external
-location first: just union-mount it directly at the target location.
-
-But union mounts also allow creating passive translator hierarchies: If there
-is a passive translator on a parent node, and further passive translators on
-child nodes, the union mount allows the child nodes with the further translator
-settings still to be visible after the parent translator has started.
-
-This could be useful for device nodes for example: let's say we have an
-ethernet multiplexer at /dev/veth. Now the virtual subnodes could all be
-directly under /dev, i.e. /dev/veth0, /dev/veth1 etc., and explicitely refer to
-the main /dev/veth node in the translator command line. It would be more
-elegant however to store the virtual nodes direcly below the main multiplexer
-node -- /dev/veth/0, /dev/veth/1 etc.
-
-There are two possible approaches how union mounts could be implemented in the
-Hurd. The first one is to let the various translators handle union mounts
-internally, i.e. let them present the underlying nodes to the clients in
-addition to the actual nodes they export themselfs. This probably can be
-implemented as some kind of extension to the existing netfs and diskfs
-libraries.
-
-The other possible apporach is less efficient and probably more tricky, but
-probably also more generic: create a special unionmount translator, which
-serves as a kind of proxy: setting the union-mounted translator on some
-internal node; and at the actual mount location, presenting a union of the
-nodes exported by this translator, and the nodes from the underlying file
-system.
-
-The goal of this project is implementing union mounts using either of the
-approaches described above. (Though it might be useful initially to prototype
-both for comparision.) The ethernet multiplexer shall serve as an example use
-case -- any changes necessary to allow using it with the union mount
-functionality are also to be considered part of the task.
+[[!meta redir=unionfs#unionmount]]