OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

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

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

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:

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>

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.



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

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]