[Xapian-discuss] Doc bug for remote database stubs ?

[Olly Betts]

On Tue, Oct 30, 2012 at 09:36:30PM +0100, Jean-Francois Dockes wrote:
> In the short description of stubs on http://xapian.org/docs/overview.html,
> it seems to me that the "program" line example should have a colon
> character before the command name, like in:
> 
>   remote :ssh xapian-prog.example.com xapian-progsrv
> 
> not, as currently in the document:
> 
>   remote ssh xapian-prog.example.com xapian-progsrv

Yes, the documentation doesn't match the code.  Thanks for pointing this
out.

> Also, as this text seems to be the only description of the stub line in the
> Xapian documentation (except if I googled it wrong), it may be useful to
> give it complete, as I think that it also needs a database directory field,
> like in:
> 
>   remote :ssh xapian-prog.example.com xapian-progsrv /path/to/db

Yeah, that too.

> I'm a bit surprised that nobody ever remarked this, and quite in doubt that
> I am right, but the fact is, that the current example line does not work
> and the last one above does...

I think most people using remote use the TCP variant, and a lot of
people probably use it directly rather than via a stub file.  I guess
nobody has used the two together before, or at least not from just
reading the docs.

Differentiating based on that colon is kind of weird, so especially
since this isn't actually correctly documented, I'm tempted to deprecate
that form, and add a "remote-prog" or something as the preferred way to
do this.

Incidentally, I think the reason it's a weird format is just due to the
history.  Originally the testsuite didn't have machinery to fire up
remote tests over TCP (it's fiddly to do as you have to ensure you start
it on a port which isn't in use, and tell the client the port number to
use).  So the prog variant was created purely for the test harness, but
later we realised it was actually useful for things like tunnelling the
connection.  But originally the remote prog backend was probably only
intended to be used in the testsuite, so a nice syntax wasn't important.

The "getting started" guide now has automated testing that the code
examples work and produce the output shown, so we should have fewer
issues of this sort in that at least.

Cheers,
    Olly