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

["Bob Stayton" <bobs@sagehill.net>]

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

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.

Bob Stayton
Sagehill Enterprises
bobs@sagehill.net

--------------------------------------------------
From: "Stefan Seefeld" <stefan@seefeld.name>
Sent: Monday, November 05, 2012 6:02 PM
To: "Richard Hamilton" <hamilton@xmlpress.net>
Cc: "Bob Stayton" <bobs@sagehill.net>; "DocBook Apps Mailing List" 
<docbook-apps@lists.oasis-open.org>
Subject: Re: [docbook-apps] semantics of "replaceable" element.

> On 11/05/2012 08:37 PM, Richard Hamilton wrote:
> > I just looked at the stylesheets, and they include a parameter called 
> > function.parens, which when set will take input of the following type:
> >
> > <function>foo<replaceable>x</replaceable><replaceable>y</replaceable></function>
> > and render it as: foo(x, y).
>
> I see. But isn't that the wrong markup for this desired output ?
> Shouldn't that use <parameter> instead of <replaceable> ?
>
> > The problem seems to be that the template for d:function checks this 
> > parameter, but the template for d:function/d:replaceable (and 
> > d:function/d:parameter) doesn't . The result when function.parens is set 
> > to 0 is inconsistent.
> >
> > I think the following change would fix the problem for Stefan, and leave 
> > the capability in for anyone who wants to use function.parens:
> >
> > <xsl:template match="d:function/d:replaceable" priority="2">
> >   <xsl:call-template name="inline.italicmonoseq"/>
> >   <xsl:if test="$function.parens != '0' and following-sibling::*">  <!--  
> > here is the changed line -->
> >     <xsl:text>, </xsl:text>
> >   </xsl:if>
> > </xsl:template>
> >
> > You'd need to do the same with d:function/d:parameter, too, though it 
> > appears that parameter is not allowed inside function, so it may be a 
> > moot point.
>
> According to http://docbook.org/tdg/en/html/parameter.html parameter is
> allowed inside function.
>
> But no matter what, it seems that these two usages of <replaceable> are
> radically different, which seems to suggest that I still don't fully
> grasp what a "replaceable" represents.
>
> Thanks,
>        Stefan
>
> --
>
>      ...ich hab' noch einen Koffer in Berlin...
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org