PDF Documentation Generator

Description

A Microsoft Word macro which allows you to generate professional PDF documentation from a Confluence site. Unlike the Confluence PDF export feature, this macro allows you complete control over the content hierarchy, layout and font styles of the generated PDF. By default, it generates a PDF that looks like a standard user manual.

For an example of offline documentation generated from Confluence using this plugin, see the GigaSpaces Offline Documentation. You need to register with the GigaSpaces website to download the documentation, but registration is easy and free.

Installation

To use this plugin you must first install a Microsoft Word macro, download a Microsoft Word template, and install or reinstall the html-tag macro by Adaptavist.

Even if you already have the html-tag macro, you must reinstall it using the attached JAR, otherwise PDF generation will not work.

Update: Using this plugin without the html-tag macro This documentation instructs you to use the html-tag macro. This has caused problems for a number of users of this plugin. For an alternative solution that does not require the html-tag macro, see my post in the comments at the bottom of this page. I'm sorry that I don't currently have time to revise the documentation accordingly.

To install the prepForPDF Macro:

1. Download the macro's .bas file (see Download Macro at the top of this page) and save it to your local machine.
2. Open Microsoft Word.
3. From the Tools menu, point to Macro and select Visual Basic Editor.
4. In the Microsoft Visual Basic window, in the tree on the left, click the Normal node.

   You must have the Normal node selected, otherwise the plugin might be installed for the current document only. You need to have it available for all documents in Word.

5. In the Microsoft Visual Basic window, from the File menu, select Import...
6. Browse to the .bas file you downloaded, select it and click Open.
7. In the Microsoft Visual Basic window, from the File menu, select Save Normal.
8. Close Microsoft Visual Basic.

If you want to create a toolbar button for easy access to the macro, right-click the Word toolbar, click Customize, select the Commands tab, under Categories select Macros, under Commands find Normal.NewMacros.wiki_prepForPDF, and drag this macro to the relevant toolbar. To change the button text, right -click the button while the Customize dialog is open, and edit the Name text box.

To download the template:
You can find a link to the latest template under Download Template at the top of this page. Click the link and download the template to a local drive or a network location you have access to.

It is recommended to save the template under your local C: drive.

To install or reinstall the html-tag macro:

1. Do one of the following:
   • If you are using the html-tag macro and have modified its whitelist of HTML tags, make sure that the whitelist in the html-tag JAR on the server contains the line <tag>font</tag>. Do not proceed to step 2.
   • If you haven't touched this macro's whitelist, or if you don't know what this is, proceed to step 2.
2. Download the attached JAR.

   You are downloading the Adaptavist html-tag macro, version 1.0, which allows you to insert HTML tags into wiki syntax. For security reasons, this macro uses a whitelist of HTML tags which are permitted. For the Confluence PDF Generator to work, the HTML tag font must added to the whitelist. The attached JAR contains the original JAR of the html-tag macro, with this tag added to the whitelist.

   Using the html-tag macro may pose a security risk, although the macro's authors advertise that it is much safer than the standard html macro shipped with Confluence. Please consult the macro's documentation before using it. The PDF Documentation Generator's author and affiliated companies are not responsible for any direct or indirect damages caused by use of the html-tag macro.

3. Upload the JAR using Confluence Administration > Plugins. If you already have the macro, it will be overwritten by the attached JAR. As mentioned, the JAR contains an updated HTML-tag whitelist.

Atlassian has announced it does not support the html-tag macro, but our experience shows that this macro works fine, for the purposes of the PDF Documentation Generator, in Confluence versions at least up to 2.3.1.

Usage

The general workflow is:

1. Create a PDF-Content Wiki Page, which includes all wiki content relevant for the PDF, with special tags that specify the hierarchy you need in the PDF. Export this page to Word.

   After the first time you use the macro, this page will already exist, but you must update it to reflect changes to the wiki content and structure made since the last time you exported it.

2. Prepare a cover for your document at a specific path.
3. Run the PrepForPDF word macro. The macro rearranges the Word file exported by the wiki into the format desired for the PDF.
4. Review the Word file and Print to PDF using the PDF writer of your choice.

1. Preparing a PDF-Content Wiki Page

In order to use this plugin, you first need to create one wiki page that includes all the content from your wiki that is relevant for the PDF. This wiki page will mirror the table of contents of your PDF file: the order of content and the hierarchy you define will determine the order and hierarchy of content in the PDF. After you prepare this page you must export it to Microsoft Word.

You can include content in this page using the {include} macro, which is standard in most versions of Confluence.

After the first time you use the macro, this page will already exist, but you must open and update it to reflect changes to the wiki content and structure made since the last time you exported it. You must update this page even if you change a wiki page name, because the {include} macro does not support TrackBack (its link is not automatically updated when page names change).

Before preparing a PDF-Content Wiki Page you must install or reinstall the Adaptavist html-tag plugin (see installation above). If you don't do this, the page will not display correctly, and you will not be able to generate a PDF.

Content Entries

Each wiki page you want to include in your PDF file, must be represented by one entry in the PDF-Content Wiki Page. The entries must be organized in the same order as the content should appear in the PDF.

An entry in the PDF-Content Wiki Page has two lines of wiki syntax, as follows:

{html-tag:tag=font|face=Arial|size=7}LEVEL#1#Introduction{html-tag:tag=/font}
{include: Introducing Product X}

• The first line has two functions:
  • It defines the hierarchical level the wiki page will receive in the PDF. This is done using an {html-tag} that defines a specific font and size, and the text LEVEL#1#.

    For each hierarchical level (level 1, level 2, etc.) this line should have a different font size and the correct level number between the # symbols. The correct syntax for all levels is shown below.

  • It displays the title that this page should get in the PDF. The PDF title can, and often will be, different from the page title in Confluence.
• The second line includes the page content, so that the full text of the wiki page appears under the PDF title. The page content should not start with a page title (you can change this in the page itself).

Do not change anything in the entry syntax except for the PDF title name after the # symbol, and the wiki page name. It is best to copy-paste the correct syntax for the level of the current entry, and then manually modify the title and page name. The correct syntax for hierarchical levels 1 through 5 is shown below.

The entry above adds the wiki page Introducing Product X to the PDF. In the PDF, this page's content will receive level 1 (i.e. a main chapter) and the title Introduction.

Here is how the entry above will look, when viewed in the PDF-Content Wiki Page:

Here is how the entry above will look in the final PDF:

Syntax of Entries for Different Levels

The following table shows the correct syntax for entries with different hierarchical levels in the PDF.

{html-tag:tag=font|face=Arial|size=7}LEVEL#1#Title in PDF{html-tag:tag=/font}
{include: Wiki Page Name}

{html-tag:tag=font|face=Arial|size=5}LEVEL#2#Title in PDF{html-tag:tag=/font}
{include: Wiki Page Name}

{html-tag:tag=font|face=Arial|size=4}LEVEL#3#Title in PDF{html-tag:tag=/font}
{include: Wiki Page Name}

{html-tag:tag=font|face=Arial|size=3}LEVEL#4#Title in PDF{html-tag:tag=/font}
{include: Wiki Page Name}

{html-tag:tag=font|face=Arial|size=2}LEVEL#5#Title in PDF{html-tag:tag=/font}
{include: Wiki Page Name}

Do not change anything in the entry syntax except for Title in PDF and Wiki Page Name. If you change anything else, PDF generation will not work.

Structure of Entries in the PDF-Content Wiki Page

The PDF-Content Wiki Page should contain a list of entries which mirrors the table of contents of your final PDF. For example, if your table of contents looks like this...

...then your PDF-Content Wiki Page should look like the following, with one entry for each table of contents item, in the correct order and with the appropriate hierarchical levels (1. is level 1, 1.1. is level 2, 1.1.1. is level 3).

{html-tag:tag=font|face=Arial|size=7}LEVEL#1#Introduction{html-tag:tag=/font}
{include: Introduction}

{html-tag:tag=font|face=Arial|size=5}LEVEL#2#System Requirements{html-tag:tag=/font}
{include: System Requirements}

{html-tag:tag=font|face=Arial|size=5}LEVEL#2#Widget Features{html-tag:tag=/font}
{include: Widget Features}

{html-tag:tag=font|face=Arial|size=7}LEVEL#1#Using the Widgets{html-tag:tag=/font}
{include: Using the Widget}

{html-tag:tag=font|face=Arial|size=5}LEVEL#2#Starting Widget{html-tag:tag=/font}
{include: Starting Widget}

{html-tag:tag=font|face=Arial|size=5}LEVEL#2#Fiddling with Widget{html-tag:tag=/font}
{include: Fiddling with Widget}

{html-tag:tag=font|face=Arial|size=4}LEVEL#3#Troubleshooting{html-tag:tag=/font}
{include: Troubleshooting}

This example assumes that the wiki page names and PDF titles are identical. In practice, you can give a different title for the PDF in the first line of each entry. But the second line of each entry must have the exact current name of the page in the wiki.

The PDF generated will look like this:

In the real PDF, there will be page breaks before each topic, and of course "Content of this wiki page" will be replaced by the full content of each page.

Exporting to Word

After you have finished preparing/updating the PDF-Content Wiki Page, export only that page to Word:

1. Navigate to the page in Confluence.

   If you are including a large number of pages in your PDF, this page will be very large and might take a long time to load – even as much as five minutes. It is worth the wait – you will eventually get the page.

2. Click the Info tab.
3. At the top-left, click the Export to Word link.

   If the page is very big, export might take a while, roughly the same time it takes to export the entire space.

4. Save the exported document on a local drive, or on a network location which you have uninterrupted access to (such as a file server).

2. Preparing Cover Document

After exporting the PDF-Content Wiki Page, you have a Microsoft Word file on your local disk which includes all the wiki content you want to include in the PDF. This file is not in its final format – you still need to run the prepForPdf Word Macro to prepare it for printing to PDF.

But before you run the macro, you must prepare an additional Word file containing your cover and front matter, and save it in a specific path with a specific name.

What the Cover Document Should Contain

The prepForPDF macro prepares your PDF documentation starting from the table of contents. If you want something to appear before the table of content – a cover page, and any front matter – you must add it in a separate Word file.

You can put any of the following in the cover document (in the order you want them to appear in the PDF):

• Cover page
• Copyright notice
• About the company
• Regulatory notices
• Any other front matter

All of these will be added automatically to the beginning of your PDF, before the table of contents, provided that you put them in the cover document.

Even if you don't want any text to appear before the table of contents, you must still create a cover document and place it in the correct path. In this case, your cover document should be blank.

Here is a sample cover document, containing only a cover page, with no other front matter.

Where to Save the Cover Document

There are two requirements for the cover document's location:

• It must be in the same folder as the PDF-Content Wiki Page, which you exported to Word and saved on your local machine (or on the local network).
• It must have the same name as the file you exported to Word, with the suffix .doc_cover.doc.
  For example, if the exported Word file is called WikiExport.doc, your cover document must be called WikiExport.doc_cover.doc.

If you do not put the cover document in the correct path, with the correct name, the macro will run until the end and then fail, which is very annoying.

3. Running the prepForPDF Word Macro

Now that you have exported your content to Word and prepared a cover document in the correct place, it is time to run the prepForPDF macro, an automatic procedure that reformats the document into a format suitable for a printed document. After the macro finishes working, you can print the document to PDF.

Considerations Before Running the Macro

For big PDFs (1000 pages or more), the macro can take a very long time to run, even several hours. While the macro is running you may not touch your machine. For this reason, you might consider:

• Finding a very fast machine, or a server, in your organization, and running the macro on it.
• If you are running on your own machine, finding another machine to work on while the macro is running.

At GigaSpaces, we run the macro on a 1300-page Word file, using a fast dual-core machine, and it takes approx. 30 minutes to complete. On a regular PC the same process takes around 2 hours.

For your convenience, when the macro finishes it displays the number of topics processed and the running time. This means you can leave your machine for a while and come back to it later, to see how long it took to run. Dividing the elapsed time by the number of topics gives you an estimate of how long the macro will take to run when you add more topics to the PDF.

Running the Macro

Before running the macro you must install it, see Installation above.

To run the prepForPDF macro:

1. Start Microsoft Word.
2. Open the Word file you exported from your PDF-Content Wiki Page.

   This must be the original Word file you exported from the wiki, with no changes. If you have edited the document, or run this macro on it once before, and saved it, the macro will not work. You must re-export the file from the wiki.

3. From the Tools menu, point to Macros. From the submenu, select Macros.
4. Select the macro wiki_prepForPDF and click Run.
5. The macro prompts for a template path. Type in the path of the template, which you saved locally during installation, and click OK.
6. The macro reminds you to place the cover document at the correct path. Make sure it is there.

   When you click OK the macro starts running. For big PDFs (1000 pages or more), this can take a very long time, even several hours.

   After the macro starts running, do not touch your machine! Switching to another window, typing something or clicking the mouse might cause Word to crash.

7. Click OK. The macro runs until it finishes preparing the document for PDF. When it finishes, it displays an info box with the number of topics processed and the total processing time.
8. After processing finishes, immediately Save As and give the document a different name. We recommend using the same name with the suffix _prep.

   If you save on the current document (with the same name), you will not be able to run the macro on it again (to run again you will need to re-export from the wiki).

If the macro did not finish running successfully, sorry, you've run into a bug. Please see our Open Issues to see if this is a known problem, and if not, please help us by pressing Debug in the error dialog, noting the line of code in which the error occurred, and adding an issue with this information.

What the Macro Does (Macro Features)

• Replaces the styles in the wiki Word export with more manageable styles, which correspond to a professional printed documentation template.
• Applies the Word template provided in this plugin, Wiki Word Export.dot, making sure that the styles are applied in practice to all the text in the document.
• Adds a custom front-matter document which you provide.
• Removes wiki stuff that should not appear in printed documentation:
  • Deletes rating boxes generated by the {rating} macro.
  • Deletes the {toggle-cloak} line of cloaked text, but only if it starts with the text "Expand this".
• As of Confluence 2.3, if your wiki uses the {code} macro, the code segments might appear with numbering (each line in the code starts with a number). This looks bad and disrupts existing numbered lists in the content. The prepForPDF macro has a subroutine called removeCodeNumbering, which takes care of this.

The removeCodeNumbering subroutine is responsible for over 80% of the macro's running time. If you do not use code in your wiki, you might want to disable it – contact us for advice on how to do this.

4. Reviewing and Printing the Prepared Document to PDF

Reviewing the Document

After running the macro successfully, you should have a Word file which is formatted like professional printed documentation. The next step is to print it to PDF, but first, we recommend you review the document to see if anything went wrong. This is especially important the first time you run the macro.

For very big PDFs, the Word document might take a very long time to load in Word and might be very slow to navigate. Consider doing the review process on the same fast machine you are running the macro on.

The best way to review is to go over every page of the PDF (you don't have to read everything, just look over it), and see if anything looks strange:

• If something looks like an isolated problem, correct it manually, and make a note to correct this problem manually each time you print the PDF.
• If there is a recurring problem, open an issue for us and request that this problem be fixed automatically by the macro. As long as there is no fix, consider either fixing this problem manually, or living with it.

In many cases, the best way to solve a problem is to go back to your wiki pages and change your formatting or page structure, to avoid the wiki syntax that caused the problem.

Printing to PDF

Once you have finished reviewing the document and correcting any errors, generate a PDF from the Word file using the PDF writer of your choice. We have had good results with Adobe Acrobat 7.0, using the PDFMaker macro, not the Distiller.

For very big PDFs (more than 1000 pages), consider running the PDF process on a fast machine.

Customizing this Plugin

You are welcome to customize both the Word Macro and the template to suit your purposes.

Customizing the Macro

You might want to customize the macro to automatically fix things that looked good on your wiki, but are not suitable for PDF documentation.

The source code of the macro is in the .bas file supplied with this plugin (download the latest version under Download Macro at the top of this page. You are welcome to modify the source code to suit your needs. If you make a change you believe might be suitable for other users, please send us your changes and we'll incorporate them into a future version.

Customizing the Template

You might want your PDF documentation to look differently from the default template we supply with the plugin. There are three levels of customization for this template:

• Changing how the existing styles look – feel free to do this, it should not affect how the macro runs. You can change the font, size, and paragraph settings of any of the existing styles in the template.
• Changing page layout – this is a bit more dangerous, but reasonable changes to page layout (such as changing from A4 to letter) should not affect how the macro runs.
• Adding or removing styles, or changing the structure – if make even the smallest change to the existing styles, the existing word macro will not work properly. If you want to customize on this level, take into account that you'll need to modify, even completely rewrite, the Word macro.

Legal Notice

The Word macro, Word template, concept and instructions described in and downloaded from this page ("the plugin") are provided "as is", without warranty of any kind, express or implied, including but not limited to warranties of merchantability and fitness for a particular purpose or non-infringement. GigaSpaces Technologies Ltd. and Gilad David Maayan will not be liable for any damage or loss in connection with the plugin.

Version History

Open Issues

Screenshots

Screenshots