[build] Broken doc links
Prompted by the thread "Toolset version for Visual Studio 2017 15.6.3" over in the user list, I was looking through some Boost.Build documentation when I found some dead links and other weirdness. Boost.Build's github page links to https://www.boost.org/build/, which appears to be fully working. On https://www.boost.org/doc/libs/1_66_0/more/getting_started/windows.html, under "5.2.1 Install Boost.Build" it links to https://www.boost.org/doc/libs/1_66_0/tools/build/index.html, which appears to be a versioned clone of the above. But at that page, the "Documentation" link points at https://www.boost.org/doc/libs/1_66_0/tools/build/doc/html/index.html, which 404s. Back in "Getting Started", in "5.2.2 Identify Your Toolset" it first links directly to https://www.boost.org/build/doc/html/bbv2/reference/tools.html (which is now an unversioned link, but does work), and then to https://www.boost.org/doc/libs/1_66_0/doc/html/bbv2/installation.html (which is a versioned link that also works). So it's not very consistent. Putting these things together, it looks like the "right" root page for the versioned documentation should be https://www.boost.org/doc/libs/1_66_0/doc/html/bbv2.html, although that lacks some user-friendliness. (And it also links to https://www.boost.org/boost-build2 for yet another URL variation... although that does redirect to https://www.boost.org/build/ at least.)
On 10 April 2018 at 06:27, Gavin Lambert via Boost
Prompted by the thread "Toolset version for Visual Studio 2017 15.6.3" over in the user list, I was looking through some Boost.Build documentation when I found some dead links and other weirdness.
Boost.Build's github page links to https://www.boost.org/build/, which appears to be fully working.
That's a copy of the website branch from git, which hasn't been updated for a while. It probably should be?
On https://www.boost.org/doc/libs/1_66_0/more/getting_started/windows.html, under "5.2.1 Install Boost.Build" it links to https://www.boost.org/doc/libs/1_66_0/tools/build/index.html, which appears to be a versioned clone of the above.
But at that page, the "Documentation" link points at https://www.boost.org/doc/libs/1_66_0/tools/build/doc/html/index.html, which 404s.
As the getting started guide is part of the boost release, it links to the documentation from the release (as you might be viewing it offline). It's actually a relative link, but it gets resolved to a link with a version number. The build documentation page links to the location of documentation build standalone, but build is part of the combined boost documentation. I've added a redirect to the website so the link works there now, although it won't in an offline copy, so that will need to fixed (either by changing the build or by fixing the link).
Back in "Getting Started", in "5.2.2 Identify Your Toolset" it first links directly to https://www.boost.org/build/doc/html/bbv2/reference/tools.html (which is now an unversioned link, but does work), and then to https://www.boost.org/doc/libs/1_66_0/doc/html/bbv2/installation.html (which is a versioned link that also works).
I think the 'unversioned link' is meant to be a link to the most up to date info from the website. The 'versioned link' is a link to the local copy of the documentation. [snip]
(And it also links to https://www.boost.org/boost-build2 for yet another URL variation... although that does redirect to https://www.boost.org/build/ at least.)
That's the old location. It's nice to update them, but the redirect means the the link still works.
On 10/04/2018 20:28, Daniel James wrote:
Back in "Getting Started", in "5.2.2 Identify Your Toolset" it first links directly to https://www.boost.org/build/doc/html/bbv2/reference/tools.html (which is now an unversioned link, but does work), and then to https://www.boost.org/doc/libs/1_66_0/doc/html/bbv2/installation.html (which is a versioned link that also works).
I think the 'unversioned link' is meant to be a link to the most up to date info from the website. The 'versioned link' is a link to the local copy of the documentation.
Ok, it almost makes sense at that spot (although as noted in the other thread, the "up-to-date list" isn't) -- having said that, I question the relevance of knowing that a version of b2 that you don't have yet (if you're using an older Boost build) supports a compiler that you want to use; so I would argue that a versioned link makes more sense there. Further down, under "5.2.4 Invoke b2" it has the same unversioned link, and it definitely doesn't make sense for that to be unversioned. It's telling you where to go to look at the command line options for b2, which ought to be the version of Boost and b2 that you actually have -- especially if you're reading it offline.
participants (2)
-
Daniel James -
Gavin Lambert