API: Installed docsets

[trollixx]

Several requests (#368, #371 and #375) have been submitted about providing a way to retrieve the list of installed docsets.

I do not consider CLI a reliable, and portable interface, so a better alternative is wanted here.

[Kwaadpepper]

Well other ways left are socket or dBus isn't it ?

[trollixx]

D-Bus almost does not exist outside of *nix world (I am aware about Windows ports).

A local socket might be the best option. Zeal already creates one for the single instance mode and handling custom URL schemes. It shouldn't be hard to utilise it for other purposes.

[Kwaadpepper]

I just read the code so:

src/main.cpp -> if socket is open -> send query and quit program
src/core/application.cpp -> server listening on socket -> query and bring to front

It could evolve in this way:

prefix=somebytestatic (like shebang or binary prefixing for format)

src/main.cpp -> if socket is open -> send query and quit program (no change)

src/core/application.cpp ->
    server listening on socket ->
        if received prefix+query
            -> query and return json to socket
        else
            -> query and bring to front

Of course there would be a need to include a jsonlib.

Also although i understand the c++ zeal code, i don't actually know the detailed characteristic of the socket just a name "ZealLocalServer". Meaning the address and port so i could connect trough with nodejs or vala for my use case.

EDIT:
I am thinking that using QLocalserver would force people to use Qt or have the language a compatibility to import qtlib (like python does, but vala does not). So using a socket would make the code more complicated since it would have to be replace to have a new tread listening on the socket. So the socket could be more Zeal specific by making use of QTcpSocket instead.

EDIT2:
Just saw bool QTcpServer::listen(const QHostAddress &address, quint16 port) in http://code.qt.io/cgit/qt/qtbase.git/tree/src/network/socket/qtcpserver.cpp line 267, this would be more portable am i wrong ?

[trollixx]

QLocalServer is just a thin wrapper on top of Unix local socket or Windows named pipe. So, there's nothing Qt-specific with it. For Vala the only difference is use of GUnixSocketAddress instead of GInetSocketAddress. For Node.js simply call net.connect() with a socket name as the first argument.

Some sort of JSON interface should be fine. It's pretty easy to detect whether payload contains JSON or something else. I am not sure there's much sense in implementing a binary protocol.

[Kwaadpepper]

Well the bin protocol is just proposal to make changes simplier.
Otherwise i guess it just have to make another QLocalserver parsing query and outputing json right ?

Edit:
Json output could be like

{
    'results':  {
        'php': ['constants','Constants','apc_define_constants'],
        'mysql': ['1204 ER_SETCONSTANT_ONLY']
        '...'
    }
}

Knowing that we can launch zeal with dash:// or from cli this will give all to abilities to make use of zeal by another program. (launching either dash://php:constants or just dash://constants)

Also i'm not sure if you will be glad for this but since there is a button "Open URL" it could give the url like

 'php': {'constants': 'file:///home/kwaadpepper/.local/share/Zeal/Zeal/docsets/PHP.docset/Contents/Resources/Documents/php.net/manual/en/function.constant.html'},

That way complete page info could be easily embed from results

EDIT2:
I was missing #368 and #371 but to solve these quick solution is to list all docsets in results and somehow maybe allowing to make blank search:

{
    'results':  {
        'php': [],
        'mysql': [],
        ...
    }
}

So even if there is no results in a docset it would be sent but with empty array. This would keep things simple as possible.

[gleber]

I'd love to see the same API provided via stdin/stdout when called with "zeal --api". This would allow to easily integrate it with various scripts (in my case it's my dotfiles bootstrap script, which ensures that I have all necessary development environment)

[ManuelSchneid3r]

Hi I am the author of albert launcher. I think this api wrapped in an albert extension would be the absolute killer workflow. Unfortunately I dont use zeal anymore because using the launcher to google is simply faster. However I like the idea of a dedicated app for documentation and I really would like to use Zeal through albert.

Please give this issue some priority.

[trollixx]

This is something I'd like to address with the new backend, which is currently in works.

[jxsl13]

Any updates?