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

Subject: Re: [Boost-docs] [quickbook] Does import work?
From: Rene Rivera (grafikrobot_at_[hidden])
Date: 2011-10-19 04:02:44

On 10/18/2011 1:18 PM, Daniel James wrote:
> 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.

Is that from an implementation or usability point of view? Because I 
might agree in the former, but not in the latter in this case.

>>> 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.

I don't think I suggested that. I merely asked if it was working as I 
was attempting to use it. I asked because I wanted to do this particular 
documentation task and I read the Quickbook documentation. It seemed 
unclear from the documentation, IMO, if what I wanted was the way it 
should be. So I asked for clarification.

If quickbook had given me an error about the my stupidly inferring that 
this was possible, my initial email about this would certainly have been 
different.

>> ====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.

If you define the semantics as what's implemented yes ;-) But if one 
defines it as what might be expected from the word "import" and the 
current documentation, one would get the impression (as I did to some 
extent) that it was already part of the semantics. But I'd gladly add a 
different keyword and figure out how to shoehorn it into quickbook while 
trying to to totally duplicate the source code parsing code.

>>>> 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.

OK, but semantically the language already does "file searching" even if 
only a singular matched, or not matched, file at a time.

> 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.

It seems that your sentiment runs counter to the Literate Programming 
ideals. Or maybe I don't understand the two parts you are referring to.

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

OK, good point. And I think I already stated my reasons for adding it. 
Which as Dave pointed out fall within the Literate Programming ideals.

-- 
-- Grafik - Don't Assume Anything
-- Redshift Software, Inc. - http://redshift-software.com
-- rrivera/acm.org (msn) - grafik/redshift-software.com
-- 102708583/icq - grafikrobot/aim,yahoo,skype,efnet,gmail