Docset for The Haiku Book

I succesfully created a docset for the Haiku Book and imported in Zeal (btw, thanks @Lrrr for fixing it so promptly!).

I am currently working on integrating Zeal with Genio by implementing an early-stage extension framework based on Haiku’s built-in scripting capabilities.
It would be great if we could automatically build the docset and make it available as a feed from the web site.
Unfortunately, I had to create it on my Mac with docsetutils but there are alternatives around like this:

If anyone is interested I can see if I’m allowed to redistribute the docset as a feed on Github.
This would be a temporary solution until we host an official build.
Any advice?

9 Likes

Hi nexus-6,

Can you explain what a docset is? I only found some wierd medical website online.

From the screenshot it looks to be related to doxygen but i’m not sure.

This is Zeal, for reference. I meant to try it a few times, but I’m still unclear on the benefits, seeing how I already have the docs for Python and Tcl installed from the Debian repositories, with more available.

Sorry, I gave for granted that everyone was familiar with it.
It’s the documentation format used by Apple for their APIs and adopted by Dash (a commercial product for MacOS) and Zeal (its open source counterpart).
It soon gained traction also outside of the Apple ecosystem and it is now one of the most common formats.
Zeal and Dash are offline API documentation browsers (like AmigaGuide, CHM Viewer, and similar tools).
Zeal comes with tens if not a hundred docsets for many languages and frameworks.
Doxygen can generate files that can be translated into docsets and Haiku’s doxygen config file already allows that.
Zeal can then be invoked on the command line to perform a search in the docsets.
Something like Zeal SetExplicitAlignment


Thus it can be easily integrated with any editor/IDE.
Being a widespread format and having a working port of Zeal, I think it would be a great addition for the developers to be able to browse the Haiku Book offline.
Once upon a time there were DontWorry / BeHappy for BeIDE (one was a doc browser the other was an autompletion tool but I don’t remember which is which).

2 Likes

This already works with the haiku book offline in the browser.

That beeing said I am interested how this functionality works with a language server, can you jump from it to the relevant documentation section?

As for distributing this, to me it sounds like making a haikuports recipe for the haiku book in this format would make most sense. Or altering the haiku build system to optionally build this, and do this for the beta releases so it can be downloaded.
e.g haikubook_docset as package build from the sourcetree.

More or less yes but Zeal supports type-ahead search and it is snappier, IMHO.
It is instead more convenient if you integrate it with an editor/IDE.

The language server is not involved, what you need is identifying the symbol (Scintilla has functions to extract the symbol under the caret, for example).
If you mean, pointing to the right Symbol corresponding to a specific class I think it’s not possible with Zeal.
The only thing is to restrict the search to the Haiku API for example with “haiku:SetTarget” should your current docsets have multiple SetTarget symbols somewhere else.

As long as we keep it up to date with every change in the docs…
Take your recent changes for example:

bool rgb_color::IsDark() const

We need to make sure that the docset on Haikuports is kept in sync with Haiku source.

I was reffering to for example typing BTabV, which as I understand would ask the language server what a possible completion is, it could return BTabView. Would then, with this symbol in Hand zeal provide the reference to this? (e.g parts of The Haiku Book: BTabView Class Reference )

If it is build with the haiku tree that would be guranteed, the revision of the package would then match the nightly (if it is build)

edit:

You can’t bring up specific documentation? or what is ment here?
what about calls to Invalidate()? Does that not know in what class you are currently operating? as in the context of the language server?

Oh and something to be aware of, Zeal can take the docset from a URL feed and whenever there is an update it prompts the user.

Not sure if got it right, do you mean automatically?
In any case it’s up to the application to decide how to trigger a specific workflow. For the time being, I’m working on implementing a menu item (Something like Extensions->Open documentation) maybe with a shortcut such as F1 or something.

BTW, there are many conversations happening on the Zeal repo like here to design a solution which addresses what you proposed.

Hmm, if it does not know the context of the langauge server I am a bit lost what the advantage is over opening the webrowser and searching for the relevant class, and it‘s relevant members manually. : /

That, and Zeal “docsets” appear to be just repackaged versions of each language’s official documentation, or equivalent: in the case of C++, it’s literally a 500-megabyte dump of cppreference.com; its selling point appears to be making it available offline in a more convenient way, which is debatable.

Memory-wise, how do docsets stack up against a compressed Markdown format? Or compressed HTML?

They’re literally just webpages, loaded into a QtWebKit control. I think uncompressed after download.

Ugh! How pointless! Even web browsers can GZip HTML, CSS and JavaScript for improved storage and bandwidth utilization. Does Zeal even have indexing better than a web browser?

According to docs, it uses a very simple SQLite database as an index. No idea how well it really works.

It sounds no better than an HTML5 browser. Didn’t SQLite get added to the bloatware W3C standard for HTML5?

Kind of? There’s the IndexedDB API, but it’s not the same thing. You’d still need to set up some sort of app to load and search an index for an entire static website (in fact there are JS libraries for it). Zeal does just that with SQLite databases in a Qt app, so you only need to worry about creating the index.

Like DevDocs API Documentation?

1 Like

DevDocs looks remarkably similar, yes! Except they seem to put more effort into converting the pages.