Re: [Boost-docs] [quickbook] Does import work?

Subject: Re: [Boost-docs] [quickbook] Does import work?
From: Daniel James (dnljms_at_[hidden])
Date: 2011-10-18 18:18:02

On 18 October 2011 04:46, Rene Rivera <grafikrobot_at_[hidden]> wrote:
>
> That seems like a weak excuse to not do something. If the semantics are
> simple and limited it's much easier for people to rely, and work with, those
> semantics.

The semantics of file handling never are never simple.

>> Then when it's
>> enshrined as a feature, someone will want to do a more sophisticated
>> glob, they'll want to control the order or exclude certain files, or
>> who knows what else.
>
> Probably, yes. But I don't think that's a good reason to not do something.
> One of the ideals of quickbook from the start was to provide for the 90% of
> the use cases as simply as possible. And either ignore the other 10%, or to
> make not make it impossible but just painful.
[snip]
> Right.. But it's already done in quickbook. So why would I want to write
> another tool to do it? In contrast to just extending the current tool?

But it isn't. You suggested that it's broken because it doesn't do
what you expect. Which suggests to me that you are the 10% case that
you want to ignore.

> ====boost/predef/version_number.h====
> /*`
> [heading BOOST_VERSION_NUMBER macro]
>
> Blah, blah:
>
> * One
> * Two
>
> */
> ====

That's very easy to implement. Although since you want different
semantics to the existing import you probably shouldn't use the same
syntax.

>>> Also note, I'm not
>>> talking about needing this for a handful of files.. I'm dealing with
>>> documenting dozens of individual files.
>>
>> That sounds like a good reason to use something with good file
>> handling capabilities.
>
> I guess you are saying that the "main" / "only?" reason not to do this is
> that the current quickbook path handling is terribly written? That seems
> like just another bad excuse :-\

Then you guessed wrong. I listed several reasons, and I wasn't talking
about the implementation there. The quickbook *language* doesn't have
good file handling capabilities. And it shouldn't. It isn't a language
for searching directories.

What you want has two phases - the first phase is to gather the
documentation source out of the headers, the second is the
documentation generation phase. These are quite distinct. There's no
good reason to squash them together. That's not a "bad excuse", that's
separation of concerns.

You don't need an excuse to reject a feature, you need a reason to add it.