Put nsmux in line with the other translator pages.

1 files changed, 117 insertions, 0 deletions

diff --git a/hurd/translator/nsmux.mdwn b/hurd/translator/nsmux.mdwn
new file mode 100644
index 00000000..c07a30bd
--- /dev/null
+++ b/hurd/translator/nsmux.mdwn
@@ -0,0 +1,117 @@
+[[!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 command:
+
+    $ git clone git://github.com/scolobb/nsmux.git
+
+`filter` translator can be obtained with the following command:
+
+    $ git clone git://github.com/scolobb/filter.git
+
+The filter is not yet working.
+
+It is highly probable that soon the code will be moved to Savannah.
+
+## 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.