Release Notes
-------------
New Features and Bugfixes in Publican 4.0
Laura Bailey
Red Hat
Documentation Team
lbailey@redhat.com
Petr Bokoč
Red Hat
Documentation Team
pbokoc@redhat.com
Tomas Capek
Red Hat
Documentation Team
tcapek@redhat.com
Zac Dover
Red Hat
Documentation Team
zdover@redhat.com
Laura Novich
Red Hat
Documentation Team
lnovich@redhat.com
Dayle Parker
Red Hat
Documentation Team
dayparke@redhat.com
David Ryan
Red Hat
Documentation Team
dryan@redhat.com
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 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:
&PRODUCTVER;, 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: "2013-02-21" Publican 4
replaces this with the datetime format, like this:
2013-02-21 13:04:12 BZ#979846
Inaccurate error message when building with a wrong
"language=" attribute
The 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 element rendered incorrectly and was in
some places bigger than the preceding title. This has been fixed.
elements will now take their size from the preceding
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, 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 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 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 in %description and %post
Previously, Publican displayed the 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" 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
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:
, , , and