HaikuBook proposal

What about having a version of the HaikuBook more well-spaced (like the BeBook) and more complete ?

If I understood correctly the HaikuBook is less complete than the BeBook on the API coverage.

I was thinking first of having the main page clearly indicating all the Kits available like below :

BeBook on the left / HaikuBook on the right

What do you think ?

I will try to look at what is missing today in the HaikuBook (compared to the BeBook), but if someone has a clear view let me know :slight_smile:

4 Likes

Not bad! I like it.

While you’re there. It would be super useful having a link in the Haiku Book to the corresponding entry of the Be Book opening in a separate tab. Maybe Doxygen can automatically build the correct link?

The BeBook format is definitely better than the HaikuBook format. Not that the latter is horrible, but the former seems more easily navigable, clean, etc.

FWIW, the single most useful feature of the HaikuBook over the BeBook is the full text search. It’s about 100% how I use it, enter the function, class, etc., click, boom you’re there.
The other advantage over the BeBook are the declarations of all member functions at the top that link to in-depth info below.

Anyway, I’m all for a HaikuBook package for offline perusal, esp. if Genio learned to jump right into the thick of it. :slight_smile:

I don’t know why you decided to create a new test doxygen environment and Doxyfile when we already have an HTML version of the HaikuBook and Doxyfile. Our html style is mostly unified across the Haiku Book and User Guide and other documents. If there are issues with the style they should be fixed there.

There are a number of small style problems throughout the docs that could be fixed running doxygen and fixing the warnings. I’ve done this before but as the document grows and we update the Doxygen version more have popped up. There are also some mobile rendering issues with our style that need addressing.

The changes to front page look ok to me if you’d like a more simplified bullet list. As far as being less complete than the BeBook that is a matter of doing the hard work of documenting everything, which I encourage those interested to help with. I and others have done our best to document as much as we can but it’s a big project and still more work is to be done.

Yes the test doxygen was to understand where the warnings came from (as I discovered one error displayed in WebPositive) and not to be a replacement of the existing style.

As the HaikuBook is less complete than the BeBook (I’m starting from a blank page here, so I’m not sure what is missing today), yes I’m interested in having a better HaikuBook, the ideal situation would be to have the Haiku Book available on the local machine (and BeBook no more needed once everything is covered).

I will first do the front page proposal on Gerrit and after that I will check what can be done :slight_smile:

1 Like

Genio now has an early stage support for extensions that can be leveraged to jump into the documentation. We already have one for Zeal but had not packaged it, yet.
The only problem I see is that, with WebPositive at least, whatever documentation is requested it will be shown in a new tab. Unless I missed a way to achieve that, it is not much convenient.

2 Likes

HaikuBook requires some stuff to be documented that isn’t. But for me personally I’d like more examples and explanations. Coming from outside it can be really confusiing to figure out how you are supposed to use an api.

3 Likes

I’d love to see more examples in the documentation.

2 Likes

If you look at the haiku sources, you already have some examples available in “haiku/src/tests” if it can help

1 Like

It should be possible to add custom fields to the refs received message to force reuse of a specific tab, I think? Not yet implemented on WebPositive side, but it should be easy to add it if we can agree on a protocol for it.

A Boolean field could tell to use the current tab vs a new one but we need a sensible way to indicate a specific one. I don’t think that an index works well in all situations, maybe a string to instruct WebPositive to pick a tab whose URL starts with that string?
Another option could be allowing separate instances of WebPositive and using the scripting capabilities to address a specific one and a specific tab. It would be WebPositive only, but I think it would be acceptable for this use case.

Pick a client-defined name. For example “Genio-documentation”

Then request that tab to be updated with your new uri. Either a tab with that specific identifier exists, and will be updated (and focused), or a new one will be opened.

That way we avoid conflicts between programms that want to do this each, and nobody will be annoyed that their banking site got overwritten because it is the “current” tab.

I’d like to see more code examples within the API documentation. Sometimes I’ve had to resort to just figuring it out though some APIs are difficult to understand.

I’m not sure I’ve grasped this correctly.
Assuming the use of scripting, do you mean something like:

  • Get the tab with name NAME
  • If it exists, load the url URL
  • If not, open a new tab with name NAME
  • load the url

Correct?

Scripting is not really needed here.

Just send a B_REFS_RECEIVED message to WebPositive including:

  • The entry_ref that you want to open, as usual
  • A “tab-name” string field with a name you generated in your app

WebPositive can then do all the hard work: see if someone already requested to open a tab with the same name, and otherwise, open it. We can also make sure that the user cannot use the tab for something else. Either make that tab open all links in new tabs, or, as soon as the user navigates/clicks on a link, erase the tab name. So that you don’t accidentally lose a webpage because you happened to navigate to it from a tab initially opened to show some documentation. Maybe these tabs should have a visual hint in Web+ as well.

1 Like

Not scripting, but a semantic extension to the message you already send to the browser.

I think pulkomandy nailed it pretty much with the outline, if you want a bit more guidance I think IRC might be a good place to talk instead.