Re: [Boost-build] [docs]multiple tokened formal args not documented properly

From: Larry Evans (cppljevans_at_[hidden])
Date: 2007-09-15 12:15:53

On 09/12/07 07:33, Larry Evans wrote:
> The page:
> 
> http://www.boost.org/boost-build2/doc/html/jam/language.html#jam.language.rules.argument_lists
> 
> contains:
> 
>    Each name in a list of formal arguments (separated by ":" in the rule
>    declaration) is bound to a single element of the corresponding actual
>    argument unless followed by one of these modifiers:
> 
> however, the example on same page:
> 
>    rule report ( pronoun index ? : state : names + )
> 
> contains apparently 2, not 1, formal argument names (i.e. pronoun and
> index) which are bound to *subparts* of the 1st actual argument.  Of 
> course if you define "name" as "1 or more white space delimited tokens"
> then the first name would be "pronoun index" and the above sentence
> would be true; however, that's not the natural interpretation of "name";
> hence, I believe this sentence should be modified to account for
> multiple formal argument names being bound to subparts of the actual
> argument.

A solution to this problem is modifying:

   http://www.boost.org/boost-build2/doc/html/jam/language.html

as shown in boost-vault/boost_docs/language.html.  The rcsdiff
is shown below:

*** language.html	2007/09/15 14:39:07	1.1
--- language.html	2007/09/15 16:04:53
***************
*** 264,274 ****
   report I 2 : sorry : Joe Dave Pete ;
   </pre>
   <p>
!           Each name in a list of formal arguments (separated by "<code 
class="literal">:</code>"
!           in the rule declaration) is bound to a single element of the 
corresponding
!           actual argument unless followed by one of these modifiers:
           </p>
! <div class="informaltable"><table class="table">
   <colgroup>
   <col>
   <col>
--- 264,293 ----
   report I 2 : sorry : Joe Dave Pete ;
   </pre>
   <p>
!           The <code>formal-argument-list</code> of a rule declaration
!           is composed of 0 or more
!           <code>formal-argument-pattern</code>'s separated by "<code
!           class="literal">:</code>". Each
!           <code>formal-argument-pattern</code> is composed of a list of
!           0 or more <code>formal-argument-name</code>'s, the last of
!           which maybe be followed by a
!           <code>last-name-suffix-symbol</code> from table, <a
!           href="last-name-symbols">
!           last name suffix symbols</a>.
!           Each <code>formal-argument-name</code> in a
!           <code>formal-argument-pattern</code> is bound to a single
!           element of the corresponding actual argument (actual
!           arguments are a list of 0 or more "elements" delimited by
!           whitespace) except if the last <code>formal-argument-name</code>
!           is followed by a
!           <code>last-name-suffix-symbol</code> from table, <a
!           href="last-name-symbols">last name suffix symbols</a>.  In this
!           case, the last name binding is described by the 2nd column
!           of the table.
!
           </p>
! <div class="informaltable"><table class="table" id="last-name-symbols">
! <caption>last name suffix symbols</caption>
   <colgroup>
   <col>
   <col>
***************
*** 281,287 ****
                   </th>
   <th>
                   <p>
!                   Semantics of preceding symbol
                   </p>
                   </th>
   </tr></thead>
--- 300,306 ----
                   </th>
   <th>
                   <p>
!                   Semantics of preceding name
                   </p>
                   </th>
   </tr></thead>