Dreamfish
Vassal
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:
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.
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.
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.
Any target documents included by the main "doc.xml" document, must start with the following declaration:
or for appendixes
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
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.
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
\templates2. 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]">
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