Docbook Olink insert dialog UX improvements

[steve.cuzner]

We have large reference books that have refentry targets for hundreds of various ref pages. The default behavior now is to fully expand the tree view for the book, so there are chapter, refentry, refsect1, refsect1, refsect3, etc. all expanded which makes scrolling to the specific link target difficult. This is mitigated by the filter option, but when you filter, the results are single flat instances rather that a filtered node. For example, if I have a refentry, foo, that has 5 refsect1 elements and I know I want to link to the syntax refsect1 of the foo refentry, if I filter on foo I quickly find it, but I can't expand it to see the refsect1 child elements, so I cannot create the link to the syntax refsect1. I can click on foo, then clear the filter which leaves the refentry foo highlighted, but it does not stay focused in the window, so then I have to scroll through the doc looking for the highlight, then find the refsect1 for syntax.

Ideally, when you filter you should return expandable nodes that are fully expandable. If not that, in addition to filtering, a simple search on the dialog that would allow you to search for foo in the full hierarchy and shift focus to it for normal operation.

[Radu]

Hi Steve,

We do not use Docbook much internally but I think I understand most of this. I created and worked a bit with a large olink database file. Please see some feedback below:

The default behavior now is to fully expand the tree view for the book, so there are chapter, refentry, refsect1, refsect1, refsect3, etc. all expanded which makes scrolling to the specific link target difficult.

How about if we only expand by default the first level in the tree? Basically for a book you would only see the chapters... maybe with an "Expand All" action added to the contextual menu of the tree...

This is mitigated by the filter option, but when you filter, the results are single flat instances rather that a filtered node. For example, if I have a refentry, foo, that has 5 refsect1 elements and I know I want to link to the syntax refsect1 of the foo refentry, if I filter on foo I quickly find it, but I can't expand it to see the refsect1 child elements, so I cannot create the link to the syntax refsect1.

I understand, present the found nodes with all descendants collapsed.

I can click on foo, then clear the filter which leaves the refentry foo highlighted, but it does not stay focused in the window, so then I have to scroll through the doc looking for the highlight, then find the refsect1 for syntax.

Indeed after you clear the filter, the selection in the tree remains in the proper place but we do not scroll to it. We can also try to fix this. As a workaround, after you select a parent node, clear the filter, you can press the TAB key to give focus to the three and then use the Up or Down arrows to move a little in the tree and have the scrolling show the current selection.

I will add an internal issue with your feedback, we might not have enough time to approach it because we plan to release Oxygen 19.1 in about a month. But maybe we can implement part of it.

Regards,
Radu

[steve.cuzner]

Your suggestion sounds reasonable. The only possible improvement would be to allow a configuration in framework for expanded elements. For example I might want to specify expand chapter, section[not(parent::section)], refentry, refsect1 and all others would be collapsed. This would certainly be a "nice to have." and your suggestion of collapsing all but the first level under root would be a huge improvement.

[Radu]

Hi Steve,

If all goes well when Oxygen 19.1 is released you will have a fix in which after the filter text is removed, the scroll will jump to the selected node.
The other improvements that you asked for will probably be postponed for a future version.

Regards,
Radu

[Radu]

Hi Steve,

We just released Oxygen 19.1 and it should have that vertical scroll fix for the dialog used to insert olinks available.

Regards,
Radu