DOCBOOK: Re: RFE #473365: Allow optional in funcprototype

["Matt G." <matt_g_@hotmail.com>]

Sorry for letting so much time go by, I tend to get behind, on these things.

My apologies, if any of this stuff has changed, since 2.0.4 of TDG (though 
it does claim to accurately reflect DTD version 4.2).


>From: Norman Walsh <ndw@nwalsh.com>
>To: docbook@lists.oasis-open.org
>Subject: DOCBOOK: RFE #473365: Allow optional in funcprototype
>Date: Tue, 21 May 2002 07:24:29 -0400
>
>  <funcprototype>
>  <funcdef>int <function>foo</function></funcdef>
>  <paramdef>int <parameter>bar</parameter></paramdef>
>  <optional>
>  <paramdef>int <parameter>baz</parameter></paramdef>
>  <paramdef>int <parameter>aaa</parameter></paramdef>
>  <optional>
>  <paramdef>int <parameter>bbb</parameter></paramdef>
>  <paramdef>int <parameter>ccc</parameter></paramdef>
>  </optional>
>  </optional>
>  </funcprototype>

I hadn't yet an occasion to use 'funcprototype', but I'm glad to see that 
'type' was recently added to 'paramdef'.  However, isn't a 'funcparam' 
really a special-case of 'type'?  Personally, I'm a bit unclear on why 
'funcparam' even exists.

And what about parameter defaults, such as in C++, XSLT, and Python?  Shall 
I submit an RFE to add some sort of 'defaultval' element, which (ideally, 
with a cardinality of '?', if 'paramdef' weren't mixed) would also be 
included in the content model of 'paramdef'?  Like 'type', 'defaultval' (or 
perhaps just 'default') should be a generic inline element, IMO.  
Personally, I can't see how the lack of a way to formalize default parameter 
values isn't a substantial deficiency, for people attempting to produce API 
documentation for languages with such a feature.  It isn't really accurate 
to try to use 'replaceable', for this purpose (given it's current semantics 
(i.e. that of a meta-syntactic variable), as specified in TDG, anyhow).

While I'm looking at the 'paramdef' content model, I can't help but wonder 
why it includes 'replaceable'.  It's not necessarily inaccurate to describe 
a formal parameter name as replaceable, but it's also not as specific as 
calling it a parameter (with the connotation that one means "formal 
parameter", in the context of a funcprototype).


Thanks for taking the time to consider my opinions.  Please advise me as to 
whether I should proceed with submitting any RFEs.


Sincerely,
Matt Gruenke


_________________________________________________________________
Get your FREE download of MSN Explorer at http://explorer.msn.com/intl.asp.