[Boost-bugs] [Boost C++ Libraries] #2701: Quickbook docs on internal link may be misleading

Subject: [Boost-bugs] [Boost C++ Libraries] #2701: Quickbook docs on internal link may be misleading
From: Boost C++ Libraries (noreply_at_[hidden])
Date: 2009-01-30 16:57:44

#2701: Quickbook docs on internal link may be misleading
------------------------------------+---------------------------------------
 Reporter:  pbristow                |       Owner:  eric_niebler
     Type:  Feature Requests        |      Status:  new         
Milestone:  Boost 1.39.0            |   Component:  quickbook   
  Version:  Boost 1.37.0            |    Severity:  Cosmetic    
 Keywords:  Quickbook link article  |  
------------------------------------+---------------------------------------
 The Quickbook docs on the really, really useful Anchor links says

 You can link within a document using:

 [link section_id.normalized_header_text The link text]

 But don't you have to include the article name, in this case 'quickbook'?

 as in

 [def __comments__   [link quickbook.syntax.comments Comments]]

 I read the docs that you only need syntax.comments.

 (I also note that the article name is actually always converted using the
 section rules, inserting _ to create a name but I don't se where this is
 explained.

 I assumed (the cause of many foulups) that I could use the section syntax
 thus to choose my own name:

 article My Book One - The Big Picture Manual : mybook1

 This didn't seem to work - perhaps by design - but it might be useful to
 avoid really long names like my_book_one_-_the_big_ picture_manual.

 It might also be helpful to tell people to look at the log file produced
 by Quickbook to find the full link address - it can get difficult when
 nested many sections deep.

 (A brilliant tool, especially with Doxygenation!)

-- 
Ticket URL: <https://svn.boost.org/trac/boost/ticket/2701>
Boost C++ Libraries <http://www.boost.org/>
Boost provides free peer-reviewed portable C++ source libraries.