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
 * these styles

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

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

pages[] = Page1 pages[] = Page2
 * 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

Page Section
; a Page section is a page because it was referred [Page1] page-size = Letter ; Letter, Legal, A3, A4, A5 or a                  ; custom size using the format ; &lt;width&gt;&lt;units&gt; &lt;height&gt;&lt;units&gt; 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 blocks[] = MapArea blocks[] = LegendArea blocks[] = DetailArea blocks[] = AttributionArea
 * to as such by the Document section. There is no
 * other identifier
 * 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
 * the other thing that pages contain is a list of blocks
 * to be rendered in that page, again using the [] syntax
 * for PHP

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