Re: [docbook-apps] semantics of "replaceable" element.

[Stefan Seefeld <stefan@seefeld.name>]

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