B(LOOD) Formatting Engine

Dreamfish

Administrator
Introduction

Blogs are great, but have their limitations, especially when it comes to posting battle reports.

Let's look at the battle reports "It's fun to slay at the Wyemm Seeyay" and "The Shadow of Koles Lorr" on the Warhammer for Adults blog.

The first thing you'll notice is that the reports span multiple posts, sometimes even with unrelated posts in between. The posts are added during the time we were playing the game in a journal kind of fashion, meaning last post comes first. Older posts tend to get burried by newer posts, making them harder to find. Dispite the "navigation" menu Gaj added at the bottom, I think it's difficult to find and to figure out where to start reading the report, especially if you're not familiar with blogs in general.

There is other information related to the battle reports on the blog, but not directly linked to it. For example, we did the above mentioned battle reports remotely. The blog contains posts about remote gaming and the guidelines involved. The reader has to know this and it's the readers job to put these pieces together. In other words, the battle reports posted on blogs are to my mind no real battle reports, but just blog posts containing pieces of a battle report.

I think battle reports like the above are a great way for introducing new people to the Oldhammer way of gaming. I think a battle report should not only contain the report, but should contain all related information, like references, dicelog, house rules, game guidelines etc. The report must not be restricted to a certain type of presentation, for example: HTML, PDF, TXT etc and should be printable.

Thinking about this I set out to create a PDF version of the above mentioned battle reports, but ended up in creating a formatting engine for battle reports. I'll try and explain how it works, the benefits and how to use it.


The Problem

1. Separation of presentation and content
Apart from the scattered information discussed above, the main problem is that the content is mixed with presentation. In the case of a blog, the content is mixed with HTML. This means, if you want to publish the same data in a different format, you'll have to extract the data from the HTML and reformat it to whatever format you want it to be.

2. Consistency
Formatting the data can be time consuming, figuring out which font to use, margins, spacings and what not. Being consistant is also a problem. Sometimes other font sizes are used, different paragraph spacings, or just forgetting previous methods. If you ever looked at the HTML blogger generates you'll know what I mean, the designer just loves to span eveything.

3. Centralisation of data
Manually updating different presentations of the same data is time consuming and subject to human mistakes.


A Solution

1. Separation of presentation and content
The general aim of separation of presentation and content is machine readability, that is, making it possible for machines to detect meaning or intent. The blog posts are the end result of the data. If you look at the content of the battle report posts, you'll notice it contains different types of data:

  • 1. Narrative texts
    2. Blog related texts
    3. Game related texts
    4. Images
    5. Comments
    6. Presentation

Only point 1, 3, and 4 belong in a battle report, point 2 and 5 belong to the blog sphere and point 6 should be separated from the data. The first step is to extract the battle report data in a machine readable format.

2. Consistency
With the use of templates, different kind of presentations can be applied on the machine readable format. Templates are divined once and always generate the same output. Different templates can be created for different purposes.

3. Centralisation of data
Having the data in a machine readable format subsequently centralises the data. Change the source, re'apply the templates and all different presentations are changed.


The B(LOOD) Report Format

I've chosen XML as the format for the machine readable "source" files. This is by far the most flexible way of divining a machine readable format. While working on the battle reports I've come up with the following schema for divining a battle report in a machine readable format.

LUvuZeY5


As you can see, the schema is actually quite generic and can be used for other documents as well, but for now we'll only concentrate on making battle reports.


The BLOOD Formatting Engine Toolkit v1.6

The principle is simple, feed the engine data, select a template and it generates the required output. Sounds great right, so how does it work?

Note: the toolkit requires the Java Runtime Environment and the .NET Framework 4.0 to function properly. More sure you've got them installed before continuing.

1. Download the latest version of the toolkit here at https://db.tt/aLQ8TzQj and extract it somewhere on your pc (sorry no Macintosh users).

Once you've extracted all the content of the toolkit archive you end up with the following directory structure.
Code:
[toolkit-v1.6]
  \bin
    \BloodFE
    \fop-1.0
  \java
    \jre6
  \reports
    \Template
      \resources
        \data
        \images
  \resources
    \config
    \fonts
    \scripts
    \styles
    \templates

2. Download the latest templates here at https://db.tt/pdIFjvWv and extract all the contents of the archive to the "[toolkit]/resources/templates/" directory.

3. Create a working folder

The toolkit contains a "[toolkit]/reports/Template/" directory by default. The "Template" directory contains the necessary files for starting a new report. Copy & Paste the "Template" directory and rename it for each new report you're going to make. The copied and renamed directory becomes the working folder of the report.

An example report can be found here at https://db.tt/kbGMBORP. It contains a complete working example of the "It's fun to slay at the Wyemm Seeyay" battle report. Just extract the contents to the "[toolkit]/reports/" directory.

4. Generate a BReport

In order to generate a BReport, you need to create an xml data file. This all sounds very technical, but is in fact pretty easy if you use an xml editor like XmlPad. This editor is free to use and is more or less an advanced notepad editor. You don't need an xml editor, but it's easier and it helps you write a valid xml document.

To start writing your report, just open the "[toolkit]/reports/[template]/resources/data/doc.xml" file with an xml editor.

XmlPad knows how to validate the document, beause the "doc.xml" file holds a reference to the "doc-schema.xsd" schema file, which in this case resides in the same directory as the "doc.xml" file.

The main "doc.xml" file must have the following root "document" element declaration.

Code:
<?xml version="1.0"?>
<document
  xmlns="http://www.old-hammer.com/2012/BReport"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xi="http://www.w3.org/2001/XInclude"
  xsi:schemaLocation="http://www.old-hammer.com/2012/BReport doc-schema.xsd"
  title="[Enter report title]">

Any target documents included by the main "doc.xml" document, must start with the following declaration:

Code:
<chapter xmlns="http://www.old-hammer.com/2012/BReport" title="[Enter chapter title]">
or for appendixes
Code:
<appendix xmlns="http://www.old-hammer.com/2012/BReport" title="[Enter appendix title]]">

Currently, the schema only allows "chapter" and "appendix" elements to be linked with XInclude. This means you can place one or more "include" elements within the "chapters" and "back-matter" elements.

NOTE: The "old-hammer.com" domain does not exist, it's only used to specify a namespace for BReport documents.

A complete example of the "It's fun to slay at the Wyemm Seeyay" battle report can be found here at https://db.tt/kbGMBORP. The data files of this report reside under the directory "[toolkit]\reports\2011WFB3Wyemm\resources\data\". You'll notice that there are multiple files, these are all linked together by the "doc.xml" file. I suggest you take a look at these data files. I believe they're self explanatory.

To generate a HTML representation of the report, simple execute the "make_html.bat" batch file under the directory "[toolkit]\reports\2011WFB3Wyemm\". This generates an "doc.html" under the same directory containing the html representation of the battle report. To generate a pdf representation of the battle report, simply execute the "make_pdf.bat" batch file.


The Formatting Engine

The engine uses XSL-T templates to translate the xml. The templates reside under the directory "[toolkit]\resources\templates\". The idea is to create a template for each required output. Don't worry about the technicality of it all, I'm just explaining it for the ones who want to know.

In theory Authors only need to know how to write a valid BReport document. With the data in place either me or the author can generate the output with one click of a button.

Unlike the HTML templates, the pdf templates are finished. You can view the PDF representation of the "It's fun to slay at the Wyemm Seeyay" battle report here at https://db.tt/A9Hhi4eW.


Conclusion

There is still some work to do, but when the effort is taken to tune the templates and schema according to our needs, everyone can start writing battle reports according to a certain (BLOOD) standard and style in various available formats. It's even possible to create an online formatting engine, in which the author uploads the data files and selects a desired output. This way the author doesn't have to download the toolkit and/or maintain the various different versions.

To make a long story even longer, the same principle could be used for generation army lists. Define a specific schema, create templates and output the required lists. This is actually exactly what Army Builder does behind the scenes. Only instead of an xml editor, the Army Builder editor is used to create xml data files. This is of course a much more user friendly way of editing. When generating the output, army builder applies the same principle as explained above. The templates supplied by army builder can even be manually adjusted or extended.

I will gladly help with questions and/or problems you might encounter. Just reply to this topic.

Cheers,
Dreamfish
 

Dreamfish

Administrator
When using Xmlpad3, you can validate it by pressing F7 or choosing "XML -> Validate" from the menu. Any errors will appear at the bottom of the screen.

The xi:include elements allows you to include another XML document. You're not required to do so, but by separating each chapter into separate documents, will keep the documents small and you'll maintain overview. Of course, you can also put everything into one document.

The "href" attribute of the xi:include element, specifies the location of the xml document that needs to be included into the source document. These documents will usally reside in the same directory as the source document. For example, the following xml line will include the "chapter-turn1.xml" document into the source document.

Code:
<xi:include href="chapter-turn1.xml" />

NOTE: you need to specify the full filename of the document, including the extension. Within windows visibility of extensions are turned off by default, so even if you're only seeing the name "chapter-turn1" within windows explorer, the file is actually called "chapter-turn1.xml".

If the target document is located in a different directory than the source document, you'll have to specify the directory path as well, like this.

Parent directory
Code:
<xi:include href="../chapter-turn1.xml" />

Sibling directory
Code:
<xi:include href="../chapters/chapter-turn1.xml" />

Absolute directory
Code:
<xi:include href="file:///c:\temp\chapters\chapter-turn1.xml" />

Web address
Code:
<xi:include href="http://localhost/chapters/chapter-turn1.xml" />

The target documents will not hold the entire (valid) document structure, but sub parts of it. In the above example, the target document "chapter-turn1.xml" will start with the root node "chapter".

Just look at the "Wyemm Seeyay" documents and you'll understand what I'm talking about.

Figure element:

The templates supplied in the toolkit search in the "[toolkit]/reports/[workingfolder]/resources/Images/" directory. You must specify a full filename (incl. extension) in the "href" attribute of the "figure" element. For example, an image named "image.jpg" which resides in the "[toolkit]/reports/[workingfolder]/resources/Images/" directory, can be located as follows:

Code:
<figure href="image.jpg" />

By default the orientation of an image is handled automatically. The above figure declaration uses a default scale of 100% for landscape images and a scale of 70% for portrait images.

Overwrite the default value by specifying the "scale" attribute explicitly.

Code:
<figure href="image.jpg" scale="90%" />
or
Code:
<figure href="image.jpg" scale="130%" />

You can use most of the commenly accepted web standards regarding images, if you stick to JPG, PNG, GIF you'll be fine.

Link element:

It's possible to link to a chapter or section within a document. To do this you most identify the chapter or section you want to link to by adding an "id" attribute to it, like this:

Code:
<chapter title="My chapter" id="chapter1">

Further within the document you can refer to this chapter as follows:

Code:
<paragraph>Look, I just finished <link href="#chapter1">My chapter</link>.</paragraph>

Note the hash symbol followed by the id of the chapter.


Textblock element:

Use the "type" attribute of the "textblock" element to change the context from normal text to narrative text, instead using "emphasis" elements in each paragraph. For example:

Code:
<textblock type="story">
  <!-- all paragraph, figure or list elements will be styled in "story" mode -->
</textblock>
<textblock>
  <!-- all paragraph, figure or list elements will be styled in "normal" mode -->
</textblock>
<textblock type="quote">
  <!-- all paragraph, figure or list elements will be styled in "quote" mode -->
</textblock>
Currently the "type" attribute supports the following values: "quote" and "story".


Online image hosting

When using the BloodFE for posting content on a Blogger blog, images must be hosted online. Furthermore, the report should be seperated in parts and the HTML generated must be compatible with Blogger.

The "make_blogger.bat" batch file, automatically uploads all images to a Picasa Web Album. It does this by creating a Web Album under the report name and uploads the images to it. All parts of the report (doc-info, chapter, appendix, etc.) creates a separate HTML file. The source of the HTML files can be copied directly into Blogger.

The BloodFE needs credentials in order to upload images to Picasa. Open the file "[toolkit]/bin/BloodFE-1.0/BloodFE.exe.config" in Notepad and enter your Google account in the following fields:

Code:
<appSettings>
  <add key="google:userid" value=""/>
  <add key="google:password" value=""/>
</appSettings>
Save the file and execute "make_blogger.bat" from your report working directory. This should do the trick. Log messages are logged in the "[toolkit]/bin/BloodFE-1.0/log/" directory. Consult it if something is not working properly.

Cover page

A note on the cover page. The pdf template looks for an image called "cover.png" in the images directory of the report. The image needs to have the following size: 8.26" by 11". You can find an example of this in the "Wyeem Seeyay" report.
 

Dreamfish

Administrator
I've removed all the threads in this topic and collected all the information discussed. I've also moved all data files to the Oldhammer storage and updated all the links.
 
Back
Top