ogre
Almost exactly three years ago, I posted an analysis of the traffic on ogre3d.org and the rough country breakdown of our users, which is always fascinating to me. I hadn’t actually been collecting web stats on the site for about a year (the previous set-up was lost when I had to recreate the server in a hurry, and somehow reinstating it never seemed to rise to the top of my TODO list), but a month ago I finally got around to adding Google Analytics to the site.
Writing good documentation is hard. While I happen to think that API references generated from source code can be extremely useful, they’re only part of the story, and eventually everyone needs to write something more substantial for their software. You can get away with writing HTML directly, and separately using a word processor to write PDFs for so long, but eventually you need a proper tool chain with the following characteristics:
- Lets the author concentrate on content rather than style
- Generates multiple formats from one source (HTML, PDF, man pages, HTML Help etc)
- Does all the tedious work for you such as TOCs, cross-references, source code highlighting, footnotes
- Is friendly to source control systems & diffs in general
- Standard enough that you could submit the content to a publisher if you wanted to
- Preferably cross-platform, standards-based and not oriented to any particular language or technology
When I came to write the OGRE manual many, many years ago, I went with Texinfo - it seemed a good idea at the time, and ticked most of the boxes above. The syntax is often a bit esoteric, and the tools used to generate output frequently a bit flaky (texi2html has caused me many headaches over the years thanks to poorly documented breaking changes), but it worked most of the time.
I’ve been meaning to replace this tool chain with something else for new projects for a while, and DocBook sprung to mind since it’s the ’new standard’ for technical documentation. It’s quite popular with open source projects now and it’s the preferred format for many publishers such as O’Reilly. In the short term, I want to write some developer instructions for OGRE for our future Mercurial setup, but in the long term, I’d really like a good documentation tool chain for all sorts of other purposes, and Texinfo feels increasingly unsatisfactory these days.
Having spent some time this week establishing a new working tool chain, and encountering & resolving a number of issues along the way, I thought I’d share my setup with you.
I love it when shots from Ogre just show up in funny places. This time, it’s from a comic strip called Stolen Pixels on the Escapist, where Ogre-powered games Torchlight and Zombie Driver have been used for comedic purposes: Thanks to BuschnicK for the heads-up on the Torchlight one, I was surprised to see Zombie Driver just days earlier too!
So, I’ve been a little quieter than usual since the new year, and that’s because I’ve been in a rather reflective mood as I plan out how I’m going to spend my time in 2010. That’s right - planning! Talk about the final frontier 😉 Basically, as you may have gleaned from my previous post, I’ve been looking to make some significant changes to the way I do things in 2010.
Zero Punctuation reviewed Torchlight yesterday! Of course he was both inaccurate (you don’t have to keep clicking at all, you can hold the button down) and overly harsh, but still very funny. It’s odd to enjoy watching something you had a hand in (albeit in a background technology way in my case) being ripped to shreds, but when it’s done in such an amusing way somehow it’s ok. I guess this is why Yahtzee hasn’t had his teeth kicked in by disgruntled game developers yet 😀
It’s now almost a year since I decided to try using Twitter, specifically to post about Ogre development work I’m doing and other Ogre-related things (well, most of the time anyway). Seeing as I totally deride the concept that it’s a good thing to share the inconsequential, tedious minutae of your life with the internet and view it as the absolute pinnacle of sad, narcissistic behaviour, joining Twitter was a hard sell.
I’ve already posted about my experiences with Git and Mercurial, the end result of which was a vastly increased respect for Git but a basically confirmed preference for Mercurial, based on ease of use, platform consistency and resilience. Mercurial’s conversion tools are really quite good - the core tools worked fine but I was impressed by hgsubversion’s speed and that it seemed to just work, in both initial conversion and pulling subsequent updates.
So, I’ve just about completed my practical experiments & review of Mercurial and Git.
In the end, I had far too many separate notes and sets of experiences to post, so I boiled the argument down into the 10 most important factors to me, and scored Mercurial and Git on a scale of 1-5 based on what I’d found when using them. Here are the (annoying) results:
<td>
<strong>Criterion</strong>
</td>
<td>
<strong>Git</strong>
</td>
<td>
<strong>Hg</strong>
</td>
<td>
Ease of use - command line
</td>
<td style="text-align: center;">
4
</td>
<td style="text-align: center;">
5
</td>
<td>
Ease of use - GUI
</td>
<td style="text-align: center;">
4
</td>
<td style="text-align: center;">
4
</td>
<td>
Platform support - core
</td>
<td style="text-align: center;">
3
</td>
<td style="text-align: center;">
5
</td>
<td>
Platform support - GUI
</td>
<td style="text-align: center;">
4
</td>
<td style="text-align: center;">
4
</td>
<td>
Web Host Functionality
</td>
<td style="text-align: center;">
5
</td>
<td style="text-align: center;">
4
</td>
<td>
Reliability & error handling
</td>
<td style="text-align: center;">
3
</td>
<td style="text-align: center;">
5
</td>
<td>
Storage efficiency
</td>
<td style="text-align: center;">
5
</td>
<td style="text-align: center;">
3
</td>
<td>
Run-time performance
</td>
<td style="text-align: center;">
5
</td>
<td style="text-align: center;">
5
</td>
<td>
Flexibility
</td>
<td style="text-align: center;">
5
</td>
<td style="text-align: center;">
4
</td>
<td>
OGRE Community support
</td>
<td style="text-align: center;">
5
</td>
<td style="text-align: center;">
4
</td>
<td>
<strong>Totals</strong>
</td>
<td style="text-align: center;">
<strong>43</strong>
</td>
<td style="text-align: center;">
<strong>43</strong>
</td>
I’ll explain the scores, and my conclusion, after the jump.
**
Penny Arcade tends to divide a room much like Marmite, but I like both. I was pleased this morning, therefore, to see Torchlight, a game deep within which little gears of my own construction are happily spinning away, featured as the news and comic of the day, and in a very positive fashion. [Penny Arcade tends to divide a room much like Marmite, but I like both. I was pleased this morning, therefore, to see Torchlight, a game deep within which little gears of my own construction are happily spinning away, featured as the news and comic of the day, and in a very positive fashion.
Woohoo, Torchlight, the new ARPG by Runic Games and using OGRE for rendering, is launching today! Well, strictly speaking the single player game launches today, with an MMO version planned for 2010. Torchlight has been developed in Seattle by a veteran team composed of the designers and leads of projects like Diablo, Diablo II, Mythos, and Fate, so you knew this was going to be good.