Coverting Abriel Local map
You all should know the fine material Harn fans have created. One such location is Abriel found at the Site of many more: www.lythia.com. The following is an informal log of what I did to convert things for use with the UGMT.
I first started with the loacl map. It consists of a "Common" and a "GM" map. Since these are handled as layers (which can be blended in the UGMT), I needed to create a layer that contains only the numbers. If you have originals the first step is significantly easier, but here I had to use some image manipulation technics (with The Gimp) I chose the Common map as ground layer and the GM map as a layer on top. Toying around a bit I found that a particular form of overlaying blended everything out except the numbers and letters. Additionally a few stripes were present (due to JPEG compression of the originals) that had to be removed and transparency was needed. How to do this is not the topic here, and would certainly let this little description explode. Suffice it to say, that after 40 minutes I had:
I now moved these images to "maps/Community/Local" in my UGMT directory. Depending on where you install the UGMT, this may read for instance "C:\UGMT\maps\Community\Local". Then I copied the "Thoen.xml" one directory up to "Abriel.xml" in the same directory and changed it to read
<atlas name="Community" vicinity="20"> <dir name="Local"> <map name="Abriel" img="Local/Abriel.png" layer1="Local/Abriel_1.png" scale="9900" tacticalspeed="1" thumbnail="Local/Abriel_mini.png" grid="1,1"/> </dir> </atlas>
The scale and grid attributes above need a little explanation. I copied scale from Thoen, but is that correct here? Scale is measured in pixels per league and opening the map shows, that this is not quite correct. I downscaled the map by 3/4 to get scale="9900", but I'd rather have all maps the same scale. Just a bit of extra work. The grid piece is something odd and should change in the future. Currently it is sufficient to choose a "x,y", which isn't in use by anybody else. Another 10 minutes were spent. Start the UGMT and check that everything is working fine. This section took about an hour.
Creating Abriel Local Index
Taking Thoen as an example I descend into the "index" directory and create an "abriel" directory and "abriel.xml". I open the latter. I also copy all the local entries from the abriel PDF that I downloaded into a working buffer of my favorite editor (emacs, YMMV). Since I copied everything in one swoop formatting has gone down the drain in a simple text editor. Some carriage-returns (about 30) get this into working order. I collect the headings and copy them into the "abriel.xml" file. The file looks something like this now:
<?xml version="1.0" encoding="UTF-8"?> <index version="0.1"> <entry name="1. Lanas of Cyrnalian" value="Community/abriel/?.html"/> ... </index>
I decide to use the numbers and letters from the PDF for the question marks. Note that your editor may support the tedious work of adding "<entry", etc. for each entry. Some people are speedy with the Ctrl-V. I used emacs-macros. This went rather fast and after 10-15 minutes I am done. Note that I have also moved the number to the end in brackets, e.g. "1. Lanas of Cyrnalian" turned into "Lanas of Cyrnalian ". This makes for a more reasonable ordering later.
Now we go back to the buffer with the half-formatted entries. We need to get them in order. Each entry will go into a file with the corresponding number. I first opened the file, e.g. "1.html", copied the stuff in. Then took the heading and footing from an existing file. (Take a thoen file for the first one.) Any paragraoh should begin with a <p>, bold-face is enclosed by <b> and </b> italics with <i> and </i>. I spent approximately 1/2 minute on each, totalling about 20 minutes.
We now turn to the part that is actually work and not mere copy and paste. I added links into the html files by scanning for noetworthy references. You need to be somewhat firm in HTML, but this actually adds cross-references that weren't there in the original PDF. I'm creative here:-) I also took a image grabber and saved all the small images as "img1.png" and so on in the same directory as the HTML files. I then added small sections like the following in the right files (see "Abriel.html")
All the links and images took me about another 15 minutes. Now I wanted to make a base entry for the front page. I called this "Abriel.html" and formatted it a bit more carefully. The same goes for another page which contains more information. By now things go a bit more smoothly and so I take 5-10 minutes for two extended pages. This section took less than 50 minutes.
Linking the map and the index
You may have a tool to help you create the HTML-pages, if you don't like to bother with HTML directly. I don't, I like to get my hands dirty. Anyway, now you need a tool to help you create a so called clickable image map. Most HTML generators should have one, Image Manipulation software such as the Gimp have one too. You will open the "Abriel.png" image and draw some circles and squares, each referring to a specific place. Saving the "Clickable image map" will result in a HTML file full of rows like
<area shape="circle" coords="679,691,33" href="1"/>
Of course, each of the href-parts should point to the right destination. Unfortunately, you do not place this into the map directory but with the index. I need to find the entry for each of the rows above and modify them as follows. The trailing "/>" must be replaced by ">" and a line just following this one with"</entry>" must be added. Between the two lines add the correct row. Now replace href with the map to be referred, here "Community/Local/Abriel". Take a look at "thoen.xml", how it should look. Creating the image map took me about 10 minutes and adding the sections 5 minutes. Save everything and start the UGMT and test it. Actually finding an error once in a while and fixing it should add up to 5 minutes by now.
Take a deep breath
I'm done with the local map! Let's see: the conversion took a good two hours. It's time for a rest and to collect some notes:
The Abriel local map is larger than the basic 64M of the JVM (Java Virtual machine) can handle. You can avoid OutOfMemoryErrors by starting "java -Xmx128m -jar UGMT.jar".
Non-ASCII characters such a the accented a are sometimes painful to edit into the XML-file. Every editor has it's own way of entering and saving them. I've had some fun with them until they were properly displayed by the UGMT :-( If you like, add 15 more minutes for this particular problem.
While tracking errors it is always a good idea to start the UGMT from a shell/cmd-box. Otherwise error messages will get stranded, which are important to find wrong syntax in XML-files.
Since I know my way around the UGMT, I probably have a head start. Things may not run as smoothly as you stumble into errors I have not foreseen. Contact me with questions.
Something that is particularly annoying for creators with the UGMT are it's terse error messages. You will get big exceptions stacks which provide almost no information except in the first line and that is sometimes useless to. The most common errors are
Things aren't done yet with Abriel. There are lot's of interior maps and then some. It takes some time to get the interior maps working, even more time than for the local map, since it is not as easy to recover the number-layer. Again that requires some retouching I will not cover here. Don't try to do all of this in one session:-) I found that the added difficulty of the interior maps was offset by the gained practice. Moreover, the interior maps have less entries. But I made 6 interior maps, which still meant 6 hours of work. But this includes map, index, HTML-links, and map-links.
You can skip many of the stages, such as layers and internal linking of the index-pages. You might even create greater blocks of texts in one file. It all depends on what you want to achieve.
Last but not least, I created a COPYRIGHT.Abriel file that contains the line
Abriel / N. Robin Crossby, Columbia Games, J. Patrick McDonald, Richard Luschek, and Patrick Nilsson
This file is copied into the "index" and "maps" directories. Both of these directories now contain material copyrighted by the above mentioned people. Strictly speaking, if you never plan to release your work, you don't have to do this, but that is considered "bad practise":-) Anyway, I did. The next step was to ask the main author, J. Patrick McDonald, for permission to publish the derived material. After you obtain that permission let other gamers appreciate the work you have done. I will gladly host the zip file.
Packaging is done through standard zip procedures. I used a command line
zip -r Abriel.zip index/*briel* maps/*briel* maps/Community/*briel* maps/Community/*/*briel* index/Community/*briel*
Technically this all takes less than five minutes. You may also check that the Zip-file expands correctly, I have established a separate user on my system specifically for that purpose. By far the longest part is waiting for permission to publish. (Which definitely does NOT mean that the involved people are lazy.)
|∗Editing Data∗||∗Adding Data∗||∗Sample Conversion∗|