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 4.0.
Publican is available for download at https://fedorahosted.org/publican/.
The Publican User Guide is available at http://jfearn.fedorapeople.org/en-US/Publican/4.0/html/Users_Guide/index.html.
Publican 4 Release Notes
Docbook 5-compatible templates are now included in Publican. This makes it possible to consume Docbook 5 content from upstream projects. BZ#697366
Publican 4 supports git for distributed sets. BZ#719832
Previously, Publican handled ids in epub output suboptimally, resulting in paras without identifiers. Publican 4 now properly handles ids in epub output. BZ#875116
Previously, Publican epub's output generated an incorrect OPF file that listed the same file multiple times. Publican 4 now generates correct OPF files that list files correctly. BZ#875119
Previously, Publican caused the end-user to download files that were not needed in built documentation. Among other undesirable behaviors, this caused epub files to be larger than was necessary. In Publican 4, every file in the OEBPS directory is added to the manifest. This means that unused images are no longer included in epub files. BZ#875125
Publican 4 improves the presentation of CSS styles in epub format. This includes improved presentation of admonitions, screen tags, and program listings, as well as the removal of the web footer tag (which previously was injected into the epub, though it should not have been). BZ#883159
Previously, Publican 4 did not support navigation for documents without a multi-page HTML format (the "html" format, as opposed to the "html-single", "pdf", or "epub" formats). This threatened to cause problems with the incorporation of legacy and upstream documentation that existed in formats other than multi-page html. Publican 4 includes functionality that, in the absence of a multi-page html document, links to another of the supported formats (that is, "html-single", "pdf", or "epub"). (Probably in cases like this, a pdf of the document will be generated and will be linked to.) BZ#885916
Publican 4 includes a new feature that provides a notification when a translation is older than the document in the source language. For instance, if the English-language source is newer than the translated document you are reading, a notice will appear informing you that you are reading a translation of a document in the source language that is not the most current version. BZ#889031
Publican 4 fixes an issue that caused the author content (the author's name and organization and so on) to be left-aligned instead of centered. This was caused by improper handling of Docbook 5. Publican 4 ships a completely separate set of CSS and XSL for DocBook 5 books in a separate brand that gets installed as "common-db5". BZ#893199
Previously, Publican organized books only alphabetically. This made it impossible to sort books by category (for instance, "Reference" or "Administration"). Publican 4 allows you to sort books by group (for instance, "Reference" or "Administration"). BZ#901560
Previously, XSL for abstract and subtitle detection assumed that the "*info" element (as in Docbook 4) was the root node of the XML file (and not the "info" element (as in Docbook 5)). This caused tragic failure to bulid Docbook 5 content in Publican (with "publican build" and "publican package") and resulted in grotesque bastardization of the XSL path in the service of publishing upstream documentation. Publican 4 replaces the nasty XSL with beautiful Perl, and the commands "publican build" and "publican package" now work in a DocBook 5 book with the files "mainfile", "info_file", and "rev_file" specified. BZ#953675
Previously, when entities were used in a file (for instance, Book_info.xml) in this context: <productnumber>&PRODUCTVER;</productnumber>, the build failed with "Invalid format for version. Value (EMPTY) does not conform to constraint (^[0-9]) at /usr/bin/publican line 713." These errors appeared because the entities were not expanded before they were checked for validity. This was not a problem in Publican itself, but rather a problem in two modules used by Publican: "XML::Catalog" and "XML::TreeBuilder". Those two modules have been patched to expand entities prior to validity checks. Publican 4 now properly expands entities before they are checked for validity. BZ#963994
Previously, building a custom site required the installation of brand web content from the brand source. Publican 4 makes it possible to install brand web content from the installed RPMs. BZ#967664
Previously, in the Legal Notice section of pdf docs, the registered 'R in a circle' character was missing after registered names like 'Linux', 'Java', and so on. Publican 4 reworks the legal notice retrieval code and reworks the cover page templates and styles, and the 'R in a circle' character has been restored. BZ#970851
Previously, the update_date field in DUMP.xml listed only the date, like this: "<update_date>2013-02-21</update_date>" Publican 4 replaces this with the datetime format, like this: <update_date>2013-02-21 13:04:12</update_date> BZ#979846
The <programlisting language="*"> tag is no longer case-sensitive. The error message that results when an unrecognized language value is used has been edited to reflect this change. BZ#987059
It is now possible to use non-ASCII characters in the publican.cfg file. This allows for the display of names that require special characters. BZ#987325
Previously, the <subtitle> element rendered incorrectly and was in some places bigger than the preceding title. This has been fixed. <subtitle> elements will now take their size from the preceding <title> and will be adjusted accordingly. BZ#987431
Previously, viewing output rendered by publican caused graphics such as logos to remain invisible because Internet Explorer versions 8 and prior did not support SVG graphics. The branding pages have been changed to provide an alternative graphic extension to enable the logo to be visible. BZ#990823
Previously, Publican incorrectly dropped entities in some attributes (for instance, when an entity was in the url attribute of an ulink tag). This meant that, though the entity was present in the docbook source, it was not present in the built HTML. This was due to a bug in XML:Treebuilder. XML:Treebuilder has been patched, and Publican 4 no longer drops entities due to this bug. BZ#994686
Previously, calling logger() with unicode characters resulted in "Wide character in print at /usr/share/perl5/vendor_perl/Publican.pm line 1092, <FH> line 7." This no longer happens when logger() is called. BZ#996266
Previously, the name of the first author listed in the author group was duplicated on the front page of a book in the PDF format. This update ensures that the duplicates no longer occur when building books in PDF. BZ#996351
Previously, Build.PL had build requires that could not be determined simply by running "$ perl Build.PL". In Publican 4, if Build.PL is run when you have outstanding dependencies, an error message appears informing you of the dependencies and of how to remedy them. BZ#999259
Previously (in Publican 3.2.0), builds of Publican that had been built in the way described in the README file (that is, CPAN-based builds from source) used the brand files and pdf/xsl from the directory where the source code had been extracted and built, and not from /usr/share/publican (the anointed, "correct" location). ConfigData.pm was rewritten, and CPAN-based builds from source of Publican 4 now correctly install the xsl and Common Content files in /usr/share/publican. BZ#999427
Previously, the "publican add_revision" command only scanned for the first (topmost) revision number in the Revision_History.xml file and incremented the revision number by one. This behavior led to the wrong revision number being inserted in books where the revision history was present in a descending order, with new revisions being added to the bottom of the file instead of the top. Publican 4 introduces the "--rev_dir" parameter to the "add_revision" option, which can be set at the book or brand level. Setting this parameter to "asc" or "ascending" will cause Publican to scan the last revision present in the file instead of the first and insert a new revision to the bottom of the Revision_History.xml file. BZ#999578
Several example commands have been adjusted in order to wrap correctly in the PDF version of the Publican User Guide. BZ#999581
In previous versions of Publican, the pdf.xsl definition file was missing a value for the "keep-together.within.column" attribute, which caused multiple error messages to be returned when building a PDF file. In Publican 4, this parameter has been set to "always" by default and no error messages are being displayed during the build. BZ#999586
The OpenSUSE installation instructions included an incorrect command; this is now corrected. BZ#1000534
Previously, the "publican print_unused" command was incorrectly detecting source files in higher-level directories as unused, even when these files were actually included in the book. In Publican 4, this issue has been fixed and XML files in higher levels of the document directory structure are being handled correctly by the command. BZ#1004955
Publican 4 supports Docbook 5 as an input format. BZ#1005042
Publican can now distinguish between tables of different sizes and apply different classes as necessary. This lets Publican apply more appropriate styles when drawing tables, such as drawing a thinner vertical line when more columns are present. BZ#1005640
In the PDF output format, the baseline dotted line rendered for tables of contents overlapped with the text around it, making the text harder to read. This update fixes the bug and the dotted line is displayed as expected, with no text overlapped. BZ#1006506
In the PDF output format, the content of the copyright note was incorrectly rendered in bold face. This update ensures the note is rendered properly. BZ#1006134
In the PDF output format, the English words in the headings were rendered in bold face whereas the localized content was not. This update ensures the headings are now rendered consistently with the localized content. BZ#1006135
Previously, the "Edition" string on the title page of a PDF book was always displayed in English, regardless of the language of the book. This update ensure the translated string is displayed as expected. BZ#1007141
Previously, if keywords were not supplied the section header "keywords" would appear in the PDF version. This was especially shown to happen in the German version. In Publican 4, the header will not appear when keywords are not supplied. BZ#1007146
Previously, building a publican document (HTML, PDF, etc.) using a link to a step within a procedure created a broken link that did not result in a 404 error. Now, it is possible to create links to steps within a procedure, provided the <step> has an ID. BZ#1009015
Previous versions of Publican were hard-coded to expect the icon.svg file in the images directory, even when the img_dir parameter specified a different directory. The path specified by the img_dir parameter is now taken into account. BZ#1011222
The Debian installation instructions published in previous versions of the Publican Users' Guide were out-of-date and potentially dangerous. The Guide now includes instructions based on the apt pinning mechanism. BZ#1013934
The Publican Users' Guide now includes instructions for installing Publican in a Docker container. BZ#1015943
Previous versions of Publican did not create or install the .mo files required for GNU gettext localization. This meant that neither the Publican user interface, nor some automatically generated content, were localized appropriately. Publican has been updated to create and install the .mo files as expected. BZ#1016421
Previously, the "edition" tag in documents was being displayed withoug any styling and justified to the left. In Publican 4, the edition is being displayed correctly in bold, centered text on the title page. BZ#1017548
Previously, when building a PDF book, using the "--langs mr-IN" option resulted in an error and the build process terminated. This bug has been fixed and Indic language PDFs are now built correctly. BZ#1018024
Previously, attempting to build Publican 4.0 from source failed on Fedora 19 because of incorrect use of pushd in the Build.PL script. This error has been corrected, and Publican 4.0 now builds correctly on Fedora 19. BZ#1018608
In a previous version of Publican, DocBook 5 books contained instances of stray "Ã" characters in html and html-single ouput where DocBook gentext had been used. This issue is resolved where Publican 4 now sets the correct Content-Type parameter. BZ#1018659
Previously, Publican displayed the <abstract> XML tag and any child tags in the %description and %post field of the book's spec file. This issue has been resolved in Publican 4, and the XML tags are no longer displayed with the text. BZ#1018796
Previously, if a book that had been translated into a language with a non-latin script was packaged, and then repackaged using the SRPM, the contents of the name_label and product_label parameters became mangled. This occurred because Publican was not handling UTF-8 characters correctly. Publican has been updated to deal correctly with UTF-8 characters, and repackaging books with non-latin scripts now works as expected. BZ#1020059
In a previous version of Publican, the the Revision_History.xml file created by Publican update_po could contain a garbled <title> in languages with a non-Latin script. This issue has been resolved in Publican 4. BZ#1020570
In a previous version of Publican, an issue existed where the group titles and descriptions could be garbled for languages written in a non-latin script. This issue is resolved in Publican 4. BZ#1022575
Previously, text formatted with several XML tags were rendered incorrectly by Publican. Publican 4 corrects rendering issues with the following XML tags so that they display correctly: <imageobject> , <textobject>, <package> , <example> and <option>. BZ#1023248
In a previous version of Publican, text formatted with <substep> , <stepalternative> , and <term> XML tags rendered incorrectly. Publican 4 restores the rendering of these XML tags to the correct formatting. BZ#1026173
A previous version of Publican attempted to chunk content inside a <refentry> tag. However, this directly conflicted with parts of xhtml-common such that chunking did not occur at all, and Publican ceased to work. Publican no longer attempts to chunk <refentry> content. BZ#1026563
Previous versions of the Publican Users' Guide contained a vague warning about using relative paths in custom XSL files. The warning has now been made more specific. BZ#1028815
The Publican Users' Guide contained typos and other minor errors, now corrected. BZ#1000534
The Document Conventions in the common content contained some minor inconsistencies in style, for example, hyphenation. The conventions are now more internally consistent. BZ#1027248
The Publican Users' Guide has been updated to clarify the suggested translation workflow. Specifically, the guide now describes how to use the publican drop_trans command to freeze content for translation. BZ#1021287
Publican now exposes the <glossterm> tag in PO files for translation. This allows translators to use the sortas attribute to fine-tune how this term will be sorted in a glosary. See the Publican Users' Guide for more information on how to use this attribute. BZ#1030591
Publican can now generate readability statistics on a book. Run the publican report on a book to generate Fog, Flesch, and Flesch-Kincaid statistics on the text. BZ#1031364
Previously, comments in code samples were syntax-highlighted bright pink. Now, comments are highlighted in light grey. BZ#1030718
Previously, Publican treated the newline escape sequences \n as normal text when it processed PO files. Therefore, if the sequence appeared in the msgstr, it would appear verbatim in the built output. Now, Publican properly escapes this sequence and does not build it into output. BZ#1036150