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

...

...

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.

No! Try to get the "Invariants" heading in that page. You can't. It is not listed in your TOCs to begin with.

I don't have a big problem with self-linking for a heading that isn't in the TOC.

...

...

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.

Even if "Invariants" is listed in your TOC, then you still have a problem. Imagine that you have all your functions doc'd in a section. Imagine all those functions have an "Invariant" subsection. I click the "Invariant" heading, it leads me to the TOC, I find a long list with lots of headings with the same "Invariants" title. Which will I choose?

The one right at the top of the window (unless the page is short, in which case it takes a little care).

I'll have to look carefully. That's what I mean by error prone.

It's only error-prone for the person trying to capture a link to the section header. The person browsing who wants to see the current context doesn't try to grab that link, so there's no error. Maybe the only right way to resolve this in the end is to get Jonathan Turkanis' menu control integrated with BoostBook. -- Dave Abrahams Boost Consulting www.boost-consulting.com