[publican-list] Revision numbers, Screen output and error messages in Publican 3.2.0

[Jeff Fearn]

Hi Norm,


On 08/21/2013 12:17 AM, Norman Dunbar wrote:
> Afternoon all,
>
> Well, it didn't take me long to hit a snag!
>
> REVISION NUMBERS:
>
> I tried to build an existing Publican book which has existed through a number of revisions. It seems that there have been changes in the revision history department. These I have found and corrected by simply adding a revision to the existing revision number - I changed "1.0" to "1.0-0". Not a major problem, as it turns out I only needed to change the very first one in the revision history!
>
> If I don't have this new format in the very first revision, the build barfs with the following error:
>
> revnumber (1.0) does not match the required format of '^([0-9.]*)-([0-9.]*)$/' at /usr/local/bin/publican line 725.
>
>
> The "add_revision" command will not work, same error, if the first revision number is not in the above format.
>
> Problem. It appears that the revision history is assumed to be in descending order from most recent revision at the top, to oldest revision at  the bottom. My books are the opposite way around. Is there a way to get publican to scan for the biggest revision number rather than finding the first one?
>
> When I add a revision number, and do not specify the --revnumber parameter, it finds the very first existing revision (1.0-0 in my case) and adds one to it to give 1.0-1 when the real revision was actually 3.2-0 and it should have added 3.2.1.
>
>
> Problem. When I use the --revnumber="3.2-1" parameter, I get it added at the very top, so my revision history is now out of sequence. Not a major problem, but again, is there a way to get Publican to add the new revision at the bottom rather than the top?
>
> Sorry, I'm not a Perl developer, I can sort of muddle though, so I'm unable to help in this problem. :-(

This is "working as intended" however unless you are building RPMs for your books it's not actually relevant. Please open a bug requesting the ability to allow oldest to newest order in the revision history.
  
>
>
> SCREEN OUTPUT:
>
> I build the user guide for 3.2 as follows:
>
> cd Publican-v3.2.0/Users_Guide
> publican build --langs=en-US --formats=pdf
>
> And let it run. It built quite happily but when I read it, there are problems with screen outputs.
>
> In section 1.2. Pull-quote Conventions there is a paragraph with the text "Output sent to a terminal is set in mono-spaced roman and presented thus:" above a screen/programlisting rendering. The rendering is all over the place, rather than being the two separate lines you intended.
>
> I reported this/a similar problem a while back and provided a fix as it was something that was really getting on my nerves with another of my books. (Jeff helped me track it down!)
>
> The following is extracted form my thread "Screen and Programlisting oddities in Publican 2.8" dated 15th March 2013:
>
> [extract]
> Found it! If I comment out the wrap-option attribute below, as shown, it works on my test chapter.
>
> <xsl:attribute-set name="monospace.verbatim.properties" use-attribute-sets="verbatim.properties monospace.properties">
>          <xsl:attribute name="text-align">start</xsl:attribute>
> <!--    <xsl:attribute name="wrap-option">wrap</xsl:attribute> -->
>          <xsl:attribute name="hyphenation-character">\</xsl:attribute>
> </xsl:attribute-set>
>
>
> So, comment out line 97 in pdf.xsl for Publican 2.8.
> [/extract]
>
> In Publican 3.0, the offending line is also 97 in Publican-v3.2.0/Users_Guide/blib/datadir/xsl/pdf.xsl.
>
> WARING: commenting this line out, as above, means that you have to manually "wrap" screen and programlistings to keep them within the boundaries of a pdf page. However, it does fix my screen problem - and makes the User Guide much better formatted!

Yeah FOP either overflows to the left of the frame or the bottom of the page, which is worse?

I'm happy to change this if you want to open a bug about it.
  
>
>
> ERROR MESSAGES:
>
> Also, when building, I see lots of these errors/warnings:
>
> Invalid property value encountered in keep-together.within-column="": org.apache.fop.fo.expr.PropertyException: file:/home/norman/Publican/Publican-v3.2.0/Users_Guide/build/en-US/xml/Users_Guide.fo:3629:48: No conversion defined ; property:'keep-together.within-column' (See position 3629:421)
>
>
> Also in my thread mentioned above, I "resolved" this by editing line 405 of pdf.xsl, which is part of the attribute set for example.properties. The line needs a value adding between "><" - from this:
>
> <xsl:attribute name="keep-together.within-column"></xsl:attribute>
>
> To this:
>
> <xsl:attribute name="keep-together.within-column">auto</xsl:attribute>

Again, happy to change this if you open a bug :)

Cheers, Jeff.

-- 
Jeff Fearn <jfearn at redhat.com>
Senior Software Engineer
Infrastructure Engineering & Development (AEU)
Red Hat Asia Pacific Pty Ltd
GPG: 0x0357E8F0