If you head out to any flavor of mari.somnol now, you'll see a story! Potentially more, by the time you're reading this! If you caught the previous post I did on my DocBook story build system, you know that it's been kind of a gigantic process already. It took another gigantic process to get it over the finish line, but I'm happy to say that I've hit all the targets I wanted to: one script to build six different versions of each story from a single double-click. I then put the output into my nofi/lofi/hifi AutoSite projects, build the project, and upload. That's all I need to do to keep a single story in sync across all three sites.
Since I've legit worked on nothing but this for days, I'm a little tired of thinking about it, but I figure I should probably get it into the journal for posterity. Besides, I am hugely proud of it, and I know I'll be rereading this in pride in a couple days anyway.
Step three: splitting the stories up with xinclude
Where I left it last, I wasn't sure if I'd be able to meet my requirement of being able to build both individual story pages and the whole story on one page. Turns out, I can! One of the glorious parts about XML is that you don't need an <html></html> sorta wrapper around your markup, you just have the markup, and if you declare your namespaces right, the processor will still understand what you wrote. In my case, I have the individual pages as separate files with
xinclude literally puts the content of the included XML file into the master file, as if you copied and pasted it in there. xsltproc and DocBook both can work with xinclude, again, with the proper namespaces. This means I can run xsltproc on any individual chapter or the master file, getting what I want out of each. Kino.
Step four: building into my AutoSite projects
Before this, for testing and learning purposes, I had my XSLT stylesheets set up to build full webpages with a doctype and everything. If you know AutoSite, you know that it's actually a templating system, where it takes stripped-down input pages with only the page's content and some metadata, and then smushes them into a rich layout template (the rest of your site markup). That way, you only have to edit the template to fix any errors or add to, say, a navbar.
As AutoSite's #1 fan now and forever, I wanted to be able to make use of my existing templates and use XSLT to output Autosite input pages I could drop into my existing projects for nofi, lofi, and hifi. This was pretty simple stuff, since input pages are still just HTML pages (or Markdown, but that's not relevant to us right now), but there were still snags.
For one thing, dcb wrote AutoSite to rely on specific whitespace around the attributes at the start of each input page, which xsltproc wasn't outputting using its <xsl:comment> processing. So this worked:
<!-- attrib title: Kevin and Theo's Multiverse Misadventure -->
But this (what xsltproc produces) did not:
<!--attrib title: Kevin and Theo's Multiverse Misadventure-->
As a result, these attributes were getting AutoSite confused, and it was passing them through as page content, breaking a lot of things in my templates as a result.
I could've worked around this with literal HTML outputting using the <xsl:text> element, but the good part of using your friend's tools is that they'll usually happily bugfix stuff for you. dcb rewrote his regex for parsing those, fixing another long-standing bug in the process (!), and I had an updated AutoSite that could handle these valid-but-odd attributes within a few days. Good lad.
The other issue was that xsltproc was spewing out an HTML doctype and some namespace attribute spam on all the pages it put out with no way to disable that. Even if I could write a new version of xsltproc to fix this, since it is open-source, that's just a lot of fucking work for no real purpose except this one niche edge case. I had a much better way to fix it, which I'd handle next step.
Step five: wrangling all this shit into a shell script
This was the most aggravating part of the process, because it required me to play with Linux. At least, something that works like Linux.
Remember, I've been basing this whole setup on Cygwin, which is a set of tools and a terminal of sorts meant to give you Linux functionality on Windows. xsltproc, coming from the GNOME camp, is naturally a Linux tool. If I wanted to automate it, I'd be writing a shell script. No big deal, nothing I haven't done before, but something always fucks up tremendously when I have to dive into the gooey guts of anything Linux-related, and this time, it was find that put me through the wringer.
find is a program that can search for files with certain criteria and then do something with them, like pass those files onto an executable or run a shell command on them. This is naturally what you want if you're trying to automate running xsltproc on a whole directory of XML files. The big frustration was that I obviously needed to make output directories for each file, named the file name but without the extension (01, 02, full, etc), and find doesn't provide functionality to pass the base name of the file to the executable you're running from it. That's because Linux doesn't care or use file extensions. At its silliest, find would try to run xsltproc on the output directories as well (also named stuff like "full.xml", despite being directories) and obviously that wouldn't work.
If that's gibberish, that's okay. I've blocked most of this out of my long-term memory for my health. My ultimate solution was to have find and xsltproc make the output directories whatever they'd be called and then use mv later on to simply scrape the .xml off each of the directory names. Hey, if we're already scripting it, might as well take the caveman approach.
This is also where I'd take care of the doctype and namespace cruft, again running find, this time on all the output HTML files it can find in the output directory, and then using sed to delete the first line of the file (the doctype) and any namespace cruft it finds anywhere in the document.
Anyway, it works. I now had xsltproc building AutoSite input pages for me. All that's left is to translate it to the other two sites.
Step six: writing lofi and hifi XSLT stylesheets
This was as much working on the AutoSite templates and CSS stylesheets for each project as it was doing stuff with XSLT. Now that I had the build process working, I just needed it to take those same files and make lofi and hifi compatible versions as well. This is also where I dragged forward my preferred story fonts (New York and Los Angeles, because the classic Mac OS fixation never dies) and also the color-coded character dialogue styling from my old sites to the new ones.
All is said and done, this had to happen. There was no way I was gonna be able to put stories on all three sites and then manage potentially six different versions of each story, even just to fix a single typo in each. Bigger changes or rewrites, not happening. This is a huge step towards being able to publish what I'm writing to my sites again like I always wanted, and I'm very proud of how it came out. Even better is the ease of updates: if I write a new chapter and want to publish it, I just add it to the DocBook, rerun the script, rebuild the AutoSite projects, and reupload. New chapter added, can link it to everyone, we're all good to go. If I want to build DocBook to some other XML-based language in the future (eBooks, maybe?), I can add that pretty quickly to the build system.
If you're curious to see the beast in all its messy glory, I made a GitHub repo for all the XSLT sheets and such. I'm sure there's lots to be cleaned up in them, but I really don't care. No one's gonna see it but me and the morbidly curious.
Anyway, all this techie junk distracts from the important stuff! Seriously, I've realized this is so techie-wonky that, when I try to explain it to friends who are less technically inclined and then show them the end result, all they see is the story—which is how it should be anyway, huh? And of course, there's the really immortal, million dollar question, "when will there be more stories, Cammy?"
Watch out. You might get what you're after.
Oh, totally random aside—can you believe I've lost weight in the past two weeks? I'm at 144lbs. That's 6lbs lighter than my stretch goal from this time last year, and nearly 30lbs lighter than I was last time I saw Caby. It feels good! Not really interested in snacking or drinking, just banging out projects and playing Guitar Hero. Lots to do, lots of time to do it. Happy Summer vacation.
