Jean-Francois Dockes
2012-Oct-30 20:36 UTC
[Xapian-discuss] Doc bug for remote database stubs ?
Hi, 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 (as appears from dbfactory.cc around line 169, the code expects a colon at position 0). To add insult to injury, the further text on the page quite helpfully specifies that no colon should be found anywhere on the "program" line :) 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 On the not-documentation side it is not really helpful that the database object creation silently fails when the line is wrong... Had to follow the code until I found the colon thing. 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... Cheers, jf
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-progsrvYes, 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/dbYeah, 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