[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [docbook-apps] semantics of "replaceable" element.
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...
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]