[[!meta copyright="Copyright © 2009, 2013 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.savannah.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.savannah.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.


## Open Issues

### IRC, freenode, #hurd, 2013-08-22

[[!tag open_issue_hurd]]

    < youpi> err, is nsmux supposed to work at all?
    < youpi> a mere ls doesn't work
    < youpi> I'm running it as a user
    < youpi> echo * does work though
    < teythoon> ah, yes, nsmux,,is,,funny :p
    < youpi> well, perhaps but I can't make it work
    < youpi> well, the trivial ,,hello does work
    < youpi> but ,,tarfs doesn't seem to be working for instance
    < youpi> same for ,,mboxfs
    < youpi> ,,xmlfs seems to somehow work a bit, but not very far...
    < youpi> so it seems just nobody is caring about putting READMEs wherever
      appropriate
    < youpi> e.g. examples in socketio/ ...