Boost logo

Boost-Build :

From: David Abrahams (dave_at_[hidden])
Date: 2006-02-04 15:02:10


Rene Rivera <grafik.list_at_[hidden]> writes:

> David Abrahams wrote:
>> Rene Rivera <grafik.list_at_[hidden]> writes:
>>
>>> I just checked in the changes I talked about earlier with regards to
>>> adding options to the SHELL/COMMAND builtin. In the process I also added
>>> to the EXIT builtin the ability to specify a result value to exit with.
>>> I needed it to be able to implement a very minimal unit test facility
>>> for testing the SHELL changes. QuickBook documentation for both is also
>>> updated:
>>>
>>> [pre
>>> rule EXIT ( /message/ * : /result-value/ ? )
>>> ]
>>
>>
>> Nitty:
>> I'm not sure you should italicize parameter names; it's just bjam
>> code. If you meant for them to be replaceable it would be
>>
>> [pre
>> EXIT ( [~message] : [~result-value] )
>> ]
>>
>> or something, but then you wouldn't be writing it as a rule
>> declaration.
>
> Well; First, the [~] replaceable just got added today and the docs got
> written a few days ago.

There's always escaping to BoostBook... when it works ;-)

> Second, I want to use the rule syntax to be as
> clear as possible since that's the syntax we explain further up in the
> docs.

Sure.

> I'm using the italics so that it matches the same text in the
> explanation. But I don't really care what style is actually used, just
> that it be the same in both context, and different within both
> context.

> _Suggestions welcome_ Underline? Bold/emphasis? Do we have other
> choices? How are replaceables styled?

As italic, which is why I thought it might be confusing with the
replaceable text. On the other hand, typically replaceable text is
not rendered in a monospace font, so maybe it'll be fine.

My point is that replaceable text should be used in a context that
looks like a /usage/ example. When writing a declaration, you should
use some distinct formatting.

>>> Blurts out the /message/ to stdout and then exits with a failure status
>>> if no /result-value/ is given, otherwise it exits with the given
>>> /result-value/.
>>>
>>> "=Echo=", "=echo=", "=Exit=", and "=exit=" are accepted as aliases for
>>> =ECHO= and =EXIT=, since it is hard to tell that these are built-in
>>> rules and not part of the language, like "=include=".
>>
>> Wouldn't that same logic hold for every builtin rule? Why are these
>> special?
>
> Hmm, good question. I don't have an answer, and the Perforce original
> authors are not likely to answer even if we asked. I remember you
> mentioning something about the builtin Jambase use Camel-Case for
> rules.

Yup. And all the truly builtin rules are UPPERCASE.

> So if that's the case then I can maybe see devoting lower-case to
> keywords, Camel-Case to rules, and UPPER-CASE to builtin rules. Not that
> I would endorse such use of syntax for the simple reason of
> distinguishing types of items. i.e. I'm not an LPCSTR kinda person
> ;-)

Me neither. It just doesn't seem worth wasting code, or explanation,
on circumventing the convention in this case.

>
>>> [pre
>>> rule SHELL ( /command/ : * )
>>> ]
>>>
>>> =SHELL= executes /command/, and then returns the standard output of
>>> /command/. =SHELL= only works on platforms with a =popen()= function in
>>> the C library. On platforms without a working =popen()= function,
>>> =SHELL= is implemented as a no-op. =SHELL= works on Unix, MacOS X, and
>>> most Windows compilers. =SHELL= is a no-op on Metrowerks compilers under
>>> Windows. There is a variable set of allowed options as additional arguments:
>>>
>>> [variablelist
>>> [[=exit-status=] [In addition to the output the result status of
>>> the executed command is returned as a second element of the result.]]
>>> [[=no-output=] [Don't capture the output of the command. Instead an
>>> empty ("") string value is returned in place of the output.]]
>>> ]
>>>
>>> Because the Perforce/Jambase defines a =Shell= rule which hides the
>>> builtin
>>
>> Why would it? Jam is case sensitive.
>
> Hm, another good question :-) Truthfully I added the COMMAND alias when
> a user complained about not being able to access the builtin through the
> SHELL name. So I'm not sure where the other name came from. I wrote the
> above from old memories :-\
>
> Perhaps that user is watching and can volunteer a rational.

Seems to me that the explanation just complicates the doc, which makes
the feature harmful on the whole.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com

Boost-Build list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk