Boost logo

Boost :

From: David Abrahams (dave_at_[hidden])
Date: 2006-03-22 08:10:14

Joel de Guzman <joel_at_[hidden]> writes:

> David Abrahams wrote:
>> Joel de Guzman <joel_at_[hidden]> writes:
>>>>That's what you have to do, neh? You click once to get to the TOC,
>>>>then you right-click the link at the top of the page.
>>>Tedious and possibly error prone, IMO ;)
>> I should add that it could only be considered tedious and
>> error-prone
>> from the POV of someone who wants to provide a link to the section.
>> For the ordinary browsing user, who wants to see where in the overall
>> outline of the document he is currently, the no-op link is
>> *definitely* tedious: it doesn't do anything! It's also confusing, of
>> course.
>> I think serving the ordinary browsing user is much more important
>> than
>> serving the guy who wants to provide a link to the section, especially
>> if the difference is just one click.
> Not exactly true. In fact it benefits the one who will use the link
> more than the one who does the link. First, let me say that indeed
> the MPL docs, as far as headings are concerned, does it the same
> way as QuickBook.

Then you must be looking at a different set of MPL docs than I am. Or
you're using a different browser, that acts completely differently
from all the browsers I've used. For example, the "Terminology"
heading at links
back to, which
is an entry in the top-level TOC of the refmanual.

The fact that many of the pages are broken up in such a fine-grained
way may make it hard to see that it's doing exactly the same thing as
the other docutils-generated docs, because you don't see the page
scrolled to show the TOC entry right at the top of the screen when the
pages are small. I guess it would be a lot better if the links went
back into rather
than up a level into the fine-grained pages.

> In my other post, I posed a usage scenario. I'll repeat parts of it
> here for reference.
> Anyway, imagine I have a doc that links to the "Invariants" section
> of the MPL doc's "ForwardSequence" concept at

Okay, that link works differently from the other ones I've seen. I
guess I don't understand the logic in use here. Aleksey must have
made some interesting choices when he built the docutils backend that
generates multi-page documents.

> Thanks to the self links of headings in the MPL docs, I can know
> the exact location. For reference it is at:
> AFAICT, there is no way to know that if the heading itself is
> not self linked.

Sure there is. You click the link, which takes you to a page with a
TOC entry that points to the heading. Then you right-click the TOC
entry and copy the link location.

> The only way is to link to the page and say, "ok, please go to
> link and see section Invariants." How
> usable is that? The user will have to search a potentially long
> page for the particular /Invariants/ section. 1) Imagine if the
> page is long. 2) What if there are more than one /Invariants/
> in various sub-sections?

Yes, it's a useful tool. I just think it's worth one more click from
you in order to make the link generally useful for browsing users.

Dave Abrahams
Boost Consulting

Boost list run by bdawes at, gregod at, cpdaniel at, john at