Bug 999581

Summary:	Screen tags, with wrapping enabled in pdf.xsl break the formatting of the screen output.
Product:	[Community] Publican	Reporter:	Norman Dunbar <norman>
Component:	publican	Assignee:	Jeff Fearn 🐞 <jfearn>
Status:	CLOSED CURRENTRELEASE	QA Contact:	tools-bugs <tools-bugs>
Severity:	medium	Docs Contact:
Priority:	unspecified
Version:	future	CC:	aigao, rlandman
Target Milestone:	---
Target Release:	---
Hardware:	x86_64
OS:	Linux
Whiteboard:
Fixed In Version:	4.0.0	Doc Type:	Bug Fix
Doc Text:		Story Points:	---
Clone Of:		Environment:
Last Closed:	2013-12-19 02:46:24 UTC	Type:	Bug
Regression:	---	Mount Type:	---
Documentation:	---	CRM:
Verified Versions:		Category:	---
oVirt Team:	---	RHEL 7.3 requirements from Atomic Host:
Cloudforms Team:	---	Target Upstream Version:
Embargoed:

Description Norman Dunbar 2013-08-21 15:42:28 UTC

Description of problem:

In a book with numerous screen (and programlisting) tags, the Publican pdf.xsl default parameter to enable wrapping of long lines in these tags, breaks the formatting.

It appears to ignore linefeeds in the source for these tags, where I have a screen, for example, with a number of lines, which should be mono-spaced, the formatting is simply wrapped at the right margin of the screen's output in the pdf document. (Created with fop.)

The parameter is:

/usr/share/publican/xsl./pdf.xsl, line 97:

<xsl:attribute name="wrap-option">wrap</xsl:attribute>

The default setting affects the pdf rendering for the User Guide for Publican 3.2. With the setting on, section 1.2 Pull Quote Conventions, the first screen there shows the problem. The data are not correctly aligned as per a "ls" command's output.

Also highly visible in the installation on Linux details, section 1.1.5 OpenSuse. There are a number of steps detailed, step 2 "install the dependencies blah blah blah..." if you look at the screen output for the command "$ sudo zypper install perl-Config-Simple perl-DateTime \ perl-DateTime-Format-DateParse ...." you will notice that the Linux "continued on the following line" characters - '\' - are not at the end of the line. The formatting has been obliterated by the wrapping.

Turning wrapping off, by commenting line 97 in pdf.xsl resolves the problem. However, it then affects lines in screen or programlistings which the author expects to wrap.

I manually wrap my own lines, I admit, but the user guide, for example, doesn't. Turning this wrapping off will break existing manuals and books where the code lines or screen output is expected to automatically wrap.

Version-Release number of selected component (if applicable):

3.2.0

How reproducible:

Always - in some documents.

Steps to Reproduce:
1. Build Publican User Guide 3.2.0.
2. Examine the sections mentioned above.

Actual results:

screen output loses it's alignment and formatting and is simply wrapped within the pdf margins in the rendered pdf document. Line feeds are seemingly ignored on multi-line screen tags.

Expected results:

Screen output to be as per the source code for the document. If wrapping is enabled, wrapping should take account of the existing linefeeds and not delete them.

Additional info:

The fop processor was used to render the pdf. I am unable to use wkhtmltopdf at present as it doesn't format my pdfs correctly. (Indexes, for example.)

Comment 2 Jeff Fearn 🐞 2013-09-23 04:30:51 UTC

In my testing the Pull-quote conventions looks correct. The OpenSuse install instructions looks wrong.

I think the bug here is the XML is wrong (for values of what Publican expects).

Current XML:

         <screen><prompt>$</prompt> <command>sudo zypper install perl-Config-Simple perl-DateTime \
perl-DateTime-Format-DateParse perl-DBD-SQLite perl-DBI \
perl-File-Find-Rule perl-File-Which perl-HTML-Format \
perl-Locale-MakeText-Gettext perl-Template-Toolkit \
perl-Test-Deep perl-Test-Pod perl-XML-LibXSLT \
perl-YAML liberation-fonts</command></screen>

White space is not as expected.

Adjust 'command' tag:

         <screen><prompt>$</prompt> <command>sudo</command> <command>zypper</command> install perl-Config-Simple perl-DateTime \
perl-DateTime-Format-DateParse perl-DBD-SQLite perl-DBI \
perl-File-Find-Rule perl-File-Which perl-HTML-Format \
perl-Locale-MakeText-Gettext perl-Template-Toolkit \
perl-Test-Deep perl-Test-Pod perl-XML-LibXSLT \
perl-YAML liberation-fonts</screen>

White space as expected.

The ridiculously semantically correct:

          <screen><prompt>$</prompt> <command>sudo</command> <command>zypper</command> <parameter>install</parameter> <parameter>perl-Config-Simple</parameter> <parameter>perl-DateTime</parameter> \
<parameter>perl-DateTime-Format-DateParse</parameter> <parameter>perl-DBD-SQLite perl-DBI</parameter> \
<parameter>perl-File-Find-Rule</parameter> <parameter>perl-File-Which</parameter> <parameter>perl-HTML-Format</parameter> \
<parameter>perl-Locale-MakeText-Gettext</parameter> <parameter>perl-Template-Toolkit</parameter> \
<parameter>perl-Test-Deep</parameter> <parameter>perl-Test-Pod</parameter> <parameter>perl-XML-LibXSLT</parameter> \
<parameter>perl-YAML</parameter> <parameter>liberation-fonts</parameter></screen>

White space as expected.

Publican has always been coded so that putting a non-verbatim tag inside a verbatim tag, does not change the nature of the non-verbatim tag.

I edited the all the screens in this section to use the tags the way Publican expects them (example 2 style).

To ssh://git.fedorahosted.org/git/publican.git
   4d0e1ec..3e99549  HEAD -> devel

Comment 3 HSS Product Manager 2013-09-23 04:47:34 UTC

HSS-QE has reviewed and declined this request. QE for this bug will be handled by IED.

Comment 4 Norman Dunbar 2013-09-28 13:05:58 UTC

Jeff,

ok, I see, it's the fact that I've treated a long "command" as a single "command" rather than a command plus parameters - which actually makes a lot more sense. I just never thought of it that way. Silly me! :-) I shall change my markup accordingly, and do it right in future!

I'm sure I've had these problems with programlistings as well, and I know I haven't nested anything in those, but they are a long chunk of text between the opening and closing programlisting tags. I'll find an example and make sure it's working with wrap on and off.

Happy to close this bug as "not a bug" or even "user error" is necessary. Thanks.

Comment 5 Norman Dunbar 2013-09-28 13:07:52 UTC

PS. Re section 1.2 Pull Quote Conventions.

In the source I have, the layout of the directory listing example is column aligned - exactly like you would get in an "ls" output. In the rendered document (pdf) they are no longer column aligned. 

Norm.

Comment 6 Ruediger Landmann 2013-10-11 02:15:36 UTC

Confirmed fixed in publican-doc-3.9.9-0.fc19.t4.noarch