PSAlter workbench: for PostScript debugging

This is a shortened version of an introductory chapter in the PSAlter user manual. It assumes, of course, that the reader has a copy of PSAlter running, but it should give an idea of what to expect, and we have added some screen shots.

The PSAlter Workbench provides a complete environment for developing, testing and debugging PostScript. You can also use it to view or translate PostScript, but most people will find it easier to use the View or Translate modes for that, since there are fewer choices to make.

This gives a whirlwind tour of the PSAlter workbench and some of its features.

Starting

Start PSAlter. Choose Workbench (or press W) on the startup screen.

You will see the PSAlter workbench, with status line at the bottom and a smaller ‘Untitled program’ child window. This will be blank.

Screen shot of workbench

Look at the status line along the bottom of the PSAlter window. This has various buttons (Run, Pause etc.) that we will be using, though if you have no mouse there are equivalent entries on the Run menu at the top.

You will also see an icon labelled %stdout. This is where the PostScript output log is written. We won't mention it further; although the output log is essential to PostScript debugging with other products, it is rarely needed in PSAlter.

Click on the Run button (or use Run | Start). PSAlter sees there is no program, so it gives you the chance to open a program and run it. Choose the file tiger.ps from the PSAlter demo files, typically in c:\psalter\demo. PSAlter will start to run the program, but first it will open up an image viewer which may partly obscure the program.

Watch the percentage bar in the window. When it is about 30% done click on the Pause button. The program will pause, and you can see what it is doing. If the program runs too fast and finishes, you can restart it with Run as often as you like.

Pausing, viewing the image

Click the right mouse button over the image viewer (not on the title) and choose Update | Update images now from the menu which appears. You can now see how far the drawing has gone. Scroll about the image or resize it if you want to see more.

Paused during run

Is the image in black and white? You can start again and have it in colour. Click Stop. Choose Options | Imaging setup and then choose Image As: 256 colours (not 256 greys). Check also that you set Resolution: 75 dpi. Now click OK, then Run again. Pause when 30% done as before.

Watching the image build

From the right button menu for the image, choose Update | Keep updating images.

Now click Run again. The program will continue, but this time much more slowly. You should be able to see the parts of the picture being added. If you can’t see anything changing, scroll around the picture in search of some action.

Now, while it is running, choose Overlay | Show current path from the image right button menu. This will show a red line for the current path. The path is the (normally) invisible construction lines used to put together the image, a piece at a time. There is not always a path to see; if you have any trouble finding it, click Stop then Run again - it is easier to see on a blank screen.

Watching the program

We will now look at the program itself. But first, remember to switch off Overlay | Show current path and Update | Keep updating images, since they will slow everything else down.

You can close down the image window or resize it so the program is visible. Never be tempted to close the program window so you can see more of the image, since that will stop everything!

Click on Walk in the status line. The program will slow to a crawl, and you will be able to see each item as it is executed. Many of the items executed are constants, which are put on the operand stack so, while it is running choose View | Stack | Operand stack. This will show items being added, and then removed by operators.

Note that you can choose to view stacks 'top down' or 'bottom down', whichever suits you best.

Looking at some data

Another important stack is the dictionary stack, though it doesn’t change very much in this program. Choose View | Stack | Dictionary stack while in the middle of the tiger.ps program and you should see a list of three dictionaries. Stretch the dictionary viewer to make it wider so you can see the names. The three items will probably be systemdict, userdict, and Adobe_Illustrator_1.2d1. Double click on the last of these and a dictionary viewer will open showing the contents of it.

Press and hold the mouse over any item in the viewer and you will see the contents expanded in the status line. You can also double click on the dictionaries and arrays to open more viewers.

You can also set a 'watch'. Click over a name in the program and press Ctrl+W. The 'watches' window will appear, showing the current value of that variable at all times. If the variable does not yet exist, it will show 'undefined'

Samples of data viewers

Setting a breakpoint

Breakpoints are all about pausing a program automatically at important moments. Most programs will take far too long to run if you walk through every part of them.

We will set an operator breakpoint. Choose Window | Breakpoint control. On the window which opens, click Add Operator, then type ‘fill’ and press Enter.

Make sure you can see the program window, then click Run to go at full speed. Fairly soon, the program will pause, and you should see ‘fill’ highlighted. Using this technique you can pause before or after any operator.

Now try another technique. Move to halfway through the program. Click on any part of it and press F9. The current word will be outlined. Whenever the program reaches this point, the program will pause. If it is within a procedure, the program may pause many times.

You can also set breakpoints on a variety of other actions, including when a name is changed or referenced; and when a particular rectangle on the page is changed.

Some help

Finally, let’s take a look at the online help. Click on Stop to stop the program. Go to the top of the program (scroll, or press Ctrl+Home).

Look for a PostScript operator such as exch, add or def. Click on the operator name, then use Help on PostScript operator from the program’s right button menu. You should see help on the operator.

Operator help screen shot

Try again, first clicking on something which is not an operator. You should now see the index of operators, and you can click on any of them to see the help for that operator.

Don’t forget that the help is not intended to teach PostScript from scratch, but as a reference for programmers who already have some knowledge of PostScript.

PSAlter is designed to be just as useful to the beginner typing in a few lines of PostScript as to the professional trying to debug large programs - PSAlter can handle files up to 500 megabytes in size.

If you are just starting be warned - examining other PostScript programs, like the sample programs, may seem a good starting point. But most of them are generated for efficiency and are very hard to read. One sample program, 7star.ps, is intended as a fairly simple example to start with.

			Home page \| Products \| Support \| Download \| Buy \| Contact You are here: Quite > Products > PSAlter > Workbench

	PSAlter Introduction Viewing PostScript EPS Workbench Fonts Release notes Upgrade How to buy Manual (PDF)		PSAlter workbench: for PostScript debugging This is a shortened version of an introductory chapter in the PSAlter user manual. It assumes, of course, that the reader has a copy of PSAlter running, but it should give an idea of what to expect, and we have added some screen shots. The PSAlter Workbench provides a complete environment for developing, testing and debugging PostScript. You can also use it to view or translate PostScript, but most people will find it easier to use the View or Translate modes for that, since there are fewer choices to make. This gives a whirlwind tour of the PSAlter workbench and some of its features. Starting Start PSAlter. Choose Workbench (or press W) on the startup screen. You will see the PSAlter workbench, with status line at the bottom and a smaller ‘Untitled program’ child window. This will be blank. Look at the status line along the bottom of the PSAlter window. This has various buttons (Run, Pause etc.) that we will be using, though if you have no mouse there are equivalent entries on the Run menu at the top. You will also see an icon labelled %stdout. This is where the PostScript output log is written. We won't mention it further; although the output log is essential to PostScript debugging with other products, it is rarely needed in PSAlter. Click on the Run button (or use Run \| Start). PSAlter sees there is no program, so it gives you the chance to open a program and run it. Choose the file tiger.ps from the PSAlter demo files, typically in c:\psalter\demo. PSAlter will start to run the program, but first it will open up an image viewer which may partly obscure the program. Watch the percentage bar in the window. When it is about 30% done click on the Pause button. The program will pause, and you can see what it is doing. If the program runs too fast and finishes, you can restart it with Run as often as you like. Pausing, viewing the image Click the right mouse button over the image viewer (not on the title) and choose Update \| Update images now from the menu which appears. You can now see how far the drawing has gone. Scroll about the image or resize it if you want to see more. Is the image in black and white? You can start again and have it in colour. Click Stop. Choose Options \| Imaging setup and then choose Image As: 256 colours (not 256 greys). Check also that you set Resolution: 75 dpi. Now click OK, then Run again. Pause when 30% done as before. Watching the image build From the right button menu for the image, choose Update \| Keep updating images. Now click Run again. The program will continue, but this time much more slowly. You should be able to see the parts of the picture being added. If you can’t see anything changing, scroll around the picture in search of some action. Now, while it is running, choose Overlay \| Show current path from the image right button menu. This will show a red line for the current path. The path is the (normally) invisible construction lines used to put together the image, a piece at a time. There is not always a path to see; if you have any trouble finding it, click Stop then Run again - it is easier to see on a blank screen. Watching the program We will now look at the program itself. But first, remember to switch off Overlay \| Show current path and Update \| Keep updating images, since they will slow everything else down. You can close down the image window or resize it so the program is visible. Never be tempted to close the program window so you can see more of the image, since that will stop everything! Click on Walk in the status line. The program will slow to a crawl, and you will be able to see each item as it is executed. Many of the items executed are constants, which are put on the operand stack so, while it is running choose View \| Stack \| Operand stack. This will show items being added, and then removed by operators. Note that you can choose to view stacks 'top down' or 'bottom down', whichever suits you best. Looking at some data Another important stack is the dictionary stack, though it doesn’t change very much in this program. Choose View \| Stack \| Dictionary stack while in the middle of the tiger.ps program and you should see a list of three dictionaries. Stretch the dictionary viewer to make it wider so you can see the names. The three items will probably be systemdict, userdict, and Adobe_Illustrator_1.2d1. Double click on the last of these and a dictionary viewer will open showing the contents of it. Press and hold the mouse over any item in the viewer and you will see the contents expanded in the status line. You can also double click on the dictionaries and arrays to open more viewers. You can also set a 'watch'. Click over a name in the program and press Ctrl+W. The 'watches' window will appear, showing the current value of that variable at all times. If the variable does not yet exist, it will show 'undefined' Setting a breakpoint Breakpoints are all about pausing a program automatically at important moments. Most programs will take far too long to run if you walk through every part of them. We will set an operator breakpoint. Choose Window \| Breakpoint control. On the window which opens, click Add Operator, then type ‘fill’ and press Enter. Make sure you can see the program window, then click Run to go at full speed. Fairly soon, the program will pause, and you should see ‘fill’ highlighted. Using this technique you can pause before or after any operator. Now try another technique. Move to halfway through the program. Click on any part of it and press F9. The current word will be outlined. Whenever the program reaches this point, the program will pause. If it is within a procedure, the program may pause many times. You can also set breakpoints on a variety of other actions, including when a name is changed or referenced; and when a particular rectangle on the page is changed. Some help Finally, let’s take a look at the online help. Click on Stop to stop the program. Go to the top of the program (scroll, or press Ctrl+Home). Look for a PostScript operator such as exch, add or def. Click on the operator name, then use Help on PostScript operator from the program’s right button menu. You should see help on the operator. Try again, first clicking on something which is not an operator. You should now see the index of operators, and you can click on any of them to see the help for that operator. Don’t forget that the help is not intended to teach PostScript from scratch, but as a reference for programmers who already have some knowledge of PostScript. PSAlter is designed to be just as useful to the beginner typing in a few lines of PostScript as to the professional trying to debug large programs - PSAlter can handle files up to 500 megabytes in size. If you are just starting be warned - examining other PostScript programs, like the sample programs, may seem a good starting point. But most of them are generated for efficiency and are very hard to read. One sample program, 7star.ps, is intended as a fairly simple example to start with. See also What is PSAlter? PostScript introduction Go to Quite At Home.

PSAlter