Customizable popup widgets

[mdinger]

Is a popup widget that the client could customize doable either as an extension or as a flag or something else for the user? For example, this was presented as an aid to discovering the meaning of specific rust terms. I suggested something here more extensive which definitely seems doable but I'm not sure if it would be possible to integrate into the doc build or not.

What I was thinking was you could use a JSON file which would house the format and structural information of a widget which could popup on click or something like that and the book generator would load it and add the widget as a floating element to the book.

[
  { "Title": "What is?", "children": [
    { "keyword": "as", "text": "primitive casting", "link": "link_to_url" },
    { "keyword": "for", "text": "for loop", "link": "link_to_url" }
  ] },
  { "Location": "top-right" }
]

Now, this might be very unusual for a doc system to want something like this. I'm not sure but it definitely seems like it might be useful for this example, and in particular the Rust docs. I'd be interested to see how well it would work in practice too.

Is this something this as a tool could supply or could support via an extension? Any thoughts or opinions?

[EDIT]

I could create a mockup of what it possibly could look like if that might help too.

[azerupi]

I could create a mockup of what it possibly could look like if that might help too.

Yes please :) Because I am not sure I understand what you are proposing.
Would it be some kind of tooltip (except that it appears on click instead of hover)?

[mdinger]

Here's an ugly mockup of what the popup thing could look like:

Based off of this, the main purpose of it would be for when the reader doesn't know what a symbol, keyword, or something else stood for, they could click on it, find the term, keyword, or whatever and find a link to what that specific item was.

That table on the other page is definitely somewhat comprehensive but I think for a topic like this, it could be compressed dramatically. Anyway, I kinda think the idea is interesting but I don't know how well it would work out in practice or if it would be straightforward to add to a tool like mdbook or not.

[azerupi]

I am not sure how useful a specific popup would be, it seems to me that this can be solved by extensive cross-linking and having a good index page.

What advantage would a specialized popup have?

[mdinger]

Yeah, I'm not too sure either. If you're reading the book and come across some term, then cross linking works great but if find something you don't understand in the wild, then you gotta start guessing where to look for it and this is failure prone.

My concern about things like this is that there are already so many chapters in the book and if it is stuffed all the way in the appendix, will anyone find it or use it? I look in the appendix in actual books but I don't know if I've ever looked for an appendix in an online doc set like that.

Another thing, I go to the python docs (the docs are decent) but there are 20 header links on the main part of the docs. Just about the only one I ever click on is the tutorial one. If they had such a page, I'd probably never have seen it.

Anyway, I thought I'd present it. Maybe it would be better just to fix up the intro section but it didn't seem like a terrible idea.

[azerupi]

I understand your worries. Most people will probably not even bother to look in an index. But I am also a little bit worried to clutter the UI. I think it would be much better to have very good search functionality that can be influenced by the client with a list of specific terms.

The look of the rendered book is pretty decent now, so I would like to start adding more features to help client and user. Like a good search and a watch command, ...

I have already briefly experimented with the watch command (see branch). I will also begin to experiment with a search functionality.

What I propose is that we focus on the search functionality for now, and once it's is implemented we can discuss this proposition again if needed. Does that sound good to you?

[mdinger]

That's interesting. A good search might remove the need for something of this type. Consider the filter thing thunderbird supplies:

That seems like a reasonable course to take.

[mdinger]

Thinking more about this. Allowing custom index pages a little like this which are searchable via different clickable search boxes might work really well. For example, there could be a "How do I", "Define" and maybe others. It'd probably need to be updated based on how people used it. It might be especially nice if you didn't even have to switch to a new page.

I think I like your idea pretty well and am pretty optimistic about how useful it could be.

[Michael-F-Bryan]

Reading through the comments in this issue it sounds like there are other, low-tech, solutions to this issue (e.g. @azerupi mentions "extensive cross-linking and having a good index page").

There is also a PR (#472) which adds search functionality to the book, which would probably be superior to a "popup index" you need to manually maintain.

@mdinger I'm going to close this issue for now seeing as the underlying issue is largely "solved". Don't be afraid to let me know if you think we should go back and revisit the idea though.