Class RGhost::Document
In: document.rb
Parent: RGhost::PsFacade

The Document class child of PsFacade is used to join postscript objects to generate output file.


Included Modules



DEFAULT_OPTIONS = { :rows_per_page => 80 , :count_pages => 10, :row_height => 0.4, :row_padding => 0.1, :font_encoding=> RGhost::Config::GS[:font_encoding], :paper => RGhost::Paper::DEFAULT_OPTIONS

Public Class methods


Creating document with 80 rows per page and custom paper :rows_per_page => 80, paper => [30,5]

Document A4 with row height 0.5 and font encoding CodePage1252 :row_height => 0.5, :font_encoding => 'CodePage1252'

Defining all margins :margin => 0.5


  • :paper - Facade to paper defined on the construction of Paper class
  • :margin, :duplex and :tuble - Facade to options defined on the construction of Paper class
  • :rows_per_page - Specifies count of rows per pages.
  • :landscape - Whether true invert de size(width per height)
  • :count_pages - Defines postscript internal variable to display with class TextIn. Example: :count_pages => 10
 doc.before_page_create :except => 1 do
  text_in :x => 15, :y => 5, :write => "Page %current_page% of %count_pages%"

The value above %count_pages% will be evaluated inside of document for all pages except page one.

  • :fontsize - Defines the size of tag :default_font.
  • :row_height and row_padding - Its names say by itself :)
  • :font_encoding - Specifies encoding of data input. You can look for supported encoding using the method RGhost::Config.encode_test

Public Instance methods

Starts and Ends internal benckmark will write in bottom of page.

 doc.benchmark :start
 doc.... #do something
 doc.benchmarck :stop
 doc.render ...

Facade to Defines low level function to optimize repetitive piece of code.

 doc.define :piece do
   set Cursor.next_row
   set Cursor.next_row
 #Repeting ten times the same code
 10.times{ :piece }

Defines a function using the method define after that call de function one time.

Creates map of tags if will be use in ‘writable’ classes(Show, Text, TextIn and TextArea). The font names file catalog can be generated by code below

  RGhost::Config.enviroment_fonts.render :pdf, :filename => "mycatalog.pdf"

this can take while. If waiting for much time you has any font with problem, remove some fonts mostly international fonts not used often. Below little piece of catalog

After genereted catalog you can map your tags.

Tags has name of tag(as Symbol) and its options. The options are

  • :name - Font name from catalog.
  • :size - Font size.
  • :color - Color.create facade
  • :encoding - If true the font will be encoding using de pattern :font_encoding of the document.

Examples :encoding => 'IsoLatin'
 d.define_tags do
  tag :my_italic,    :name => 'Hershey-Gothic-Italian-Oblique', :size => 10
  tag :myfont,       :name => 'Hershey-Plain'
  tag :font_encoded, :name => 'NimbusMonL-Regu',    :size => 8,  :color => 0.5, :encoding => true
  tag :other_font,   :name => 'NimbusMonL-Regu',    :size => 10
  tag :arial,        :name => 'Arial-ItalicMT',     :color => '#ADAD66'
  tag :arial_bold,   :name => 'NimbusSanL-BoldItal',:size => 12, :color => '#ADAD66'

You can use :default_font tag for custom the default font.

Using tags

With Show class 'My Text on this row', :with => :my_italic, :align => :page_center

With Show class overrinding tag‘s color. 'My Text on this row', :with => :my_italic, :align => :page_center, :color => :red

With TextIn class.

 doc.text_in :x=> 3, :y=> 10, :tag => :arial_bold , :write => "Here's point(3,10)"

With Text

 doc.text '<myfont>My Text</myfont>on this row.<arial>Other text</arial><my_italic>Italic font</my_italic>'

With TextArea

 txt='<myfont>My Text</myfont>on this row.<arial>Other text</arial><my_italic>Italic font</my_italic>'
 doc.text_area txt, :text_align => :center, :width => 5, :x => 3, :y => 10

Using tag

 doc.use_tag :myfont "Simple Text", :tag => nil # it will use :myfont "Simple Text2", :tag => nil # it will use :myfont too

Rghost can make use of Encapsulated Postscript files to act as templates(EPS). This way you can create the visual layout of the page using a graphics tool and just paint the dynamic pieces over using Rghost.

Above we have mytemplate.eps that was generated by a graphic app, my_ruby_program.rb that takes care of the positioning and at last the generated output.

A Template use example Let‘s say that the files first.eps and content.eps already exist. Now we shall see how to create a document that uses the template first.eps for the cover and the rest of the document uses content.eps.

 d = :margin_top => 5, :margin_bottom => 2

Just for the first page

 d.first_page do
  image "/my/dir/first.eps"                          #loads the template
  text_in :x=> 5, :y=> 17, :text => "My Report", :with => :big
  next_page                                          #go to the next page using cursors

Callback for all other pages.

 d.before_page_create :except => 1 do
  image "/my/dir/content.eps"
  text_in :text => "Page %current_page% of %count_pages%", :x => 18, :y => 27, :with => :normal

1500 rows

 1500.times do |n| "Value #{n}"

We have a cover page and 1500 rows, judging by the margins each page supports 46 rows, so we have 1500/46 = 32.60 pages plus the cover. Rounding it up totals 34 pages for the :count_pages

  d.define_variable(:count_pages, 34)
  d.render :pdf, :filename => "/tmp/test.pdf"

If we knew the amount of pages beforehand we could state it on the creation of the document, i.e.

  :current_pages => 34

The example uses one template per page, but this is not a limit in RGhost. You can have multiple images and templates on per page. Just have to define the template: :margin_top => 5, :margin_bottom => 2
   d.define_template(:myform, '/local/template/form1.eps', :x=> 3, :y => 5)

and call it on the document.

  d.use_template :myform


  • :name - Template‘s name.
  • :file_path - Path to file.
  • :options - Options facade to Image.for(or image)

Informs is ready to converts/prints

Prints the text file using the predefined tag +:pre+

Example :paper => :A4, :landscape => true
 doc.print_file "/etc/passwd"
 doc.render :pdf, :filename => "/tmp/passwd.pdf

Facade to RubyGhostEngine.render Converts a document to an output format, such as :pdf, :png, :ps, :jpeg, :tiff etc The paramter device can be found at RGhost::Constants::Devices or at


Method render have the following options available.

  • :filename - File path.
  • :logfile - Writes the converter‘s process into a file.
  • :multipage - Whether true the output will be one page per file posfixed by _0001.ext, for example, for one file name ‘test.png’ with two pages will create test_001.png and test_002.png
  • :resolution - Integer value to output resolution.
  • :size - Crops a single page using a string of dimension, example, ‘200x180’, ‘140x90’.
  • :range - Specifies range of pages(PDF only)

Ghostscript interpreter options

Array of Hashes for Ghostscript interpreter look at for more details. You can use two parameter :s and :d, examples

   :s => [{:GenericResourceDir => /dir, :DEFAULTPAPERSIZE=> "a3"}]
   :d => [ {:TextAlphaBits => 2}  ]

Or one string using the parameter :raw, as below

   :raw => "-sGenericResourceDir=/test -dTextAlphaBits=2"

  #do something

  doc.render :pdf,  :filename => 'foo.pdf   # PDF output
  doc.render :jpeg, :filename => 'foo.jpg'  # JPEG output
  doc.render :png,  :filename => 'foo.png',  :multipage => true      # PNG output one page per file
  doc.render :tiff, :filename => 'foo.tiff', :resolution => 300      # TIFF with 300dpi
  doc.render :ps, :raw => '-sFONTMAP=/var/myoptional/font/map', :filename => ''

Testing if has errors
 doc.raw "hahahah!" #it produce error in ps stack
 doc.render :jpeg, :filename => 'with_error.jpg'
 puts r.errors  if r.error? #=> GPL Ghostscript 8.61: Unrecoverable error, exit code 1.\ Error: /undefined in hahahah!


Using printing system
  #do something
  doc.render :laserjet, :filename => f
  `lpr #{f}`

Windows shared printer

 doc.render :eps9mid, :filename => "//machine/printer"

Behavior as render but returns content file after convertion.

Example with Rails

 def my_action
   #do something
   send_data doc.render_stream(:pdf), :filename => "/tmp/myReport.pdf"

TCP/IP direct printer

 require 'socket'
 #do something
 printer ='', 9100)
 printer.write doc.render_stream(:ps)

With method virtual_pages you can define any virtual pages per physical page. The cursor into virtual page jumps in column for each virtual page and run primitives next_page when ends columns. Look the example below. Example for a document without virtual pages we will has
 doc.text File.readlines("/tmp/mytext.txt")

will generate

Now for a document with 3 virtual pages
 doc.virtual_pages do
   new_page :width => 4
   new_page :width => 7, :margin_left => 1
   new_page :width => 4, :margin_left => 1
 doc.text File.readlines("/tmp/mytext.txt")

will generate

PS: The parameter margin left of first virtual page won‘t be used because it‘s will use page‘s margin left.