[build] Broken doc links

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

[build] Broken doc links

Boost - Dev mailing list
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.)


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [build] Broken doc links

Boost - Dev mailing list
On 10 April 2018 at 06:27, Gavin Lambert via Boost
<[hidden email]> wrote:
> 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.

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [build] Broken doc links

Boost - Dev mailing list
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.


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost