Joel de Guzman <joel@boost-consulting.com> writes:

David Abrahams wrote:

...

Joel de Guzman <joel@boost-consulting.com> 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