David Abrahams wrote:
Joel de Guzman <[EMAIL PROTECTED]> writes:
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
No, I'm not.
you're using a different browser, that acts completely differently
Firefox and IE.
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.
In those docs, look at a page with multiple headings and click
on the heading. See:
http://www.boost.org/libs/mpl/doc/refmanual/forward-sequence.html
for example. And click on the "Invariants" heading. Those sub-headings
are not even listed in your TOCs.
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.
Whatever he did, IMO is a good thing.
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.
No! Try to get the "Invariants" heading in that page. You
can't. It is not listed in your TOCs to begin with.
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? I'll have to look
carefully. That's what I mean by error prone.
Again, for reference, try: http://tinyurl.com/omouw.
Try getting the link to the /Invariants/ section.
Regards,
--
Joel de Guzman
http://www.boost-consulting.com
http://spirit.sf.net
-------------------------------------------------------
This SF.Net email is sponsored by xPML, a groundbreaking scripting language
that extends applications into web and mobile media. Attend the live webcast
and join the prime developer group breaking into this new coding territory!
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=110944&bid=241720&dat=121642
_______________________________________________
Boost-docs mailing list
[email protected]
Unsubscribe and other administrative requests:
https://lists.sourceforge.net/lists/listinfo/boost-docs
