migrating from Confluence to Paligo

[Robert Lauriston]

I'll keep a diary of what I've been doing.

[Robert Lauriston]

I have around 350 topics in Confluence. The PDF output is almost 400 pages.

First step: export using Scroll DocBook Exporter, import that into Paligo. I'd say 90% of the topics need no cleanup.

HTML5 output had a "Lorem Ipsum" front door for choosing among multiple languages. I have only English. Paligo support fixed that.

The search button was dead in HTML5 output. Paligo support said that was a known bug and fixed it overnight.

Our company's standard fonts are SourceSansPro and DejaVuSansMono. Paligo support added those overnight.

[Robert Lauriston]

I'm very confused about how footers get into PDF output.

I could not find any way to add text or variables such as date, page number, doc version. The header and footer settings in the UI have no place for that.

Paligo support duplicated the footer in some way that is invisible to me, so I can't edit it. They're working on exposing that.

I'm planning to export the DocBook or Paligo XML so I can look at that and see what objects are involved in creating the footer and how they relate. I'm a bit frustrated that I can't do that in the UI. But once everything is exposed and working per our requirements, I suppose I won't care.

[Robert Lauriston]

I think code listings will take the most time for me to clean up. In some cases, linebreaks are lost, in others, <?linebreak?> appears at the end of some lines.

It doesn't surprise me that these are problematic since code listings are a pain point in Confluence and the WYSIWYG editor tends to add cruft.

I have some 120-column command output that has to fit within the margins of the PDF, can't add line breaks because the output is tabular. Paligo support's still working on that one.

[Robert Lauriston]

In Confluence, I use "internal" labels to mark content that should be excluded from customer docs, and then exclude that label in the Scroll PDF and HTML exporter settings.

In Paligo, I can do almost exactly the same thing. I set the audience attribute to "internal" for those topics, create another audience attribute "public" (which I don't actually apply to any topics), then when publishing select audience=public in the profiling attributes.

It would be slick if one could map Confluence labels to DocBook attributes, but I guess that would be a feature of Scroll DocBook Exporter, not Paligo.

[Robert Lauriston]

I opened a feature request for making headers and footers editable in the UI.

http://paligo.freshdesk.com/support/discussions/topics/1000079331

Paligo support sent me a copy of the inaccessible local.10n.xml file:

<?xml version="1.0" encoding="UTF-8"?>

<l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">
    <l:l10n language="en" english-language-name="English">
        <l:gentext key="pagenumber" text="page "/>
        <l:gentext key="pagenumber_of" text=" of "/>
        <l:gentext key="footer_center_line_1" text="WebAction, Inc."/>
        <l:gentext key="footer_center_line_2" text="proprietary and confidential."/>
        <l:gentext key="footer_right_line_1" text="Not to be distributed or reproduced"/>
        <l:gentext key="footer_right_line_2" text="without permission"/>          
    </l:l10n>
</l:i18n>

[Robert Lauriston]

Miscellaneous PDF issues:

Can I change the table default format to match Confluence's?

In the Layout editor, Tables > General, set Frame = border, Rules = all

Paligo support fixed or fixing(hidden from user):

• How do I suppress the blank page after the title page?
• How do I suppress the index page?
• How do I change the table of contents indents?
• How do I get rid of the dead bookmark after the index page, the one with the same name as the title page?

Paligo support still working on:

Images appearing over text or over each other on some pages.

[Robert Lauriston]

Image sizes look like another thing that's going to require significant cleanup. Most if not all are fine in HTML5, but in PDF a many are way too big or too small.

Apparently I'll have to set the size manually for each problem image. There's apparently not a separate setting for PDF and HTML, or for HTML output to exclude size settings.

[Sharon Burton]

One of the things I really admire about these guys is they typically fix any bobbles fast. That really helps.

[Robert Lauriston]

I just shipped a major release, so I'm going to try migrating for real.

I dealt with the 120-column command output in Confluence by using screen shots, so that's not an issue for now.

I'm going to clean up the problematic line breaks in code listings in the DocBook export before importing into Paligo.

[Robert Lauriston]

So after three or four days' work I've completed my first pass through the 27,999-line DocBook file I exported from Confluence, cleaning up the programlisting elements. Next step, cleaning up the code elements.

[Robert Lauriston]

I went back and forth a few times with Paligo support trying to clean up the Confluence export without introducing new problems, and am finally past that stage and going through topic by topic, manually cleaning up the remaining minor issues.

Any future Paligo customer migrating from Confluence should benefit greatly from what they learned from my migration.

The default image width in the PDF layout was two inches, which is ridiculous. I changed that to none.

The Antenna House pxpi setting defaults to 96, which I think makes screen shots too large, I had them change that to 125.

[Robert Lauriston]

Wrapping up my fourth week (minus a few days off) on this migration project and still plugging away. I got through the >350 pages of the PDF and fixed or opened tickets on all the problems, and am now working my way through the online help. I'm finding fewer issues there since I've already dealt with the ones that affect all outputs.

They just rolled out Paligo 2.0 shortly before I started this project, so I believe I'm the first one to find a lot of bugs and usability issues. They've been fixing them quickly, so future users shouldn't encounter most of them.

[Robert Lauriston]

I finally finished working my way through the HTML5 output yesterday.

The first two weeks were spent going back and forth with Paligo support cleaning up the DocBook exported from Confluence.

Manual cleanup after that took roughly one day per 50 pages in the PDF. Much of it was dealing with code blocks and tables that were running over the right margins. The rest was mostly random bad formatting, which in many cases resulted from my working around bugs in Confluence by inserting HTML with the Source Editor.

Side benefit, I caught and fixed a lot of minor errors and made the sample code formatting consistent. I was also working with Paligo support to make the output look like it did before, changing fonts and so on.

The one issue I haven't found a fix for is getting 120-column programlisting elements to fit in the PDF. I had the same problem in Confluence, so I'm continuing to work around it the same way, by using screen shots.