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 replaceablelogin-name/replaceable and such, where if the user types login-name it would not work. Hope that helps. Bob Stayton Sagehill Enterprises b...@sagehill.net -- From: Stefan Seefeld ste...@seefeld.name Sent: Monday, November 05, 2012 6:02 PM To: Richard Hamilton hamil...@xmlpress.net Cc: Bob Stayton b...@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: functionfooreplaceablex/replaceablereplaceabley/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-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
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 replaceablelogin-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: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
Re: [docbook-apps] semantics of replaceable element.
Hi Dick, Thanks for noticing that the comma insertion should be controlled by the 'function.parens' stylesheet param. I made the fix that you suggested to make the comma conditional on that param. By default, the commas will be off now, as they should be. Bob Stayton Sagehill Enterprises b...@sagehill.net -- From: Richard Hamilton hamil...@xmlpress.net Sent: Monday, November 05, 2012 5:37 PM To: Bob Stayton b...@sagehill.net Cc: Stefan Seefeld ste...@seefeld.name; DocBook Apps Mailing List docbook-apps@lists.oasis-open.org Subject: Re: [docbook-apps] semantics of replaceable element. I missed that this only happened when there was a sibling. The example I tried only had one instance of replaceable embedded. When I added a second instance, it worked exactly as Stefan describes. Sorry for any confusion. To complete what I suspect Bob was going to suggest, you can add a template to your customization that removes this behavior (the template below would do the job). I just looked at the stylesheets, and they include a parameter called function.parens, which when set will take input of the following type: functionfooreplaceablex/replaceablereplaceabley/replaceable/function and render it as: foo(x, y). 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. Dick --- XML Press XML for Technical Communicators http://xmlpress.net hamil...@xmlpress.net On Nov 5, 2012, at 5:13 PM, Bob Stayton wrote: I checked the archives, and apparently these templates that add a comma in the context of the function element were added very early in the XSL development, back in 2001. Given the variety of elements that function can contain, including indexterms,and the variety of contexts in which function can appear, including para, does anyone think these generated commas are appropriate? Are there more restricted contexts where they might be appropriate? If we eliminate the generated commas, would that mess up a lot of output? For now, I would suggest that you Bob Stayton Sagehill Enterprises b...@sagehill.net -- From: Stefan Seefeld ste...@seefeld.name Sent: Monday, November 05, 2012 4:05 PM To: Richard Hamilton hamil...@xmlpress.net Cc: DocBook Apps Mailing List docbook-apps@lists.oasis-open.org Subject: Re: [docbook-apps] semantics of replaceable element. On 11/05/2012 06:50 PM, Richard Hamilton wrote: Hi Stefan, I suspect the problem is in your customization. I just tried this with 1.77.1 (PDF and HTML), and there were no commas inserted in the output. Hi Richard, thanks for following up so quickly. I don't yet use a customization for this. Please have a look at either the fo/inline.xsl or html/inline.xsl stylesheets and look for the template matching d:function/d:replaceable. It does indeed add a comma if there is more content after the replaceable element: xsl:template match=d:function/d:replaceable priority=2 xsl:call-template name=inline.italicmonoseq/ xsl:if test=following-sibling::* xsl:text, /xsl:text /xsl:if /xsl:template (In my docs I have things like functionvsip_replaceabled/replaceableclip/function, such that the comma would be inserted between the 'd' and the 'clip'. Stefan -- ...ich hab' noch einen Koffer in Berlin... - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
Re: [docbook-apps] semantics of replaceable element.
Hi Bob, Glad to help. Looking at the rest of this thread, it is interesting that in DB 5, parameter is not allowed in function. I don't see a problem allowing replaceable, but if we want to preserve the usefulness of the function.parens capability, it might be worth considering allowing parameter back in. Can you add a discussion of this question to the agenda for the next TC meeting? Then if the TC thinks we should go forward, I'd be glad to file an RFE. Best regards, Dick --- XML Press XML for Technical Communicators http://xmlpress.net hamil...@xmlpress.net On Nov 6, 2012, at 11:12 AM, Bob Stayton wrote: Hi Dick, Thanks for noticing that the comma insertion should be controlled by the 'function.parens' stylesheet param. I made the fix that you suggested to make the comma conditional on that param. By default, the commas will be off now, as they should be. Bob Stayton Sagehill Enterprises b...@sagehill.net -- From: Richard Hamilton hamil...@xmlpress.net Sent: Monday, November 05, 2012 5:37 PM To: Bob Stayton b...@sagehill.net Cc: Stefan Seefeld ste...@seefeld.name; DocBook Apps Mailing List docbook-apps@lists.oasis-open.org Subject: Re: [docbook-apps] semantics of replaceable element. I missed that this only happened when there was a sibling. The example I tried only had one instance of replaceable embedded. When I added a second instance, it worked exactly as Stefan describes. Sorry for any confusion. To complete what I suspect Bob was going to suggest, you can add a template to your customization that removes this behavior (the template below would do the job). I just looked at the stylesheets, and they include a parameter called function.parens, which when set will take input of the following type: functionfooreplaceablex/replaceablereplaceabley/replaceable/function and render it as: foo(x, y). 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. Dick --- XML Press XML for Technical Communicators http://xmlpress.net hamil...@xmlpress.net On Nov 5, 2012, at 5:13 PM, Bob Stayton wrote: I checked the archives, and apparently these templates that add a comma in the context of the function element were added very early in the XSL development, back in 2001. Given the variety of elements that function can contain, including indexterms,and the variety of contexts in which function can appear, including para, does anyone think these generated commas are appropriate? Are there more restricted contexts where they might be appropriate? If we eliminate the generated commas, would that mess up a lot of output? For now, I would suggest that you Bob Stayton Sagehill Enterprises b...@sagehill.net -- From: Stefan Seefeld ste...@seefeld.name Sent: Monday, November 05, 2012 4:05 PM To: Richard Hamilton hamil...@xmlpress.net Cc: DocBook Apps Mailing List docbook-apps@lists.oasis-open.org Subject: Re: [docbook-apps] semantics of replaceable element. On 11/05/2012 06:50 PM, Richard Hamilton wrote: Hi Stefan, I suspect the problem is in your customization. I just tried this with 1.77.1 (PDF and HTML), and there were no commas inserted in the output. Hi Richard, thanks for following up so quickly. I don't yet use a customization for this. Please have a look at either the fo/inline.xsl or html/inline.xsl stylesheets and look for the template matching d:function/d:replaceable. It does indeed add a comma if there is more content after the replaceable element: xsl:template match=d:function/d:replaceable priority=2 xsl:call-template name=inline.italicmonoseq/ xsl:if test=following-sibling::* xsl:text, /xsl:text /xsl:if /xsl:template (In my docs I have things like functionvsip_replaceabled/replaceableclip/function, such that the comma would be inserted between the 'd' and the 'clip'. Stefan -- ...ich hab' noch einen Koffer in Berlin... - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
[docbook-apps] semantics of replaceable element.
Hello, I'm writing an API documentation for generic C code, where certain tokens in a given (function) name are to be substituted to map the name to a real function name. For example, I'm using functioncompute_replaceablet/replaceable/function to stand for a set of functions compute_f, compute_d, compute_i, etc. It even happens that certain names contain multiple such replaceable parameters. However, the stylesheets at present inject commas, which makes it impossible to have replaceable tags in the middle of a name. I'm reading http://docbook.org/tdg/en/html/replaceable.html but it doesn't suggest anything that would justify such a comma injection. What is the use-case for this ? Am I using replaceable wrongly ? (I can of course customize the template matching d:function/d:replaceable, but it still seems I'm missing something. Any help would be appreciated. Thanks, Stefan -- ...ich hab' noch einen Koffer in Berlin... - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
Re: [docbook-apps] semantics of replaceable element.
Hi Stefan, I suspect the problem is in your customization. I just tried this with 1.77.1 (PDF and HTML), and there were no commas inserted in the output. Best Regards, Dick --- XML Press XML for Technical Communicators http://xmlpress.net hamil...@xmlpress.net On Nov 5, 2012, at 2:42 PM, Stefan Seefeld wrote: Hello, I'm writing an API documentation for generic C code, where certain tokens in a given (function) name are to be substituted to map the name to a real function name. For example, I'm using functioncompute_replaceablet/replaceable/function to stand for a set of functions compute_f, compute_d, compute_i, etc. It even happens that certain names contain multiple such replaceable parameters. However, the stylesheets at present inject commas, which makes it impossible to have replaceable tags in the middle of a name. I'm reading http://docbook.org/tdg/en/html/replaceable.html but it doesn't suggest anything that would justify such a comma injection. What is the use-case for this ? Am I using replaceable wrongly ? (I can of course customize the template matching d:function/d:replaceable, but it still seems I'm missing something. Any help would be appreciated. Thanks, Stefan -- ...ich hab' noch einen Koffer in Berlin... - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
Re: [docbook-apps] semantics of replaceable element.
On 11/05/2012 06:50 PM, Richard Hamilton wrote: Hi Stefan, I suspect the problem is in your customization. I just tried this with 1.77.1 (PDF and HTML), and there were no commas inserted in the output. Hi Richard, thanks for following up so quickly. I don't yet use a customization for this. Please have a look at either the fo/inline.xsl or html/inline.xsl stylesheets and look for the template matching d:function/d:replaceable. It does indeed add a comma if there is more content after the replaceable element: xsl:template match=d:function/d:replaceable priority=2 xsl:call-template name=inline.italicmonoseq/ xsl:if test=following-sibling::* xsl:text, /xsl:text /xsl:if /xsl:template (In my docs I have things like functionvsip_replaceabled/replaceableclip/function, such that the comma would be inserted between the 'd' and the 'clip'. Stefan -- ...ich hab' noch einen Koffer in Berlin... - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
Re: [docbook-apps] semantics of replaceable element.
I checked the archives, and apparently these templates that add a comma in the context of the function element were added very early in the XSL development, back in 2001. Given the variety of elements that function can contain, including indexterms,and the variety of contexts in which function can appear, including para, does anyone think these generated commas are appropriate? Are there more restricted contexts where they might be appropriate? If we eliminate the generated commas, would that mess up a lot of output? For now, I would suggest that you Bob Stayton Sagehill Enterprises b...@sagehill.net -- From: Stefan Seefeld ste...@seefeld.name Sent: Monday, November 05, 2012 4:05 PM To: Richard Hamilton hamil...@xmlpress.net Cc: DocBook Apps Mailing List docbook-apps@lists.oasis-open.org Subject: Re: [docbook-apps] semantics of replaceable element. On 11/05/2012 06:50 PM, Richard Hamilton wrote: Hi Stefan, I suspect the problem is in your customization. I just tried this with 1.77.1 (PDF and HTML), and there were no commas inserted in the output. Hi Richard, thanks for following up so quickly. I don't yet use a customization for this. Please have a look at either the fo/inline.xsl or html/inline.xsl stylesheets and look for the template matching d:function/d:replaceable. It does indeed add a comma if there is more content after the replaceable element: xsl:template match=d:function/d:replaceable priority=2 xsl:call-template name=inline.italicmonoseq/ xsl:if test=following-sibling::* xsl:text, /xsl:text /xsl:if /xsl:template (In my docs I have things like functionvsip_replaceabled/replaceableclip/function, such that the comma would be inserted between the 'd' and the 'clip'. Stefan -- ...ich hab' noch einen Koffer in Berlin... - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
Re: [docbook-apps] semantics of replaceable element.
I missed that this only happened when there was a sibling. The example I tried only had one instance of replaceable embedded. When I added a second instance, it worked exactly as Stefan describes. Sorry for any confusion. To complete what I suspect Bob was going to suggest, you can add a template to your customization that removes this behavior (the template below would do the job). I just looked at the stylesheets, and they include a parameter called function.parens, which when set will take input of the following type: functionfooreplaceablex/replaceablereplaceabley/replaceable/function and render it as: foo(x, y). 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. Dick --- XML Press XML for Technical Communicators http://xmlpress.net hamil...@xmlpress.net On Nov 5, 2012, at 5:13 PM, Bob Stayton wrote: I checked the archives, and apparently these templates that add a comma in the context of the function element were added very early in the XSL development, back in 2001. Given the variety of elements that function can contain, including indexterms,and the variety of contexts in which function can appear, including para, does anyone think these generated commas are appropriate? Are there more restricted contexts where they might be appropriate? If we eliminate the generated commas, would that mess up a lot of output? For now, I would suggest that you Bob Stayton Sagehill Enterprises b...@sagehill.net -- From: Stefan Seefeld ste...@seefeld.name Sent: Monday, November 05, 2012 4:05 PM To: Richard Hamilton hamil...@xmlpress.net Cc: DocBook Apps Mailing List docbook-apps@lists.oasis-open.org Subject: Re: [docbook-apps] semantics of replaceable element. On 11/05/2012 06:50 PM, Richard Hamilton wrote: Hi Stefan, I suspect the problem is in your customization. I just tried this with 1.77.1 (PDF and HTML), and there were no commas inserted in the output. Hi Richard, thanks for following up so quickly. I don't yet use a customization for this. Please have a look at either the fo/inline.xsl or html/inline.xsl stylesheets and look for the template matching d:function/d:replaceable. It does indeed add a comma if there is more content after the replaceable element: xsl:template match=d:function/d:replaceable priority=2 xsl:call-template name=inline.italicmonoseq/ xsl:if test=following-sibling::* xsl:text, /xsl:text /xsl:if /xsl:template (In my docs I have things like functionvsip_replaceabled/replaceableclip/function, such that the comma would be inserted between the 'd' and the 'clip'. Stefan -- ...ich hab' noch einen Koffer in Berlin... - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
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: functionfooreplaceablex/replaceablereplaceabley/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-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
