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.

Fix for ALSA Speaker volume level resetting to zero at boot

Up until 2011 the problem of the volume level in ALSA resetting to zero at boot was a common occurrence in my Linux installations. Actually it was a common occurrence in Linux, full stop; search the Web using keywords such as “alsa reset volume” and you’ll find umpteen links. In 2012 the situation improved and I thought the problem had become a thing of the past, but it resurfaced in 2013 on my main laptop and has plagued me through every update since (well, apart from in one release of KDE). Every time I reboot, the ALSA Speaker channel’s volume is zero when I log-in to KDE. And, as KMix is a PulseAudio mixer by default these days, I have to launch ALSAMixer and raise the volume of the Speaker channel manually.

I don’t know if the source of the problem lies in KDE, PulseAudio or ALSA itself. It did disappear after one upgrade to KDE earlier this year (I don’t recall which release of KDE) but returned in the next KDE upgrade, so I suspect it is a KDE issue. In earlier days I could resolve the problem using the commands alsactrl store and alsactl restore and similar approaches. However, this time none of those fixes work for me. The problem never bothered me much, as I always connect external speakers to my laptop’s headphone socket when I’m at home, and I don’t want my laptop emitting sounds at the office. Nevertheless, the fact the problem exists niggled me, so I decided to try and fix it. Rather than expending any more effort trying to get the usual approaches to work (the Web is littered with suggested fixes over the years), I decided to reset the Speaker volume to the same level at each boot by using an automatically-launched shell script. The method I use is given below, and should work with either OpenRC or systemd in Gentoo Linux.

1. Create the file /etc/local.d/20set_alsa_volume.start containing the following:

#!/bin/bash
# Reset ALSA Speaker channel on the first sound card to 90% after booting.
su -c "amixer -c 0 -- sset Speaker playback 90%" -s /bin/sh fitzcarraldo

(Replace “fitzcarraldo” with your own user name, of course.)

2. Make the script executable:

# chmod +x 20set_alsa_volume.start

That’s all there is to it. The volume of the ALSA Speaker channel is always set to 90% after I reboot and login to the desktop environment. KMix remembers the PulseAudio volume setting from the previous session, so I can still avoid blasting the laptop’s speakers.

By the way, the manual pages for the amixer and alsamixer commands make useful reading:

$ man amixer
$ man alsamixer

For example, the first audio card (Card 0) in my main laptop has the following controls:

$ amixer -c 0 scontrols
Simple mixer control ‘Master’,0
Simple mixer control ‘Headphone’,0
Simple mixer control ‘Speaker’,0
Simple mixer control ‘PCM’,0
Simple mixer control ‘Mic’,0
Simple mixer control ‘Mic Boost’,0
Simple mixer control ‘Beep’,0
Simple mixer control ‘Capture’,0
Simple mixer control ‘Auto-Mute Mode’,0
Simple mixer control ‘Digital’,0
Simple mixer control ‘Internal Mic’,0
Simple mixer control ‘Internal Mic Boost’,0

Update (January 29, 2015): I found the cause of the problem: PulseAudio. I edited the file /usr/share/pulseaudio/alsa-mixer/paths/analog-output.conf as per user agmg‘s January 2013 post Re: [SOLVED] Problems with PulseAudio 3.0 in the PCLinuxOS Forums:

Again, I had to edit the file: /usr/share/pulseaudio/alsa-mixer/paths/analog-output.conf

and change this:

[Element Speaker]
switch = mute
volume = off

to this:

[Element Speaker]
switch = mute
volume = merge

I realized that editing the [Element Desktop Speaker] section of the above file, has no effect on the issue. Only the edit to [Element Speaker] is needed in my case.

In my case this change forces the ALSA Speaker channel volume to 100% after rebooting (irrespective of the volume levels I set via ALSAMixer and KMix before shutdown).

The contents of the file /usr/share/pulseaudio/alsa-mixer/paths/analog-output.conf also include the following comment:

; See analog-output.conf.common for an explanation on the directives

The contents of the file analog-output.conf.common include the following comment:

; volume = ignore | merge | off | zero | <volume step> # What to do with this volume: ignore it, merge it into the device
;                                                      # volume slider, always set it to the lowest value possible, or always
;                                                      # set it to 0 dB (for whatever that means), or always set it to
;                                                      # <volume step> (this only makes sense in path configurations where
;                                                      # the exact hardware and driver are known beforehand).

So I could have tried volume = <volume step> instead of volume = merge, although I have no idea what value <volume step> would need to be. Anyway, the Bash script /etc/local.d/20set_alsa_volume.start that I created does the job in a different way without me having to tinker with the troublesome PulseAudio, so I reverted to volume = off in the file analog-output.conf and reverted to using /etc/local.d/20set_alsa_volume.start as explained earlier.