doc: fix broken relative md links

[willcl-ark]

These relative links in our documentation are broken, fix them.

[DrahtBot]

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Code Coverage

For detailed information about the code coverage, see the test coverage report.

Reviews

See the guideline for information on the review process.

Type	Reviewers
ACK	ryanofsky, maflcko
Concept ACK	katesalazar
Stale ACK	ismaelsadeeq

If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update.

Conflicts

Reviewers, this pull request conflicts with the following ones:

• #30034 (ci: add markdown link check job by willcl-ark)
• #29965 (Lint: support running individual rust linters and improve subtree exclusion by davidgumberg)

If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

[maflcko]

lgtm

[maflcko]

ACK 8e394d1

[maflcko]

Is there an easy way to find those?

[ismaelsadeeq]

utACK 8e394d1

[willcl-ark]

Is there an easy way to find those?

I was using this https://github.com/becheran/mlc/ in offline mode to find broken internal links. I'm sure it wouldn't take much to modify it to surface relative links, if we want them all absolute?

[maflcko]

Would it be easy to add mlc (or something like it) to the lint CI task? (Just as an idea for a follow-up, not for here)

[ryanofsky]

Code review 8e394d1

I don't think it is good to change these to absolute links. When I open these files in emacs I can click the relative links it will load the target files. If I change the links to be absolute, it tries to open non-existent paths on my root file system.

I imagine emacs is not the only tool which behaves this way. Is it necessary to make links absolute for broken link detection to work, or some other motivation to make them absolute?

[maflcko]

Is it necessary to make links absolute for broken link detection to work, or some other motivation to make them absolute?

I brought it up, because absolute paths are already used, and it makes it more robust if a file or paragraph is moved. However, if mlc (or similar) is added in the future and checks against this, relative paths should be fine (and maybe preferred, if that helps with emacs)?

[willcl-ark]

The mlc tool seems fine with relative or absolute, so long as they resolve.

nvim seems to jump using relative or absolute links.

I did check to see if one or the other was more markdown-compliant, but it seems they purposefully avoided specifying. Seems like here we might prefer relative so we cater to emacs users, all other things being equal?

[ryanofsky]

Oh, ok. I wasn't aware absolute links were already being used. I would slightly prefer links in the two files I wrote (libraries.md and multiprocess.md) to be relative so they work with emacs and so links within the files use a consistent style. But since I am the one responsible for a lot of these broken links, don't weigh my opinion too heavily 😉

[willcl-ark]

I would slightly prefer links in the two files I wrote (libraries.md and multiprocess.md) to be relative so they work with emacs and so links within the files use a consistent style

A rough search of *.md files shows me that we have 87 absolute links and 72 relative:

Details

will@ubuntu in ~/src/bitcoin on  fix-links [$!?] : 🐍 (bitcoin)
₿ rg "\]\(\/" */**.md | wc -l
87

will@ubuntu in ~/src/bitcoin on  fix-links [$!?] : 🐍 (bitcoin)
₿ rg "\]\(\.\." */**.md | wc -l
72

...but it seems very reasonable to not break the documents you wrote/lead in maintaining, so I reverted those to relative in 4b9f49d.

4b9f49d also fixes a broken external link to flake8 (it seems they deleted the gitlab repo entirely and moved to GitHub).

Would it be easy to add mlc (or something like it) to the lint CI task? (Just as an idea for a follow-up, not for here)

Yes it should be; I already had a second commit in this branch to run this as a GHA but dropped it (as I thought these are quite unlikely to break regularly).

I could open a PR to have this GHA run scheduled weekly (or something like that) if there's interest.

if mlc (or similar) is added in the future and checks against this, relative paths should be fine (and maybe preferred, if that helps with emacs)?

Yes agree, relative seems better if they are being checked.

[katesalazar]

Concept ACK

[ryanofsky]

Code review ACK 4b9f49d. Thanks for the updates!

[ryanofsky]

In commit "doc: fix broken relative md links" (4b9f49d)

This is also updating the flake8 project url, not just changing links to be absolute, so could mention this in the commit message

[maflcko]

ACK 4b9f49d

[ismaelsadeeq]

Re ACK 4b9f49d