Re: [boost] [quickbook] [MPL] Knowing where you are the wrong way

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
http://www.boost.org/libs/mpl/doc/refmanual/terminology.html links
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
back into
http://www.boost.org/libs/mpl/doc/refmanual/refmanual_toc.html 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
> http://tinyurl.com/omouw.

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:
>
> http://www.boost.org/libs/mpl/doc/refmanual/forward-sequence.html#invariants
>
> 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