Monday, July 16, 2012

pstops tutorial (psutils)

I have recently started to port my game engine GGE to HTML5. So i downloaded javascript & HTML5 tutorials (PDFs) from

But now a days i only keep pocket references for technologies i use instead of heavy books. So i wanted to make a pocket version of those PDFs. I found "pstops" after google'ing, in just an hour i was irritated by the mangled parameters it needed and badly documented manpages & stuffs on internet.

But these two pages made my concept clear and i achieved my task in few minutes.

[REF1] Read this first:

[REF2] Then ( this will make you clear about what exactly pstops does):

My own description ( i assume you have read REF1):
pstops => postscript to postscript converter with desired arrangements, page layouts and sizes.

I will describe this powerful utility by small implementation because that in run accomplishes many people's job.

For experiments please get a ps file of atleast 16 pages. You can convert a PDF into ps by using pdftops utility (its a part of psutils). I am using 23 page file. Lets do some ps conversions.

1. Flip all the pages vertically Or horizontally
pstops '1:0V' 

pstops '1:0H' 

As you can see the parameters of pstops are:

pstops  [ -q ] [ -b ] [ -wwidth ] [ -hheight ] [ -ppaper ] [ -dlwidth ] pagespecs [ infile [ outfile ] ]

Most of us have difficulty in pagespecs parameter only. Which is described below:

pagespecs   = [modulo:]specs
specs          = spec[+specs][,specs]
spec            = [-]pageno[L][R][U][H][V][@scale][(xoff,yoff)]

In our flip example, we used '1:0H', What are these hex like codes? lets dissect -
1 => it tells that we want  to print 1 page of "" in 1 page of (A4 by default).
If we want to print 4 pages in 1 A4 page we have to use '4:0', for 8 we use '8:0'

: sign is followed by SPECS. But we have nothing after 0. It simply means that we want to use original unchanged source pages in output file. With -0 end becomes start and start becomes end page. i.e. page numbers get inverted.

2. Lets print two pages in one side, i.e. total 4 in 1 output page. Portrait mode 
pstops '4:0'
output => [1] [2] [3] [4] [5] [6] Wrote 6 pages, 1250990 bytes

We get 6 pages in output. But, upon seeing why we get only 6 pages printed from source instead of all pages? The answer is simple: Did we specified how and where the pages had to be printed? we told to print 0 only i.e. 1st page ( 0 index => 0+1 page number ) of every block.

You don't know what block is? Please refer to REF1 above. In brief i also write here:
Blocks = total pages in input file / total pages we want in our 1 page of output file

1 block simply means number of input pages we want to be printed in 1 output page, above we told to print only 0th index Or 1st page of every block. That is why only 1st pages were printed.

Below is the proper command to print all pages.
pstops '4:0@0.5(0.0w,0.5h)+2@0.5(0.0w,0.0h),1@0.5(0.0w,0.5h)+3@0.5(0.0w,0.0h)'

It will output 2 portrait pages per side. Lets understand all the parameters:
4: => 4 input pages / 1 output page

0 => 0th index of block i.e. 1st page
(0.0w,0.5h) => move right by 0% of page width. 50% of height. AFAIK the w,h are of source page.
@0.5 => scale to become 50% of original size.

+ => continuing page on 1st side.
2 => 2nd index of block i.e. 3rd page
(0.0w,0.0h) => no movement, just remain at output's Origin i.e. left-bottom. Just like Cartesian coordinates.
@0.5 => scale to become 50% of original size.

1. x,y are offsets, this is what i have understood, they are not exact render start points. Therefore you should have noticed to draw from top we just have to go 0.5h ( half of output page height instead of full height). 

2. I have not used rotations. You should keep in mind that after rotation the origin of that rotated page still remains at its own left-bottom. So the whole output will change after using rotations. Try it:

pstops '4:0L@0.5(0.0w,0.5h)+2L@0.5(0.0w,0.0h),1L@0.5(0.0w,0.5h)+3L@0.5(0.0w,0.0h)'

It outputs blank pages! You know why?
Because when we rotated left (imagine you are holding the paper at left-bottom and rotated it left. Then it goes outside of the output page boundaries. For that you have to translate all pages by full width.

so try this now:

pstops '4:0L@0.5(0.75w,0.5h)+2L@0.5(0.75w,0.0h),1L@0.5(0.75w,0.5h)+3L@0.5(0.75w,0.0h)'

in parameters we have described that 1st side of output page will follow this specification:
pages: 1, 3
and the second back side will follow this: ( separated by comma )
pages: 2, 4

Then all the coming blocks will follow these specifications.

For more details below is a simple illustration: please neglect the quality, i made it quickly to illustrate rather than writing 100 lines. :-)

hope this tutorial will help you to understand how to utilize the power of pstops without Hit n Trials method :-p. Please let me know if you find some bugs or wrong info (if really it is).

Search TAGs:
linux 4-up, make 8 page booklet, linux pstops tutorial, pstops concept, how pstops works, make mini booklets, 8 page booklets