Paul Gideon Dann’s patchset for Poppler to enable Okular (Qt5) to use Cairo rather than Splash to render PDF files

If you view the same PDF file in Okular (KDE) and Evince (GNOME), you may notice that fonts and lines are rendered better in Evince. Both applications use Poppler to render text and graphics in PDF files, but Poppler uses a different rendering backend in the two applications. For Evince Poppler uses the Cairo library, whereas for Okular Poppler uses Splash, a backend inherited from Poppler’s predecessor Xpdf (still in development). Unfortunately for KDE users, Cairo often does a better job than Splash. However, independent software engineer Paul Gideon Dann came to the rescue by producing the patchset poppler-cairo-backend to modify Poppler in order to make it use the Cairo library instead of Splash when Poppler is used by Okular. To quote the README file for Paul’s patchset:

Purpose of this Patchset

Currently, the default backend for the Qt5 wrapper (used by Okular) is Splash. Unfortunately, Splash does not support subpixel rendering of fonts, so those of us using KDE are stuck with somewhat ugly-looking fonts. This patchset adds support for the Cairo backend to the Qt5 wrapper. It also forces subpixel rendering in the Cairo backend. The upshot of this is that we get beautiful fonts in Okular.

The README focuses on fonts, but in fact the rendering of lines in graphics in PDF files can also be improved by the application of the patchset.

Apparently the Poppler maintainer feels that the introduction of a dependency on Cairo to the Qt5 wrapper (even an optional dependency) in Poppler would be controversial, and he is not willing to merge the patchset. For Okular users who already have Cairo installed (e.g. for Firefox, Inkscape, Scribus and so on), and who are noticing inadequate rendering of some PDF files, Paul’s patchset is worth trying.

In Gentoo Linux, which is a source code-based distribution, it is very easy to apply the patchset. For example, I did the following to apply the patchset for Poppler 0.80.0 in a ~amd64 (Testing Branch) installation:

1. Created a package-specific and version-specific directory to hold the patchset:

root # mkdir -p /etc/portage/patches/app-text/poppler-0.80.0

2. Downloaded the patchset for Poppler 0.80.0 from the following Web page:

https://github.com/giddie/poppler-cairo-backend/tree/76e607bcf010d6d9b8df5cb0f851ef9c91d4caf2

3. Copied the patchset to the directory created in Step 1:

root # cp /home/fitzcarraldo/Downloads/*.patch /etc/portage/patches/app-text/poppler-0.80.0/
root # ls -1 /etc/portage/patches/app-text/poppler-0.80.0
0001-Cairo-backend-added-to-Qt5-wrapper.patch
0002-Setting-default-Qt5-backend-to-Cairo.patch
0003-Apply-subpixel-rendering-in-Cairo-Backend.patch

4. Checked first that the patchset could be applied successfully before actually using it:

root # cd /usr/portage/app-text/poppler
root # ebuild poppler-0.80.0.ebuild clean prepare
 * poppler-0.80.0.tar.xz BLAKE2B SHA512 size ;-) ...                                     [ ok ]
 * checking ebuild checksums ;-) ...                                                     [ ok ]
 * checking auxfile checksums ;-) ...                                                    [ ok ]
 * checking miscfile checksums ;-) ...                                                   [ ok ]
>>> Unpacking source...
>>> Unpacking poppler-0.80.0.tar.xz to /var/tmp/portage/app-text/poppler-0.80.0/work
>>> Source unpacked in /var/tmp/portage/app-text/poppler-0.80.0/work
>>> Preparing source in /var/tmp/portage/app-text/poppler-0.80.0/work/poppler-0.80.0 ...
 * Applying poppler-0.60.1-qt5-dependencies.patch ...                                    [ ok ]
 * Applying poppler-0.28.1-fix-multilib-configuration.patch ...                          [ ok ]
 * Applying poppler-0.78.0-respect-cflags.patch ...                                      [ ok ]
 * Applying poppler-0.61.0-respect-cflags.patch ...                                      [ ok ]
 * Applying poppler-0.57.0-disable-internal-jpx.patch ...                                [ ok ]
 * Applying 0001-Cairo-backend-added-to-Qt5-wrapper.patch ...                            [ ok ]
 * Applying 0002-Setting-default-Qt5-backend-to-Cairo.patch ...                          [ ok ]
 * Applying 0003-Apply-subpixel-rendering-in-Cairo-Backend.patch ...                     [ ok ]
 * User patches applied.
>>> Source prepared.

5. Re-merged Poppler to apply the patchset to the Poppler source code and rebuild the patched package:

root # emerge -1v poppler

These are the packages that would be merged, in order:

Calculating dependencies... done!
[ebuild   R    ] app-text/poppler-0.80.0:0/90::gentoo  USE="cairo cjk cxx introspection jpeg jpeg2k lcms png qt5 tiff utils -curl -debug -doc -nss" 0 KiB

Total: 1 package (1 reinstall), Size of downloads: 0 KiB

>>> Verifying ebuild manifests
>>> Emerging (1 of 1) app-text/poppler-0.80.0::gentoo
>>> Installing (1 of 1) app-text/poppler-0.80.0::gentoo
>>> Jobs: 1 of 1 complete                           Load avg: 1.06, 1.11, 0.95
>>> Auto-cleaning packages...

>>> No outdated packages were found on your system.

 * GNU info directory index is up-to-date.

6. Re-merged Okular so that it uses the patched Poppler dependency:

root # emerge -1v okular

These are the packages that would be merged, in order:

Calculating dependencies... done!
[ebuild   R    ] kde-apps/okular-19.08.1:5::gentoo  USE="chm crypt djvu image-backend pdf postscript tiff -debug -epub -handbook -markdown -mobi -mobile -plucker -share -speech -test" 0 KiB

Total: 1 package (1 reinstall), Size of downloads: 0 KiB

>>> Verifying ebuild manifests
>>> Emerging (1 of 1) kde-apps/okular-19.08.1::gentoo
>>> Installing (1 of 1) kde-apps/okular-19.08.1::gentoo
>>> Jobs: 1 of 1 complete                           Load avg: 1.17, 1.13, 1.04
>>> Auto-cleaning packages...

>>> No outdated packages were found on your system.

 * GNU info directory index is up-to-date.

My thanks go to Paul for taking the time to produce the patchset.

Completing PDF forms and adding your signature without having to print the form

A recent post in the Gentoo Forums made me interested to find out what is actually achievable with fillable PDF forms in Gentoo Linux and Windows 10 without being required to purchase a software licence, be it for personal or professional use, in order to be able to complete PDF forms (including forms that have automatically-updating bar codes).

Designing PDF Forms

It is possible to create PDF forms with LibreOffice, although LibreOffice cannot create a form containing bar codes that get updated automatically with the information entered in fields on the form. In order to create PDF forms that contain automatically-updating bar codes it is necessary to purchase Adobe Acrobat DC or Adobe LiveCycle Designer, which are Windows-only applications. As forms usually have several fields, 2D bar code symbologies are used in order to be able to encode the amount of data in a practical way. See the Adobe demonstration video Capture electronic data from printed forms.

Using PDF Forms

However, the enquiry in the above-mentioned forum thread was not about designing PDF forms, it was about being able to complete existing PDF forms (including forms that have automatically-updating bar codes, and including being able to add a written signature to the form without printing it out):

Hi,

I need to sign pdfs, and sometimes fill out pdf forms which also need to be signed. At the moment I get them, print them, sign them and scan them back in to return to the sender. I’d like to simplify that.

I know that on Windows and Mac OS your adobe software can sign the pdf, but I don’t even know how that works exactly.

It would be really neat if there were an app which could handle all that.

Oh yeah, another thing. Some forms (all?) when you fill them out and print them have a bar of machine-readable gobbledygook on the page which lets the recipient of a printed pdf scan the data back in with 100% accuracy. That would be neat too.

Thanks.

Although I have sometimes added my signature to a PDF form before printing it out — more on that later — I had never come across PDF forms with automatically-updating bar codes, so my curiosity was piqued. I decided to investigate if free applications could be used to complete PDF forms (including those with automatically-updating bar codes) and add a written signature. My investigations were carried out in Linux and Windows 10, and my findings are given below. In summary, I discovered that I could do all these things in Linux as well as in Windows 10, although in Linux I had to resort to running a Windows application under WINE if a PDF form contained automatically-updating bar codes. I did not bother trying the GNOME document viewer Evince, as I could find no evidence on the Web of it having the capability of updating bar codes automatically, and I use KDE.

For my tests I used the following four PDF forms I found on the Web:

  1. acrobat8_barcodedforms.pdf, an October 2006 PDF article from Adobe containing three sample form fields and an associated automatically-updating bar code (PDF417 symbology).
  2. barcode_field.pdf, a February 2013 sample PDF form with three fields and three associated bar codes of different symbologies (PDF417, Data Matrix and QR Code).
  3. PdfFormExample.pdf, a June 2013 sample PDF form created using LibreOffice (and therefore not containing automatically-updating bar codes).
  4. sample_barcoded_demo.pdf, a December 2005 sample PDF form from Adobe with an automatically-updating bar code (PDF417 symbology).

1. Windows 10

1.1 Acrobat Reader DC

This is the ubiquitous ‘free’ closed-source application you can download from Adobe.

Below are screenshots of the four sample PDF forms opened in Acrobat Reader DC…

1.1.1 I could enter text in the three fields in acrobat8_barcodedforms.pdf, and the bar code was updated accordingly:

Acrobat Reader DC - acrobat8_barcodedforms.pdf

Acrobat Reader DC - acrobat8_barcodedforms.pdf

I used my smartphone’s Barcode Scanner app to read the bar code on the hard-copy form printed by Acrobat Reader DC:

Text1Text2Text3I am able to change the text in these fields of this form to see how 2D barcodes work.

1.1.2 I could enter text in the three fields in barcode_field.pdf, but the three bar codes were not visible:

Acrobat Reader DC - acrobat8_barcodedforms.pdf

Acrobat Reader DC - barcode_field.pdf

1.1.3 I could enter text in the fields in PdfFormExample.pdf:

Acrobat Reader DC - PdfFormExample.pdf

Acrobat Reader DC - PdfFormExample.pdf

1.1.4 I could enter text in all fields of sample_barcoded_demo.pdf and the field contents were echoed in the box ‘Barcode Contents’ but the bar code itself was not visible:

Acrobat Reader DC - sample_barcoded_demo.pdf

Acrobat Reader DC - sample_barcoded_demo.pdf

So, in summary, Acrobat Reader DC is not a viable option if you have to deal with forms that include automatically-updating bar codes.

1.2 PDF-XChange Editor

This application from Canadian company Tracker Software Products supersedes their deprecated PDF-XChange Viewer and has additional features. Neither application is open-source, though. Some features only work fully if you purchase a software licence and enter the licence key. For example, if you add a signature to a PDF form (‘Document’ > ‘Signatures and Initials’) and then save it, DEMO stamps are added to the new PDF file (which still has editable fields). However, if you print the PDF form (either to a PDF file or to paper) then DEMO stamps are not added (but the new PDF file is not fillable/editable). Click on the two links below to view the sample PDF file PdfFormExample.pdf signed and saved to a new PDF file, and the sample PDF file PdfFormExample.pdf signed and printed to a new PDF file:

PdfFormExample_with_signature_added_then_Saved.pdf

PdfFormExample_with_signature_added_then_Printed_to_PDF.pdf

If you save them to disk and open them in PDF-XChange Editor, you will see the distinction.

As stated on the company’s Web site, the free application can be used for private and work purposes:

The FREE download of the PDF-XChange Editor may be used without limitation for Private, Commercial, Government and all uses, provided it is not: incorporated or distributed for profit/commercial gain with other software or media distribution of any type – without first gaining permission.

Below are screenshots of the four sample PDF forms opened in PDF-XChange Editor…

1.2.1 I could enter text in the three fields in acrobat8_barcodedforms.pdf, and the bar code was updated accordingly:

PDF-XChange Editor - acrobat8_barcodedforms.pdf

PDF-XChange Editor - acrobat8_barcodedforms.pdf

I used my smartphone’s Barcode Scanner app to read the bar code on the hard-copy form printed by PDF-XChange Editor:

Text1Text2Text3
I am able to change the text in these fields of this formto see how 2D barcodes work.

Notice that the layout of the encoded text is slightly different to the bar code generated by Adobe Acrobat Reader DC.

1.2.2 I could enter text in the three fields in barcode_field.pdf, and the three bar codes were visible:

PDF-XChange Editor - barcode_field.pdf

PDF-XChange Editor - barcode_field.pdf

I used my smartphone’s Barcode Scanner app to read the three bar codes on the hard-copy form printed by PDF-XChange Editor:

The PDF417 bar code was read as follows:

text_0:PDF417 barcode:I can enter text in these fields of this form and can see the three barcodes to the right of these fields in PDF-XChange Editor.

The Data Matrix bar code was read as follows:

text_1:Data Matrix barcode:
To change the barcode field to the right, type in this box. The barcode field to the right will reflect the contents of the text field as barcode after the text field lost the focus. To reset the contents of all barcode fields, cick the ‘Rset’ button.

Notice that the words ‘click’ and ‘Reset’ in the field were apparently not encoded correctly.

The QR Code bar code was read as a meaningless apparently random bunch of characters.

The PDF file and the three bar codes were generated on the fly by PHP code calling the pdflib library produced by the company PDFlib GmbH. I do not know how accurate this particular PDF file is, or how accurate is the Bar Code Scanner app on my smartphone.

1.2.3 I could enter text in the fields in PdfFormExample.pdf:

PDF-XChange Editor - PdfFormExample.pdf

PDF-XChange Editor - PdfFormExample.pdf

1.2.4 I could enter text in all fields of sample_barcoded_demo.pdf, and the field contents were echoed in the box ‘Barcode Contents’ and the bar code itself was visible:

PDF-XChange Editor - sample_barcoded_demo.pdf

PDF-XChange Editor - sample_barcoded_demo.pdf

I used my smartphone’s Barcode Scanner app to read the PDF417 bar code on the hard-copy form printed by PDF-XChange Editor:

Brian
S
Fitzgerald
Calle Fitzcarrald, 225
Iquitos

bsf@iquitos.nom.pe

So, in summary, PDF-XChange Editor appears to be a possible option in Windows 10, whether or not you have to deal with forms that include automatically-updating bar codes. I am quite impressed with the application.

2. Linux

2.1 Acrobat Reader 9

This is the free closed-source Linux application you can install via the Portage package manager (the package is app-text/acroread).

Below are screenshots of the four sample PDF forms opened in Acrobat Reader 9 for Linux.

2.1.1 I could enter text in the three fields in acrobat8_barcodedforms.pdf, and the bar code was updated accordingly:

Acrobat Reader 9 Linux - acrobat8_barcodedforms.pdf

Acrobat Reader 9 Linux - acrobat8_barcodedforms.pdf

I used my smartphone’s Barcode Scanner app to read the bar code on the hard-copy form printed by Acrobat Reader 9 for Linux:

Text1Text2Text3I am able to change the text in these fields of this form to see how 2D barcodes work.

2.1.2 I could enter text in the three fields in barcode_field.pdf, but the three bar codes were not visible:

Acrobat Reader 9 Linux - barcode_field.pdf

Acrobat Reader 9 Linux - barcode_field.pdf

2.1.3 I could enter text in the fields in PdfFormExample.pdf:

Acrobat Reader 9 Linux - PdfFormExample.pdf

Acrobat Reader 9 Linux - PdfFormExample.pdf

2.1.4 I could enter text in all fields of sample_barcoded_demo.pdf, and the field contents were echoed in the box ‘Barcode Contents’ but the bar code itself was not visible:

Acrobat Reader 9 Linux - sample_barcoded_demo.pdf

Acrobat Reader 9 Linux - sample_barcoded_demo.pdf

So, in summary, Acrobat Reader 9 for Linux is not a viable option if you have to deal with forms that include automatically-updating bar codes.

2.2 Okular

This is the well-known KDE document viewer application.

Below are screenshots of the four sample PDF forms opened in Okular.

2.2.1 I could enter text in the three fields in acrobat8_barcodedforms.pdf but the bar code was not visible:

Okular - acrobat8_barcodedforms.pdf

Okular - acrobat8_barcodedforms.pdf

2.2.2 I could enter text in the three fields in barcode_field.pdf but the three bar codes were not visible:

Okular - barcode_field.pdf

Okular - barcode_field.pdf

2.2.3 I could enter text in the fields in PdfFormExample.pdf:

Okular - PdfFormExample.pdf

Okular - PdfFormExample.pdf

2.2.4 I could enter text in all fields of sample_barcoded_demo.pdf but the field contents were not echoed in the box ‘Barcode Contents’ and the bar code itself was not visible:

Okular - sample_barcoded_demo.pdf

Okular - sample_barcoded_demo.pdf

So, in summary, Okular is not a viable option if you have to deal with forms that include automatically-updating bar codes. In fact, Okular was the worst of the bunch.

2.3 PDF-XChange Editor

To install this Windows application under WINE in Linux:

$ export WINEPREFIX=$HOME/.wine-pdfxve6
$ export WINEARCH="win32"
$ winecfg # Select Windows 10.
$ cd .wine-pdfxve6/drive_c/
$ # Copy downloaded installer to C: drive:
$ cp ~/Downloads/PDFXVE6.zip .
$ unzip PDFXVE6.zip
$ # Install PDF-XChange Editor:
$ wine PDFXVE6.exe

  • Click ‘Install’.
  • Click ‘Next’.
  • Select ‘I accept the terms in the License Agreement’ and click ‘Next’.
  • Click ‘Custom’.
  • Click ‘Browsers Plugins’ and select ‘Don’t install’. Click ‘Next’.
  • Leave ‘Create a Start Menu folder’ ticked. Untick ‘Create Desktop Icons.’ Untick ‘Set PDF-XChange Editor as default application for PDF files’. Untick ‘Set Printer “PDF-XChange Lite V6” As Default’. Click ‘Next’.
  • Select ‘Free Version’ and click ‘Next’.
  • Click ‘Install’.
  • Untick ‘Launch PDF-XChange Editor’ and click ‘Finish’.
  • Click ‘Close’.

KDE Plasma 5 then has an entry for PDF-XChange Editor in the Application Launcher under ‘Applications’ > ‘Wine’ > ‘Programs’ > ‘Tracker Software’. Alternatively, to launch PDF-XChange Editor from the command line, you should enter:

$ WINEPREFIX="$HOME/.wine-pdfxve6" && WINEARCH="win32" && wine $WINEPREFIX/drive_c/Program\ Files/Tracker\ Software/PDF\ Editor/PDFXEdit.exe

If you also want the Windows application running under WINE to be able to access PDF files on a NAS, i.e. to be able to open Samba shares, see my previous post How to enable a Windows application in WINE to access a Samba share on a NAS.

I will not bother showing screenshots of the four sample PDF files open in PDF-XChange Editor running under WINE in Linux, as the application’s behaviour is the same as in Windows (see the screenshots in sections 1.2.1 to 1.2.4 above). So, in summary, PDF-XChange Editor appears to be a viable option in Linux (albeit running under WINE), irrespective of whether or not you have to deal with forms that include automatically-updating bar codes.

3. Adding a signature to a soft copy of the PDF form

I am referring to a person’s written signature here, not to a digital signature. Rather than having to print the completed form on paper in order to sign it with a pen, then scan the fully-completed form in order to send it via e-mail, fax or whatever, many people wish to add their signature directly to the PDF form without having to print it. Below I explain the method I use to do this in both Linux and Windows.

3.1 Create a PNG file with your signature (one-time operation)

  1. Get a blank white piece of paper.
  2. Sign your name on the page.
  3. Scan the page with your scanner and save the image as a PNG file.
  4. Open the image with GIMP.
  5. Crop the image around the signature.
  6. Select ‘Layer’ > ‘Transparency’ > ‘Add Alpha Channel’.
  7. Select the Fuzzy Select Tool from the toolbox.
  8. Click on each white area and press the Delete key. Do this for the area around the signature and inside any loops. Obviously don’t click on the signature itself.
  9. Select ‘File’ > ‘Export’.
  10. Save the image as a PNG file.

3.2 Signing PDF documents

  1. Launch LibreOffice Draw and open the PDF file you wish to sign.
  2. Select ‘Insert’ > ‘Image…’ and select the PNG file of your signature. The image will be inserted.
  3. To move the signature around on the page, hover the mouse cursor over the image until the cursor changes to a red dot with four arrowheads, then click-and-hold to grab the image drag it.
  4. To reduce the size of the signature, hover the mouse cursor over the image until the cursor changes to a red dot with four arrowheads, then click and release. You will then see small blue ‘handles’ on the outline of the image. Hover the mouse cursor over a handle at one of the four corners of the image until the cursor changes to a Resize cursor. Click-and-hold and move the cursor to increase or decrease the size of the signature whilst maintaining the ratio of width to height.
  5. To save the completed and signed PDF form, select ‘File’ > ‘Export as PDF…’, click on ‘Export’ and give the file a name of your choice.

The new PDF file will contain all the information visible on the previous PDF file plus your written signature. However, unlike the original PDF file, you will not be able to modify any of the data. Therefore I recommend you retain a copy of the original PDF file before you added the signature, in case you wish to change any of field entries in future.

Note that the free PDF-XChange Editor can be used instead of LibreOffice Draw providing the PDF form is not secured or restricted, and providing you print it to a new PDF file using a virtual PDF printer driver. If the PDF form is secured or changes restricted, then use LibreOffice Draw as described above.

If you are using a PDF viewer that refuses to save your completed form as a PDF file after you have entered data in the fields (notice the message in the purple bar in the screenshots of Acrobat Reader 9 for Linux, for example), print the page to a PDF file instead by using the virtual PDF printer (‘Microsoft Print to PDF’ in Windows; CUPS ‘Virtual PDF Printer’ in Linux) at a resolution of e.g. 600 dpi (if possible). You should then be able to open that PDF file in LibreOffice Draw or PDF-XChange Editor to add your signature as explained above and print the signed form to a new PDF file.

Installing and configuring the CUPS-PDF virtual printer driver

Some applications, such as LibreOffice, have built-in support for exporting their output to PDF files. For applications without built-in support for creating PDF files there may already be an installed ‘Print to File (PDF)’ driver in your installation that you can use. However, the Print to File (PDF) option does not appear in the list of available printers in all applications. Fortunately, CUPS has a driver named CUPS-PDF which you can install to create a virtual printer that will produce PDF files.

I install the package net-print/cups-pdf and use the CUPS Printer Manager in a browser to set up a virtual printer to ‘print’ PDF files. I use the driver in conjunction with a shell script that calls a utility to display a ‘Save As’ dialogue box so the user can specify the directory and name of the PDF file.

KDialog (KDE/Qt) and Zenity (GTK+) are two well-known dialogue box tools for use in shell scripts (see, for example, the Linux Magazine article Adding graphic elements to your scripts with Zenity and KDialog). However, although I use KDE on my main laptop, I was unable to get KDialog working properly in a shell script launched by the CUPS PDF driver, so I resorted to using Zenity, which I found simple to use and reliable. My shell script using Zenity is listed further down.

Although Zenity has performed this job perfectly for me in all releases of KDE since 2007, it rankled that I could not get KDialog to do the job. However, a couple of Gentoo users were able to use KDialog successfully with the CUPS PDF driver, each with a different approach to the other, but their approaches both consisted of two shell scripts. In contrast, a solution using Zenity uses only one shell script. You can see the KDialog solutions by the two users (Havin_it and sicvolo) in Gentoo Forums thread [TIP] CUPS-PDF “Save As” with kdialog. I was determined to have a single shell script using KDialog, and was able to conflate sicvolo‘s two-script solution. My thanks go to him for his clever code in his two shell scripts, as I would never have worked it out myself. My single shell script using KDialog is listed further down.

First I will explain how to install the CUPS PDF driver package, then how to use the CUPS Printer Manager to install the virtual printer, and finally how to use a shell script with either Zenity or KDialog in order to display a graphical dialogue box prompting you to specify the directory and file name for the PDF file to be created. I use Gentoo Linux, but the procedure will be similar in other distributions (package manager commands excepted).

1.0  Installation of the cups-pdf driver and virtual printer

1.1  Install the cups-pdf package:

# emerge cups-pdf

1.2  Launch a Web browser and enter http://localhost:631/ in the Address bar to display the CUPS Printer Manager.

1.3  Click on ‘Administration’ to call up the Administration page, then click ‘Add Printer’. If prompted, enter the username ‘root’ (without the quotes) and the root user’s password.

1.4  Select ‘CUPS-PDF (Virtual PDF Printer)’ in the list of local printers, and click ‘Continue’.

1.5  Enter a name, decription and location for the virtual printer. For example, I entered ‘Virtual_PDF_Printer’, ‘Virtual PDF Printer’ and ‘Mesh Edge DX’ (without the quotes), respectively. Then click ‘Continue’.

1.6  Select ‘Generic’ in the ‘Make:’ box, and click ‘Continue’.

1.7  Select ‘Generic CUPS-PDF Printer (w/ options) (en)’ in the ‘Model:’ box, and click ‘Add Printer’. The virtual printer should now be available for you to use.

1.8  When you come to print from an application, if you select Virtual_PDF_Printer from the list of available printers the PDF file will be saved in the directory /var/spool/cups-pdf/<your username>/. Note that the directory will be created automatically the first time you ‘print’ to PDF.

1.9  Optionally, you could create a shortcut (Desktop Config File) on your Desktop to open the directory mentioned in Step 1.8 above.

1.10 Optionally, instead of Step 1.9 you could edit the file /etc/cups/cups-pdf.conf as root user to get cups-pdf to ‘print’ PDF documents to your Desktop instead of in /var/spool/cups-pdf/<your username>/, by changing the line:

#Out /var/spool/cups-pdf/${USER}

to:

Out ${HOME}/Desktop


2.0  How to display a dialog box prompting for the directory and file name of the PDF file

If you prefer to be prompted for a file name so that you can save the PDF file wherever you want and give it any name you want, perform the steps below instead of Steps 1.9 or 1.10 above. Either perform the steps in 2.1 (Zenity) or the steps in 2.2 (KDialog). Then perform the steps in 2.3, which apply in both cases.

2.1   Zenity (GTK+)

2.1.1   Install Zenity:

# emerge zenity

2.1.2   Check it is installed:

# eix -I zenity
[I] gnome-extra/zenity
Available versions: 3.12.1 {debug libnotify test +webkit}
Installed versions: 3.12.1(13:49:47 04/12/14)(libnotify webkit -debug -test)
Homepage: https://wiki.gnome.org/Projects/Zenity
Description: Tool to display dialogs from the commandline and shell scripts

2.1.3   Using a text editor, create the following shell script in your home directory and give it a meaningful name, such as cups-pdf_script.sh:

#!/bin/bash
CURRENT_PDF="${1}"
CURRENT_USER="${2}"
DISPLAY=:0.0
export DISPLAY
XAUTHORITY=/home/${CURRENT_USER}/.Xauthority
export XAUTHORITY
PDFNAME=$(zenity --file-selection --save --confirm-overwrite)
mv "$CURRENT_PDF" "$PDFNAME"

2.2   KDialog (KDE/Qt)

2.2.1   Install KDialog:

# emerge kde-base/kdialog

2.2.2   Check it is installed:

# eix -I kde-base/kdialog
[I] kde-base/kdialog
Available versions: (4) 4.12.5(4/4.12) (~)4.14.2(4/4.14) (~)4.14.3(4/4.14)
{aqua debug}
Installed versions: 4.14.3(4)(00:56:36 04/12/14)(-aqua -debug)
Homepage: http://www.kde.org/
Description: KDialog can be used to show nice dialog boxes from shell scripts

2.2.3   Using a text editor, create the following shell script in your home directory and give it a meaningful name such as cups-pdf_script.sh:

#!/bin/bash

get_dbus()
{
if [ -z $1 ]; then
    echo "specify user" >> $HOME/cups-pdf_script.log
    return 1
fi
# Search these processes for the session variable (they are run as the current user and have the DBUS session variable set)
compatiblePrograms=( kdeinit kded4 pulseaudio trackerd )

# Attempt to get a program pid
for index in ${compatiblePrograms[@]}; do
   PID=$(ps -ef | grep $1 | grep ${index} | head -1 | awk '{print $2}')
   if [[ "${PID}" != "" ]]; then
      break
   fi
done
if [[ "${PID}" == "" ]]; then
   echo "Could not detect active login session" >> $HOME/cups-pdf_script.log
   return 1
fi
QUERY_ENVIRON="$(tr '\0' '\n' < /proc/${PID}/environ | grep "DBUS_SESSION_BUS_ADDRESS" | cut -d "=" -f 2-)"
if [[ "${QUERY_ENVIRON}" != "" ]]; then
#   echo ${QUERY_ENVIRON} >> $HOME/cups-pdf_script.log
   return 0
else
   echo "Could not find dbus session ID in user environment." >> $HOME/cups-pdf_script.log
   return 1
fi
}

CURRENT_PDF="$1"
CURRENT_USER="$2"

export DISPLAY=:0
export XAUTHORITY=/home/${CURRENT_USER}/.Xauthority
export HOME=/home/${CURRENT_USER}/
CONFIG_FILE="/home/${CURRENT_USER}/.pdf-writer.conf"
CANCELLED="No"

date > $HOME/cups-pdf_script.log

get_dbus ${CURRENT_USER}
if [ $? -eq 0 ]; then
   export DBUS_SESSION_BUS_ADDRESS=${QUERY_ENVIRON}
   while [ True ]; do
      CURDATE=$(/bin/date +%Y%m%d)
      CURNAME=$(/bin/cat "$CONFIG_FILE")
      BASENAME=$(basename $CURRENT_PDF)
      FILENAME=$(/usr/bin/kdialog --getsavefilename "$CURNAME$CURDATE-" "*.pdf" --title="Save PDF")
      if [ $? -eq 1 ]; then
         CANCELLED="Yes"
         break
      fi
      echo $FILENAME
      if [ ! "$FILENAME" = "" ]; then
         if [ -e "$FILENAME" ]; then
            /usr/bin/kdialog --warningcontinuecancel "File already exists"
            if [ $? -eq 1 ]; then
               continue;
            fi
         fi
         FILENAME=$(echo $FILENAME.pdf | sed -re "s/(\.pdf)+$/.pdf/g")
         break;
      else
         /usr/bin/kdialog --error "You must select a file or hit Cancel."
      fi
      break
   done
   if [ "${CANCELLED}" == "No" ]; then
      /bin/cp "${CURRENT_PDF}" "${FILENAME}"
      okular "${FILENAME}" &
   fi
   /bin/rm "${CURRENT_PDF}"
   echo "No errors encountered." >> $HOME/cups-pdf_script.log
   exit 0
else
   /bin/rm "${CURRENT_PDF}"
   echo "Errors encountered." >> $HOME/cups-pdf_script.log
   exit 1
fi

2.3   Whichever of the above two options (Zenity or KDialog) you chose, do the following:

2.3.1   Make the shell script file executable:

# chmod +x /home/<your username>/cups-pdf_script.sh

2.3.2   Edit the file /etc/cups/cups-pdf.conf, find the line starting with ‘#PostProcessing‘, and change it to:

PostProcessing /home/<your username>/cups-pdf_script.sh

2.3.3   Restart CUPS:

# /etc/init.d/cupsd restart # If your installation uses OpenRC.

# systemctl restart cups.service # If your installation uses systemd.

Now, when you select Virtual_PDF_Printer from your applications’ list of available printers and click ‘Print’, a pop-up window should appear, allowing you to select the target directory for the PDF file and enter a file name of your choice.

Split an A4 PDF file into two A5 PDF files

This week I scanned a couple of receipts in order to submit them to a client with an expenses claim. The two receipts were physically small enough to both fit on an A4 page, so I lay them both on the bed of a scanner and produced a PDF file with the two receipts on one A4 page. The resulting scan looked rather like the sketch in Figure 1. However, a couple of days later I remembered that the client wanted copies of receipts to be submitted individually, but the office scanner had stopped working and so I needed to split the original PDF file into two PDF files containing images rather like the sketches in Figures 2 and 3.

Figure 1 - original A4 image

Figure 1 - original A4 image

Figure 2 - A5 bottom half of original A4 image

Figure 2 - A5 bottom half of original A4 image

Figure 3 - A5 top half of original A4 image

Figure 3 - A5 top half of original A4 image

I was surprised to find little information on the Web about how to do such a thing. I did come across three applications that looked like they probably could do the job: jPdf Tweak, BRISS and krop. jPdf Tweak is in the Portage main tree (app-text/jpdftweak). BRISS isn’t. The krop Web page does have a link to an ebuild which could be downloaded and installed via a local overlay. I did have a brief play with jPdf Tweak and it looks powerful, but I did not find it particularly intuitive and I would need to study the manual in detail. Anyway, I thought I would try a command line approach for the fun of it.

Searching the Web I came across a site with a Perl script that looked promising: Split (crop) double page PDFs in two posted by someone called iblis (to whom I’m grateful). It uses a Perl module PDF:API2 which does exist in the Portage main tree (dev-perl/PDF-API2) and which I already had installed. I modified the last couple of lines of the script very slightly, so it now looks like this:

#!/usr/bin/env perl
use strict; use warnings;
use PDF::API2;
     
my $filename = shift || 'test.pdf';
my $oldpdf = PDF::API2->open($filename);
my $newpdf = PDF::API2->new;
     
for my $page_nb (1..$oldpdf->pages) {
my ($page, @cropdata);
     
$page = $newpdf->importpage($oldpdf, $page_nb);
@cropdata = $page->get_mediabox;
$cropdata[2] /= 2;
$page->cropbox(@cropdata);
$page->trimbox(@cropdata);
$page->mediabox(@cropdata);
     
$page = $newpdf->importpage($oldpdf, $page_nb);
@cropdata = $page->get_mediabox;
$cropdata[0] = $cropdata[2] / 2;
$page->cropbox(@cropdata);
$page->trimbox(@cropdata);
$page->mediabox(@cropdata);
}
     
(my $newfilename = $filename) =~ s/(.*)\.(\w+)$/$1.split.$2/;
$newpdf->saveas($newfilename);
     
__END__

I saved it with the file name split_pdf_A4_to_A5.pl and made it executable:

$ chmod +x split_pdf_A4_to_A5.pl

Then I used the following procedure to split the original PDF file:

1. I used the excellent command line utility pdftk (the package app-text/pdftk in Gentoo), which I had already installed, to rotate the A4 page clockwise and save it in a file named rotated.pdf:

$ pdftk original.pdf rotate 1-1right output rotated.pdf

Now the A4 page looked similar to the sketch in Figure 4.

Figure 4 - original A4 image, rotated clockwise by 90 degrees

Figure 4 - original A4 image, rotated clockwise by 90 degrees

2. I used the Perl script to split the A4 page into two A5 pages within one PDF file:

$ ./split_pdf_A4_to_A5.pl rotated.pdf

The above command created a file rotated.split.pdf containing two A5 pages.

3. Finally, I split the two-page PDF file into two separate single-page files:

$ pdftk rotated.split.pdf burst

which left me with two A5 PDF files named page_0001.pdf and page_0002.pdf similar to the sketches in Figures 2 and 3 above.

Mission accomplished. 🙂