From: SourceForge.net <noreply@so...>  20091031 02:47:37

Bugs item #2889817, was opened at 20091031 02:47 Message generated for change (Tracker Item Submitted) made by kbr You can respond by visiting: https://sourceforge.net/tracker/?func=detail&atid=373747&aid=2889817&group_id=21935 Please note that this message will contain a full copy of the comment thread, including the initial issue submission, for this request, not just the latest update. Category: XSL Group: output: HTML Status: Open Resolution: None Priority: 5 Private: No Submitted By: Kai Brommann (kbr) Assigned to: Nobody/Anonymous (nobody) Summary: informalequation in toe and numbering Initial Comment: TDGV0.0.25 for V5.0 states for the equation element: [Processing systems that number equations or build a table of equations at the beginning of a document may have difficulty correctly formatting documents that contain both equations with titles and equations without titles. You are advised to use informalequation for equations without titles.] Assuming this caveat doesn't say that such difficulty is a feature and not a bug, here is a detailed description of the problem: Informalequation doesn't have a title, so probably it makes no sense to have it included in the table of equations, instead only equations (which should have a title as quoted above, the title may be optional rather than required according to TDG nevertheless) are to be listed there. Otherwise the result is an empty row in the table of equations. More generally speaking, every time an informal equation is linked to, it should not be tried to include its title while linking, because it has not title. Perhaps it could be fixed by some customization layer, but if it's a bug it better should be fixed in the stylesheets directly. Directly related is the question of numbering, let's say you have in the same chapter equation1 with title1 equation2 with title2 informalequation1 informalequation2 informalequation3 then the numbering (displayed together with the respective element) should go as follows: Equation 1. Title1 Equation 2. Title2 (1) (2) (3) so equation and informalequation should have separate counters, and the equation is accompanied with the term Equation and its title (same as table and figure), while the informalequation should only have its number in parentheses or the like. The current (buggy) behaviour is: Equation 1. Title1 Equation 2. Title2 Equation 2. Equation 2. Equation 2. so for informalequations the counter of the equations is reused as well (but not incremented on the other hand), and the notexisting title is of course empty, so should not be tried to be displayed. Instead, while linking, the two types can easily be distinguished, the desired behaviour would process the input (see ...) as: (see Equation 1.Title1) versus (see (1)) For an actual example how it should be done, you can also see the dblatex tool please where it is done properly for pdf. Thanx for your effort. (no error messages, Xalan2.7.1 and docbookxslns1.75.2/xhtml1_1/chunk.xsl toolchain, no test document necessary, no customization layer)  You can respond by visiting: https://sourceforge.net/tracker/?func=detail&atid=373747&aid=2889817&group_id=21935 
From: SourceForge.net <noreply@so...>  20091113 09:07:03

Bugs item #2889817, was opened at 20091030 19:47 Message generated for change (Comment added) made by bobstayton You can respond by visiting: https://sourceforge.net/tracker/?func=detail&atid=373747&aid=2889817&group_id=21935 Please note that this message will contain a full copy of the comment thread, including the initial issue submission, for this request, not just the latest update. Category: XSL Group: output: HTML Status: Open Resolution: None Priority: 5 Private: No Submitted By: Kai Brommann (kbr) Assigned to: Nobody/Anonymous (nobody) Summary: informalequation in toe and numbering Initial Comment: TDGV0.0.25 for V5.0 states for the equation element: [Processing systems that number equations or build a table of equations at the beginning of a document may have difficulty correctly formatting documents that contain both equations with titles and equations without titles. You are advised to use informalequation for equations without titles.] Assuming this caveat doesn't say that such difficulty is a feature and not a bug, here is a detailed description of the problem: Informalequation doesn't have a title, so probably it makes no sense to have it included in the table of equations, instead only equations (which should have a title as quoted above, the title may be optional rather than required according to TDG nevertheless) are to be listed there. Otherwise the result is an empty row in the table of equations. More generally speaking, every time an informal equation is linked to, it should not be tried to include its title while linking, because it has not title. Perhaps it could be fixed by some customization layer, but if it's a bug it better should be fixed in the stylesheets directly. Directly related is the question of numbering, let's say you have in the same chapter equation1 with title1 equation2 with title2 informalequation1 informalequation2 informalequation3 then the numbering (displayed together with the respective element) should go as follows: Equation 1. Title1 Equation 2. Title2 (1) (2) (3) so equation and informalequation should have separate counters, and the equation is accompanied with the term Equation and its title (same as table and figure), while the informalequation should only have its number in parentheses or the like. The current (buggy) behaviour is: Equation 1. Title1 Equation 2. Title2 Equation 2. Equation 2. Equation 2. so for informalequations the counter of the equations is reused as well (but not incremented on the other hand), and the notexisting title is of course empty, so should not be tried to be displayed. Instead, while linking, the two types can easily be distinguished, the desired behaviour would process the input (see ...) as: (see Equation 1.Title1) versus (see (1)) For an actual example how it should be done, you can also see the dblatex tool please where it is done properly for pdf. Thanx for your effort. (no error messages, Xalan2.7.1 and docbookxslns1.75.2/xhtml1_1/chunk.xsl toolchain, no test document necessary, no customization layer)  >Comment By: Robert Stayton (bobstayton) Date: 20091113 01:07 Message: I would propose the following: a) equation elements are numbered, and informalequations are not. Use informalequation when no reference is to be made to the equation. This makes informalequation parallel with informaltable, informalfigure, etc. b) Include only equation elements in the List of Equations. If an equation has no title, then only the number is displayed with the page number. Currently only equations with titles appear in the TOC. c) Number all equation elements, whether they have a title or not. d) Add a stylesheet parameter to select the style of equation numbering. One style says "Equation 3.2. Optional title", placed above or below the equation. The other style uses "(3.2)" beside the equation, with the optional title above or below it (with no number).  You can respond by visiting: https://sourceforge.net/tracker/?func=detail&atid=373747&aid=2889817&group_id=21935 
From: SourceForge.net <noreply@so...>  20091115 22:25:30

Bugs item #2889817, was opened at 20091031 02:47 Message generated for change (Comment added) made by kbr You can respond by visiting: https://sourceforge.net/tracker/?func=detail&atid=373747&aid=2889817&group_id=21935 Please note that this message will contain a full copy of the comment thread, including the initial issue submission, for this request, not just the latest update. Category: XSL Group: output: HTML Status: Open Resolution: None Priority: 5 Private: No Submitted By: Kai Brommann (kbr) Assigned to: Nobody/Anonymous (nobody) Summary: informalequation in toe and numbering Initial Comment: TDGV0.0.25 for V5.0 states for the equation element: [Processing systems that number equations or build a table of equations at the beginning of a document may have difficulty correctly formatting documents that contain both equations with titles and equations without titles. You are advised to use informalequation for equations without titles.] Assuming this caveat doesn't say that such difficulty is a feature and not a bug, here is a detailed description of the problem: Informalequation doesn't have a title, so probably it makes no sense to have it included in the table of equations, instead only equations (which should have a title as quoted above, the title may be optional rather than required according to TDG nevertheless) are to be listed there. Otherwise the result is an empty row in the table of equations. More generally speaking, every time an informal equation is linked to, it should not be tried to include its title while linking, because it has not title. Perhaps it could be fixed by some customization layer, but if it's a bug it better should be fixed in the stylesheets directly. Directly related is the question of numbering, let's say you have in the same chapter equation1 with title1 equation2 with title2 informalequation1 informalequation2 informalequation3 then the numbering (displayed together with the respective element) should go as follows: Equation 1. Title1 Equation 2. Title2 (1) (2) (3) so equation and informalequation should have separate counters, and the equation is accompanied with the term Equation and its title (same as table and figure), while the informalequation should only have its number in parentheses or the like. The current (buggy) behaviour is: Equation 1. Title1 Equation 2. Title2 Equation 2. Equation 2. Equation 2. so for informalequations the counter of the equations is reused as well (but not incremented on the other hand), and the notexisting title is of course empty, so should not be tried to be displayed. Instead, while linking, the two types can easily be distinguished, the desired behaviour would process the input (see ...) as: (see Equation 1.Title1) versus (see (1)) For an actual example how it should be done, you can also see the dblatex tool please where it is done properly for pdf. Thanx for your effort. (no error messages, Xalan2.7.1 and docbookxslns1.75.2/xhtml1_1/chunk.xsl toolchain, no test document necessary, no customization layer)  >Comment By: Kai Brommann (kbr) Date: 20091115 22:25 Message: 1 Thank you for your comment. 2 Now that I have had a second look at my bug report, it appears to me that instead of talking about informalequations I already the whole time was actually targeting the equation without title(!). I have run some tests, the informalequations behave already as they should, and the equations without titles are the buggy ones. Ok, I hope the audience can follow this reformulation, I think I shouldn't change the title of the initial bug report though because otherwise everybody gets completely confused ... 3 A quick journey to the bookshelf reveals that various numbering schemes are in use, some use the same single counter for table, figure, equation, example, while others use separate counters even for formal equations with title versus minor equation without title but with a reference number, and other books simply don't support numbering of equations without titles, so let's divide the bug into parts: there is an inconsistent behaviour of the stylesheets regarding equations without titles, they should not appear in the TOE and the numbering should not conflict with that of the equations with titles, and there is then furthermore the question if separate counters are used or the same counter. I proposed the first solution (which is what dblatex has chosen to do), while you prefer the latter. Both solutions are ok with me, the main point is only that any obvious present inconsistency in html is repaired. 4 So your proposed solution is also completely fine with me: >>I would propose the following: >>a) equation elements are numbered, and informalequations are not. Use >>informalequation when no reference is to be made to the equation. This >>makes informalequation parallel with informaltable, informalfigure, etc. Yes, agreed. As stated above I actually was complaining about the equations without title and not the informalequations. Today the informalequations look already ok to me. The parallelism is a good point to mention. >>b) Include only equation elements in the List of Equations. If an >>equation has no title, then only the number is displayed with the page >>number. No, here I would like to disagree. I would like to have only the equations with title be included in the List Of Equations, and the equations without title being omitted (as well as the informalequations). Those nearly empty rows in the TOE should go away. Perhaps it is only a customization thing, then how to accomplish it? But as far as I can tell, the default behaviour should be to omit those empty lines from the TOE, without need for customization. >>> Currently only equations with titles appear in the TOC. No, I think at the moment also the equations without title appear in the TOE, and this should be changed. Perhaps here you were irritated by the initial problem of my post, in that I pretended to talk about informalequation while actually mentally I wasn't :) >>c) Number all equation elements, whether they have a title or not. Yes >>d) Add a stylesheet parameter to select the style of equation numbering. >>One style says "Equation 3.1. Optional title", placed above or below the >>equation. The other style uses "(3.1)" beside the equation, with the >>optional title above or below it (with no number). Hm, perhaps yes, but probably not quite. what I would like to have a heavyweight: Equation 3.1 Title Einstein Formula E = mc^2 placed above or below, only for equations which have a title, and a lightweight a + b = c (3.1) beside the equation, without any Equation term, and without any title display, not together with the equation, and as well not in linking by xref linkend = xml:id to it, for equations without a title, but those two procedures be working at the same time. Now I don't know if you also intended this or rather not. So it should be possible to have those two different styles be switched on at the same time, depending on if a title is present or not. I I read your comment correctly, you instead only propose to offer a stylesheet parameter exclusively choosing between the two styles, while I have a simultanious scenario in mind. Perhaps this is too much to ask for, well I dare... [ Additional information: I have already the following .xsl stylesheet for producing .xhtml: <xsl:param name="formal.title.placement"> equation after </xsl:param> and in my .css: .equation .title { margintop: 0; marginleft: 20px; float: left; backgroundcolor: #00AABB; } but now how shall I specify the two different styles for equation only dependent on if a title is there or not? I am a complete newbie regarding stylesheet parameters... but at least I have tried. ]  For full clarity, let's link to a publicly visible neutral unbiased thirdparty webpage showing the problem: http://dblatex.sourceforge.net/ (produced using content="DocBook XSL Stylesheets V1.72.0, which means no difference to 1.75.2 in the discussion here) There is an equation with a title followed by an equation without a title, and we have in the .html TOE (table of equation): [ List of Equations 3.1. Simple Formula 3.1. ] and everybody will admit that there are two problems: the 3.1 is doubled, if at all it should be 3.1 and 3.2, and since the second item anyway doesn't have a title it should not appear in the TOE in my opinion anyway. Equations without titles are lightweight components with no meaning outside of their context, they only have a number so they can be referenced in the nearby text. The reader looking for 3.2 can go to chapter 3, this is already indicated by the number, that is enough. In the TOE only equations with generally known or understandable titles should be shown. Normally in a mathematical proof or something, one would have let's say twenty minor equations without title, being inserted one into another as the proof goes along, finally leading to one famous equation with title. Only the famous equation into the TOE please:) Rather stylesheet than customization sort of thing it seems to me, by the nature of matters. Besides, when we go to the corresponding chapter, there is a link to the equation without title, looking like: [ The formula Equation 3.1, "" below: Equation 3.1. ... ] it looks like the ugly "" indicates a title was tried to be displayed, but the title is empty, so it should not have been tried, instead the link should be displayed as [ The formula (3.1) below: ... ] if separate counters for equations with and without titles would be used, or since we have agreed that using the same counter is equally valid, the counter is incremented and it should be displayed as [ The formula (3.2) below: ... ] Hereby pay attention that for equations without title the announcement proclamation [ Equation 3.1. ] in front of or below the equation should be gone at all. (This should be settled in the stylesheets directly rather than be done by a customization, depending on if the title is set or not. If done by a stylesheet parameter, how to do it? But default stylesheet is better.)  TDG V0.0.25 [tdg5/en/html/ch02.html] or svn repository [trunk/defguide5/en/src/ch02.xml] should be updated to state clearly that formal means 'with numbering enabled' rather than 'with title'. At the moment it reads: [ Examples, Figures, and Table: The distinction between formal and informal elements is that formal elements have titles while informal ones do not. Equation: Informal equations don't have titles. For reasons of backwardcompatibility, Equations are not required to have titles. However, it may be more difficult for some stylesheet languages to properly enumerate Equations if they lack titles. ] Those passages as well as the sentences from elements/equation/db.equation.xml mentioned in the initial bug report should be reformulated to reflect the neatly settled situation once this bug here in focus is fixed. For example equations are not only not required to have titles because of backwardcompatibility, but now also because of having the possibility of numbering of equations for which no title can be imagined and where titles would be completely misplaced overhead, and at least for the docbookxsl stylesheets all problems will be gone in the near future:) (Btw., to ensure perfect symmetry for equation, table, figure, example regarding formal versus informal, one should make the title optional not only for equation but also for table, figure and example, but perhaps this change is not so easily done, too late in the process. Well, only an idea.) Thank you for your patience, I hope now everything is cleary explained.  Comment By: Robert Stayton (bobstayton) Date: 20091113 09:07 Message: I would propose the following: a) equation elements are numbered, and informalequations are not. Use informalequation when no reference is to be made to the equation. This makes informalequation parallel with informaltable, informalfigure, etc. b) Include only equation elements in the List of Equations. If an equation has no title, then only the number is displayed with the page number. Currently only equations with titles appear in the TOC. c) Number all equation elements, whether they have a title or not. d) Add a stylesheet parameter to select the style of equation numbering. One style says "Equation 3.2. Optional title", placed above or below the equation. The other style uses "(3.2)" beside the equation, with the optional title above or below it (with no number).  You can respond by visiting: https://sourceforge.net/tracker/?func=detail&atid=373747&aid=2889817&group_id=21935 
From: SourceForge.net <noreply@so...>  20091202 07:17:56

Bugs item #2889817, was opened at 20091030 19:47 Message generated for change (Comment added) made by bobstayton You can respond by visiting: https://sourceforge.net/tracker/?func=detail&atid=373747&aid=2889817&group_id=21935 Please note that this message will contain a full copy of the comment thread, including the initial issue submission, for this request, not just the latest update. Category: XSL Group: output: HTML >Status: Pending >Resolution: Fixed Priority: 5 Private: No Submitted By: Kai Brommann (kbr) >Assigned to: Robert Stayton (bobstayton) Summary: informalequation in toe and numbering Initial Comment: TDGV0.0.25 for V5.0 states for the equation element: [Processing systems that number equations or build a table of equations at the beginning of a document may have difficulty correctly formatting documents that contain both equations with titles and equations without titles. You are advised to use informalequation for equations without titles.] Assuming this caveat doesn't say that such difficulty is a feature and not a bug, here is a detailed description of the problem: Informalequation doesn't have a title, so probably it makes no sense to have it included in the table of equations, instead only equations (which should have a title as quoted above, the title may be optional rather than required according to TDG nevertheless) are to be listed there. Otherwise the result is an empty row in the table of equations. More generally speaking, every time an informal equation is linked to, it should not be tried to include its title while linking, because it has not title. Perhaps it could be fixed by some customization layer, but if it's a bug it better should be fixed in the stylesheets directly. Directly related is the question of numbering, let's say you have in the same chapter equation1 with title1 equation2 with title2 informalequation1 informalequation2 informalequation3 then the numbering (displayed together with the respective element) should go as follows: Equation 1. Title1 Equation 2. Title2 (1) (2) (3) so equation and informalequation should have separate counters, and the equation is accompanied with the term Equation and its title (same as table and figure), while the informalequation should only have its number in parentheses or the like. The current (buggy) behaviour is: Equation 1. Title1 Equation 2. Title2 Equation 2. Equation 2. Equation 2. so for informalequations the counter of the equations is reused as well (but not incremented on the other hand), and the notexisting title is of course empty, so should not be tried to be displayed. Instead, while linking, the two types can easily be distinguished, the desired behaviour would process the input (see ...) as: (see Equation 1.Title1) versus (see (1)) For an actual example how it should be done, you can also see the dblatex tool please where it is done properly for pdf. Thanx for your effort. (no error messages, Xalan2.7.1 and docbookxslns1.75.2/xhtml1_1/chunk.xsl toolchain, no test document necessary, no customization layer)  >Comment By: Robert Stayton (bobstayton) Date: 20091201 23:17 Message: I checked in the files to implement the changes. They will appear in the next snapshot build, but it seems that snapshot builds are not currently happening.  Comment By: Robert Stayton (bobstayton) Date: 20091201 23:17 Message: A fix for this issue has been added to the current codebase. Please test the fix with the latest snapshot from: http://docbook.sourceforge.net/snapshots/  Comment By: Kai Brommann (kbr) Date: 20091115 14:25 Message: 1 Thank you for your comment. 2 Now that I have had a second look at my bug report, it appears to me that instead of talking about informalequations I already the whole time was actually targeting the equation without title(!). I have run some tests, the informalequations behave already as they should, and the equations without titles are the buggy ones. Ok, I hope the audience can follow this reformulation, I think I shouldn't change the title of the initial bug report though because otherwise everybody gets completely confused ... 3 A quick journey to the bookshelf reveals that various numbering schemes are in use, some use the same single counter for table, figure, equation, example, while others use separate counters even for formal equations with title versus minor equation without title but with a reference number, and other books simply don't support numbering of equations without titles, so let's divide the bug into parts: there is an inconsistent behaviour of the stylesheets regarding equations without titles, they should not appear in the TOE and the numbering should not conflict with that of the equations with titles, and there is then furthermore the question if separate counters are used or the same counter. I proposed the first solution (which is what dblatex has chosen to do), while you prefer the latter. Both solutions are ok with me, the main point is only that any obvious present inconsistency in html is repaired. 4 So your proposed solution is also completely fine with me: >>I would propose the following: >>a) equation elements are numbered, and informalequations are not. Use >>informalequation when no reference is to be made to the equation. This >>makes informalequation parallel with informaltable, informalfigure, etc. Yes, agreed. As stated above I actually was complaining about the equations without title and not the informalequations. Today the informalequations look already ok to me. The parallelism is a good point to mention. >>b) Include only equation elements in the List of Equations. If an >>equation has no title, then only the number is displayed with the page >>number. No, here I would like to disagree. I would like to have only the equations with title be included in the List Of Equations, and the equations without title being omitted (as well as the informalequations). Those nearly empty rows in the TOE should go away. Perhaps it is only a customization thing, then how to accomplish it? But as far as I can tell, the default behaviour should be to omit those empty lines from the TOE, without need for customization. >>> Currently only equations with titles appear in the TOC. No, I think at the moment also the equations without title appear in the TOE, and this should be changed. Perhaps here you were irritated by the initial problem of my post, in that I pretended to talk about informalequation while actually mentally I wasn't :) >>c) Number all equation elements, whether they have a title or not. Yes >>d) Add a stylesheet parameter to select the style of equation numbering. >>One style says "Equation 3.1. Optional title", placed above or below the >>equation. The other style uses "(3.1)" beside the equation, with the >>optional title above or below it (with no number). Hm, perhaps yes, but probably not quite. what I would like to have a heavyweight: Equation 3.1 Title Einstein Formula E = mc^2 placed above or below, only for equations which have a title, and a lightweight a + b = c (3.1) beside the equation, without any Equation term, and without any title display, not together with the equation, and as well not in linking by xref linkend = xml:id to it, for equations without a title, but those two procedures be working at the same time. Now I don't know if you also intended this or rather not. So it should be possible to have those two different styles be switched on at the same time, depending on if a title is present or not. I I read your comment correctly, you instead only propose to offer a stylesheet parameter exclusively choosing between the two styles, while I have a simultanious scenario in mind. Perhaps this is too much to ask for, well I dare... [ Additional information: I have already the following .xsl stylesheet for producing .xhtml: <xsl:param name="formal.title.placement"> equation after </xsl:param> and in my .css: .equation .title { margintop: 0; marginleft: 20px; float: left; backgroundcolor: #00AABB; } but now how shall I specify the two different styles for equation only dependent on if a title is there or not? I am a complete newbie regarding stylesheet parameters... but at least I have tried. ]  For full clarity, let's link to a publicly visible neutral unbiased thirdparty webpage showing the problem: http://dblatex.sourceforge.net/ (produced using content="DocBook XSL Stylesheets V1.72.0, which means no difference to 1.75.2 in the discussion here) There is an equation with a title followed by an equation without a title, and we have in the .html TOE (table of equation): [ List of Equations 3.1. Simple Formula 3.1. ] and everybody will admit that there are two problems: the 3.1 is doubled, if at all it should be 3.1 and 3.2, and since the second item anyway doesn't have a title it should not appear in the TOE in my opinion anyway. Equations without titles are lightweight components with no meaning outside of their context, they only have a number so they can be referenced in the nearby text. The reader looking for 3.2 can go to chapter 3, this is already indicated by the number, that is enough. In the TOE only equations with generally known or understandable titles should be shown. Normally in a mathematical proof or something, one would have let's say twenty minor equations without title, being inserted one into another as the proof goes along, finally leading to one famous equation with title. Only the famous equation into the TOE please:) Rather stylesheet than customization sort of thing it seems to me, by the nature of matters. Besides, when we go to the corresponding chapter, there is a link to the equation without title, looking like: [ The formula Equation 3.1, "" below: Equation 3.1. ... ] it looks like the ugly "" indicates a title was tried to be displayed, but the title is empty, so it should not have been tried, instead the link should be displayed as [ The formula (3.1) below: ... ] if separate counters for equations with and without titles would be used, or since we have agreed that using the same counter is equally valid, the counter is incremented and it should be displayed as [ The formula (3.2) below: ... ] Hereby pay attention that for equations without title the announcement proclamation [ Equation 3.1. ] in front of or below the equation should be gone at all. (This should be settled in the stylesheets directly rather than be done by a customization, depending on if the title is set or not. If done by a stylesheet parameter, how to do it? But default stylesheet is better.)  TDG V0.0.25 [tdg5/en/html/ch02.html] or svn repository [trunk/defguide5/en/src/ch02.xml] should be updated to state clearly that formal means 'with numbering enabled' rather than 'with title'. At the moment it reads: [ Examples, Figures, and Table: The distinction between formal and informal elements is that formal elements have titles while informal ones do not. Equation: Informal equations don't have titles. For reasons of backwardcompatibility, Equations are not required to have titles. However, it may be more difficult for some stylesheet languages to properly enumerate Equations if they lack titles. ] Those passages as well as the sentences from elements/equation/db.equation.xml mentioned in the initial bug report should be reformulated to reflect the neatly settled situation once this bug here in focus is fixed. For example equations are not only not required to have titles because of backwardcompatibility, but now also because of having the possibility of numbering of equations for which no title can be imagined and where titles would be completely misplaced overhead, and at least for the docbookxsl stylesheets all problems will be gone in the near future:) (Btw., to ensure perfect symmetry for equation, table, figure, example regarding formal versus informal, one should make the title optional not only for equation but also for table, figure and example, but perhaps this change is not so easily done, too late in the process. Well, only an idea.) Thank you for your patience, I hope now everything is cleary explained.  Comment By: Robert Stayton (bobstayton) Date: 20091113 01:07 Message: I would propose the following: a) equation elements are numbered, and informalequations are not. Use informalequation when no reference is to be made to the equation. This makes informalequation parallel with informaltable, informalfigure, etc. b) Include only equation elements in the List of Equations. If an equation has no title, then only the number is displayed with the page number. Currently only equations with titles appear in the TOC. c) Number all equation elements, whether they have a title or not. d) Add a stylesheet parameter to select the style of equation numbering. One style says "Equation 3.2. Optional title", placed above or below the equation. The other style uses "(3.2)" beside the equation, with the optional title above or below it (with no number).  You can respond by visiting: https://sourceforge.net/tracker/?func=detail&atid=373747&aid=2889817&group_id=21935 
From: SourceForge.net <noreply@so...>  20091205 21:31:29

Bugs item #2889817, was opened at 20091031 02:47 Message generated for change (Settings changed) made by kbr You can respond by visiting: https://sourceforge.net/tracker/?func=detail&atid=373747&aid=2889817&group_id=21935 Please note that this message will contain a full copy of the comment thread, including the initial issue submission, for this request, not just the latest update. Category: XSL Group: output: HTML >Status: Open Resolution: Fixed Priority: 5 Private: No Submitted By: Kai Brommann (kbr) Assigned to: Robert Stayton (bobstayton) Summary: informalequation in toe and numbering Initial Comment: TDGV0.0.25 for V5.0 states for the equation element: [Processing systems that number equations or build a table of equations at the beginning of a document may have difficulty correctly formatting documents that contain both equations with titles and equations without titles. You are advised to use informalequation for equations without titles.] Assuming this caveat doesn't say that such difficulty is a feature and not a bug, here is a detailed description of the problem: Informalequation doesn't have a title, so probably it makes no sense to have it included in the table of equations, instead only equations (which should have a title as quoted above, the title may be optional rather than required according to TDG nevertheless) are to be listed there. Otherwise the result is an empty row in the table of equations. More generally speaking, every time an informal equation is linked to, it should not be tried to include its title while linking, because it has not title. Perhaps it could be fixed by some customization layer, but if it's a bug it better should be fixed in the stylesheets directly. Directly related is the question of numbering, let's say you have in the same chapter equation1 with title1 equation2 with title2 informalequation1 informalequation2 informalequation3 then the numbering (displayed together with the respective element) should go as follows: Equation 1. Title1 Equation 2. Title2 (1) (2) (3) so equation and informalequation should have separate counters, and the equation is accompanied with the term Equation and its title (same as table and figure), while the informalequation should only have its number in parentheses or the like. The current (buggy) behaviour is: Equation 1. Title1 Equation 2. Title2 Equation 2. Equation 2. Equation 2. so for informalequations the counter of the equations is reused as well (but not incremented on the other hand), and the notexisting title is of course empty, so should not be tried to be displayed. Instead, while linking, the two types can easily be distinguished, the desired behaviour would process the input (see ...) as: (see Equation 1.Title1) versus (see (1)) For an actual example how it should be done, you can also see the dblatex tool please where it is done properly for pdf. Thanx for your effort. (no error messages, Xalan2.7.1 and docbookxslns1.75.2/xhtml1_1/chunk.xsl toolchain, no test document necessary, no customization layer)  >Comment By: Kai Brommann (kbr) Date: 20091205 21:31 Message: 1) Due to the missing snapshots, I took it as a challenge and decided to build one on my own, following the instructions in: https://docbook.svn.sourceforge.net/svnroot/docbook/trunk/xsl/README.BUILD so I checked out from the svn repository the modules: xsl buildtools gentext but in the 'make all' step the following error occurred: Makefile:4: $DOCBOOK_SVN/releasetools/Variables.mk: No such file or directory Makefile:115: $DOCBOOK_SVN/releasetools/Targets.mk: No such file or directory Makefile:116: $DOCBOOK_SVN/releasetools/xslns.mk: No such file or directory make: *** No rule to make target `$DOCBOOK_SVN/releasetools/xslns.mk'. Stop. which was easily fixed by simply also checking out releasetools (so either something should be done to remove this dependency on releasetools for a developeronly build, or the instructions need to be updated). Then I ran into errors like: Cannot read config: ~kbr/.xmlc Well, in some files one finds [Where is the config file? Defaults to ~/.xmlc] so probably the instructions should talk about .xmlc instead of .xmlrc at leeast renaming the file accordingly did the magic, the build finally worked successfully. One minor comment: in the instructions, the mentioned thirdparty software versions are a little bit outdated perhaps, instead of xalan2.7.0.jar jaxp1.3.jar xmlcommonsresolver1.1.jar I used xalan2.7.1 jaxp2.2ea xmlcommonsresolver1.2.jar so while we are at it, this could be updated as well (always use the latest and greatest). 2.) a.)Now for the docbook stylesheet bug in focus, I can confirm noticable improvements: the numberings of equations without title now are also incremented as they should it is no longer tried to display a title which is not existing, neither during linking by xref nor beside the equation b.)but I feel we are not completely done yet: b1.)in the table of equations TOE, still the equations without title are displayed, some part looks like: 9.1. Euler formula 9.2. 11.1. RiemannHurwitz identity 11.2. Frobenius formula 11.3. 11.4. 11.5. 13.1. BakerCampbellHausdorff formula which is already an improvement (before the fix, numbers were not incremented for equations without title), but I think the final goal should be: 9.1. Euler formula 11.1. RiemannHurwitz identity 11.2. Frobenius formula 13.1. BakerCampbellHausdorff formula b2.) the appearance of the links to equations without title now is something like ... that the following diagram (Equation 11.4) ... (please note that while the DocBook element is named equation, actually it is ment to be used for general mathematical expressions of all kinds, which can well be just a term or a MathML diagram, no equals sign in sight in this case) and beside the equation without title now we have as XHTML page source (for example using a MathML input): </p><div class="equation"><a xmlns:saxon="http://icl.com/saxon"; id="commutingdiagram" /><div class="equationcontents"> <mml:math xmlns="http://docbook.org/ns/docbook"; xmlns:mml="http://www.w3.org/1998/Math/MathML"; xmlns:xlink="http://www.w3.org/1999/xlink"; overflow="scroll"> ... </mml:math> </div><p class="title">Equation 11.4. </p></div><p><br class="equationbreak" /> </p> This is already quite ok, it is overall consistent as it is. We are now talking about matters of taste. There are use cases where the above behaviour is exactly what one would like to have, in other circumstances it is still a little bit to heavyweight. Probably what one would need, is a stylesheet parameter where the appearance of links to as well as what is displayed accompanying the equation can be customized, (now comes the important point:) depending on if a title is present or not. It should be treated as if there would be two separate docbook elements. Then the default setting can stay as is now, and if desired (just for nonexisting titles) in linking and besides the equation: Equation 11.4. could be changed into (11.4) [it is sort of a function, input the number, output = (input) so one would definitely not want to map Equation to ( and . to ) or the like :)] Conclusion: If issue 2.)a.) TOE is also repaired, the status of the bug can be set from pending to closed. If there is some spare time left, then some customization options targetting only the equations without titles would be appreciated, to achieve (11.4) instead of Equation 11.4., but perhaps it would mean a too invasive hack into the stylesheets. Or it is already possible to customize as described (without affecting the equations with title), but I don't know how, then please tell how. Thanx for your fix, we are almost there. P.S.: it was a good idea to ask about the issue on the docbookapps mailing list, we got some positive feedback I think. Actually I already had posted the problem some years ago (instead of creating a bug report): http://lists.oasisopen.org/archives/docbookapps/200605/msg00096.html http://lists.oasisopen.org/archives/docbookapps/200605/msg00148.html but without a reaction (sigh). Finally I ended up with inventing titles just to avoid the issue. Now we are on a good way to solve the problem.  Comment By: Robert Stayton (bobstayton) Date: 20091202 07:17 Message: I checked in the files to implement the changes. They will appear in the next snapshot build, but it seems that snapshot builds are not currently happening.  Comment By: Robert Stayton (bobstayton) Date: 20091202 07:17 Message: A fix for this issue has been added to the current codebase. Please test the fix with the latest snapshot from: http://docbook.sourceforge.net/snapshots/  Comment By: Kai Brommann (kbr) Date: 20091115 22:25 Message: 1 Thank you for your comment. 2 Now that I have had a second look at my bug report, it appears to me that instead of talking about informalequations I already the whole time was actually targeting the equation without title(!). I have run some tests, the informalequations behave already as they should, and the equations without titles are the buggy ones. Ok, I hope the audience can follow this reformulation, I think I shouldn't change the title of the initial bug report though because otherwise everybody gets completely confused ... 3 A quick journey to the bookshelf reveals that various numbering schemes are in use, some use the same single counter for table, figure, equation, example, while others use separate counters even for formal equations with title versus minor equation without title but with a reference number, and other books simply don't support numbering of equations without titles, so let's divide the bug into parts: there is an inconsistent behaviour of the stylesheets regarding equations without titles, they should not appear in the TOE and the numbering should not conflict with that of the equations with titles, and there is then furthermore the question if separate counters are used or the same counter. I proposed the first solution (which is what dblatex has chosen to do), while you prefer the latter. Both solutions are ok with me, the main point is only that any obvious present inconsistency in html is repaired. 4 So your proposed solution is also completely fine with me: >>I would propose the following: >>a) equation elements are numbered, and informalequations are not. Use >>informalequation when no reference is to be made to the equation. This >>makes informalequation parallel with informaltable, informalfigure, etc. Yes, agreed. As stated above I actually was complaining about the equations without title and not the informalequations. Today the informalequations look already ok to me. The parallelism is a good point to mention. >>b) Include only equation elements in the List of Equations. If an >>equation has no title, then only the number is displayed with the page >>number. No, here I would like to disagree. I would like to have only the equations with title be included in the List Of Equations, and the equations without title being omitted (as well as the informalequations). Those nearly empty rows in the TOE should go away. Perhaps it is only a customization thing, then how to accomplish it? But as far as I can tell, the default behaviour should be to omit those empty lines from the TOE, without need for customization. >>> Currently only equations with titles appear in the TOC. No, I think at the moment also the equations without title appear in the TOE, and this should be changed. Perhaps here you were irritated by the initial problem of my post, in that I pretended to talk about informalequation while actually mentally I wasn't :) >>c) Number all equation elements, whether they have a title or not. Yes >>d) Add a stylesheet parameter to select the style of equation numbering. >>One style says "Equation 3.1. Optional title", placed above or below the >>equation. The other style uses "(3.1)" beside the equation, with the >>optional title above or below it (with no number). Hm, perhaps yes, but probably not quite. what I would like to have a heavyweight: Equation 3.1 Title Einstein Formula E = mc^2 placed above or below, only for equations which have a title, and a lightweight a + b = c (3.1) beside the equation, without any Equation term, and without any title display, not together with the equation, and as well not in linking by xref linkend = xml:id to it, for equations without a title, but those two procedures be working at the same time. Now I don't know if you also intended this or rather not. So it should be possible to have those two different styles be switched on at the same time, depending on if a title is present or not. I I read your comment correctly, you instead only propose to offer a stylesheet parameter exclusively choosing between the two styles, while I have a simultanious scenario in mind. Perhaps this is too much to ask for, well I dare... [ Additional information: I have already the following .xsl stylesheet for producing .xhtml: <xsl:param name="formal.title.placement"> equation after </xsl:param> and in my .css: .equation .title { margintop: 0; marginleft: 20px; float: left; backgroundcolor: #00AABB; } but now how shall I specify the two different styles for equation only dependent on if a title is there or not? I am a complete newbie regarding stylesheet parameters... but at least I have tried. ]  For full clarity, let's link to a publicly visible neutral unbiased thirdparty webpage showing the problem: http://dblatex.sourceforge.net/ (produced using content="DocBook XSL Stylesheets V1.72.0, which means no difference to 1.75.2 in the discussion here) There is an equation with a title followed by an equation without a title, and we have in the .html TOE (table of equation): [ List of Equations 3.1. Simple Formula 3.1. ] and everybody will admit that there are two problems: the 3.1 is doubled, if at all it should be 3.1 and 3.2, and since the second item anyway doesn't have a title it should not appear in the TOE in my opinion anyway. Equations without titles are lightweight components with no meaning outside of their context, they only have a number so they can be referenced in the nearby text. The reader looking for 3.2 can go to chapter 3, this is already indicated by the number, that is enough. In the TOE only equations with generally known or understandable titles should be shown. Normally in a mathematical proof or something, one would have let's say twenty minor equations without title, being inserted one into another as the proof goes along, finally leading to one famous equation with title. Only the famous equation into the TOE please:) Rather stylesheet than customization sort of thing it seems to me, by the nature of matters. Besides, when we go to the corresponding chapter, there is a link to the equation without title, looking like: [ The formula Equation 3.1, "" below: Equation 3.1. ... ] it looks like the ugly "" indicates a title was tried to be displayed, but the title is empty, so it should not have been tried, instead the link should be displayed as [ The formula (3.1) below: ... ] if separate counters for equations with and without titles would be used, or since we have agreed that using the same counter is equally valid, the counter is incremented and it should be displayed as [ The formula (3.2) below: ... ] Hereby pay attention that for equations without title the announcement proclamation [ Equation 3.1. ] in front of or below the equation should be gone at all. (This should be settled in the stylesheets directly rather than be done by a customization, depending on if the title is set or not. If done by a stylesheet parameter, how to do it? But default stylesheet is better.)  TDG V0.0.25 [tdg5/en/html/ch02.html] or svn repository [trunk/defguide5/en/src/ch02.xml] should be updated to state clearly that formal means 'with numbering enabled' rather than 'with title'. At the moment it reads: [ Examples, Figures, and Table: The distinction between formal and informal elements is that formal elements have titles while informal ones do not. Equation: Informal equations don't have titles. For reasons of backwardcompatibility, Equations are not required to have titles. However, it may be more difficult for some stylesheet languages to properly enumerate Equations if they lack titles. ] Those passages as well as the sentences from elements/equation/db.equation.xml mentioned in the initial bug report should be reformulated to reflect the neatly settled situation once this bug here in focus is fixed. For example equations are not only not required to have titles because of backwardcompatibility, but now also because of having the possibility of numbering of equations for which no title can be imagined and where titles would be completely misplaced overhead, and at least for the docbookxsl stylesheets all problems will be gone in the near future:) (Btw., to ensure perfect symmetry for equation, table, figure, example regarding formal versus informal, one should make the title optional not only for equation but also for table, figure and example, but perhaps this change is not so easily done, too late in the process. Well, only an idea.) Thank you for your patience, I hope now everything is cleary explained.  Comment By: Robert Stayton (bobstayton) Date: 20091113 09:07 Message: I would propose the following: a) equation elements are numbered, and informalequations are not. Use informalequation when no reference is to be made to the equation. This makes informalequation parallel with informaltable, informalfigure, etc. b) Include only equation elements in the List of Equations. If an equation has no title, then only the number is displayed with the page number. Currently only equations with titles appear in the TOC. c) Number all equation elements, whether they have a title or not. d) Add a stylesheet parameter to select the style of equation numbering. One style says "Equation 3.2. Optional title", placed above or below the equation. The other style uses "(3.2)" beside the equation, with the optional title above or below it (with no number).  You can respond by visiting: https://sourceforge.net/tracker/?func=detail&atid=373747&aid=2889817&group_id=21935 
From: SourceForge.net <noreply@so...>  20091206 18:55:31

Bugs item #2889817, was opened at 20091030 19:47 Message generated for change (Comment added) made by bobstayton You can respond by visiting: https://sourceforge.net/tracker/?func=detail&atid=373747&aid=2889817&group_id=21935 Please note that this message will contain a full copy of the comment thread, including the initial issue submission, for this request, not just the latest update. Category: XSL Group: output: HTML Status: Open Resolution: Fixed Priority: 5 Private: No Submitted By: Kai Brommann (kbr) Assigned to: Robert Stayton (bobstayton) Summary: informalequation in toe and numbering Initial Comment: TDGV0.0.25 for V5.0 states for the equation element: [Processing systems that number equations or build a table of equations at the beginning of a document may have difficulty correctly formatting documents that contain both equations with titles and equations without titles. You are advised to use informalequation for equations without titles.] Assuming this caveat doesn't say that such difficulty is a feature and not a bug, here is a detailed description of the problem: Informalequation doesn't have a title, so probably it makes no sense to have it included in the table of equations, instead only equations (which should have a title as quoted above, the title may be optional rather than required according to TDG nevertheless) are to be listed there. Otherwise the result is an empty row in the table of equations. More generally speaking, every time an informal equation is linked to, it should not be tried to include its title while linking, because it has not title. Perhaps it could be fixed by some customization layer, but if it's a bug it better should be fixed in the stylesheets directly. Directly related is the question of numbering, let's say you have in the same chapter equation1 with title1 equation2 with title2 informalequation1 informalequation2 informalequation3 then the numbering (displayed together with the respective element) should go as follows: Equation 1. Title1 Equation 2. Title2 (1) (2) (3) so equation and informalequation should have separate counters, and the equation is accompanied with the term Equation and its title (same as table and figure), while the informalequation should only have its number in parentheses or the like. The current (buggy) behaviour is: Equation 1. Title1 Equation 2. Title2 Equation 2. Equation 2. Equation 2. so for informalequations the counter of the equations is reused as well (but not incremented on the other hand), and the notexisting title is of course empty, so should not be tried to be displayed. Instead, while linking, the two types can easily be distinguished, the desired behaviour would process the input (see ...) as: (see Equation 1.Title1) versus (see (1)) For an actual example how it should be done, you can also see the dblatex tool please where it is done properly for pdf. Thanx for your effort. (no error messages, Xalan2.7.1 and docbookxslns1.75.2/xhtml1_1/chunk.xsl toolchain, no test document necessary, no customization layer)  >Comment By: Robert Stayton (bobstayton) Date: 20091206 10:55 Message: Regarding 2a, I'm not able to duplicate the problem of equations without titles appearing in the List of Equations. The code in 1.75.2 selects them as follows: <xsl:calltemplate name="list.of.titles"> <xsl:withparam name="titles" select="'equation'"/> <xsl:withparam name="nodes" select=".//equation[title or info/title]"/> </xsl:calltemplate> The nodes it selects must have a title. My output LOE does not include equations without titles. Are you using a customization, by any chance? Regarding the customization issues, I think there are sufficient opportunities for custization of links and formatting to enable variations that different people need. For example, there is now a separate template named "equation.without.title" that can be customized to handle that case, and links can be customized using the parameter 'local.l10n.xml' as with other gentext.  Comment By: Kai Brommann (kbr) Date: 20091205 13:31 Message: 1) Due to the missing snapshots, I took it as a challenge and decided to build one on my own, following the instructions in: https://docbook.svn.sourceforge.net/svnroot/docbook/trunk/xsl/README.BUILD so I checked out from the svn repository the modules: xsl buildtools gentext but in the 'make all' step the following error occurred: Makefile:4: $DOCBOOK_SVN/releasetools/Variables.mk: No such file or directory Makefile:115: $DOCBOOK_SVN/releasetools/Targets.mk: No such file or directory Makefile:116: $DOCBOOK_SVN/releasetools/xslns.mk: No such file or directory make: *** No rule to make target `$DOCBOOK_SVN/releasetools/xslns.mk'. Stop. which was easily fixed by simply also checking out releasetools (so either something should be done to remove this dependency on releasetools for a developeronly build, or the instructions need to be updated). Then I ran into errors like: Cannot read config: ~kbr/.xmlc Well, in some files one finds [Where is the config file? Defaults to ~/.xmlc] so probably the instructions should talk about .xmlc instead of .xmlrc at leeast renaming the file accordingly did the magic, the build finally worked successfully. One minor comment: in the instructions, the mentioned thirdparty software versions are a little bit outdated perhaps, instead of xalan2.7.0.jar jaxp1.3.jar xmlcommonsresolver1.1.jar I used xalan2.7.1 jaxp2.2ea xmlcommonsresolver1.2.jar so while we are at it, this could be updated as well (always use the latest and greatest). 2.) a.)Now for the docbook stylesheet bug in focus, I can confirm noticable improvements: the numberings of equations without title now are also incremented as they should it is no longer tried to display a title which is not existing, neither during linking by xref nor beside the equation b.)but I feel we are not completely done yet: b1.)in the table of equations TOE, still the equations without title are displayed, some part looks like: 9.1. Euler formula 9.2. 11.1. RiemannHurwitz identity 11.2. Frobenius formula 11.3. 11.4. 11.5. 13.1. BakerCampbellHausdorff formula which is already an improvement (before the fix, numbers were not incremented for equations without title), but I think the final goal should be: 9.1. Euler formula 11.1. RiemannHurwitz identity 11.2. Frobenius formula 13.1. BakerCampbellHausdorff formula b2.) the appearance of the links to equations without title now is something like ... that the following diagram (Equation 11.4) ... (please note that while the DocBook element is named equation, actually it is ment to be used for general mathematical expressions of all kinds, which can well be just a term or a MathML diagram, no equals sign in sight in this case) and beside the equation without title now we have as XHTML page source (for example using a MathML input): </p><div class="equation"><a xmlns:saxon="http://icl.com/saxon"; id="commutingdiagram" /><div class="equationcontents"> <mml:math xmlns="http://docbook.org/ns/docbook"; xmlns:mml="http://www.w3.org/1998/Math/MathML"; xmlns:xlink="http://www.w3.org/1999/xlink"; overflow="scroll"> ... </mml:math> </div><p class="title">Equation 11.4. </p></div><p><br class="equationbreak" /> </p> This is already quite ok, it is overall consistent as it is. We are now talking about matters of taste. There are use cases where the above behaviour is exactly what one would like to have, in other circumstances it is still a little bit to heavyweight. Probably what one would need, is a stylesheet parameter where the appearance of links to as well as what is displayed accompanying the equation can be customized, (now comes the important point:) depending on if a title is present or not. It should be treated as if there would be two separate docbook elements. Then the default setting can stay as is now, and if desired (just for nonexisting titles) in linking and besides the equation: Equation 11.4. could be changed into (11.4) [it is sort of a function, input the number, output = (input) so one would definitely not want to map Equation to ( and . to ) or the like :)] Conclusion: If issue 2.)a.) TOE is also repaired, the status of the bug can be set from pending to closed. If there is some spare time left, then some customization options targetting only the equations without titles would be appreciated, to achieve (11.4) instead of Equation 11.4., but perhaps it would mean a too invasive hack into the stylesheets. Or it is already possible to customize as described (without affecting the equations with title), but I don't know how, then please tell how. Thanx for your fix, we are almost there. P.S.: it was a good idea to ask about the issue on the docbookapps mailing list, we got some positive feedback I think. Actually I already had posted the problem some years ago (instead of creating a bug report): http://lists.oasisopen.org/archives/docbookapps/200605/msg00096.html http://lists.oasisopen.org/archives/docbookapps/200605/msg00148.html but without a reaction (sigh). Finally I ended up with inventing titles just to avoid the issue. Now we are on a good way to solve the problem.  Comment By: Robert Stayton (bobstayton) Date: 20091201 23:17 Message: I checked in the files to implement the changes. They will appear in the next snapshot build, but it seems that snapshot builds are not currently happening.  Comment By: Robert Stayton (bobstayton) Date: 20091201 23:17 Message: A fix for this issue has been added to the current codebase. Please test the fix with the latest snapshot from: http://docbook.sourceforge.net/snapshots/  Comment By: Kai Brommann (kbr) Date: 20091115 14:25 Message: 1 Thank you for your comment. 2 Now that I have had a second look at my bug report, it appears to me that instead of talking about informalequations I already the whole time was actually targeting the equation without title(!). I have run some tests, the informalequations behave already as they should, and the equations without titles are the buggy ones. Ok, I hope the audience can follow this reformulation, I think I shouldn't change the title of the initial bug report though because otherwise everybody gets completely confused ... 3 A quick journey to the bookshelf reveals that various numbering schemes are in use, some use the same single counter for table, figure, equation, example, while others use separate counters even for formal equations with title versus minor equation without title but with a reference number, and other books simply don't support numbering of equations without titles, so let's divide the bug into parts: there is an inconsistent behaviour of the stylesheets regarding equations without titles, they should not appear in the TOE and the numbering should not conflict with that of the equations with titles, and there is then furthermore the question if separate counters are used or the same counter. I proposed the first solution (which is what dblatex has chosen to do), while you prefer the latter. Both solutions are ok with me, the main point is only that any obvious present inconsistency in html is repaired. 4 So your proposed solution is also completely fine with me: >>I would propose the following: >>a) equation elements are numbered, and informalequations are not. Use >>informalequation when no reference is to be made to the equation. This >>makes informalequation parallel with informaltable, informalfigure, etc. Yes, agreed. As stated above I actually was complaining about the equations without title and not the informalequations. Today the informalequations look already ok to me. The parallelism is a good point to mention. >>b) Include only equation elements in the List of Equations. If an >>equation has no title, then only the number is displayed with the page >>number. No, here I would like to disagree. I would like to have only the equations with title be included in the List Of Equations, and the equations without title being omitted (as well as the informalequations). Those nearly empty rows in the TOE should go away. Perhaps it is only a customization thing, then how to accomplish it? But as far as I can tell, the default behaviour should be to omit those empty lines from the TOE, without need for customization. >>> Currently only equations with titles appear in the TOC. No, I think at the moment also the equations without title appear in the TOE, and this should be changed. Perhaps here you were irritated by the initial problem of my post, in that I pretended to talk about informalequation while actually mentally I wasn't :) >>c) Number all equation elements, whether they have a title or not. Yes >>d) Add a stylesheet parameter to select the style of equation numbering. >>One style says "Equation 3.1. Optional title", placed above or below the >>equation. The other style uses "(3.1)" beside the equation, with the >>optional title above or below it (with no number). Hm, perhaps yes, but probably not quite. what I would like to have a heavyweight: Equation 3.1 Title Einstein Formula E = mc^2 placed above or below, only for equations which have a title, and a lightweight a + b = c (3.1) beside the equation, without any Equation term, and without any title display, not together with the equation, and as well not in linking by xref linkend = xml:id to it, for equations without a title, but those two procedures be working at the same time. Now I don't know if you also intended this or rather not. So it should be possible to have those two different styles be switched on at the same time, depending on if a title is present or not. I I read your comment correctly, you instead only propose to offer a stylesheet parameter exclusively choosing between the two styles, while I have a simultanious scenario in mind. Perhaps this is too much to ask for, well I dare... [ Additional information: I have already the following .xsl stylesheet for producing .xhtml: <xsl:param name="formal.title.placement"> equation after </xsl:param> and in my .css: .equation .title { margintop: 0; marginleft: 20px; float: left; backgroundcolor: #00AABB; } but now how shall I specify the two different styles for equation only dependent on if a title is there or not? I am a complete newbie regarding stylesheet parameters... but at least I have tried. ]  For full clarity, let's link to a publicly visible neutral unbiased thirdparty webpage showing the problem: http://dblatex.sourceforge.net/ (produced using content="DocBook XSL Stylesheets V1.72.0, which means no difference to 1.75.2 in the discussion here) There is an equation with a title followed by an equation without a title, and we have in the .html TOE (table of equation): [ List of Equations 3.1. Simple Formula 3.1. ] and everybody will admit that there are two problems: the 3.1 is doubled, if at all it should be 3.1 and 3.2, and since the second item anyway doesn't have a title it should not appear in the TOE in my opinion anyway. Equations without titles are lightweight components with no meaning outside of their context, they only have a number so they can be referenced in the nearby text. The reader looking for 3.2 can go to chapter 3, this is already indicated by the number, that is enough. In the TOE only equations with generally known or understandable titles should be shown. Normally in a mathematical proof or something, one would have let's say twenty minor equations without title, being inserted one into another as the proof goes along, finally leading to one famous equation with title. Only the famous equation into the TOE please:) Rather stylesheet than customization sort of thing it seems to me, by the nature of matters. Besides, when we go to the corresponding chapter, there is a link to the equation without title, looking like: [ The formula Equation 3.1, "" below: Equation 3.1. ... ] it looks like the ugly "" indicates a title was tried to be displayed, but the title is empty, so it should not have been tried, instead the link should be displayed as [ The formula (3.1) below: ... ] if separate counters for equations with and without titles would be used, or since we have agreed that using the same counter is equally valid, the counter is incremented and it should be displayed as [ The formula (3.2) below: ... ] Hereby pay attention that for equations without title the announcement proclamation [ Equation 3.1. ] in front of or below the equation should be gone at all. (This should be settled in the stylesheets directly rather than be done by a customization, depending on if the title is set or not. If done by a stylesheet parameter, how to do it? But default stylesheet is better.)  TDG V0.0.25 [tdg5/en/html/ch02.html] or svn repository [trunk/defguide5/en/src/ch02.xml] should be updated to state clearly that formal means 'with numbering enabled' rather than 'with title'. At the moment it reads: [ Examples, Figures, and Table: The distinction between formal and informal elements is that formal elements have titles while informal ones do not. Equation: Informal equations don't have titles. For reasons of backwardcompatibility, Equations are not required to have titles. However, it may be more difficult for some stylesheet languages to properly enumerate Equations if they lack titles. ] Those passages as well as the sentences from elements/equation/db.equation.xml mentioned in the initial bug report should be reformulated to reflect the neatly settled situation once this bug here in focus is fixed. For example equations are not only not required to have titles because of backwardcompatibility, but now also because of having the possibility of numbering of equations for which no title can be imagined and where titles would be completely misplaced overhead, and at least for the docbookxsl stylesheets all problems will be gone in the near future:) (Btw., to ensure perfect symmetry for equation, table, figure, example regarding formal versus informal, one should make the title optional not only for equation but also for table, figure and example, but perhaps this change is not so easily done, too late in the process. Well, only an idea.) Thank you for your patience, I hope now everything is cleary explained.  Comment By: Robert Stayton (bobstayton) Date: 20091113 01:07 Message: I would propose the following: a) equation elements are numbered, and informalequations are not. Use informalequation when no reference is to be made to the equation. This makes informalequation parallel with informaltable, informalfigure, etc. b) Include only equation elements in the List of Equations. If an equation has no title, then only the number is displayed with the page number. Currently only equations with titles appear in the TOC. c) Number all equation elements, whether they have a title or not. d) Add a stylesheet parameter to select the style of equation numbering. One style says "Equation 3.2. Optional title", placed above or below the equation. The other style uses "(3.2)" beside the equation, with the optional title above or below it (with no number).  You can respond by visiting: https://sourceforge.net/tracker/?func=detail&atid=373747&aid=2889817&group_id=21935 
From: SourceForge.net <noreply@so...>  20091207 00:59:53

Bugs item #2889817, was opened at 20091031 02:47 Message generated for change (Comment added) made by kbr You can respond by visiting: https://sourceforge.net/tracker/?func=detail&atid=373747&aid=2889817&group_id=21935 Please note that this message will contain a full copy of the comment thread, including the initial issue submission, for this request, not just the latest update. Category: XSL Group: output: HTML >Status: Pending Resolution: Fixed Priority: 5 Private: No Submitted By: Kai Brommann (kbr) Assigned to: Robert Stayton (bobstayton) Summary: informalequation in toe and numbering Initial Comment: TDGV0.0.25 for V5.0 states for the equation element: [Processing systems that number equations or build a table of equations at the beginning of a document may have difficulty correctly formatting documents that contain both equations with titles and equations without titles. You are advised to use informalequation for equations without titles.] Assuming this caveat doesn't say that such difficulty is a feature and not a bug, here is a detailed description of the problem: Informalequation doesn't have a title, so probably it makes no sense to have it included in the table of equations, instead only equations (which should have a title as quoted above, the title may be optional rather than required according to TDG nevertheless) are to be listed there. Otherwise the result is an empty row in the table of equations. More generally speaking, every time an informal equation is linked to, it should not be tried to include its title while linking, because it has not title. Perhaps it could be fixed by some customization layer, but if it's a bug it better should be fixed in the stylesheets directly. Directly related is the question of numbering, let's say you have in the same chapter equation1 with title1 equation2 with title2 informalequation1 informalequation2 informalequation3 then the numbering (displayed together with the respective element) should go as follows: Equation 1. Title1 Equation 2. Title2 (1) (2) (3) so equation and informalequation should have separate counters, and the equation is accompanied with the term Equation and its title (same as table and figure), while the informalequation should only have its number in parentheses or the like. The current (buggy) behaviour is: Equation 1. Title1 Equation 2. Title2 Equation 2. Equation 2. Equation 2. so for informalequations the counter of the equations is reused as well (but not incremented on the other hand), and the notexisting title is of course empty, so should not be tried to be displayed. Instead, while linking, the two types can easily be distinguished, the desired behaviour would process the input (see ...) as: (see Equation 1.Title1) versus (see (1)) For an actual example how it should be done, you can also see the dblatex tool please where it is done properly for pdf. Thanx for your effort. (no error messages, Xalan2.7.1 and docbookxslns1.75.2/xhtml1_1/chunk.xsl toolchain, no test document necessary, no customization layer)  >Comment By: Kai Brommann (kbr) Date: 20091207 00:59 Message: Regarding 2b1, TOE, or List of Equations: Ok, my fault, I first of all should have tested the standard .xsl. I can confirm that using [html/xhtml/xhtml1_1]/docbook.xsl both work. But [html/xhtml/xhtml1_1]/chunk.xsl do not work yet. And the latter is what I use, so I directly had jumped at my usecase. Wild guess: In html/autotoc.xsl I can find your mentioned patch about select=".//equation[title or info/title]"/> But probably the fix is still missing in the chunk versions. I tried to patch manually in chunkcommon.xsl and [html, xhtml, xhtml1_1]/chunktoc.xsl but without immediate effect. >>>Are you using a customization, by any chance? yes, for the record at the moment it runs like: <?xml version="1.0" encoding="utf8"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"; version="1.0"> <xsl:import href="xhtml1_1/chunk.xsl"/> <xsl:template name="user.preroot"> <xsl:text disableoutputescaping="yes"><?xmlstylesheet type="text/xsl" href="xsl/mathml.xsl"?> </xsl:text> </xsl:template> <xsl:param name="local.l10n.xml" select="document('')"/> <xsl:variable name="html.stylesheet">xsl/docbook.css</xsl:variable> <xsl:param name="html.ext" select="'.xhtml'"/> <xsl:param name="use.extensions" select="'1'"/> <xsl:param name="formal.title.placement"> equation after </xsl:param> <xsl:param name="callout.graphics.path" select="'img/callouts/'"/> <xsl:param name="callout.graphics" select="'1'"></xsl:param> <xsl:param name="callouts.extension" select="'1'"></xsl:param> <xsl:param name="callout.graphics.extension" select="'.png'"></xsl:param> <xsl:param name="callout.defaultcolumn" select="'58'"/> </xsl:stylesheet> but probably this is not the cause of the TOE problem, since the error for chunk still occurs without customization as well. >>>Regarding the customization issues: ... there is now a separate template named "equation.without.title" Very good, I didn't know this. Ok, but if I search for the template like find $DOCBOOK_SVN/xsl name "*"  xargs grep "equation.without.title" up to now only in xsl/fo/formal.xsl I can find the new template and two calls to it. Am I missing something, or should the template by default also be used in the (x)html stylesheets, so that overriding the template would have an effect? Or should I use something like <xsl:param name="local.l10n.xml" select="document('')"/> <l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">; <l:l10n language="en"> <l:context name="title"> <l:template name="equation.without.title" text="(%n)"/> </l:context> <l:context name="xref"> <l:template name="equation.without.title" text="(%n)"/> </l:context> </l:l10n> </l:i18n> ?! well, anyway adding this snippet to my customization .xsl did not work out of the box, perhaps I can tweak it a little bit more. But as stated above, I would first of all expect the new template to be mentioned in the (x)html area for the customization being able to work. Or am I on the wrong track?  Comment By: Robert Stayton (bobstayton) Date: 20091206 18:55 Message: Regarding 2a, I'm not able to duplicate the problem of equations without titles appearing in the List of Equations. The code in 1.75.2 selects them as follows: <xsl:calltemplate name="list.of.titles"> <xsl:withparam name="titles" select="'equation'"/> <xsl:withparam name="nodes" select=".//equation[title or info/title]"/> </xsl:calltemplate> The nodes it selects must have a title. My output LOE does not include equations without titles. Are you using a customization, by any chance? Regarding the customization issues, I think there are sufficient opportunities for custization of links and formatting to enable variations that different people need. For example, there is now a separate template named "equation.without.title" that can be customized to handle that case, and links can be customized using the parameter 'local.l10n.xml' as with other gentext.  Comment By: Kai Brommann (kbr) Date: 20091205 21:31 Message: 1) Due to the missing snapshots, I took it as a challenge and decided to build one on my own, following the instructions in: https://docbook.svn.sourceforge.net/svnroot/docbook/trunk/xsl/README.BUILD so I checked out from the svn repository the modules: xsl buildtools gentext but in the 'make all' step the following error occurred: Makefile:4: $DOCBOOK_SVN/releasetools/Variables.mk: No such file or directory Makefile:115: $DOCBOOK_SVN/releasetools/Targets.mk: No such file or directory Makefile:116: $DOCBOOK_SVN/releasetools/xslns.mk: No such file or directory make: *** No rule to make target `$DOCBOOK_SVN/releasetools/xslns.mk'. Stop. which was easily fixed by simply also checking out releasetools (so either something should be done to remove this dependency on releasetools for a developeronly build, or the instructions need to be updated). Then I ran into errors like: Cannot read config: ~kbr/.xmlc Well, in some files one finds [Where is the config file? Defaults to ~/.xmlc] so probably the instructions should talk about .xmlc instead of .xmlrc at leeast renaming the file accordingly did the magic, the build finally worked successfully. One minor comment: in the instructions, the mentioned thirdparty software versions are a little bit outdated perhaps, instead of xalan2.7.0.jar jaxp1.3.jar xmlcommonsresolver1.1.jar I used xalan2.7.1 jaxp2.2ea xmlcommonsresolver1.2.jar so while we are at it, this could be updated as well (always use the latest and greatest). 2.) a.)Now for the docbook stylesheet bug in focus, I can confirm noticable improvements: the numberings of equations without title now are also incremented as they should it is no longer tried to display a title which is not existing, neither during linking by xref nor beside the equation b.)but I feel we are not completely done yet: b1.)in the table of equations TOE, still the equations without title are displayed, some part looks like: 9.1. Euler formula 9.2. 11.1. RiemannHurwitz identity 11.2. Frobenius formula 11.3. 11.4. 11.5. 13.1. BakerCampbellHausdorff formula which is already an improvement (before the fix, numbers were not incremented for equations without title), but I think the final goal should be: 9.1. Euler formula 11.1. RiemannHurwitz identity 11.2. Frobenius formula 13.1. BakerCampbellHausdorff formula b2.) the appearance of the links to equations without title now is something like ... that the following diagram (Equation 11.4) ... (please note that while the DocBook element is named equation, actually it is ment to be used for general mathematical expressions of all kinds, which can well be just a term or a MathML diagram, no equals sign in sight in this case) and beside the equation without title now we have as XHTML page source (for example using a MathML input): </p><div class="equation"><a xmlns:saxon="http://icl.com/saxon"; id="commutingdiagram" /><div class="equationcontents"> <mml:math xmlns="http://docbook.org/ns/docbook"; xmlns:mml="http://www.w3.org/1998/Math/MathML"; xmlns:xlink="http://www.w3.org/1999/xlink"; overflow="scroll"> ... </mml:math> </div><p class="title">Equation 11.4. </p></div><p><br class="equationbreak" /> </p> This is already quite ok, it is overall consistent as it is. We are now talking about matters of taste. There are use cases where the above behaviour is exactly what one would like to have, in other circumstances it is still a little bit to heavyweight. Probably what one would need, is a stylesheet parameter where the appearance of links to as well as what is displayed accompanying the equation can be customized, (now comes the important point:) depending on if a title is present or not. It should be treated as if there would be two separate docbook elements. Then the default setting can stay as is now, and if desired (just for nonexisting titles) in linking and besides the equation: Equation 11.4. could be changed into (11.4) [it is sort of a function, input the number, output = (input) so one would definitely not want to map Equation to ( and . to ) or the like :)] Conclusion: If issue 2.)a.) TOE is also repaired, the status of the bug can be set from pending to closed. If there is some spare time left, then some customization options targetting only the equations without titles would be appreciated, to achieve (11.4) instead of Equation 11.4., but perhaps it would mean a too invasive hack into the stylesheets. Or it is already possible to customize as described (without affecting the equations with title), but I don't know how, then please tell how. Thanx for your fix, we are almost there. P.S.: it was a good idea to ask about the issue on the docbookapps mailing list, we got some positive feedback I think. Actually I already had posted the problem some years ago (instead of creating a bug report): http://lists.oasisopen.org/archives/docbookapps/200605/msg00096.html http://lists.oasisopen.org/archives/docbookapps/200605/msg00148.html but without a reaction (sigh). Finally I ended up with inventing titles just to avoid the issue. Now we are on a good way to solve the problem.  Comment By: Robert Stayton (bobstayton) Date: 20091202 07:17 Message: I checked in the files to implement the changes. They will appear in the next snapshot build, but it seems that snapshot builds are not currently happening.  Comment By: Robert Stayton (bobstayton) Date: 20091202 07:17 Message: A fix for this issue has been added to the current codebase. Please test the fix with the latest snapshot from: http://docbook.sourceforge.net/snapshots/  Comment By: Kai Brommann (kbr) Date: 20091115 22:25 Message: 1 Thank you for your comment. 2 Now that I have had a second look at my bug report, it appears to me that instead of talking about informalequations I already the whole time was actually targeting the equation without title(!). I have run some tests, the informalequations behave already as they should, and the equations without titles are the buggy ones. Ok, I hope the audience can follow this reformulation, I think I shouldn't change the title of the initial bug report though because otherwise everybody gets completely confused ... 3 A quick journey to the bookshelf reveals that various numbering schemes are in use, some use the same single counter for table, figure, equation, example, while others use separate counters even for formal equations with title versus minor equation without title but with a reference number, and other books simply don't support numbering of equations without titles, so let's divide the bug into parts: there is an inconsistent behaviour of the stylesheets regarding equations without titles, they should not appear in the TOE and the numbering should not conflict with that of the equations with titles, and there is then furthermore the question if separate counters are used or the same counter. I proposed the first solution (which is what dblatex has chosen to do), while you prefer the latter. Both solutions are ok with me, the main point is only that any obvious present inconsistency in html is repaired. 4 So your proposed solution is also completely fine with me: >>I would propose the following: >>a) equation elements are numbered, and informalequations are not. Use >>informalequation when no reference is to be made to the equation. This >>makes informalequation parallel with informaltable, informalfigure, etc. Yes, agreed. As stated above I actually was complaining about the equations without title and not the informalequations. Today the informalequations look already ok to me. The parallelism is a good point to mention. >>b) Include only equation elements in the List of Equations. If an >>equation has no title, then only the number is displayed with the page >>number. No, here I would like to disagree. I would like to have only the equations with title be included in the List Of Equations, and the equations without title being omitted (as well as the informalequations). Those nearly empty rows in the TOE should go away. Perhaps it is only a customization thing, then how to accomplish it? But as far as I can tell, the default behaviour should be to omit those empty lines from the TOE, without need for customization. >>> Currently only equations with titles appear in the TOC. No, I think at the moment also the equations without title appear in the TOE, and this should be changed. Perhaps here you were irritated by the initial problem of my post, in that I pretended to talk about informalequation while actually mentally I wasn't :) >>c) Number all equation elements, whether they have a title or not. Yes >>d) Add a stylesheet parameter to select the style of equation numbering. >>One style says "Equation 3.1. Optional title", placed above or below the >>equation. The other style uses "(3.1)" beside the equation, with the >>optional title above or below it (with no number). Hm, perhaps yes, but probably not quite. what I would like to have a heavyweight: Equation 3.1 Title Einstein Formula E = mc^2 placed above or below, only for equations which have a title, and a lightweight a + b = c (3.1) beside the equation, without any Equation term, and without any title display, not together with the equation, and as well not in linking by xref linkend = xml:id to it, for equations without a title, but those two procedures be working at the same time. Now I don't know if you also intended this or rather not. So it should be possible to have those two different styles be switched on at the same time, depending on if a title is present or not. I I read your comment correctly, you instead only propose to offer a stylesheet parameter exclusively choosing between the two styles, while I have a simultanious scenario in mind. Perhaps this is too much to ask for, well I dare... [ Additional information: I have already the following .xsl stylesheet for producing .xhtml: <xsl:param name="formal.title.placement"> equation after </xsl:param> and in my .css: .equation .title { margintop: 0; marginleft: 20px; float: left; backgroundcolor: #00AABB; } but now how shall I specify the two different styles for equation only dependent on if a title is there or not? I am a complete newbie regarding stylesheet parameters... but at least I have tried. ]  For full clarity, let's link to a publicly visible neutral unbiased thirdparty webpage showing the problem: http://dblatex.sourceforge.net/ (produced using content="DocBook XSL Stylesheets V1.72.0, which means no difference to 1.75.2 in the discussion here) There is an equation with a title followed by an equation without a title, and we have in the .html TOE (table of equation): [ List of Equations 3.1. Simple Formula 3.1. ] and everybody will admit that there are two problems: the 3.1 is doubled, if at all it should be 3.1 and 3.2, and since the second item anyway doesn't have a title it should not appear in the TOE in my opinion anyway. Equations without titles are lightweight components with no meaning outside of their context, they only have a number so they can be referenced in the nearby text. The reader looking for 3.2 can go to chapter 3, this is already indicated by the number, that is enough. In the TOE only equations with generally known or understandable titles should be shown. Normally in a mathematical proof or something, one would have let's say twenty minor equations without title, being inserted one into another as the proof goes along, finally leading to one famous equation with title. Only the famous equation into the TOE please:) Rather stylesheet than customization sort of thing it seems to me, by the nature of matters. Besides, when we go to the corresponding chapter, there is a link to the equation without title, looking like: [ The formula Equation 3.1, "" below: Equation 3.1. ... ] it looks like the ugly "" indicates a title was tried to be displayed, but the title is empty, so it should not have been tried, instead the link should be displayed as [ The formula (3.1) below: ... ] if separate counters for equations with and without titles would be used, or since we have agreed that using the same counter is equally valid, the counter is incremented and it should be displayed as [ The formula (3.2) below: ... ] Hereby pay attention that for equations without title the announcement proclamation [ Equation 3.1. ] in front of or below the equation should be gone at all. (This should be settled in the stylesheets directly rather than be done by a customization, depending on if the title is set or not. If done by a stylesheet parameter, how to do it? But default stylesheet is better.)  TDG V0.0.25 [tdg5/en/html/ch02.html] or svn repository [trunk/defguide5/en/src/ch02.xml] should be updated to state clearly that formal means 'with numbering enabled' rather than 'with title'. At the moment it reads: [ Examples, Figures, and Table: The distinction between formal and informal elements is that formal elements have titles while informal ones do not. Equation: Informal equations don't have titles. For reasons of backwardcompatibility, Equations are not required to have titles. However, it may be more difficult for some stylesheet languages to properly enumerate Equations if they lack titles. ] Those passages as well as the sentences from elements/equation/db.equation.xml mentioned in the initial bug report should be reformulated to reflect the neatly settled situation once this bug here in focus is fixed. For example equations are not only not required to have titles because of backwardcompatibility, but now also because of having the possibility of numbering of equations for which no title can be imagined and where titles would be completely misplaced overhead, and at least for the docbookxsl stylesheets all problems will be gone in the near future:) (Btw., to ensure perfect symmetry for equation, table, figure, example regarding formal versus informal, one should make the title optional not only for equation but also for table, figure and example, but perhaps this change is not so easily done, too late in the process. Well, only an idea.) Thank you for your patience, I hope now everything is cleary explained.  Comment By: Robert Stayton (bobstayton) Date: 20091113 09:07 Message: I would propose the following: a) equation elements are numbered, and informalequations are not. Use informalequation when no reference is to be made to the equation. This makes informalequation parallel with informaltable, informalfigure, etc. b) Include only equation elements in the List of Equations. If an equation has no title, then only the number is displayed with the page number. Currently only equations with titles appear in the TOC. c) Number all equation elements, whether they have a title or not. d) Add a stylesheet parameter to select the style of equation numbering. One style says "Equation 3.2. Optional title", placed above or below the equation. The other style uses "(3.2)" beside the equation, with the optional title above or below it (with no number).  You can respond by visiting: https://sourceforge.net/tracker/?func=detail&atid=373747&aid=2889817&group_id=21935 
From: SourceForge.net <noreply@so...>  20091207 06:05:20

Bugs item #2889817, was opened at 20091030 19:47 Message generated for change (Comment added) made by bobstayton You can respond by visiting: https://sourceforge.net/tracker/?func=detail&atid=373747&aid=2889817&group_id=21935 Please note that this message will contain a full copy of the comment thread, including the initial issue submission, for this request, not just the latest update. Category: XSL Group: output: HTML Status: Pending Resolution: Fixed Priority: 5 Private: No Submitted By: Kai Brommann (kbr) Assigned to: Robert Stayton (bobstayton) Summary: informalequation in toe and numbering Initial Comment: TDGV0.0.25 for V5.0 states for the equation element: [Processing systems that number equations or build a table of equations at the beginning of a document may have difficulty correctly formatting documents that contain both equations with titles and equations without titles. You are advised to use informalequation for equations without titles.] Assuming this caveat doesn't say that such difficulty is a feature and not a bug, here is a detailed description of the problem: Informalequation doesn't have a title, so probably it makes no sense to have it included in the table of equations, instead only equations (which should have a title as quoted above, the title may be optional rather than required according to TDG nevertheless) are to be listed there. Otherwise the result is an empty row in the table of equations. More generally speaking, every time an informal equation is linked to, it should not be tried to include its title while linking, because it has not title. Perhaps it could be fixed by some customization layer, but if it's a bug it better should be fixed in the stylesheets directly. Directly related is the question of numbering, let's say you have in the same chapter equation1 with title1 equation2 with title2 informalequation1 informalequation2 informalequation3 then the numbering (displayed together with the respective element) should go as follows: Equation 1. Title1 Equation 2. Title2 (1) (2) (3) so equation and informalequation should have separate counters, and the equation is accompanied with the term Equation and its title (same as table and figure), while the informalequation should only have its number in parentheses or the like. The current (buggy) behaviour is: Equation 1. Title1 Equation 2. Title2 Equation 2. Equation 2. Equation 2. so for informalequations the counter of the equations is reused as well (but not incremented on the other hand), and the notexisting title is of course empty, so should not be tried to be displayed. Instead, while linking, the two types can easily be distinguished, the desired behaviour would process the input (see ...) as: (see Equation 1.Title1) versus (see (1)) For an actual example how it should be done, you can also see the dblatex tool please where it is done properly for pdf. Thanx for your effort. (no error messages, Xalan2.7.1 and docbookxslns1.75.2/xhtml1_1/chunk.xsl toolchain, no test document necessary, no customization layer)  >Comment By: Robert Stayton (bobstayton) Date: 20091206 22:05 Message: Ah, I missed the chunking version. I checked in the fix in chunkcommon.xsl so now only equations with title or info/title are included.  Comment By: Kai Brommann (kbr) Date: 20091206 16:59 Message: Regarding 2b1, TOE, or List of Equations: Ok, my fault, I first of all should have tested the standard .xsl. I can confirm that using [html/xhtml/xhtml1_1]/docbook.xsl both work. But [html/xhtml/xhtml1_1]/chunk.xsl do not work yet. And the latter is what I use, so I directly had jumped at my usecase. Wild guess: In html/autotoc.xsl I can find your mentioned patch about select=".//equation[title or info/title]"/> But probably the fix is still missing in the chunk versions. I tried to patch manually in chunkcommon.xsl and [html, xhtml, xhtml1_1]/chunktoc.xsl but without immediate effect. >>>Are you using a customization, by any chance? yes, for the record at the moment it runs like: <?xml version="1.0" encoding="utf8"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"; version="1.0"> <xsl:import href="xhtml1_1/chunk.xsl"/> <xsl:template name="user.preroot"> <xsl:text disableoutputescaping="yes"><?xmlstylesheet type="text/xsl" href="xsl/mathml.xsl"?> </xsl:text> </xsl:template> <xsl:param name="local.l10n.xml" select="document('')"/> <xsl:variable name="html.stylesheet">xsl/docbook.css</xsl:variable> <xsl:param name="html.ext" select="'.xhtml'"/> <xsl:param name="use.extensions" select="'1'"/> <xsl:param name="formal.title.placement"> equation after </xsl:param> <xsl:param name="callout.graphics.path" select="'img/callouts/'"/> <xsl:param name="callout.graphics" select="'1'"></xsl:param> <xsl:param name="callouts.extension" select="'1'"></xsl:param> <xsl:param name="callout.graphics.extension" select="'.png'"></xsl:param> <xsl:param name="callout.defaultcolumn" select="'58'"/> </xsl:stylesheet> but probably this is not the cause of the TOE problem, since the error for chunk still occurs without customization as well. >>>Regarding the customization issues: ... there is now a separate template named "equation.without.title" Very good, I didn't know this. Ok, but if I search for the template like find $DOCBOOK_SVN/xsl name "*"  xargs grep "equation.without.title" up to now only in xsl/fo/formal.xsl I can find the new template and two calls to it. Am I missing something, or should the template by default also be used in the (x)html stylesheets, so that overriding the template would have an effect? Or should I use something like <xsl:param name="local.l10n.xml" select="document('')"/> <l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">; <l:l10n language="en"> <l:context name="title"> <l:template name="equation.without.title" text="(%n)"/> </l:context> <l:context name="xref"> <l:template name="equation.without.title" text="(%n)"/> </l:context> </l:l10n> </l:i18n> ?! well, anyway adding this snippet to my customization .xsl did not work out of the box, perhaps I can tweak it a little bit more. But as stated above, I would first of all expect the new template to be mentioned in the (x)html area for the customization being able to work. Or am I on the wrong track?  Comment By: Robert Stayton (bobstayton) Date: 20091206 10:55 Message: Regarding 2a, I'm not able to duplicate the problem of equations without titles appearing in the List of Equations. The code in 1.75.2 selects them as follows: <xsl:calltemplate name="list.of.titles"> <xsl:withparam name="titles" select="'equation'"/> <xsl:withparam name="nodes" select=".//equation[title or info/title]"/> </xsl:calltemplate> The nodes it selects must have a title. My output LOE does not include equations without titles. Are you using a customization, by any chance? Regarding the customization issues, I think there are sufficient opportunities for custization of links and formatting to enable variations that different people need. For example, there is now a separate template named "equation.without.title" that can be customized to handle that case, and links can be customized using the parameter 'local.l10n.xml' as with other gentext.  Comment By: Kai Brommann (kbr) Date: 20091205 13:31 Message: 1) Due to the missing snapshots, I took it as a challenge and decided to build one on my own, following the instructions in: https://docbook.svn.sourceforge.net/svnroot/docbook/trunk/xsl/README.BUILD so I checked out from the svn repository the modules: xsl buildtools gentext but in the 'make all' step the following error occurred: Makefile:4: $DOCBOOK_SVN/releasetools/Variables.mk: No such file or directory Makefile:115: $DOCBOOK_SVN/releasetools/Targets.mk: No such file or directory Makefile:116: $DOCBOOK_SVN/releasetools/xslns.mk: No such file or directory make: *** No rule to make target `$DOCBOOK_SVN/releasetools/xslns.mk'. Stop. which was easily fixed by simply also checking out releasetools (so either something should be done to remove this dependency on releasetools for a developeronly build, or the instructions need to be updated). Then I ran into errors like: Cannot read config: ~kbr/.xmlc Well, in some files one finds [Where is the config file? Defaults to ~/.xmlc] so probably the instructions should talk about .xmlc instead of .xmlrc at leeast renaming the file accordingly did the magic, the build finally worked successfully. One minor comment: in the instructions, the mentioned thirdparty software versions are a little bit outdated perhaps, instead of xalan2.7.0.jar jaxp1.3.jar xmlcommonsresolver1.1.jar I used xalan2.7.1 jaxp2.2ea xmlcommonsresolver1.2.jar so while we are at it, this could be updated as well (always use the latest and greatest). 2.) a.)Now for the docbook stylesheet bug in focus, I can confirm noticable improvements: the numberings of equations without title now are also incremented as they should it is no longer tried to display a title which is not existing, neither during linking by xref nor beside the equation b.)but I feel we are not completely done yet: b1.)in the table of equations TOE, still the equations without title are displayed, some part looks like: 9.1. Euler formula 9.2. 11.1. RiemannHurwitz identity 11.2. Frobenius formula 11.3. 11.4. 11.5. 13.1. BakerCampbellHausdorff formula which is already an improvement (before the fix, numbers were not incremented for equations without title), but I think the final goal should be: 9.1. Euler formula 11.1. RiemannHurwitz identity 11.2. Frobenius formula 13.1. BakerCampbellHausdorff formula b2.) the appearance of the links to equations without title now is something like ... that the following diagram (Equation 11.4) ... (please note that while the DocBook element is named equation, actually it is ment to be used for general mathematical expressions of all kinds, which can well be just a term or a MathML diagram, no equals sign in sight in this case) and beside the equation without title now we have as XHTML page source (for example using a MathML input): </p><div class="equation"><a xmlns:saxon="http://icl.com/saxon"; id="commutingdiagram" /><div class="equationcontents"> <mml:math xmlns="http://docbook.org/ns/docbook"; xmlns:mml="http://www.w3.org/1998/Math/MathML"; xmlns:xlink="http://www.w3.org/1999/xlink"; overflow="scroll"> ... </mml:math> </div><p class="title">Equation 11.4. </p></div><p><br class="equationbreak" /> </p> This is already quite ok, it is overall consistent as it is. We are now talking about matters of taste. There are use cases where the above behaviour is exactly what one would like to have, in other circumstances it is still a little bit to heavyweight. Probably what one would need, is a stylesheet parameter where the appearance of links to as well as what is displayed accompanying the equation can be customized, (now comes the important point:) depending on if a title is present or not. It should be treated as if there would be two separate docbook elements. Then the default setting can stay as is now, and if desired (just for nonexisting titles) in linking and besides the equation: Equation 11.4. could be changed into (11.4) [it is sort of a function, input the number, output = (input) so one would definitely not want to map Equation to ( and . to ) or the like :)] Conclusion: If issue 2.)a.) TOE is also repaired, the status of the bug can be set from pending to closed. If there is some spare time left, then some customization options targetting only the equations without titles would be appreciated, to achieve (11.4) instead of Equation 11.4., but perhaps it would mean a too invasive hack into the stylesheets. Or it is already possible to customize as described (without affecting the equations with title), but I don't know how, then please tell how. Thanx for your fix, we are almost there. P.S.: it was a good idea to ask about the issue on the docbookapps mailing list, we got some positive feedback I think. Actually I already had posted the problem some years ago (instead of creating a bug report): http://lists.oasisopen.org/archives/docbookapps/200605/msg00096.html http://lists.oasisopen.org/archives/docbookapps/200605/msg00148.html but without a reaction (sigh). Finally I ended up with inventing titles just to avoid the issue. Now we are on a good way to solve the problem.  Comment By: Robert Stayton (bobstayton) Date: 20091201 23:17 Message: I checked in the files to implement the changes. They will appear in the next snapshot build, but it seems that snapshot builds are not currently happening.  Comment By: Robert Stayton (bobstayton) Date: 20091201 23:17 Message: A fix for this issue has been added to the current codebase. Please test the fix with the latest snapshot from: http://docbook.sourceforge.net/snapshots/  Comment By: Kai Brommann (kbr) Date: 20091115 14:25 Message: 1 Thank you for your comment. 2 Now that I have had a second look at my bug report, it appears to me that instead of talking about informalequations I already the whole time was actually targeting the equation without title(!). I have run some tests, the informalequations behave already as they should, and the equations without titles are the buggy ones. Ok, I hope the audience can follow this reformulation, I think I shouldn't change the title of the initial bug report though because otherwise everybody gets completely confused ... 3 A quick journey to the bookshelf reveals that various numbering schemes are in use, some use the same single counter for table, figure, equation, example, while others use separate counters even for formal equations with title versus minor equation without title but with a reference number, and other books simply don't support numbering of equations without titles, so let's divide the bug into parts: there is an inconsistent behaviour of the stylesheets regarding equations without titles, they should not appear in the TOE and the numbering should not conflict with that of the equations with titles, and there is then furthermore the question if separate counters are used or the same counter. I proposed the first solution (which is what dblatex has chosen to do), while you prefer the latter. Both solutions are ok with me, the main point is only that any obvious present inconsistency in html is repaired. 4 So your proposed solution is also completely fine with me: >>I would propose the following: >>a) equation elements are numbered, and informalequations are not. Use >>informalequation when no reference is to be made to the equation. This >>makes informalequation parallel with informaltable, informalfigure, etc. Yes, agreed. As stated above I actually was complaining about the equations without title and not the informalequations. Today the informalequations look already ok to me. The parallelism is a good point to mention. >>b) Include only equation elements in the List of Equations. If an >>equation has no title, then only the number is displayed with the page >>number. No, here I would like to disagree. I would like to have only the equations with title be included in the List Of Equations, and the equations without title being omitted (as well as the informalequations). Those nearly empty rows in the TOE should go away. Perhaps it is only a customization thing, then how to accomplish it? But as far as I can tell, the default behaviour should be to omit those empty lines from the TOE, without need for customization. >>> Currently only equations with titles appear in the TOC. No, I think at the moment also the equations without title appear in the TOE, and this should be changed. Perhaps here you were irritated by the initial problem of my post, in that I pretended to talk about informalequation while actually mentally I wasn't :) >>c) Number all equation elements, whether they have a title or not. Yes >>d) Add a stylesheet parameter to select the style of equation numbering. >>One style says "Equation 3.1. Optional title", placed above or below the >>equation. The other style uses "(3.1)" beside the equation, with the >>optional title above or below it (with no number). Hm, perhaps yes, but probably not quite. what I would like to have a heavyweight: Equation 3.1 Title Einstein Formula E = mc^2 placed above or below, only for equations which have a title, and a lightweight a + b = c (3.1) beside the equation, without any Equation term, and without any title display, not together with the equation, and as well not in linking by xref linkend = xml:id to it, for equations without a title, but those two procedures be working at the same time. Now I don't know if you also intended this or rather not. So it should be possible to have those two different styles be switched on at the same time, depending on if a title is present or not. I I read your comment correctly, you instead only propose to offer a stylesheet parameter exclusively choosing between the two styles, while I have a simultanious scenario in mind. Perhaps this is too much to ask for, well I dare... [ Additional information: I have already the following .xsl stylesheet for producing .xhtml: <xsl:param name="formal.title.placement"> equation after </xsl:param> and in my .css: .equation .title { margintop: 0; marginleft: 20px; float: left; backgroundcolor: #00AABB; } but now how shall I specify the two different styles for equation only dependent on if a title is there or not? I am a complete newbie regarding stylesheet parameters... but at least I have tried. ]  For full clarity, let's link to a publicly visible neutral unbiased thirdparty webpage showing the problem: http://dblatex.sourceforge.net/ (produced using content="DocBook XSL Stylesheets V1.72.0, which means no difference to 1.75.2 in the discussion here) There is an equation with a title followed by an equation without a title, and we have in the .html TOE (table of equation): [ List of Equations 3.1. Simple Formula 3.1. ] and everybody will admit that there are two problems: the 3.1 is doubled, if at all it should be 3.1 and 3.2, and since the second item anyway doesn't have a title it should not appear in the TOE in my opinion anyway. Equations without titles are lightweight components with no meaning outside of their context, they only have a number so they can be referenced in the nearby text. The reader looking for 3.2 can go to chapter 3, this is already indicated by the number, that is enough. In the TOE only equations with generally known or understandable titles should be shown. Normally in a mathematical proof or something, one would have let's say twenty minor equations without title, being inserted one into another as the proof goes along, finally leading to one famous equation with title. Only the famous equation into the TOE please:) Rather stylesheet than customization sort of thing it seems to me, by the nature of matters. Besides, when we go to the corresponding chapter, there is a link to the equation without title, looking like: [ The formula Equation 3.1, "" below: Equation 3.1. ... ] it looks like the ugly "" indicates a title was tried to be displayed, but the title is empty, so it should not have been tried, instead the link should be displayed as [ The formula (3.1) below: ... ] if separate counters for equations with and without titles would be used, or since we have agreed that using the same counter is equally valid, the counter is incremented and it should be displayed as [ The formula (3.2) below: ... ] Hereby pay attention that for equations without title the announcement proclamation [ Equation 3.1. ] in front of or below the equation should be gone at all. (This should be settled in the stylesheets directly rather than be done by a customization, depending on if the title is set or not. If done by a stylesheet parameter, how to do it? But default stylesheet is better.)  TDG V0.0.25 [tdg5/en/html/ch02.html] or svn repository [trunk/defguide5/en/src/ch02.xml] should be updated to state clearly that formal means 'with numbering enabled' rather than 'with title'. At the moment it reads: [ Examples, Figures, and Table: The distinction between formal and informal elements is that formal elements have titles while informal ones do not. Equation: Informal equations don't have titles. For reasons of backwardcompatibility, Equations are not required to have titles. However, it may be more difficult for some stylesheet languages to properly enumerate Equations if they lack titles. ] Those passages as well as the sentences from elements/equation/db.equation.xml mentioned in the initial bug report should be reformulated to reflect the neatly settled situation once this bug here in focus is fixed. For example equations are not only not required to have titles because of backwardcompatibility, but now also because of having the possibility of numbering of equations for which no title can be imagined and where titles would be completely misplaced overhead, and at least for the docbookxsl stylesheets all problems will be gone in the near future:) (Btw., to ensure perfect symmetry for equation, table, figure, example regarding formal versus informal, one should make the title optional not only for equation but also for table, figure and example, but perhaps this change is not so easily done, too late in the process. Well, only an idea.) Thank you for your patience, I hope now everything is cleary explained.  Comment By: Robert Stayton (bobstayton) Date: 20091113 01:07 Message: I would propose the following: a) equation elements are numbered, and informalequations are not. Use informalequation when no reference is to be made to the equation. This makes informalequation parallel with informaltable, informalfigure, etc. b) Include only equation elements in the List of Equations. If an equation has no title, then only the number is displayed with the page number. Currently only equations with titles appear in the TOC. c) Number all equation elements, whether they have a title or not. d) Add a stylesheet parameter to select the style of equation numbering. One style says "Equation 3.2. Optional title", placed above or below the equation. The other style uses "(3.2)" beside the equation, with the optional title above or below it (with no number).  You can respond by visiting: https://sourceforge.net/tracker/?func=detail&atid=373747&aid=2889817&group_id=21935 
From: SourceForge.net <noreply@so...>  20091210 20:47:45

Bugs item #2889817, was opened at 20091031 02:47 Message generated for change (Comment added) made by kbr You can respond by visiting: https://sourceforge.net/tracker/?func=detail&atid=373747&aid=2889817&group_id=21935 Please note that this message will contain a full copy of the comment thread, including the initial issue submission, for this request, not just the latest update. Category: XSL Group: output: HTML >Status: Closed Resolution: Fixed Priority: 5 Private: No Submitted By: Kai Brommann (kbr) Assigned to: Robert Stayton (bobstayton) Summary: informalequation in toe and numbering Initial Comment: TDGV0.0.25 for V5.0 states for the equation element: [Processing systems that number equations or build a table of equations at the beginning of a document may have difficulty correctly formatting documents that contain both equations with titles and equations without titles. You are advised to use informalequation for equations without titles.] Assuming this caveat doesn't say that such difficulty is a feature and not a bug, here is a detailed description of the problem: Informalequation doesn't have a title, so probably it makes no sense to have it included in the table of equations, instead only equations (which should have a title as quoted above, the title may be optional rather than required according to TDG nevertheless) are to be listed there. Otherwise the result is an empty row in the table of equations. More generally speaking, every time an informal equation is linked to, it should not be tried to include its title while linking, because it has not title. Perhaps it could be fixed by some customization layer, but if it's a bug it better should be fixed in the stylesheets directly. Directly related is the question of numbering, let's say you have in the same chapter equation1 with title1 equation2 with title2 informalequation1 informalequation2 informalequation3 then the numbering (displayed together with the respective element) should go as follows: Equation 1. Title1 Equation 2. Title2 (1) (2) (3) so equation and informalequation should have separate counters, and the equation is accompanied with the term Equation and its title (same as table and figure), while the informalequation should only have its number in parentheses or the like. The current (buggy) behaviour is: Equation 1. Title1 Equation 2. Title2 Equation 2. Equation 2. Equation 2. so for informalequations the counter of the equations is reused as well (but not incremented on the other hand), and the notexisting title is of course empty, so should not be tried to be displayed. Instead, while linking, the two types can easily be distinguished, the desired behaviour would process the input (see ...) as: (see Equation 1.Title1) versus (see (1)) For an actual example how it should be done, you can also see the dblatex tool please where it is done properly for pdf. Thanx for your effort. (no error messages, Xalan2.7.1 and docbookxslns1.75.2/xhtml1_1/chunk.xsl toolchain, no test document necessary, no customization layer)  >Comment By: Kai Brommann (kbr) Date: 20091210 20:47 Message: yes, works now as expected. thank you, so I set the status from pending to closed. bye  Comment By: Robert Stayton (bobstayton) Date: 20091207 06:05 Message: Ah, I missed the chunking version. I checked in the fix in chunkcommon.xsl so now only equations with title or info/title are included.  Comment By: Kai Brommann (kbr) Date: 20091207 00:59 Message: Regarding 2b1, TOE, or List of Equations: Ok, my fault, I first of all should have tested the standard .xsl. I can confirm that using [html/xhtml/xhtml1_1]/docbook.xsl both work. But [html/xhtml/xhtml1_1]/chunk.xsl do not work yet. And the latter is what I use, so I directly had jumped at my usecase. Wild guess: In html/autotoc.xsl I can find your mentioned patch about select=".//equation[title or info/title]"/> But probably the fix is still missing in the chunk versions. I tried to patch manually in chunkcommon.xsl and [html, xhtml, xhtml1_1]/chunktoc.xsl but without immediate effect. >>>Are you using a customization, by any chance? yes, for the record at the moment it runs like: <?xml version="1.0" encoding="utf8"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"; version="1.0"> <xsl:import href="xhtml1_1/chunk.xsl"/> <xsl:template name="user.preroot"> <xsl:text disableoutputescaping="yes"><?xmlstylesheet type="text/xsl" href="xsl/mathml.xsl"?> </xsl:text> </xsl:template> <xsl:param name="local.l10n.xml" select="document('')"/> <xsl:variable name="html.stylesheet">xsl/docbook.css</xsl:variable> <xsl:param name="html.ext" select="'.xhtml'"/> <xsl:param name="use.extensions" select="'1'"/> <xsl:param name="formal.title.placement"> equation after </xsl:param> <xsl:param name="callout.graphics.path" select="'img/callouts/'"/> <xsl:param name="callout.graphics" select="'1'"></xsl:param> <xsl:param name="callouts.extension" select="'1'"></xsl:param> <xsl:param name="callout.graphics.extension" select="'.png'"></xsl:param> <xsl:param name="callout.defaultcolumn" select="'58'"/> </xsl:stylesheet> but probably this is not the cause of the TOE problem, since the error for chunk still occurs without customization as well. >>>Regarding the customization issues: ... there is now a separate template named "equation.without.title" Very good, I didn't know this. Ok, but if I search for the template like find $DOCBOOK_SVN/xsl name "*"  xargs grep "equation.without.title" up to now only in xsl/fo/formal.xsl I can find the new template and two calls to it. Am I missing something, or should the template by default also be used in the (x)html stylesheets, so that overriding the template would have an effect? Or should I use something like <xsl:param name="local.l10n.xml" select="document('')"/> <l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">; <l:l10n language="en"> <l:context name="title"> <l:template name="equation.without.title" text="(%n)"/> </l:context> <l:context name="xref"> <l:template name="equation.without.title" text="(%n)"/> </l:context> </l:l10n> </l:i18n> ?! well, anyway adding this snippet to my customization .xsl did not work out of the box, perhaps I can tweak it a little bit more. But as stated above, I would first of all expect the new template to be mentioned in the (x)html area for the customization being able to work. Or am I on the wrong track?  Comment By: Robert Stayton (bobstayton) Date: 20091206 18:55 Message: Regarding 2a, I'm not able to duplicate the problem of equations without titles appearing in the List of Equations. The code in 1.75.2 selects them as follows: <xsl:calltemplate name="list.of.titles"> <xsl:withparam name="titles" select="'equation'"/> <xsl:withparam name="nodes" select=".//equation[title or info/title]"/> </xsl:calltemplate> The nodes it selects must have a title. My output LOE does not include equations without titles. Are you using a customization, by any chance? Regarding the customization issues, I think there are sufficient opportunities for custization of links and formatting to enable variations that different people need. For example, there is now a separate template named "equation.without.title" that can be customized to handle that case, and links can be customized using the parameter 'local.l10n.xml' as with other gentext.  Comment By: Kai Brommann (kbr) Date: 20091205 21:31 Message: 1) Due to the missing snapshots, I took it as a challenge and decided to build one on my own, following the instructions in: https://docbook.svn.sourceforge.net/svnroot/docbook/trunk/xsl/README.BUILD so I checked out from the svn repository the modules: xsl buildtools gentext but in the 'make all' step the following error occurred: Makefile:4: $DOCBOOK_SVN/releasetools/Variables.mk: No such file or directory Makefile:115: $DOCBOOK_SVN/releasetools/Targets.mk: No such file or directory Makefile:116: $DOCBOOK_SVN/releasetools/xslns.mk: No such file or directory make: *** No rule to make target `$DOCBOOK_SVN/releasetools/xslns.mk'. Stop. which was easily fixed by simply also checking out releasetools (so either something should be done to remove this dependency on releasetools for a developeronly build, or the instructions need to be updated). Then I ran into errors like: Cannot read config: ~kbr/.xmlc Well, in some files one finds [Where is the config file? Defaults to ~/.xmlc] so probably the instructions should talk about .xmlc instead of .xmlrc at leeast renaming the file accordingly did the magic, the build finally worked successfully. One minor comment: in the instructions, the mentioned thirdparty software versions are a little bit outdated perhaps, instead of xalan2.7.0.jar jaxp1.3.jar xmlcommonsresolver1.1.jar I used xalan2.7.1 jaxp2.2ea xmlcommonsresolver1.2.jar so while we are at it, this could be updated as well (always use the latest and greatest). 2.) a.)Now for the docbook stylesheet bug in focus, I can confirm noticable improvements: the numberings of equations without title now are also incremented as they should it is no longer tried to display a title which is not existing, neither during linking by xref nor beside the equation b.)but I feel we are not completely done yet: b1.)in the table of equations TOE, still the equations without title are displayed, some part looks like: 9.1. Euler formula 9.2. 11.1. RiemannHurwitz identity 11.2. Frobenius formula 11.3. 11.4. 11.5. 13.1. BakerCampbellHausdorff formula which is already an improvement (before the fix, numbers were not incremented for equations without title), but I think the final goal should be: 9.1. Euler formula 11.1. RiemannHurwitz identity 11.2. Frobenius formula 13.1. BakerCampbellHausdorff formula b2.) the appearance of the links to equations without title now is something like ... that the following diagram (Equation 11.4) ... (please note that while the DocBook element is named equation, actually it is ment to be used for general mathematical expressions of all kinds, which can well be just a term or a MathML diagram, no equals sign in sight in this case) and beside the equation without title now we have as XHTML page source (for example using a MathML input): </p><div class="equation"><a xmlns:saxon="http://icl.com/saxon"; id="commutingdiagram" /><div class="equationcontents"> <mml:math xmlns="http://docbook.org/ns/docbook"; xmlns:mml="http://www.w3.org/1998/Math/MathML"; xmlns:xlink="http://www.w3.org/1999/xlink"; overflow="scroll"> ... </mml:math> </div><p class="title">Equation 11.4. </p></div><p><br class="equationbreak" /> </p> This is already quite ok, it is overall consistent as it is. We are now talking about matters of taste. There are use cases where the above behaviour is exactly what one would like to have, in other circumstances it is still a little bit to heavyweight. Probably what one would need, is a stylesheet parameter where the appearance of links to as well as what is displayed accompanying the equation can be customized, (now comes the important point:) depending on if a title is present or not. It should be treated as if there would be two separate docbook elements. Then the default setting can stay as is now, and if desired (just for nonexisting titles) in linking and besides the equation: Equation 11.4. could be changed into (11.4) [it is sort of a function, input the number, output = (input) so one would definitely not want to map Equation to ( and . to ) or the like :)] Conclusion: If issue 2.)a.) TOE is also repaired, the status of the bug can be set from pending to closed. If there is some spare time left, then some customization options targetting only the equations without titles would be appreciated, to achieve (11.4) instead of Equation 11.4., but perhaps it would mean a too invasive hack into the stylesheets. Or it is already possible to customize as described (without affecting the equations with title), but I don't know how, then please tell how. Thanx for your fix, we are almost there. P.S.: it was a good idea to ask about the issue on the docbookapps mailing list, we got some positive feedback I think. Actually I already had posted the problem some years ago (instead of creating a bug report): http://lists.oasisopen.org/archives/docbookapps/200605/msg00096.html http://lists.oasisopen.org/archives/docbookapps/200605/msg00148.html but without a reaction (sigh). Finally I ended up with inventing titles just to avoid the issue. Now we are on a good way to solve the problem.  Comment By: Robert Stayton (bobstayton) Date: 20091202 07:17 Message: I checked in the files to implement the changes. They will appear in the next snapshot build, but it seems that snapshot builds are not currently happening.  Comment By: Robert Stayton (bobstayton) Date: 20091202 07:17 Message: A fix for this issue has been added to the current codebase. Please test the fix with the latest snapshot from: http://docbook.sourceforge.net/snapshots/  Comment By: Kai Brommann (kbr) Date: 20091115 22:25 Message: 1 Thank you for your comment. 2 Now that I have had a second look at my bug report, it appears to me that instead of talking about informalequations I already the whole time was actually targeting the equation without title(!). I have run some tests, the informalequations behave already as they should, and the equations without titles are the buggy ones. Ok, I hope the audience can follow this reformulation, I think I shouldn't change the title of the initial bug report though because otherwise everybody gets completely confused ... 3 A quick journey to the bookshelf reveals that various numbering schemes are in use, some use the same single counter for table, figure, equation, example, while others use separate counters even for formal equations with title versus minor equation without title but with a reference number, and other books simply don't support numbering of equations without titles, so let's divide the bug into parts: there is an inconsistent behaviour of the stylesheets regarding equations without titles, they should not appear in the TOE and the numbering should not conflict with that of the equations with titles, and there is then furthermore the question if separate counters are used or the same counter. I proposed the first solution (which is what dblatex has chosen to do), while you prefer the latter. Both solutions are ok with me, the main point is only that any obvious present inconsistency in html is repaired. 4 So your proposed solution is also completely fine with me: >>I would propose the following: >>a) equation elements are numbered, and informalequations are not. Use >>informalequation when no reference is to be made to the equation. This >>makes informalequation parallel with informaltable, informalfigure, etc. Yes, agreed. As stated above I actually was complaining about the equations without title and not the informalequations. Today the informalequations look already ok to me. The parallelism is a good point to mention. >>b) Include only equation elements in the List of Equations. If an >>equation has no title, then only the number is displayed with the page >>number. No, here I would like to disagree. I would like to have only the equations with title be included in the List Of Equations, and the equations without title being omitted (as well as the informalequations). Those nearly empty rows in the TOE should go away. Perhaps it is only a customization thing, then how to accomplish it? But as far as I can tell, the default behaviour should be to omit those empty lines from the TOE, without need for customization. >>> Currently only equations with titles appear in the TOC. No, I think at the moment also the equations without title appear in the TOE, and this should be changed. Perhaps here you were irritated by the initial problem of my post, in that I pretended to talk about informalequation while actually mentally I wasn't :) >>c) Number all equation elements, whether they have a title or not. Yes >>d) Add a stylesheet parameter to select the style of equation numbering. >>One style says "Equation 3.1. Optional title", placed above or below the >>equation. The other style uses "(3.1)" beside the equation, with the >>optional title above or below it (with no number). Hm, perhaps yes, but probably not quite. what I would like to have a heavyweight: Equation 3.1 Title Einstein Formula E = mc^2 placed above or below, only for equations which have a title, and a lightweight a + b = c (3.1) beside the equation, without any Equation term, and without any title display, not together with the equation, and as well not in linking by xref linkend = xml:id to it, for equations without a title, but those two procedures be working at the same time. Now I don't know if you also intended this or rather not. So it should be possible to have those two different styles be switched on at the same time, depending on if a title is present or not. I I read your comment correctly, you instead only propose to offer a stylesheet parameter exclusively choosing between the two styles, while I have a simultanious scenario in mind. Perhaps this is too much to ask for, well I dare... [ Additional information: I have already the following .xsl stylesheet for producing .xhtml: <xsl:param name="formal.title.placement"> equation after </xsl:param> and in my .css: .equation .title { margintop: 0; marginleft: 20px; float: left; backgroundcolor: #00AABB; } but now how shall I specify the two different styles for equation only dependent on if a title is there or not? I am a complete newbie regarding stylesheet parameters... but at least I have tried. ]  For full clarity, let's link to a publicly visible neutral unbiased thirdparty webpage showing the problem: http://dblatex.sourceforge.net/ (produced using content="DocBook XSL Stylesheets V1.72.0, which means no difference to 1.75.2 in the discussion here) There is an equation with a title followed by an equation without a title, and we have in the .html TOE (table of equation): [ List of Equations 3.1. Simple Formula 3.1. ] and everybody will admit that there are two problems: the 3.1 is doubled, if at all it should be 3.1 and 3.2, and since the second item anyway doesn't have a title it should not appear in the TOE in my opinion anyway. Equations without titles are lightweight components with no meaning outside of their context, they only have a number so they can be referenced in the nearby text. The reader looking for 3.2 can go to chapter 3, this is already indicated by the number, that is enough. In the TOE only equations with generally known or understandable titles should be shown. Normally in a mathematical proof or something, one would have let's say twenty minor equations without title, being inserted one into another as the proof goes along, finally leading to one famous equation with title. Only the famous equation into the TOE please:) Rather stylesheet than customization sort of thing it seems to me, by the nature of matters. Besides, when we go to the corresponding chapter, there is a link to the equation without title, looking like: [ The formula Equation 3.1, "" below: Equation 3.1. ... ] it looks like the ugly "" indicates a title was tried to be displayed, but the title is empty, so it should not have been tried, instead the link should be displayed as [ The formula (3.1) below: ... ] if separate counters for equations with and without titles would be used, or since we have agreed that using the same counter is equally valid, the counter is incremented and it should be displayed as [ The formula (3.2) below: ... ] Hereby pay attention that for equations without title the announcement proclamation [ Equation 3.1. ] in front of or below the equation should be gone at all. (This should be settled in the stylesheets directly rather than be done by a customization, depending on if the title is set or not. If done by a stylesheet parameter, how to do it? But default stylesheet is better.)  TDG V0.0.25 [tdg5/en/html/ch02.html] or svn repository [trunk/defguide5/en/src/ch02.xml] should be updated to state clearly that formal means 'with numbering enabled' rather than 'with title'. At the moment it reads: [ Examples, Figures, and Table: The distinction between formal and informal elements is that formal elements have titles while informal ones do not. Equation: Informal equations don't have titles. For reasons of backwardcompatibility, Equations are not required to have titles. However, it may be more difficult for some stylesheet languages to properly enumerate Equations if they lack titles. ] Those passages as well as the sentences from elements/equation/db.equation.xml mentioned in the initial bug report should be reformulated to reflect the neatly settled situation once this bug here in focus is fixed. For example equations are not only not required to have titles because of backwardcompatibility, but now also because of having the possibility of numbering of equations for which no title can be imagined and where titles would be completely misplaced overhead, and at least for the docbookxsl stylesheets all problems will be gone in the near future:) (Btw., to ensure perfect symmetry for equation, table, figure, example regarding formal versus informal, one should make the title optional not only for equation but also for table, figure and example, but perhaps this change is not so easily done, too late in the process. Well, only an idea.) Thank you for your patience, I hope now everything is cleary explained.  Comment By: Robert Stayton (bobstayton) Date: 20091113 09:07 Message: I would propose the following: a) equation elements are numbered, and informalequations are not. Use informalequation when no reference is to be made to the equation. This makes informalequation parallel with informaltable, informalfigure, etc. b) Include only equation elements in the List of Equations. If an equation has no title, then only the number is displayed with the page number. Currently only equations with titles appear in the TOC. c) Number all equation elements, whether they have a title or not. d) Add a stylesheet parameter to select the style of equation numbering. One style says "Equation 3.2. Optional title", placed above or below the equation. The other style uses "(3.2)" beside the equation, with the optional title above or below it (with no number).  You can respond by visiting: https://sourceforge.net/tracker/?func=detail&atid=373747&aid=2889817&group_id=21935 