Support internal links in the PDF version

[tsalo]

Internal linking to entity definitions introduced in #568 does not work in the PDF version of the specification. While we're comfortable with leaving these links as a web-only feature, if anyone does have the time and interest to figure out how to support the links in the PDF version, that would be very helpful.

This stems from #568 (comment).

[sappelhoff]

+1, would be awesome to get the internal links in the PDF working.

Currently we are explicitly removing all internal links from the MD source as a build step on the way from markdown to PDF, see:

bids-specification/pdf_build_src/process_markdowns.py

Line 102 in 1d2c972

def remove_internal_links(root_path, link_type):

If I remember correctly that is because our internal links often look like this:

[inheritance-principle](../some-file.md#some-section-header)

That is, the internal links are often across different files.

--> This works well for the html generated from the MD source with mkdocs, because the html specification still consists out of several documents (html documents) that stay interlinked that way.

However when building a PDF, we append all the distinct documents into a single document, and the links that were previously across different files stop working, because we have a single file now.

A solution would thus probably be to replace the above linked remove_internal_links function with a function that replaces the cross-file links with links how they are predicted to be once all distinct files have been appended into a single file.

---

PS: links that may be helpful

• https://stackoverflow.com/q/4779582/5201771
• https://stackoverflow.com/q/37327374/5201771