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
>> 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
>> I think serving the ordinary browsing user is much more important
>> 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"
back to http://www.boost.org/libs/mpl/doc/refmanual.html#id529, 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
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 http://tinyurl.com/omouw 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 www.boost-consulting.com