On 11/06/2012 01:54 PM, Bob Stayton wrote:
>> According to http://docbook.org/tdg/en/html/parameter.html parameter is
>> allowed inside function.
>
> More research shows that parameter is allowed in function DocBook 4,
> but not DocBook 5. In DocBook 4, function could contain all kinds of
> elements, and it was apparently used to present function syntax as
> well, based on that early stylesheet template.
>
> It seems that the elements for documenting function syntax were
> changed significantly in DocBook 5. To show the syntax of a function
> in DocBook 5, you should use funcsynopsis. The function element itself
> is now only used to name a function, typically inline, so that is why
> parameter is no longer allowed in function.
Right, that's exactly how I use the markup. Thanks for confirming that.
>
> Regarding the semantics of replaceable, I use it when I need to
> indicate user input in which the text that is shown would not make
> sense if used literally. So I don't think it would be used for
> function parameters, which do make sense as variables in an
> expression. I would use it for <replaceable>login-name</replaceable>
> and such, where if the user types "login-name" it would not work. Hope
> that helps.
That all sounds good to me. Thanks.
I'm still rather uneasy with the stylesheet's attempt to synthesize
language-specific syntax with all the synopsis markup elements. But that
really is an entirely separate discussion. (And a while ago we have
worked on an extension vocabulary to add proper support for modeling (at
least C and C++).
So, I think it would be best if <replaceable> would not attempt to
synthesize programming-language syntax. But the solution to
conditionalize that behavior based on an attribute setting also sounds
like a good fix.
Thanks,
Stefan
--
...ich hab' noch einen Koffer in Berlin...
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
