Use heading text for references to heading even across pages

[panglesd]

Fix #941 and #779.

[jonludlam]

Did this last commit fix a bug?

[panglesd]

The interface for Ref_tools.resolve_reference was changed to also return a paragraph option: the "paragraph"¹ is a possible replacement text computed when resolving the reference. In the case of a title, this "paragraph" is the title.

However, before the last commit, this paragraph was not always output as Some by resolve_reference, so there was some code in Link which looked for the title content in the missing case.

In short, the last commit does not fix a bug, it just moves this lookup of title content from Link.comment_inline_element to Ref_tools.resolve_reference so that the lookup of the title content is centralized in one place.

Footnotes

1. paragraph here is just a type alias for inline_element with_location list. Not an actual paragraph. ↩

[jonludlam]

This seems fine, as far as it goes. At some point I think it'd be good if resolve_reference returned the component of the thing it found rather than just some extracted text, more like Tools.resolve_module and the like. This would allow a tool to look up an element by reference and then show the docs for that element.

In any case, this is a step in the right direction and fixes some bugs, so in it goes. Thanks!