Bug 492021

Summary: PDF page breaks
Product: [Community] Publican Reporter: Dani Coulson <dcoulson>
Component: publicanAssignee: Jeff Fearn <jfearn>
Status: CLOSED CURRENTRELEASE QA Contact: Content Services Development <ecs-dev-list>
Severity: low Docs Contact:
Priority: low    
Version: 2.0CC: daobrien, mmcallis, publican-list
Target Milestone: ---Keywords: Documentation
Target Release: ---   
Hardware: All   
OS: Linux   
Whiteboard:
Fixed In Version: 0.45 Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2009-03-25 01:07:08 EDT Type: ---
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---

Description Dani Coulson 2009-03-24 19:53:34 EDT
Description of problem:
There is currently no way of controlling where page breaks occur in pdf. This is causing  a display issue to be reported, where steps have their corresponding screenshots displayed on the next page. I would like be able to control this so that I could either force page breaks or somehow tell publican to keep the text and image on the same page. This would make documents more user-friendly.


Version-Release number of selected component (if applicable):
publican-0.41-3.el5


How reproducible:
Always


Steps to Reproduce:
1. make pdf
2.
3.
  
Actual results:
page breaks are uncontrollable 

Expected results:
n/a

Additional info:
Please contact me if there is any additional information you require.
Comment 1 David O'Brien 2009-03-24 21:52:09 EDT
I'll second this. I've also had reviewers asking about all the white space and/or empty pages. Some of it can be explained (end of chapters, etc.), but having a "keep with next" attribute or something similar available would be a bonus.
Comment 2 Jeff Fearn 2009-03-24 21:59:03 EDT
Please include the SVN source location and the relevant page numbers in the PDF, so I can test this.
Comment 3 Dani Coulson 2009-03-24 22:08:44 EDT
https://svn.devel.redhat.com/repos/ecs/SolidICE/4.2

Installation_Guide

Pages 9-19
Comment 4 Jeff Fearn 2009-03-25 01:07:08 EDT
0. await the patched Publican (version 0.45).

It includes a change to the way steps inside procedures are presented. By default, all parts of a step are now kept together on a single page. NB: the presentation of listitems in orderedlists is unchanged.

Consequently, the fix is as follows.

1. the orderedlist becomes a procedure as follows
		<procedure>
			<step>
				<title>Execute the SolidICE Installer</title>
				<para>
					To run the SolidICE Installer, execute the required file: <filename>SolidIce_xxxxx.exe</filename>
				</para>
			</step>
			<step>
				<title>License File Import</title>
				<para>A valid license file may be provided either now or once the installation is complete. Click <guibutton>Browse</guibutton> to navigate to the location of the license file and then then click <guibutton>Next</guibutton>.</para>
				<figure id="license_file">
					<title>License File Import</title>
					<mediaobject>
						<imageobject>
							<imagedata fileref="images/license_file.png" format="PNG"/>
						</imageobject>
					</mediaobject>
				</figure>
			</step>
		</procedure>

2. no step in the procedure can be more than a page long.

If a procedure is longer than a page, the text of the procedure runs off the end of the page and is unreadable. Also, the images either don't appear or are pushed off to the next page in the way they currently are in ordered lists.

3. Can you guess who wrote that?
Comment 5 David O'Brien 2009-03-25 20:01:07 EDT
When you say "By default, all parts of a step are now kept together on a single page", does that mean there is a way to avoid that behaviour? I'm pretty sure I don't have any steps that are that long, but it seems that if I do these steps will now "break".

Point #2 indicates that a procedure cannot be longer than a page. I thought we were talking about steps, not procedures. It wouldn't take very much to have a procedure go longer than one page, especially with a screenshot in the middle of it.
Comment 6 Jeff Fearn 2009-03-25 20:23:24 EDT
(In reply to comment #5)
> When you say "By default, all parts of a step are now kept together on a single
> page", does that mean there is a way to avoid that behaviour? I'm pretty sure I
> don't have any steps that are that long, but it seems that if I do these steps
> will now "break".

You are correct, steps longer than a page will be broken in the PDF.

This is a limitation of FOP where you can't have keep together set and do page breaks.

This behaviour is unavoidable until FOP is fixed :(

> Point #2 indicates that a procedure cannot be longer than a page. I thought we
> were talking about steps, not procedures. It wouldn't take very much to have a
> procedure go longer than one page, especially with a screenshot in the middle
> of it.  

You are correct, #2 should read:

If a step is longer than a page the texts and images of that step will run off the end of the page and are no longer viewable.