Re: [boost] [quickbook] diagnosing a missing [endsect]?

Subject: Re: [boost] [quickbook] diagnosing a missing [endsect]?
From: Daniel James (dnljms_at_[hidden])
Date: 2017-03-16 01:53:16

On 15 March 2017 at 23:21, Peter Dimov via Boost <boost_at_[hidden]> wrote:
>
> Is it worth diagnosing this problem in some way? We probably can't disallow
> unbalanced sections in an [include], but this could be a warning? (If
> someone pays it any attention, of course.)

There already is a warning if a section isn't closed at the end of any
file which starts with a docinfo block:

$ cd libs/core/doc
$ git checkout 064cfd3d732621bea36733ca3c4e513c83654418^
$ quickbook core.qbk
Generating Output File: core.xml
core.qbk: warning: Missing [endsect] detected at end of file.

Although I imagine it can easily get lost in all the output from boost
build, doxygen and boostbook. Could add an option to make it an error
I suppose.

An include which doesn't have a docinfo block is mostly treated like a
straight textual include, which is why the warning will appear in the
containing file. For [quickbook 1.6] documents, included files with a
docinfo block are treated more like documents in their own right, so
quickbook will warn about unclosed sections in that file.

Tricky thing for boost documentation is that the 'library' element
doesn't allow any children which have quickbook docinfo blocks. In
boostbook sections can have a 'sectioninfo' block, so maybe there
should be a docinfo block for sections (which confusingly would have
to be called something other than 'section'). Or a way of indicating
that a file (or perhaps all files) should be self-contained.

It might be better to rethink how structural elements (book, part,
chapter, library, etc.) and 'section' work so that they're more
consistent.