GNOME Bugzilla – Bug 791442
DhKeywordModel: remove feature to filter by book and page?
Last modified: 2018-01-21 12:07:59 UTC
DhKeywordModel: remove feature to filter by book and page? The feature has been implemented in bug #340069 in 2006. I think the feature has been removed in 2008: commit 5c5ff46ba1c6d91595515c30d21c008329f9cc40 In 2009 the feature has been re-added: commit 4a824384b3e786c76ab58409f09890ac74dbf105 commit 054737547420db3f7e4825ee645a20c1d119aced And now: * The feature is buggy: - The completion is broken, it tries to complete by name/title, it should instead complete by ID (book_id, page_id). - The search results are duplicated (two times the same results, at least for me). * It is undocumented, it's hard to discover the feature. * Nobody has reported the above bugs on bugzilla, I think not a lot of people are aware that the feature exists. * It's not really useful IMHO, I use Devhelp almost every day and I never use that feature. * It complicates the code, the fact that the code is more complicated can introduce bugs in other more important features. So, I would like to remove that feature, to simplify the code.
For a description of the feature as originally intended, see: https://bugzilla.gnome.org/show_bug.cgi?id=340069#c0 (the GTK+ 3 book ID is now "gtk3", not "gtk"). Filtering by book is not easy to use, it can be difficult to know the book ID. And is it really useful? Filtering by page: for GObject classes the "page ID" is the same as the class name, so it's for example possible to search "page:GtkNotebook". But simply searching "GtkNotebook" without filtering by page gives also the link to the GtkNotebook page, and we can see all the GtkNotebook API at the top of the HTML page. So for me the feature is not useful.
(In reply to Sébastien Wilmet from comment #0) > - The completion is broken, it tries to complete by name/title, it > should instead complete by ID (book_id, page_id). I've added a FIXME comment for that in dh_book_get_completions(): commit 814aef03813aa723ed9be6a94a608a2f98748beb.
Ok so, this is not a feature for users of the DevHelp UI, lets be clear about that. If you want to remove the interoperability of devhelp and IDEs or other DX tools, then I wont argue, as I dont much maintain this area of code any more, but I think it is a very cool feature. Also please consider if it is only the API (command line interface) which are bothersome to you or if it's the whole feature, maybe we can change this for a D-Bus custom startup notification for Devhelp or something like that instead. I'll just note here why things are done the way they are, what are the requirements for a tool which wants to programatically show a very particular documentation page to the user via devhelp ? * Searching within scope When the user of your RAD tool or IDE clicks on the help button for the "activate" signal on that class which is exposed in the IDE's symbol browser, it is important to search for the "activate" signal in DevHelp for exactly: - That object class (many classes have an "activate" signal, it's important to disambiguate here) - That book (many GObject using libraries now have multiple APIs which are parallel installable, it's important to get the activate signal documentation for the GtkButton class in GTK+3 if that's what the user is using). * Displaying an exact page, top of page When we search devhelp with just the book and page ID, this is to avoid having to search for the "GtkButton" documentation, which would result in DevHelp scrolling to an obnoxious "typedef _GtkButton GtkButton" offset in the documentation. When the user wants to see "The docs for GtkButton", the application which launches DevHelp needs a way to tell DevHelp to display the top of the page, and not some weird offset within the docs describing the typedef. So yeah, again this is not for users of the DevHelp UI, it's API for any IDE or tooling which wants to either embed the DevHelp UI or launch it as a companion app to view specific documentation. Glade and Anjuta have been using this feature since I added it to DevHelp - I would regret to see the interoperability disappear, but would not mind (and would welcome) a cleanup here (change from CLI interaction to something else ? helper library with D-Bus stuff ?) if there is a better way for these apps to be interacting.
Thanks for the explanations, now I better understand. It's entirely possible to refactor the code, to fix the bugs and have a cleaner implementation. I definitely don't want to remove interactions between Devhelp and other dev tools. Whether it's implemented with a command line or D-Bus doesn't change much. What matters more to me is the complexity of the internal implementation, especially the search function in DhKeywordModel (I've already started to refactor the code, initially it was a huge function with 8 indentation levels, hard to follow).
I've now refactored the code, fixed all the bugs that I've found (3 or 4 in total), written some unit tests and documented the "book:" and "page:" feature. For the documentation, see commit 08a4c6f1af1daaaab6e99f12d5c20bdb2f0f0b78. So no, the feature will not be removed :-)
(In reply to Sébastien Wilmet from comment #5) > I've now refactored the code, fixed all the bugs that I've found (3 or 4 in > total), written some unit tests and documented the "book:" and "page:" > feature. > > For the documentation, see commit 08a4c6f1af1daaaab6e99f12d5c20bdb2f0f0b78. > > So no, the feature will not be removed :-) Thanks !