Release Notes

New Features and Bugfixes in Publican 4.0

Laura Bailey

Red Hat
Documentation Team

Petr Bokoč

Red Hat
Documentation Team

Tomas Capek

Red Hat
Documentation Team

Zac Dover

Red Hat
Documentation Team

Laura Novich

Red Hat
Documentation Team

Dayle Parker

Red Hat
Documentation Team

David Ryan

Red Hat
Documentation Team

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 50-compatible templates

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

Publican 4 supports git for distributed sets. BZ#719832

Internal identifiers properly rendered in epub output

Previously, Publican handled ids in epub output suboptimally, resulting in paras without identifiers. Publican 4 now properly handles ids in epub output. BZ#875116

OPF manifest corrected for epub output

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

Unneeded files now left out of epub output

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

CSS styles corrected in epub output

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

Support navigation for docs without multi-page HTML format

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

Website now indicates when a translation is older than the document in the original language

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

Docbook 5 CSS Update

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

Sorting books by group

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

Improvements to XSL re: Docbook 5

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

Entities now expanded prior to validation

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

Install brand web content from RPM

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

Missing "registered character" in pdf Legal Notice now restored

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

Inaccurate error message when building with a wrong <programlisting> "language=" attribute

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

~/.publican.cfg doesn't work properly with non-ASCII characters

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

Subtitle rendering improved

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

Graphics in Internet Explorer 8 improved

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

Entities in attributes improved

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

Calling logger() no longer causes wide character error

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

First author duplicated in PDF output

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

Build.PL requires now listed

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

Builds from source install common content in correct location

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

Revision History improved

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

Screen tags, with wrapping enabled in pdf.xsl break the formatting of the screen output.

Several example commands have been adjusted in order to wrap correctly in the PDF version of the Publican User Guide. BZ#999581

keep-together.within.column attribute improved in pdf.xsl

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

Corrected OpenSUSE installation instructions

The OpenSUSE installation instructions included an incorrect command; this is now corrected. BZ#1000534

Publican print_unused incorrectly detects files from higher levels in the directory structure (but within the book) as unused.

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

Docbook 5 supported as input format

Publican 4 supports Docbook 5 as an input format. BZ#1005042

Identify table sizes with classes

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

Table of Contents text is overlapping with the dotted base line in PDF version

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 pdf format Copyright content is in bold, whereras it's not bold in html, html-single, epub format.

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 pdf output, headings format is not rendered properly.

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

"Edition x" on title page of translated PDF's appears in English, not the language of translation

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

The word "stichworter" ("keywords" in German) appears right after Legal Notice in PDF of translation.

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

Creating an xref to a <step> results in a dead link

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

img_dir not taken into account when locating icon.svg

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

Update Debian installation instructions

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

Add Docker installation instructions

The Publican Users' Guide now includes instructions for installing Publican in a Docker container. BZ#1015943

Build.PL does not compile .po files and doesn't install resulting .mo files

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

"edition" on the title page of docs is not styled

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

Cannot build Indic-language PDFs with Publican 3.99

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

Building Publican 4.0 in Fedora 19 throws undefined subroutine error

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

Stray characters in DocBook 5 output

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

Publican includes XML tags from <abstract> in %description and %post

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

UTF-8 name_label and product_label get mangled when rebuilding from SRPM

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

UTF-8 -- "Revision History" <title> garbled in translated revision histories in non-Latin scripts

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

[UTF-8] Doc group titles and descriptions on splash pages garbled in non-latin scripts

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

Broken styles in 3.99

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

More style changes in 3.99

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

Books that contain <refentry>s do not work

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

Clarify where relative paths are used in brand instructions

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

Minor fixes to Users' Guide

The Publican Users' Guide contained typos and other minor errors, now corrected. BZ#1000534

Minor fixes to Common Content

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

Clarify translation instructions

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

Expose glossterm in PO files

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

Readability statistics

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

Syntax highlighting now makes code comments light grey

Previously, comments in code samples were syntax-highlighted bright pink. Now, comments are highlighted in light grey. BZ#1030718

Newline sequences now properly escaped in translations

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