=============================================================================
PrintPDF - Easy PDF creation with GhostScript                    Version 1.20

(c) Stephen Fryatt, 2005-2023                                   20 April 2023
=============================================================================

  This file, and a StrongHelp version, are contained within the PrintPDF
  application.  These can be accessed from the 'Help' entry in the Filer
  menu and from the 'Help' entry in PrintPDF's iconbar menu.

Licence
-------

  PrintPDF is licensed under the EUPL, Version 1.2 only (the "Licence"); you
  may not use this work except in compliance with the Licence.

  You may obtain a copy of the Licence at
  http://joinup.ec.europa.eu/software/page/eupl

  Unless required by applicable law or agreed to in writing, software
  distributed under the Licence is distributed on an "AS IS" basis, WITHOUT
  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

  See the Licence for the specific language governing permissions and
  limitations under the Licence.

  The source for PrintPDF can be found on GitHub, at
  https://github.com/steve-fryatt/printpdf



Introduction
------------

  PrintPDF provides a front-end to the "*ps2pdf" command in GhostScript,
  allowing PDF documents to be produced more easily.  Normally, the process
  requires a document to be 'printed' to a postscript file, before that file
  is passed through GhostScript and converted into a PDF.  This two stage
  process is complicated by the fact that the RISC OS printer drivers can
  only 'print' to a file in a single location, so care has to be taken not to
  overwrite an existing postscript file before it has been converted.

  By setting up a dedicated postscript driver in Printers, which prints to a
  specific location, PrintPDF can watch out for new documents being printed
  and add them to a queue.  These are processed in turn, with the resulting
  PDF files being saved using drag-and-drop from a dialogue box.  To the
  user, printing from an application while this printer driver is selected
  will result in a Create PDF dialogue box opening; the PDF is saved
  directly, and no postscript files need be seen.

  As the process behind the scenes still involves creating a postscript file
  and then converting that to a PDF, PrintPDF also provides a quick way to
  convert any of these files which already exist by dragging them to its
  icon.

  In addition to this manual, interactive help is fully supported.



Installing PrintPDF
-------------------

  To install PrintPDF, drag the !PrintPDF application directory from the
  archive to a suitable location on your hard disc; the directory containing
  your other printing utilities may be a good place.

  Once the application has been copied, it should be set to be seen by the
  filer when the machine starts: the easiest way to achieve this is to add it
  to the list of applications in Configure.  Start Configure by
  double-clicking on !Boot (or selecting 'Configure...' from the Task
  Manager's iconbar menu on recent versions of RISC OS), then select 'Boot'
  and finally 'Look at'.  Drag the !PrintPDF application from your hard disc
  into the list of applications.

  PrintPDF is 32-bit neutral, and requires the 32-bit Shared C Library to be
  installed.  If needed, this can be found in the System Resources on RISC OS
  Open Ltd's website at https://www.riscosopen.org/content/downloads/common.

  If you are already using R-Comp's PDFsuite, then this is all the
  installation that is required.  Running PrintPDF instead of PDFmaker will
  result in PDF generation being controlled by PrintPDF; now read the section
  on Using PrintPDF.

  If PDFsuite is not present, then before PrintPDF can be used, a copy of
  GhostScript must be installed on the machine.  In addition, it is a good
  idea (although not essential) to add a new "PDF" printer definition to
  Printers, so that PDFs can be created automatically when documents are
  printed.


  Installing GhostScript
  ----------------------

  In order to convert postscript files into PDFs, PrintPDF makes use of the
  facilities provided by GhostScript.  As a result, it is necessary for the
  !GhostScr application to have been installed and seen by the filer
  ('booted') before trying to use PrintPDF.

  If you do not already have a copy of GhostScript version 8.5, it can be
  found at http://www.mw-software.com/software/ghostscript/ghostscript.htm.

  GhostScript must be installed on a filing system that supports long file
  names and unlimited files per directory.  If you are not using an E+ or F+
  format hard disc (the new formats supplied with RISC OS 4 and 5), you will
  either need to upgrade or investigate Richard Atterer's raFS (from
  http://www.atterer.net/) or Andy Armstrong's X-Files (from
  http://wonderworks.geekgang.com/free/).

  Once installed, GhostScript must also have been seen by the filer before
  PrintPDF can carry out PDF conversions; again the easiest way to do this is
  via Configure.  Go back to the list of applications to be looked at on
  startup (start Configure by double-clicking on !Boot, then select 'Boot'
  and finally 'Look at'); drag the !GhostScr application from your hard disc
  into it.


  Setting up Printers
  -------------------

  Although PrintPDF can be used without changing the configuration of
  Printers, setting up a dedicated printer definition which prints to a
  PostScript file in the PrintPDF queue allows the PDF creation process to be
  simplified.

  There are several alternative ways to set things up, and two or more can be
  used in parallel (allowing, for example, PS2 and PS3 icons so that PDF
  output can be generated via whichever is currently selected):

  * Use the standard PoScript2 driver; while this works fine, it means that
    the icon used to indicate the "PDF printer" is fairly nondescript.  This
    uses PostScript2 to send data to the printer.

  * Use a slightly modified version of the PoScript2 driver (supplied in the
    Printers folder of the PrintPDF archive), which allows a different "PDF"
    icon to be displayed but is otherwise identical and also results in PS2
    data being used.

  * Use the PDF3 driver supplied in the PrintDefs.PrintPDF folder of the PS3
    Driver download from Martin Wuerthner and John Tytgat (this is commercial
    software -- see http://www.mw-software.com/software/ps3/ps3.html).  This
    allows PrintPDF to send PostScript3 data to GhostScript.

  On most systems, the second and third options are preferred depending on
  whether the PS2 or PS3 drivers are to be used.

  To set up by any of these methods, first load PrintPDF so that its icon is
  on the iconbar.  If it has been configured to run without an icon, see the
  Setting Choices section for details on how to change this.  Next load
  Printers and select 'Printer control...' from the iconbar menu, to open the
  Printer control window.

  Locate the printer definition file to be used, and drag it into the Printer
  control window.  This will be one of three:

  * For the standard PostScript2 driver, locate the printer definitions
    supplied with your machine, and drag the PoScript2 file from the
    Postscript directory to the window.  This should add a new printer, with
    the name "PoScript2".

  * For the "PDF printer" using PS2, find the PDF definition from the
    Printers folder of the PrintPDF archive and drag it to the window: this
    should add a new printer with the name "PDF".

  * For the PostScript3 driver, find the PDF3 definition from the
    PrintDefs/PrintPDF folder of the PS3 archive from Martin Wuerthner and
    John Tytgat, and drag it to the window: this should add a new printer
    with the name "PDF3".

  Click Menu over the new printer's line, and select 'Connection...' to open
  the Connections dialogue.  Select 'File' at the bottom of the list, click
  on the pop-up menu icon to the right of the field, and drag the file from
  the save dialogue to the PrintPDF icon on the iconbar; this should update
  the filename shown by Printers.  Make sure that 'Append to file' is not
  ticked, then click on 'Set' to update the details.

  Click Menu over the name again, and select 'Configure...' from the menu to
  open the PostScript printer configuration dialogue.  If using the standard
  PoScript2 driver, then enter "PDF" in the 'Name' field to allow the new
  printer definition to be identified.  Ensure that 'Colour' is ticked, then
  click on 'OK' to set the changes.

  On the iconbar, select the printer which you wish to use as your default,
  then select 'Save choices' from the iconbar menu to save the changes for
  future use.



Using PrintPDF
--------------

  To use PrintPDF, double-click to install it on the iconbar in the usual
  way.  If space on the iconbar is limited, it can be run in the background
  with no icon present; see the Setting Choices section for how to configure
  this option.

  For PrintPDF to be able to convert PostScript files into PDFs, a copy of
  GhostScript must have been seen by the Filer: it is recommended that
  Ghostscript is included in the list of applications to boot when the
  machine starts (see the instructions for Installing PrintPDF).

  Load Printers, and select on the iconbar the printer definition set up to
  work with PrintPDF.  Open the document from which you wish to create a PDF,
  and print it in the usual way.

  Instead of being sent to a printer, after a short pause the Create PDF
  dialogue should open.  This contains options to determine how the
  conversion is carried out, a file icon and a field for the filename.  With
  the options set correctly, enter a suitable filename and drag the file icon
  to the directory where the PDF is to be saved.  This will start the
  conversion process.

  Dragging a file into the file name field will set the path and filename.  A
  /pdf extension will be added automatically, and any existing extension will
  be replaced.  If the file dragged in already has an extension of /pdf, it
  will not be used to avoid accidentally overwriting the existing file.

  During the conversion, the file will be shown as incomplete in the
  directory display.  At the end of the conversion, if the option is set in
  the choices, a small window will pop up in the centre of the desktop to
  show that it has finished.  The PDF can now be loaded into a PDF viewer for
  checking.

  If 'Add to queue' is clicked, then the print job will be added to the queue
  instead of being converted to a PDF immediately; this allows several print
  jobs to be converted into a single PDF file.  The contents of the filename
  field is used to identify the print job in the queue: this does not need to
  conform to the standard filename conventions.  The other options in the
  dialogue box are ignored at this stage (they will be set when the files are
  taken from the queue for conversion).  See Using the Queue for more
  details.


  Setting the conversion options
  ------------------------------

  A number of options can be set to control how the conversion is carried
  out.  These affect various aspects of the process, such as the quality,
  size and security of the resulting PDF.

  The 'PDF version' field allows the version of PDF file to be set, to target
  different versions of PDF reader.  Versions 1.2 (Acrobat 3), 1.3 (Acrobat
  4) and 1.4 (Acrobat 5) are currently supported by GhostScript, although a
  number of features in version 1.4 are not yet implemented (see the
  documentation supplied with GhostScript for more details).

  The 'Optimization' of the file controls aspects of the conversion such as
  the use of compression and the resolution of any images that are included.
  A number of preset options are provided by GhostScript or the various
  parameters can be set manually, as described in the Document Optimization
  chapter.

  The 'Information' field allows the PDF document information to be set up:
  document title, subject, author and content keywords.  When the field shows
  'None' then the default values set by the printing system will be used.
  Clicking on the pop-up menu to the right of the field gives access to these
  entries, allowing them to be changed.  Most PDF readers show the document
  title in the titlebar of the display window, while the other fields appear
  with the document properties or document information.

  The paper size of the PDF document can be varied using the 'Paper size'
  field.  If 'Document' is selected then whatever size is defined in the
  printer driver will be passed straight through: note that this comes from
  the NAME of the paper, and there are some tight limitations on this if
  GhostScript is to recognise it.  Alternatively, one of the custom paper
  sizes supported by GhostScript can be selected from the various submenus:
  these are all internationally accepted 'standard' sizes.

  If none of the standard sizes are suitable, then selecting 'Custom...' will
  allow a non-standard paper width and height to be entered into the Custom
  paper size dialogue.  These can be specified in either mm, inches or points
  (1/72 inches) by using the radio icons to the right of the fields.
  Clicking on 'Set' will store the custom page size; clicking on 'Cancel'
  will abandon any changes which have been made.

  The 'Bookmarks' field can be used to attach a bookmarks file to the
  conversion: these can be used to identify chapter and section headings or
  other key locations in a document and enable readers to navigate through it
  easily.  The pop-up menu to the right allows a bookmarks file to be
  selected from those currently open in the bookmark editor; when it shows
  'None', no bookmarks will be used.  Selecting 'Create...' will open a new
  set of bookmarks in the bookmarks editor, while dragging a bookmarks file
  to the Create PDF window will load it and set it as the current file in the
  field.  Details of how to use the editor to create or load sets of
  bookmarks are given in the Bookmark Editor section.

  The 'Encryption' field allows access to the document encryption, password
  protection and access limitation features, if GhostScript 8.5 or better is
  being used.  When the field shows 'Unprotected', no encryption is applied;
  clicking on the pop-up menu icon opens a transient dialogue box to allow
  the various settings to be changed.

  Entering a password into the 'Owner password' field will cause the document
  to be encrypted with it.  This password controls the use of encryption: if
  it is blank, none is used and the other protection features will be
  unavailable.

  If an owner password is given, an 'Access password' may also be specified:
  if present, it must be entered by recipients of the document before they
  can view it.  Finally, a series of tick boxes allow the use of an encrypted
  document to be restricted: additional options become available if a PDF of
  version 1.4 (Acrobat 5) is being created.


  Other processing options
  ------------------------

  The 'Preprocess postscript file' option allows the postscript file
  generated by Printers to be passed through GhostScript's "*ps2ps" command
  before the PDF generation is started.  While this adds time to the
  conversion, it can allow some files to work which would otherwise fail to
  convert.  However, it can degrade the file quality and may also cause other
  unexpected problems and side effects.  As a result, it is not recommended
  to use preprocessing routinely; instead, apply it on a file-by-file basis
  should problems be experienced without its use.

  At the bottom of the dialogue is field to supply a 'PDFMark file' for the
  conversion: enter a filename into the field, or drag a suitable text file
  in from the filer.  This is a special file used by GhostScript to control
  different aspects of the conversion: at present it is intended for advanced
  users, and its operation is beyond the scope of this manual.


  Changing printer options
  ------------------------

  When printing, options such as page size and colour are controlled by the
  Printers application.  To change these, select 'Printer control...' from
  the Printers iconbar menu and double-click over the PDF PostScript printer
  entry to open the PostScript printer configuration dialogue.

  Paper size can be changed from the 'Paper' field at the top of the window.
  The sizes are chosen from the sizes that Printers knows about, and can be
  edited and added to in the usual way.  Further down the dialogue, the
  'Colour' option allows black and white or colour printing to be selected.

  The 'Text printing options' at the bottom of the dialogue control the way
  in which text printing is handled.  PrintPDF can cope with documents
  printed in text mode (such as those from a text editor), and the settings
  here adjust the way in which the output is fitted on to the page.


  Converting existing PostScript files
  ------------------------------------

  It is also possible to convert PostScript files which already exist on
  disc, by dragging them to the PrintPDF icon on the iconbar.  They will be
  added to the queue of files for conversion, and processed in turn.



Document Optimization
---------------------

  The 'Optimization' field allows control over aspects of the conversion such
  as the use of compression and the resolution of any images that are
  included.  A number of preset options are provided by GhostScript, or the
  various parameters can be set manually.

  The presets on offer are Default, Screen, EBook, Printer and Prepress.
  When in use, page data is always compressed; colour and greyscale images
  always use DCT (JPEG) compression, while mono images use CCITT Fax
  encoding.  Where applicable, downsampling is always done using the bicubic
  method with a threshold of 1.5 and depth set to off.

  * 'Default' does not downsample images.  Pages are rotated page by page.

  * 'Screen' downsamples colour and greyscale images to 72dpi, and mono
    images to 300dpi.  Pages are rotated page by page.

  * 'EBook' downsamples colour and greyscale images to 150dpi, and mono
    images to 300dpi.  Pages are rotated using 'all'.

  * 'Printer' does not downsample images.  Pages are not rotated.

  * 'Prepress' does not downsample images.  Pages are not rotated.

  | (!) Several of the preset options can interact badly with the RISC OS
  |     printing system.  In many cases it is better to avoid their use and
  |     set the optimization manually with the 'Custom...' option described
  |     below.

  To set the parameters manually, select 'Custom...' from the list to open
  the Custom optimization dialogue.  If 'Set' is clicked on, the settings in
  the dialogue box will be used by the conversion; clicking 'Cancel', or
  closing the dialogue by clicking outside it, will leave the existing
  settings in force.  The options control the downsampling of images to
  reduce their resolution, image compression, page rotation and compression
  of the overall page data.

  Downsampling can be enabled independently for colour, greyscale and mono
  images, using the three switches in the 'Image downsampling' section.  For
  each type of image, a target resolution in DPI can be set, and the method
  used to reduce the size can be selected from subsampling or averaging.

  The threshold can be used to limit downsampling to images which are more
  than a given resolution, and is specified in terms of a ratio of the target
  resolution.  That is, if the threshold is 1.5 and the target resolution is
  300, then the resolution of the original image must be more than 1.5 x 300,
  or 450, for downsampling to take place.  The colour depth of the resulting
  images (in bits per colour per pixel) can also be set; 'Off' indicates that
  the original depth will be retained.

  Compression can also be enabled for each type of image, using the 'Image
  compression' section.  The switches on the left turn compression on or off
  for each category, and the algorithm to be used can be specified.  In
  addition to the images, compression of the overall page data can also be
  enabled using 'Compress pages'.

  Finally, the orientation of individual pages can specified in the 'Auto
  page rotation' section. 'None' leaves all the pages as they are in the
  printed document, while 'All' will rotate all the pages to the same
  position to suit the predominant text orientation in the file. 'Page by
  page' will rotate each page individually, based on the predominant text
  orientation on it.



Bookmark Editor
---------------

  The bookmark editor is used to create sets of bookmarks, which can be
  attached to PDF files when they are created.  Bookmarks are links to pages
  within a PDF document, and most PDF viewers can be made to display them and
  allow the user to follow them.  The popular !PDF viewer on RISC OS refers
  to bookmarks as the "document outline", and displays them through the
  left-hand icon on its toolbar.

  To enable PDFs to be generated with bookmarks in them, PrintPDF allows
  files containing sets of bookmarks to be created and maintained: these can
  then be loaded back into the bookmark editor when their associated document
  is printed to PDF, and used in the conversion.  To create a new bookmarks
  file, click Select on PrintPDF's iconbar icon.

  A bookmarks file contains of a series of bookmark entries, each consisting
  of a title in the left-hand column and a page number in the right.  Page
  numbers always count from 1, and refer to pages in the finished PDF
  document.  If a document consists of several files joined together via
  PrintPDF's queue, then the numbers continue in sequence through each of the
  source documents in turn.  Page numbering as understood by software such as
  Impression or Ovation Pro is not seen by PrintPDF, and so can not be used.

  A new file initially contains a single line, but more can be inserted using
  'Insert -- Before row' and 'Insert -- After row' from the bookmarks menu,
  by pressing Tab in the page number column, or by pressing Return.  Lines
  can be deleted by using 'Delete row' from the menu, or by pressing
  Backspace in an empty title cell (ie. deleting back out of the empty cell).

  A set of bookmarks is given a name using the 'name' field at the right-hand
  side of the toolbar: this is used to identify the bookmarks during PDF
  creation.  The bookmarks to be used must be chosen in the 'Bookmarks' field
  of the Create PDF window before saving the PDF document.


  Saving and loading bookmarks
  ----------------------------

  Sets of bookmarks can be saved using the 'save' button in the toolbar or by
  selecting 'File -- Save' from the menu.  Once saved, files can be loaded
  back into the editor by double-clicking on them in the usual manner.

  An asterisk to the right of the bookmark editor window's titlebar indicates
  that there are unsaved changes within it.

  In order to use a set of bookmarks in the PDF creation process, the
  bookmarks file must be open in the bookmarks editor.  It does not have to
  have been saved, however.


  Nesting bookmarks
  -----------------

  Although bookmarks can consist of a simple list of references, the PDF
  format allows them to be nested.  This means that top-level bookmarks
  (chapter headings, for example) can have children under them (sub headings,
  perhaps) and these can in turn have their own children, and so on.  In this
  chapter of the PrintPDF manual, for example, the top-level bookmark would
  be "Bookmark Editor", while it would have children of "Saving and loading
  bookmarks" and "Nesting bookmarks".

  To produce nested bookmark entries, create a normal bookmark entry and use
  'Level -- Promote' from the menu or click on the 'promote' toolbar button
  to indent it.  The bookmark above will gain a 'node' to its left, showing
  that it now has a child: as such, the first bookmark in the list can never
  be indented.  The process can be reversed using 'Level -- Demote' or the
  'demote' button in the toolbar.

  The 'Promote all' and 'Demote all' options are similar in action, but try
  to promote and demote logical groups of bookmarks following the selected
  one.  In general, they will promote or demote all of the nodes following
  the selected one at the same level, and any of their children.  When
  demoting, it may sometimes be necessary to demote additional nodes so as to
  avoid breaking the bookmark structure: this will happen regardless of
  whether or not "all" is used.

  Clicking on the 'node' buttons to the left of the parent bookmarks allows
  their children to be hidden or revealed.  These settings are saved in the
  file and carried across to the finished PDF, so toggling these affects the
  unsaved status of the bookmarks file. 'View -- Expand all' and 'View --
  Contract all', along with the associated toolbar buttons, can be used to
  fully expand or fully contract the set of bookmarks.



Using the Queue
---------------

  Instead of converting print jobs into PDF files immediately, it is possible
  to add them to a queue of pending jobs for conversion at a later time.
  This allows separate print jobs to be grouped together and converted into a
  single PDF file.

  Note that the queue is cleared when PrintPDF is quit, so make sure that any
  outstanding print jobs are converted first.


  Adding files to the queue
  -------------------------

  To add a print job to the queue, click 'Add to queue' in the Create PDF
  dialogue instead of clicking 'Create' or dragging the file icon to a
  directory.

  The text in the filename field of the dialogue is used to identify the job
  in the queue.  As a result, it makes sense to ensure that this is
  recognisable (and not just left as the default); standard filename
  requirements do not apply to names in the queue.

  Since no conversion takes place at this stage, none of the other fields in
  the Create PDF dialogue are used.  The options will be set at the point
  where the files are taken from the queue and converted into a PDF.


  Accessing and working with the queue
  ------------------------------------

  To open the queue, select 'Queue...' from the iconbar menu; this will open
  the queue dialogue, which contains a scrolling list of all the queued print
  jobs.

  The entries in the queue consist of a PDF file icon alongside the names
  they were given when they were added.  To the left is a tick box which
  allows individual entries to be selected for conversion; to the right is a
  cross which allows items to be marked for deletion when the queue window is
  closed.

  The order of the entries in the queue can be changed by dragging individual
  items with Select.


  Creating PDFs from the queue
  ----------------------------

  To create a PDF from one or more items in the queue, select the items
  (using the tick boxes on the left) and place them in the required order by
  dragging them up or down the list.  Where more than one item is selected,
  they will be placed in the resulting PDF starting with the item nearest the
  top of the queue window and working down towards the bottom.

  When the required files are selected, click on 'Create' to close the queue
  and open the Create PDF dialogue.  The process for setting options and
  starting the conversion is the same as when converting a single file, and
  is described in the section on Using PrintPDF.

  Any items which were not selected for inclusion will remain in the queue
  for conversion later.



Setting Choices
---------------

  Selecting 'Choices...' from the iconbar menu allows various options to be
  set.  If PrintPDF is running without an iconbar icon, the Choices dialogue
  can be opened by double-clicking on !PrintPDF in a filer window for a
  second time.

  The 'PDF options' section sets the default options for the PDF conversion
  process, which appear in the Create PDF dialogue.  See Using PrintPDF for
  details of the available parameters (the bookmarks options are not
  included, as these will depend upon which bookmarks files are loaded at
  conversion time). 'Default file' allows the default filename used for new
  files to be set: this can be used to add a /pdf ending, alter the name
  completely, or specify a full pathname.  Dragging a file from a filer
  window into the field will set the name.

  'Indicate conversion end' specifies whether a pop-up window will appear at
  the end of the conversion process, to show that it has been completed.
  Although the file should be marked as incomplete during the conversion,
  this makes it clearer when GhostScript has finished.

  If 'Reset for every conversion' is ticked, the default filename and the
  options as set in this window will be used each time the Create PDF
  dialogue opens.  Otherwise, the filename and these options will be set when
  PrintPDF loads and after that the settings from the last conversion will be
  remembered.

  'Show iconbar icon' specifies whether PrintPDF will place an icon on the
  iconbar or not.  Since the icon is only used for printing postscript files
  and configuring Printers, running without an icon present saves space on a
  crowded bar.

  'Taskwindow memory' sets the amount of RAM given to GhostScript when a
  conversion is started.  How much is set will depend on the memory in the
  machine, but 8Mb (8192Kb) is recommended as a minimum unless free memory is
  tight.  If enough memory is available, 16Mb (16384Kb) or more is suggested.
  If too little memory is allocated here, it may result in unpredictable
  crashes.

  To set the options, click on 'Apply'; to save them to disc for future use,
  click on 'Save'.  As ever, Adjust clicks will update the settings and leave
  the window open. 'Cancel' will close the window and forget any changes;
  Adjust clicks will reset the window's contents to the currently stored
  settings.

  The PrintPDF choices dialogue can not be opened when there is a conversion
  in progress.  Conversely, new conversions will not start until the dialogue
  has been closed (and any files which are printed or dragged to the iconbar
  will be queued).



External Control API
--------------------

  To enable third-party applications to make use of PrintPDF, an external
  control API is provided using the "Message_PrintPDFControl" Wimp User
  Message.  Using this message, application authors can prime PrintPDF for a
  pending conversion, supplying a filename to which the resulting PDF should
  be saved.  The application can then initiate printing in the usual way,
  after which PrintPDF will notify it of the end of the conversion by sending
  it a User Message in reply.


  Message_PrintPDFControl (&5A480)
  --------------------------------

  A single User Message is used in the control API:
  "Message_PrintPDFControl", which has the number &5A480.  Every message
  contains a single reason code at offset 20 into the message block, which
  identifies its purpose.

  There are two reason codes used by PrintPDF to respond to messages from an
  application, which indicate the outcome of an operation.

  Success (1)

    The Success code is used to indicate that a conversion has completed
    without error, and the resulting PDF has been saved to the specified
    file.

    There is no additional data in the message block.

  Failure (2)

    The Failure code is used to indicate that either a command could not be
    accepted, or that a conversion failed.

    The message block contains an additional error code at offset 24, which
    is described in the appropriate places below.


  Initiating a conversion
  -----------------------

  To initiate a conversion under the API, an application should send
  "Message_PrintPDFControl" to PrintPDF with a reason code of Set Filename
  (0).  The full filename to which the PDF is to be written should be
  supplied from offset 24 into the block.

  The message should be sent recorded, either direct to PrintPDF or broadcast
  to all tasks.  If a suitable version of PrintPDF is loaded, then either

  * the message will be silently acknowledged if the request is accepted, or

  * a response will be sent with a Failure (2) reason code if the request
    failed.  There are two reasons why a request may fail: the API is already
    in use by an application, which has an error code of 0 at offset 24, or
    the filename was empty, which has an error code of 1.

  If the message bounces, this indicates that a suitable version of PrintPDF
  was not running on the computer.

  Should the message be accepted and silently acknowledged, then the
  application should proceed to print its document in the usual manner.  Once
  the printing is complete, then PrintPDF will respond to the original
  message in one of two ways.

  * If the conversion succeeded, then a Success (1) reason code will be
    returned.

  * If the conversion failed, then a Failure (2) reason code will be
    returned, with an error code at offset 24 indicating a possible cause of
    the problem.  At present, the only value is 2, which indicates a general
    conversion failure.

  Whichever outcome is achieved, the API is freed up ready for another
  conversion to be started.


  Cancelling a conversion
  -----------------------

  Since the API is locked from the point where a filename is set until the
  point where the conversion completes, it is possible for an application
  which sends a Set Filename request and then never initiates a print job (or
  whose print job fails before any output is generated) to block all future
  API requests.

  To reduce the impact of this, PrintPDF will watch for the exit of the task
  which currently has control of the API.  If this occurs, the API is
  released.

  In addition, an application can also clear a filename if it no longer
  wishes to initiate a print job.  To do this, is should send
  "Message_PrintPDFControl" to PrintPDF with a reason code of Clear Filename
  (3).

  The message should be sent recorded, either direct to PrintPDF or broadcast
  to all tasks.  If a suitable version of PrintPDF is loaded, then either

  * the message will be silently acknowledged if the request is accepted
    (either because the filename was cleared, or because one was not set in
    the first place), or

  * a response will be sent with a Failure (2) reason code if the request
    failed.  A request will fail if the task making it is not the task which
    set the filename, in which case there will be an error code of 3 at
    offset 24.

  If the message bounces, this indicates that a suitable version of PrintPDF
  was not running on the computer.



Version History
---------------

  Here is a list of the versions of PrintPDF, along with all the changes
  made.


  0.10 (10 July 2005)
  -------------------

  First Beta release.


  0.20 (16 July 2005)
  -------------------

  Second beta release.

  * Checks TaskManager on initialisation to prevent multiple copies running.
  * Seeing another copy of PrintPDF starting will open the Choices window.
  * Added 'Show iconbar icon' option.
  * Compiled against OSLib 6.70, using GCC 3.4.4r3.
  * Corrected URL for website link.
  * Changed name of child tasks.


  0.30 (4 September 2005)
  -----------------------

  Third beta release.

  * Writes GhostScript parameters to a file in PipeFS and calls "*gs @" to
    get around command line length restrictions on RISC OS 3.
  * Opens a "conversion finished" pop-up when child task terminates.


  0.31 (4 September 2005)
  -----------------------

  Update to third beta release.

  * The "conversion finished" pop-up can be selected from the Choices window.
  * While GhostScript is converting a file, the destination is given load and
    exec addresses of &DEADDEAD.


  0.32 (10 September 2005)
  ------------------------

  Update to third beta release.

  * Added FileName option token, and use it to override FileName token in
    Messages file when set.
  * Full path and filename is remembered between conversions if 'Reset for
    every conversion' option is off.


  0.40 (19 May 2006)
  ------------------

  Fourth beta release.

  * Default leafname changed to PDFFile/pdf.
  * Added preprocess option to allow files to be passed through "*ps2ps"
    before going on to "*ps2pdf".  This can help some files to work with
    GhostScript 8.5.
  * Added support for encrypted PDFs and security features in GhostScript
    8.5.


  0.41 (23 May 2006)
  ------------------

  Update to fourth beta release.

  * Encryption windows grey out when no creation password is entered.
  * Changes to the manual and interactive help text.


  0.45 (13 August 2006)
  ---------------------

  Update to fourth beta release.

  * Save filename preserved again unless 'Reset every...' option is on (was
    lost in 0.40).
  * Included Richard Hallas' RISC OS 5 iconsprites designs.
  * Restructured options handling, making it the job of both conversion and
    choices code to maintain their own state rather than having conversion
    assume that choices will maintain state across calls.
  * Added support for retaining encryption and protection options between
    sessions.
  * All changes to convert dialogue are remembered for next conversion, even
    if Cancel is clicked (was inconsistent).


  0.50 (9 November 2007)
  ----------------------

  Fifth beta release.

  * Support for EBook optimization added.
  * Printer optimization now sets "-dUseCIEColor=true" to prevent warnings
    from GhostScript.
  * Added 'custom' optimization option, to allow individual parameters to be
    set.
  * Some corrections to interactive help texts.
  * Some corrections to GhostScript command-line parameters.
  * Added 'Default file' option to choices window.


  0.51 (17 November 2007)
  -----------------------

  Update to fifth beta release.

  * Corrections to window templates for choices window.
  * Dragging a file to the 'Default file' field in the choices window sets
    the pathname.
  * Dragging a file to the file name field in the save PDF window sets the
    filename.
  * Included PDF600 printer definition, supplied by Bernard Veasey.


  0.52 (6 April 2008)
  -------------------

  Update to fifth beta release.

  * Support added for R-Comp's PDFsuite.


  0.60 (11 October 2008)
  ----------------------

  Sixth beta release.

  * Print jobs can be queued and merged into a single PDF.
  * Handles open target files more gracefully.


  0.61 (10 November 2008)
  -----------------------

  Update to sixth beta release.

  * Intermediate "*ps2ps" files correctly saved into queue (broken in 0.60).


  0.70 (6 March 2010)
  -------------------

  Seventh beta release.

  * Support for document information fields (title, author, subject,
    keywords) via the PDFMark interface.
  * Additional PDFMark file can be supplied to GhostScript for each
    conversion.
  * Manual updated to reflect PostScript3 driver setup details.


  0.71 (20 April 2010)
  --------------------

  Update to seventh beta release.

  * Fix escaping of ( and ) in PDFDocEncoding strings.


  0.80 (30 June 2010)
  -------------------

  Eighth beta release.

  * Add bookmarks editor.


  0.81 (1 July 2010)
  ------------------

  Update to eighth beta release.

  * Remove incorrect page-position data from bookmarks.


  0.82 (5 July 2010)
  ------------------

  Update to eighth beta release.

  * Internal improvements and restructuring of code.
  * Autoscrolling bookmark editor window no longer opens queue pane.


  0.83 (6 July 2010)
  ------------------

  Update to eighth beta release.

  * Fix click/drag behaviour in bookmark editor.
  * Adjust close of bookmarks window conforms to Style Guide.
  * Warn of unsaved bookmarks and pending conversions before quit.


  0.84 (9 July 2010)
  ------------------

  Update to eighth beta release.

  * Merge printer sprites into application IconSprites and amend installation
    procedure.
  * Fix sprite selection on RISC OS 6.
  * Improve manual and interactive help.
  * Remove ineffectual PDF600 printer definition file.


  0.85 (11 July 2010)
  -------------------

  Update to eighth beta release.

  * Dragging bookmark files to the Create PDF window loads it and sets it as
    the current bookmarks for the conversion.
  * Internal improvements and restructuring of code.


  0.86 (2 November 2010)
  ----------------------

  Update to eighth beta release.

  * Adjust-clicks on iconbar open the queue window.
  * New bookmarks can be created from the pop-up menu in the Create PDF
    window.
  * Correctly set bookmark page positions, and ignore broken YOffset values
    in offending bookmark file format.


  0.87 (17 April 2011)
  --------------------

  Update to eighth beta release.

  * Correct buffer length calculations and text truncation in PDF Doc
    Encoding conversions.


  0.88 (4 August 2012)
  --------------------

  Update to eighth beta release.

  * Extensive internal restructuring.
  * Rebuilt to confirm ARMv6 compatibility.


  1.00 (14 October 2012)
  ----------------------

  First stable release.

  * Relicensed as Open Source.


  1.10 (26 February 2016)
  -----------------------

  Second stable release.

  * Support added for controlling paper size (ticket #392).
  * Don't assume that child task will start immediately, to avoid problems
    when launching Zap to handle task windows (ticket #356).


  1.11 (5 March 2017)
  -------------------

  Update to second stable release.

  * Fix !Help so that 'Help' menu items work correctly.
  * Improve error handling when Templates or Sprites are missing on startup.


  1.12 (22 October 2017)
  ----------------------

  Update to second stable release.

  * Bookmark title fields no longer overwrite each other when multiple files
    are open (ticket #619).
  * Remove all unbounded string operations from source code.


  1.13 (28 July 2020)
  -------------------

  Update to second stable release.

  * Correctly ensure that a C99-friendly version of the Shared C Library is
    present (ticket #635).
  * Use ResConf-style system variables to identify resources.


  1.20 (20 April 2023)
  --------------------

  Third stable release.

  * Add support for an external control API, allowing other applications to
    automate the process of generating PDFs.




Updates and Contacting Me
-------------------------

  If you have any comments about PrintPDF, or would like to report any bugs
  that you find, you can email me at the address below.

  Updates to PrintPDF and more software for RISC OS computers can be found
  on my website at http://www.stevefryatt.org.uk/risc-os

  Stephen Fryatt
  email: info@stevefryatt.org.uk
