Many clicks or keyboard hits away…
Copy, switch window either with twitcher or mouse, select the search bar and paste it or even worse typing.
Instead, with one keyboard shortcut or one/two clicks and you can get Zeal’s window instantly.
Not a big deal per se but if you do that many times in a coding session it can saves a lot of time.
Having said that, if there are better options I’d like to know them.
How? Didn‘t you say before that it can‘t know the context? In that case opening it in webpositive is faster since you need to find the class manually anyway.
I think our friend here means that Zeal, being a desktop app, can stay hidden in the traybar icon and pop open when you hit a key combo, whatever else you may be doing at the moment.
If Zeal is used in standalone mode, i.e. without any sort of integration, albeit conceptually similar cannot be really compared to the HaikuBook viewed in WebPositive.
Zeal can search the indexed symbols in any position so if you type ‘application’, it will find all the occurrences of BApplication along with other symbols in the available docsets. Moreover, it supports fuzzy search so if you type ‘aplication’, it will return the expected results regardless of a typo.
The Haiku Book generated by Doxygen does not allow that.
If Zeal is used with the search term as an argument from the commandline it can be integrated in a code editor. The existing window will be reused, broght to front and activated, no additional windows will be opened and the search box will be filled with the terms passed automatically.
As far as I know, WebPositive does not allow that as every URL will be opened in a new tab.
Furthermore, the Haiku Book generated by doxygen does not accept query strings to trigger a search. At least, I could not figure out how.
Zeal is not bad, it lacks a few useful options which Dash has but I con cope with that, namely docset search groups and snippets.
Of course, if multiple search result are available for a certain symbol it cannot point to the exact one we pass from the editor with painstaking precision. However, it’s acceptable and for the time being, it’s the best we have.
I‘m not convinced really, the only advantage you mentioned is fuzzy search, which is something I‘ve not missed in HaikuBook so far.
The current Haiku book is already a 80% solution, works fairly well.
I don‘t think it makes sense investing a big ammount of effort to then get a 85% solution, it just does not seem worth it considering all the things it can‘t do.
To explain a bit, this is what I would expect from a documentation engine in relation to an IDE (note I‘m rather thinking about Paladin‘s style as I‘ve not used genio)
- Look up symbols in the current file
→ Show exercpt of the documentation (for example enum Explantation) Inline in a popup, show short explanation in tab completion. - Jump to definition of symbols in header files or modules
- Show alternatives in the current scope, for an enumeration show other possible values
These for me would be features that would improve my workflow massively, a slightly faster search however does not. (and both could likely be added to the current HaikuBook without too much effort)
Here is a little mockup what I would expect:
Now, this example would be better if that documentation actually said what unit the textheight and length are in. Pixels? unicode code points? bytes? : )
But I think you should see what I mean with this
Edit: documentation for B_VERTICAL in the scope of say a scrollbar should also ideally have an image included to show how vertical and horizontal look like.
I know enough people that struggle with this, also to define what „direction“ a scrollbar has.
We probably have different standpoints and past experience.
Form a technical standpoint you are mixing two different features: LSP and API documentation.
These are LSP capabilities, which by the way Genio already implements. I’ve never used other solutions like Vim+YouCompleteMe but they should support these, too.
I’m not sure I have understood the third point, though. Could you elaborate?
LSP supports the signature/type expansion and clangd supports the expansion of any doxygen style header as long as it is in a translation unit in the project. This means that Haiku API documentation will not be shown.
OmniSharp supports XML doc instead even with compiled assemblies but this is a feature due to Roslyn and how the CLR is designed.
I can’t comment on pylsp, I need to double check.
Just mentioned the three LS that we currently support in Genio.
Having said that, your idea is reasonable but I don’t know of any technology that allows that.
Because of their technical similarities in this design it makes sense to extend the LSP for this or transfer the internal knowledge of the LSP in a sidechannel.
If you highlight B_VERTICAL it should show B_HORIZONTAL
for bitfields it show additional values you can add for example B_AUTO_UPDATE_SIZE_LIMITS for a BWindow constructor
I was able to use that doxygen2docset tool to generate a docset from my Arch Linux PC. I also have it compiled for Haiku but have not done anything with it. I have a very crude script that can generate the docset pretty quickly if you’re interested.
I have also added some sqlite commands to modify the docset index so that methods are prefixed with the class or namespace. These commands are not optimized at all and should probably be extended to include types other than methods. This allows directly searching for a method in a specific class and also gives results that are easier to identify when doing basic searches.
2 Likes
Brilliant! I’ll try it soon.
Clangd can return the symbol from an lsp position in the document, perhaps it can be used to pass additional info to Zeal to narrow down the search.
In Genio we retrieve the symbol via Scintilla instead because of the asynchronous nature of the protocol which makes things more complex.
I’ll see if we can support this scenario.
1 Like
I have just noticed that the HaikuBook is already part of the user contributed feeds for the Dash app. It looks as though it hasn’t been updated in a while and it doesn’t have my index “improvements”. There is a github mirror which contains Zeal-compatible feed links as well. It may be possible to submit a pull request with my version instead, or, I also have a github workflow that can generate a docset feed.