Layout Specification

This is just a starting point for discussion on how to describe the layout of a print production document.

DMSG INI File Format

This structure was developed by DM Solutions Group for its MapSherpa PDF map generator. It is processed by some PHP code and a PDF is generated using FPDF, although any PDF library could be used. MapServer is used. The structure could easily be converted to another format such as XML or YAML. This structure is focused on producing PDF documents from flexible templates, it is not designed to handle generic production layout tasks but it can hopefully be extended to include additional needs as they are discussed/discovered.

Here is a sample PDF .

There are several concepts central to the structure:

an overall document section that describes the pages in the document and default style values (font face, units of measure, document metadata)
page sections that describe individual pages in the document (size, orientation, margins, and style values for that page) and a list of blocks in the page
blocks that are rectangular regions to be rendered on a page. Blocks have size, position, style values and a type
styling uses CSS-like naming structure and values where practical
Styles are inherited by child blocks when not explicitly defined in a child block
all values that have units inherit the default units of the document or can have units as part of the value and are automatically converted

Style Keys

any section may define the following style keys

font-face = DejaVuSans
font-size = 12pt
font-style = normal
font-weight = normal
text-decoration = none
line-height = 16pt
text-align = left
vertical-align = top
background-color = 255 255 255 ; colors are RGB 0-255
color = 0 0 0
border-color = 0 0 0
border-width = 0 ; may use two (top-bottom and left-right)
                 ; or four (top, right, bottom, left) values
margin = 0pt     ; may use two (top-bottom and left-right)
                 ; or four (top, right, bottom, left) values
padding = 0pt    ; may use two (top-bottom and left-right)
                 ; or four (top, right, bottom, left) values

In addition, you can create sections that contain common styles and refer to them directly rather than defining the styles individually in a block. It is not necessary to define all the style values, there are always default values that get inherited.

[DefaultStyle]
font-face = DejaVuSans
font-size = 12pt
font-style = normal
font-weight = normal
text-decoration = none
line-height = 16pt
text-align = left
vertical-align = top
background-color = 255 255 255
color = 0 0 0

Document Section

; mandatory section called Document
;
; Document section can set default style values 
; to be inherited by all pages/blocks either inline
; or by including a style = StyleBlock to point 
; to another section that defines any or all of 
; these styles

[Document]
margin = 0
units = mm
style = DefaultStyle

; document metadata embedded in the PDF, visible
; to the viewer in document info
creator = My Application
author = My Name
subject = My Subject
keywords = a list of keywords

; pages in the Document, a quirk of PHP is that
; when it parses an ini file and a key contains
; square brackets, it converts it to an array
; containing values for each key thus defined
pages[] = Page1
pages[] = Page2

Page Section

; a Page section is a page because it was referred
; to as such by the Document section.  There is no 
; other identifier
[Page1]
; may define any of the style rules here and/or use
; a style = StyleBlock to import styles.  Any styles
; not explicitly set inherit the style values of the
; Document.  The values that can be set explicitly on
; a page are
page-size = Letter ; Letter, Legal, A3, A4, A5 or a
                   ; custom size using the format
                   ; <width><units> <height><units>
orientation = Landscape ; or Portrait
margin = 0.5in ; note we use mm for the document units
               ; but we can set any sized value in any
               ; unit we wish
; the other thing that pages contain is a list of blocks
; to be rendered in that page, again using the [] syntax
; for PHP
blocks[] = MapArea
blocks[] = LegendArea
blocks[] = DetailArea
blocks[] = AttributionArea

Block Sections

A block section has a location specified relative to its containing block, a list of blocks it contains, a type and any type-specific values. Positioning can be broken into vertical and horizontal components. Horizontally, you must specify at least two of left, width and right. If you specify left and right then the width is calculated automatically from the size of the parent, taking into consideration the margin, border, padding of the parent block. Vertically you must specify at least two of top, height and bottom. Same rules apply for height.

Also, a block section can specify an overflow block. When content exceeds the size of a block, the extra content is then sent to the overflow block. Overflow blocks can be chained to other overflow blocks. Content continues to flow until it has been completed rendered or there are no further blocks (at which point the content is truncated).

[MapArea]
top = 0 ; pinned to the top of the block it is contained in
left = 0 ; pinned to the left of the block it is contained in
right = 2in  ; pinned to the right of the block it is contained in, 
             ; width is calculated automatically from the 
bottom = 2in ; pinned to the right of the block it is contained in,
             ; width is calculated automatically from the
type = map   ; means use the MapBlock plugin to render this block
map = %map%  ; the map file or PHP MapScript map object to use
             ; in this case it comes from a variable that is passed
             ; to the PDF Document rendering engine at runtime
resolution = 300 ; render the map at 300 dpi, which increases the
                 ; size in pixels of the map and scales all sizes
                 ; and widths in the map file by the appropriate
                 ; amount.  This would not be necessary if we could
                 ; get appropriate PDF vector output from MapServer
grid = true ; render a grid surrounding the map and on the map
gridticksize = 1mm 
gridstyle = [GridStyleBlock] ; a style block that controls the style
                             ; of the fonts etc when rendering the
                             ; grid surround

Block Types

There are several block types that have been created for the DMSG layout engine

text. A generic block of text
image. An image
northarrow. Renders a true north arrow for a particular map block.
map. The map block draws a mapserver map as a raster, automatically scaling the map to higher resolution as required and embedding it as an image in the PDF. The map block includes the ability to specify a grid surrounding the map based on a GRID layer in the map. We extract the pixel coordinates of the intersection of the grid lines on the map with the edge of the map, do some funky math to figure out PDF coordinates based on the position of the map in the PDF and then add a neatline, grid tick marks and values outside the map itself using PDF objects
legend. Renders a legend for a particular map block. We generate the legend in PDF objects rather than relying on MapServer's legend
scalebar. Renders a scalebar using PDF objects