Re: [Boost-docs] Quickbook documentation

Subject: Re: [Boost-docs] Quickbook documentation
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2008-12-08 17:42:43

> -----Original Message-----
> From: boost-docs-bounces_at_[hidden] [mailto:boost-docs-
> bounces_at_[hidden]] On Behalf Of John Maddock
> Sent: 08 December 2008 12:15
> To: Discussion of Boost Documentation
> Subject: Re: [Boost-docs] Quickbook documentation
> 
> Vladimir Prus wrote:
> >> I'm reading Quickbook documentation, and see this under:
> >> "Heading 6":
> >>
> >>
> >> [link section_id.normalized_header_text The link text]
> >>
> >> and cannot understand it. What is "normalized_header_text", and why
> >> do I need that if I want just to refer to a section name?
> 
> OK, to refer to a section you need it's ID in the Docbook markup - the
> easiest way to do that IMO is to generate the HTML docs and then navigate
to
> the section you want to link to and copy it's URL, so for example:
> 
> http://www.boost.org/doc/tools/build/doc/html/bbv2/tasks/alias.html
> 
> would have the section ID:
> 
> "bbv2.tasks.alias".
> 
> But otherwise...
> 
> Quickbook generates nested section ID's:
> 
> section1.nested1.nested2
> 
> for nested sections, and each part of the name is either:
> 
> * The name you gave the section if you used [section:myname My Title].
> * The section title with whitespace replaced with "_" if you used [section
> My Title].

Can I just add that this means that it is a really good idea to always give
section title IDs - or you may end up with section id that
_are_a_very_long_section_id_name_indeed!

As I reader and editor, I have also found it very useful to add a comment to
the end of the section when you create the section, by copying and pasting
and converting to a comment with a /

[section_1 section 1
....
] [/end section_1 section 1] 

This avoids puzzling about the nesting afterwards (QuickBook doesn't give
too much help if you mismatch them).

And don't forget a Boost licence as a comment at the end of each and every
file - or a nag will come round later.

Paul

---
Paul A. Bristow
Prizet Farmhouse
Kendal, UK   LA8 8AB
[phone], mobile [phone]
pbristow_at_[hidden]