Release Notes ------------- New Features and Bugfixes in Publican 3.2 Laura Bailey Red Hat Engineering Content Services Zac Dover Red Hat Engineering Content Services Misha Husnain Ali Red Hat Engineering Content Services Rüdiger Landmann Red Hat Engineering Content Services Dayle Parker Red Hat Engineering Content Services Scott Radvan Red Hat Engineering Content Services Bruce Reeler Red Hat Engineering Content Services Gemma Sheldon Red Hat Engineering Content Services Copyright © 2013 Red Hat, Inc. This material may only be distributed subject to the terms and conditions set forth in the GNU Free Documentation License (GFDL), V1.2 or later (the latest version is presently available at http://www.gnu.org/licenses/fdl.txt). Abstract This document describes the enhancements and fixes included in Publican 3.2. Publican is available for download at https://fedorahosted.org/publican/. The Publican User Guide is available at http://jfearn.fedorapeople.org/en-US/Publican/3.2/html/Users_Guide/index.html. ------------------------------------------------------------------------ Swapped values now in the correct places Previously, the site stats report swapped the languages values and the products values. Languages values and products values are now in the correct places. Tags nested inside tags no longer disapper when publican creates .po files BZ #909728 Previously, tags nested inside tags disappeared during the creation of .po files. This meant that the source string and the translated string did not correspond to one another. A patch to Publican ensures that tags nested inside tags do not disappear during the creation of .po files. trans_drop command added BZ #887707 A new command, publican trans_drop, creates a snapshot of the source language for use in translation. extras.dir parameter added to publican.cfg BZ #953998 A new parameter, extras_dir, has been added to the publican.cfg file. extras_dir allows the user to override the default location of the "extras" directory. This functionality was previously provided by the extras/ directory. Duplicate sources no longer installed BZ #966143 Previously, brand installations caused duplications of css, images, and scripts sources. This caused installations of Publican to be larger than was necessary. A patch to Publican prevents the duplication of these sources. Installations of publican are now reduced in size. Broken CPAN link repaired BZ #973461 A broken link to CPAN describing supported highlighting values in Kate has been replaced with a link that is not broken. Users can now specify the image directory BZ #919481 A new parameter, image_dir has been added to the publican.cfg file. image_dir allows the user to specify which directory contains images. The default setting of image_dir is images. Revision History ID now correctly generated BZ #911462 Previously, the ID of the Revision History file was lost, which caused problems when xrefs linked to the Revision History. IDs for Revision_History.xml in translated books are now being generated correctly by publican, allowing the books to build. Incomplete language codes now mapped to existing translations BZ #844202 Previously, failure to specify the region in a language parameter (that is, en instead of en-US) caused Common Content to revert to en-US. This caused the Common Content file to fail to translate. Two-letter language codes are now mapped to existing translations in cases where there is no contention between existing translations. Default use of wkhtmltopdf can be overridden BZ #953728 Previously, Publican did not allow users to override the default use of wkhtmltopdf. wkhtmltopdf was the default, and if it was not installed, FOP would be used. It is now possible for a user to override this and choose which PDF tool to use, if both PDF tools are installed. Site JavaScript is now customizable BZ #956935 Previously, it was not possible to customize the site JavaScript in /usr/share/publican/sitetemplate/toc.js. A site parameter, toc_js, has been added, and brands are now allowed to ship template/ directory. It is now possible to customize site Javascript in /usr/share/publican/sitetemplate/toc.js. book_ver_list now exposed to products_index.tmpl and versions_index.tmpl BZ #962643 Previously, it was not possible to access the book formats in the product templates and in the version templates. book_ver_list is now exposed to products_index.tmpl and versions_index.tmpl. It is now possible to access book formats in the product templates and in the version templates. This makes it possible (for instance) to produce tables that provide links to documents in each available format. Chapter headings, section headings, and subsection headings are now different sizes BZ #924518 Previously, the common brand that was automatically installed with Publican did not use different sizes for chapter headings, section headings, and subsection headings. A patch to Publican adjusts the size of the chapter headings, section headings, and subsection headings to make it easier to determine how deeply nested a chapter, section, or subsection is. Case-insensitive language attributes on programlistings now supported BZ #919474 Previously, it was not possible to use case-insensitive "language" attributes on programlistings. This meant that upstream code was not always interoperable with publican (for instance, Publican did not accept because it expected ). The language attribute on programlistings is now case-insensitive. Publican generated faulty specfiles on Fedora 19 BZ #982424 The version of libmxl2 shipped in Fedora 19 ignores some whitespace in XSL templates that previous versions honoured. When Publican used its web-spec.xsl and dt_htmlsingle_spec.xsl and web-home-spec.xsl templates to generate RPM specfiles to package documents, the specfiles would be invalid because various parameters would not begin on new lines. The %post and %postun scriptlets were also sometimes corrupted because of missing whitespace. Packaging either did not work at all, or the packages caused unexpected results when installed on a Publican-maintained website. The XSL templates are now updated to move whitespace to where new libxml2 honours it to generate valid specfiles. Fixed typos in common content BZ #952490, BZ #974918 The common content files contained minor instances of incorrect grammar and unnecessary punctuation (such as exclamation marks in titles) in the Document Conventions and Getting Help and Giving Feedback" sections. The grammar issues are now corrected in Publican and the Red Hat brand. As a result, the common content now appears as expected within the preface of a Publican document. Stopped menu bouncing BZ #953716 Previously, when viewing a book on a web_style 2 site, the web site menu popped in and out when the mouse is moved off the browser, which is annoying. Now, the web site menu stays hidden until moused over. Fixed IDs missing from admonitions BZ #966494 Unlike most other XML elements, admonitions (such as warning, note and important elements) did not have an ID. As a result, linking to admonitions from other locations within the document or via a URL was not possible. This problem persisted event with an explicit admonition ID specified in the XML. This problem is now fixed so that admonition IDs appear in the html, whether they are explicitly set by the user or automatically generated. Corpauthor element supported for PDF covers BZ #908666 When building a book without an authorgroup and instead using a corpauthor, the PDF version of the book would fail to build with a author list can not be calculated before building error. This issue is now fixed and as a result, a book without only a corpauthor instead of an authorgroup builds the PDF version of the document as expected. Fixed multiple calls to update_po breaking packaging. BZ #891167 Running update_po multiple times resulted in duplicate entries in the translated Revision_History.xml if the source language Revision_History.xml was not updated first. This created revision numbers that were out of chronological order, and prevented books from being packaged. This has been fixed and version numbers in Revision_History.xml now increment correctly when running the update_po command multiple times. Added website labels and translations BZ #979885 English versions of localized strings were requested to be added to the Publican source code as part of trans_strings (available in templates) and labels.js (available in JavaScript). The strings were: Knowledge, Document, Document Language, Document Home and Product Documentation. The strings were added as a patch to the Publican source code and are now available. Add orgname to block/inline code BZ #872955 When generating PO files, the orgname information did not appear inline and broke the flow of the sentence, which resulted in translation diffulties. This is now fixed and the orgname information appears inline as expected and does not break the flow of the sentence. Fixed get_keywords not using correct info file BZ #957956 When the PDF version of a document is built after specifying an alternate book information file using the info_file parameter, a keyword list can not be calculated before building error displays and the build fails. This occurred because Publican referred to Book_Info.xml instead of the file specified using the info_file parameter to calculate the keyword list. This is now fixed and Publican builds the PDF using the file specified via info_file (if this parameter is used) and defaults to Book_Info.xml if info_file is not used. Improved web print CSS BZ #927513 Previously, books were unreadable in print preview due to the same CSS being used for both standalone print preview as well as web content. A separate CSS style sheet has been created for viewing content on web sites and as a result, print preview displays correctly. Fixed pre border in PDF BZ #905752 Code samples in PDF builds were not properly surrounded by border/shading. This update provides proper shading in PDF. Fixed EPUB DOCTYPE BZ #875129 Previously, EPUB books were published with XHTML 1.0 Strict DOCTYPE. With this update, EPUB files are now constructed with XHTML 1.1. Fixed step first child style BZ #971221 Using tags with an id allocated resulted in the associated anchor tag creating an empty line after the number. This formatting issue has been corrected. Fixed long link word wrap in PDF. BZ #923481 Previously, long URLs did not wrap correctly. This caused long links to extend far into the right margin of a page and push content to the left. Publican now wraps long URLs so they do not affect page format. Added pub_dir option to override publish directory BZ #830062 When publishing, a custom output directory can now be specified via the --pub_dir option. Removed show_unknown parameter and associated code BZ #915428 Certain XML tags caused Publican to display a warning. These warnings come from historical usage decisions made regarding these tags. Publican no longer gives a warning when these tags are encountered. Publican now supports all DocBook conditionals BZ #919486 Previously, Publican supported only the arch, lang, and conditional conditional attributes. Publican now supports the full list of DocBook 4 conditions: arch, condition, conformance, lang, os, revision, revisionflag, role, security, userlevel, and vendor. Also, profiling allowed only option to be set at a time, for example: arch: "i386" Now, Publican allows multiple conditions to be set on an element, with ; representing logical or. For example: arch: "i386;x86_64" Important Publican supports the lang attribute, but sets it implicitly when it builds a document and applies any localisations to its XML. Do not attempt to set this attribute in XML. Flag spaces in product number as invalid BZ #973895 Previously, building a document with a space in the product version information displayed a FOP error because Publican did not reject the invalid product version values. This is now fixed and Publican rejects product version values with a space and the build fails as expected. Standardized prompts in commands BZ #880456 Prompts ($) have been added to all commands in the Publican 3.0 Users' Guide. In addition, some screen output boxes contained more than one command in sequence. To avoid confusion, these have been fixed to display one command per screen output box. Updated web_formats publican.cfg info in User Guide BZ #839141 The Publican User Guide incorrectly advised specifying web formats by enclosing the entire parameter in quotation marks. This is fixed and the Publican User Guide now advises specifying web formats by enclosing only the values of the parameter in quotation marks (for example, web_formats: "html-single,pdf"). Replaced 'home page' with 'product or version page' BZ #921803 Publican 3.0 User Guide documentation incorrectly instructed the user to create a home page using the procedure described in Section 7.1.3. This has been corrected to instruct the user to create a product or version page. Fix PDF ignoring cover logo BZ #974353 Previously when building a .PDF file, Publican had to have a file named title_logo.svg in the /images folder, and would fall back to common content if the file was missing. This is fixed and now PDFs are generated with the title logo specified in Book_Info.xml. Fix empty pot files not being deleted BZ #961413 Previously, empty .PO files were produced when an XML file with no translatable content was present. Now Publican checks for content and if there is none, it does not create a .PO file. Fix long title layout on cover page in PDF BZ #956934 Previously in a generated .PDF file, a long title (>30chars) overlapped with the line separator between the title and subtitle. This has been fixed and long titles no longer overlap the separator. Added Mac OS X Lion installation instructions BZ #979229 The Publican User Guide now includes instructions for installing Publican on OS X version 7.2.3 (Lion). Add file handle limit workaround to FAQ BZ #952476 A workaround for situations in which the number of file handles open exceeds the default limit has been added to the FAQ in the Publican User's Guide. Fix UTF8 image names getting mangled in publish BZ #953618 Previously, file names that contained non-ASCII characters would cause Publican to print an "image missing" warning when trying to publish. This has been corrected so that non-ASCII characters in file names are processed correctly. Added wkhtmltopdf_opts parameter to pass options to wkhtmltopdf. BZ #951290 The wkhtmltopdf_opts parameter has been added to allow wkhtmltopdf command line arguments when building a book in PDF format. This allows users to specify page layout options, such as portrait or landscape. Fix edition missing on PDF cover pages BZ #956940 The edition value was not displayed in books. Publican has been updated to show this value on the cover and title pages only if specified. Support XML in add_revision member BZ #862465 Special characters in any add_revision member entries were replaced by entities and caused build errors. Publican has been updated, allowing the use and proper display of special characters in add_revision members. Fix duplicate footnotes in bibliography BZ #653447 Previously, a footnote in generated two entries in the HTML. This has been corrected so that the footnote only appears once. Fix Link from footlink to footlink-ref not working in PDF BZ #909786 Previously in a PDF, inline links within footnotes did not link back to the body text containing the footnote reference, however the book text correctly linked to the footnote. This fix enables these links to work in both directions. Fix TOC draft watermark in PDF BZ #905271 The draft watermark was not configured to display in a book's Table of Contents. Publican has been updated to ensure the watermark is displayed as a whole in each page, including in any Table of Contents. Add common-db5 sub package. BZ #958495 The publican-common-db5-web brand package has been added so that DocBook 5 brands can be used with Publican. BZ #958343 Previously, Publican resolved XML entities that appeared in CDATA blocks, causing them to be replaced. Publican no longer resolves XML entities that appear in CDATA blocks. Support decimals in colwidth and convert exact measures to pixels. BZ #913775 Previously, when defining a column width in a table using fractions of an inch, Publican was unable to process the parameter when publishing. As a result, Publican would render the table incorrectly using a of 100% instead. This update includes the ability to define a fractional column width and render tables as instructed. Tweak equation formatting BZ #804531 The equation and mathphrase tags appeared as left-aligned plain text, limiting their visibility. Publican has been updated to validate without warning and display any equation or mathphrase tags to stand out and appear different to plain text. Fix POT-Creation-Date format BZ #985836 Dates in PO translation files are generated by Publican to track file creation dates. Publican has been updated to display the creation dates in a format that complies with GNU convention. Fixed web_dir not used for home page packages BZ #988191 The web_dir parameter was introduced for Publican 3.1 to specify the default web directory location was not extended to web-home-spec.xsl resulting in the parameter not working for a web home package. This has been and web-home-spec.xsl now uses web_dir correctly. Updated web site instructions BZ #979224 The web site instructions for installing and updating Publican were outdated. These instructions have been brought up to date.