Re: [Firebird-docs] Document building toolset
On Mon, 15 Sep 2014 23:53:57 +0200, Paul Vinkenoog p...@vinkenoog.nl wrote: Hello Mark, I will do some more testing, but is it ok if I replace the files on firebirdsql.org (ALLJARS.ZIP and docbook-stylesheets.zip)? No, please don't. One of the reasons that some components are rather dated is that it took us quite some time to get everything working the way we wanted. New versions of the stylesheets, but especially new versions of Apache FOP, have often introduced incompatibilities. Is there a list of known incompatibilities? Not that I know of. But we did run into trouble after upgrading the DocBook stylesheets and/or Apache FOP. That's why I'm hesitant to upgrade for the sake of it, unless of course the benefits are worth the extra work it may cause us. What exactly are the rendering issues you encountered? I had some issues with specifying the width of columns in a segmentedlist as table. You mean, when tweaking XSLT templates or adding/adjusting xsl:params? Because segmentedlists don't support width attributes, AFAIK. At least not in DcoBook 4.5. I didn't delve to deeply, but the message I found mentioned a problem with an option that was added as a default when transforming a segmentedlist as a table. I mistakenly thought that would solve it; it didn't. It did however remove a number of warnings when building the wireprotocol documentation regarding that invalid option ;) A message on the docbook-xsl mailinglist seemed to suggest that was fixed in a newer version. Unfortunately that didn't fix it, so now I have changed it to a normal table (although it looks like the custom stylesheets apply some modifications for html tables that it doesn't do for CALS tables). That's possible. The templates in the custom stylesheets were created on an as-needed basis. If it fixed the immediate problem, the solution generally wasn't extended to related elements. Well, now I have to decide if I keep the CALS definition and update the xsl, or change it to a html definition. However if I look at all the changes between docbook-xsl 1.72 (the version used by the project) and docbook-xsl 1.78.1 then I am wondering if there isn't some other stuff we are missing. Maybe we do. I think the bottom line is: do we miss a great new feature or a fix for an annoying bug if we don't upgrade? If the answer is yes, we should make an effort to upgrade. But this involves building all the manuals and visually inspecting them to see if any weird stuff happens. If so, then we must adapt our custom stylesheets. If this turns out to be a lot of work, then we might be better off fixing that bug or adding that feature in our current custom set. I saw a number of changes in docbook-xsl that might remove the need to have some of the existing customizations (at least with regard to tables in FO). Either way, I'm willing to do my share of the work, but again, please let's not do it just for the sake of upgrading. For now I have changed back to the default jars and XSL. I understand that this might be time better spent on other stuff. I might revisit this in the future though. Mark -- Want excitement? Manually upgrade your production database. When you want reliability, choose Perforce. Perforce version control. Predictably reliable. http://pubads.g.doubleclick.net/gampad/clk?id=157508191iu=/4140/ostg.clktrk ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] Document building toolset
Hello Mark, I will do some more testing, but is it ok if I replace the files on firebirdsql.org (ALLJARS.ZIP and docbook-stylesheets.zip)? No, please don't. One of the reasons that some components are rather dated is that it took us quite some time to get everything working the way we wanted. New versions of the stylesheets, but especially new versions of Apache FOP, have often introduced incompatibilities. Is there a list of known incompatibilities? Not that I know of. But we did run into trouble after upgrading the DocBook stylesheets and/or Apache FOP. That's why I'm hesitant to upgrade for the sake of it, unless of course the benefits are worth the extra work it may cause us. What exactly are the rendering issues you encountered? I had some issues with specifying the width of columns in a segmentedlist as table. You mean, when tweaking XSLT templates or adding/adjusting xsl:params? Because segmentedlists don't support width attributes, AFAIK. At least not in DcoBook 4.5. A message on the docbook-xsl mailinglist seemed to suggest that was fixed in a newer version. Unfortunately that didn't fix it, so now I have changed it to a normal table (although it looks like the custom stylesheets apply some modifications for html tables that it doesn't do for CALS tables). That's possible. The templates in the custom stylesheets were created on an as-needed basis. If it fixed the immediate problem, the solution generally wasn't extended to related elements. However if I look at all the changes between docbook-xsl 1.72 (the version used by the project) and docbook-xsl 1.78.1 then I am wondering if there isn't some other stuff we are missing. Maybe we do. I think the bottom line is: do we miss a great new feature or a fix for an annoying bug if we don't upgrade? If the answer is yes, we should make an effort to upgrade. But this involves building all the manuals and visually inspecting them to see if any weird stuff happens. If so, then we must adapt our custom stylesheets. If this turns out to be a lot of work, then we might be better off fixing that bug or adding that feature in our current custom set. Either way, I'm willing to do my share of the work, but again, please let's not do it just for the sake of upgrading. Cheers, Paul Vinkenoog -- Want excitement? Manually upgrade your production database. When you want reliability, choose Perforce Perforce version control. Predictably reliable. http://pubads.g.doubleclick.net/gampad/clk?id=157508191iu=/4140/ostg.clktrk ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
Re: [Firebird-docs] Document building toolset
Hi Mark, I was working on the wireprotocol documentation and had some PDF rendering issues. So I looked at the toolset for building documentation, and I noticed that some of it is rather dated (for example the docbook-xsl and Apache FOP). In my local copy I have replaced docbook-xsl and FOP with the latest version. I haven't looked closely at all output yet, but apart from higher memory requirements and more verbose logging it seems to work. I didn't fully solve the rendering issue that triggered this, but it looks like some of the custom XSLs may need some tweaking. I will do some more testing, but is it ok if I replace the files on firebirdsql.org (ALLJARS.ZIP and docbook-stylesheets.zip)? No, please don't. One of the reasons that some components are rather dated is that it took us quite some time to get everything working the way we wanted. New versions of the stylesheets, but especially new versions of Apache FOP, have often introduced incompatibilities. Is there a special reason that you want to upgrade? Does the new version offer a feature you need, or fix a bug you suffer from? If yes, we can consider it, but we must make sure that the new version builds *all* our manuals (including the Release Notes) correctly in PDF, multi-page HTML and single-page HTML. What exactly are the rendering issues you encountered? Cheers, Paul Vinkenoog -- Want excitement? Manually upgrade your production database. When you want reliability, choose Perforce Perforce version control. Predictably reliable. http://pubads.g.doubleclick.net/gampad/clk?id=157508191iu=/4140/ostg.clktrk ___ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
