Request for Docs Freeze Extension for Serverguide

[Doug Smythies]

Hi,

I will just add:

In case anyone saw some serverguide merge proposal comments yesterday saying "Summary: We're trading PDF formatting for HTML formating"
Please know that Peter Petrakis and I sorted it out, and for how things are being done in the serverguide now, which is different than when the new chapter started (or so I am told), the fixes that give better table formatting in PDF versions have no effect on the HTML. I think this is important to understand. While not the perfect solution, we do have a way to have both the HTML and PDF versions have good looking tables.

And on this:
"... because fop is quite a tricky technology..." 
Oh my gosh, is it ever. It took me about ten hours to figure out the nested lists (such as a list within <screen>) fonts sizes issue. I find it very hard to follow.

Myself, I would like to get the warnings, errors, and other messages during PDF generation down to 0. Then maybe we could add a verify the PDF step before a merge proposal is submitted. The current root problem is some lines within <screen> things end up truncated in the PDF. The issue is that is it not clear from the warning if the PDF is actually truncated or not. I have not looked into it much yet, to see if there is somewhere to redefine when that warning is triggered.

The footnotes issue Peter mentioned is (evidently) a many years old problem, and the fixed version of fop is included in 12.04. It merely took time to trickle down to be included in Ubuntu. See also: https://bugs.launchpad.net/serverguide/+bug/957068 

The new issues we had the other day were relatively easy to sort out.

Hope this input helps.

Doug Smythies

-----Original Message-----
From: matthew.east at gmail.com [mailto:matthew.east at gmail.com] On Behalf Of Matthew East
Sent: March-22-2012 05:23
To: Peter Matulis
Cc: Ubuntu Doc; Doug Smythies
Subject: Re: Request for Docs Freeze Extension for Serverguide

[trimming the circulation list a bit]

On 22 March 2012 11:39, Peter Matulis <peter.matulis at canonical.com> wrote:
> On 12-03-22 04:04 AM, Matthew East wrote:
>> On 21 March 2012 19:19, Peter Matulis <peter.matulis at canonical.com> wrote:
>>> A small but important change is that we want to make the XML 
>>> validation step part and parcel of the actual build.  It was found 
>>> that some people were omitting this step which led to some 
>>> non-trivial headaches.  Anyone wanting to lend a hand in at least 
>>> validating existing material please head on over to:
>>
>> It should be enough that contributors use the validations script 
>> provided in the branch before submitting their branches, and that 
>> reviewers use the same script when merging branches. I'm very happy 
>> to take care of any validation errors that remain by this weekend.
>
> Why not make it part of the build process itself?  It's one less 
> command to type and it could have really helped in the last few days.

Ok, if it is thought to help, no problem. If contributors are building html or pdf as part of their testing procedure, then perhaps they will notice validation errors.

> Another problem we're having is the build of the PDF.  It was found 
> that tables are not displaying properly and that footnotes in HTML 
> lists will not even show if there is not a certain version of the 
> 'fop' package in use on the build machine.  New issues, which I don't 
> quite understand yet, emerged yesterday in a particular branch contribution.
>
> I'm CC'ing Doug Smythies as he has been putting in a lot of effort to 
> analyze and resolve most of the PDF issues.  Doug, please chime in if 
> you have anything to add.

I've seen that work, and it is great stuff with a difficult concept.
I'm not sure there is a way around the issues you describe though, because fop is quite a tricky technology...

--
Matthew East
http://www.mdke.org
gnupg pub 1024D/0E6B06FF