=============================================================================
PS2Paper - Manage PostScript 2 Paper Sizes                       Version 0.11

(c) Stephen Fryatt, 2013-2020                                    28 July 2020
=============================================================================

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

Licence
-------

  PS2Paper is licensed under the EUPL, Version 1.1 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 PS2Paper can be found alongside this binary download, at
  http://www.stevefryatt.org.uk/software

  The necessary libraries and build tools can be found at
  http://www.stevefryatt.org.uk/software/build



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

  PS2Paper is a utility to help manage the different paper sizes configured
  for the Acorn Level 2 PostScript printer driver supplied with RISC OS.
  Note that PS2Paper is NOT required when using the Level 3 PostScript driver
  from John Tytgat and Martin Wuerthner.

  Perhaps surprisingly for a printer driver, the Level 2 PostScript driver
  does not directly use the paper dimensions defined in Printers.  Instead,
  it uses the NAME of the paper to help identify a snippet of PostScript data
  held in a small file inside !Printers (or the user's choices inside !Boot),
  and includes this in a suitable place in the PostScript data being output.
  If this snippet contains the page dimensions, these then get passed on to
  whatever subsequently reads the PostScript output.

  The purpose of PS2Paper is to help keep track of the different papers
  defined on your system and the corresponding PostScript snippets -- and to
  help ensure that the sizes given in those snippets actually match the sizes
  given for the associated paper definitions.

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



Installing PS2Paper
-------------------

  To install PS2Paper, drag the !PS2Paper application directory from the
  archive to a suitable location on your hard disc.  Once copied, PS2Paper
  can be started by double-clicking in the usual way.

  PS2Paper is 26/32-bit neutral, and should therefore run on all hardware
  systems as long as the 32-bit Shared C Library is installed.  If required,
  this can be found in the System Resources on RISC OS Open Ltd's website at
  https://www.riscosopen.org/content/downloads/common.



Using PS2Paper
--------------

  Once installed on disc, PS2Paper can be started in the usual way by
  double-clicking on its application directory to place a copy on the
  iconbar.  Once on the iconbar, a Select click on its icon will scan the
  paper sizes on the system and then open the paper window.

  The window shows a list of the paper sizes available to the PostScript
  Level 2 printer driver, grouped into the three sections that they are held
  in within Printers.  Although these all appear in the dialogue which opens
  when selecting 'Edit paper sizes...' from the Printers iconbar menu, the
  fact that there are three distinct places which hold paper definitions
  explains why it's possible to have more than one paper size with the same
  name.

  Each row shows the width and height of the paper, in either millimetres,
  inches or points (as selected from the toolbar, or from the 'Dimension
  units' submenu).  Note that this is the overall paper dimension, before any
  margins are applied.  To the right of these 'Width' and 'Height' columns is
  the 'Size' column, which shows either 'OK' or 'Ambiguous' -- we will come
  on to this soon.

  The 'File Name' column shows the name of the PostScript snippet file
  associated with the paper.  The name of the file is derived from the name
  of the paper associated with it, converted to lower case and truncated at
  the first space.  As a result, a paper definition named 'A4' would have a
  snippet file called a4 -- but then, so would a paper size with the name
  'A4 Paper' or even 'A4 (Generic PS)'.

  There's clearly a risk that with this ambiguity in file names, two or more
  paper definitions could both resolve to the same name for the snippet file.
  If all of the affected paper sizes are the same, the 'Size' column shows
  'OK', but if any of them are different they ALL show 'Ambiguous'.

  Finally, the 'Status' column shows what PS2Paper can make of the snippet
  file and its contents.  If there is no file of the given name on the
  system, the file icon is greyed out and the status shows as 'Missing'; if
  there is a file, but it wasn't created by PS2Paper, the column shows
  'Unknown'.  Otherwise, the column shows 'Correct' if the snippet contains
  the same dimensions as shown in the 'Width' and 'Height' columns, or
  'Incorrect' if there's a discrepancy.

  Double-clicking on a file icon in the 'File Name' column will run it in the
  usual way: hold down Shift to load a snippet into a text editor for
  inspection.  The selected files can also be run by selecting 'Selection --
  Run snippet' from the menu.

  The different paper definitions can be selected by clicking Select or
  Adjust on the items in the 'Paper Name' column.  To update the contents of
  the PostScript snippet files for the selected papers so that they contain
  the correct paper dimensions (or create new ones if the files don't exist),
  choose 'Selection -- Write files' from the menu.



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

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


  0.10 (29 October 2016)
  ----------------------

  First beta release, for feedback and comment.


  0.11 (28 July 2020)
  -------------------

  Update to first beta release, for feedback and comment.

  * Remove all unbounded string operations from source code.
  * Correctly ensure that a C99-friendly version of the Shared C Library is
    present (ticket #637).
  * Use ResConf-style system variables to identify resources.




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

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

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

  Stephen Fryatt
  email: steve@stevefryatt.org.uk
