Inside Baseball

I'm a simple man with simple desires, but boy are they hard to satisfy.

(This post has very little to do with the debate topic, but instead is about the tools of the presentation.)

See, as it stands, I have something like 200 pages on this site plus around 400 blog posts.   That's a good bit of content, even if most of it is ancient at the moment.

I've obviously dabbled in websites and web design for awhile.  ST-v-SW.Net started as rough HTML pages hand-written and hand-coded in the Pico editor via a telnet session into the server, or on Windows Notepad (preferably the former since uploading was a bit of a chore).  Later, I used Frontpage, a WYSIWYG editor (meaning I didn't have to just save and see what the page looked like from the browser).  In recent years I've tried to use Kompozer but it does weird things that slow down my machine, meaning that it isn't really usable in the WYSIWYG way . . . that's depressing, since it's probably the best option out there short of something obnoxious like Dreamweaver (which, when I tried it several years ago, was completely ridiculous).   And almost all of them screw with the HTML you typed whether you want them to or not.

For some other work I've messed around with assorted "content management systems", or CMS's like Joomla, Drupal, CMSimple, and so on.   Generally speaking, these are database-driven (usually MySQL), though some like CMSimple are flat-file and databaseless.   Most have an online editor meaning you go in to your browser and into the administrative area of your site and get WYSIWYG (or nearly so) action.  They are generally considered dynamic (forums being a prime example of a dynamic site), though few really do that part well.  Either way, there are limitations on what you can do with them.

By analogy, the old way was like DOS . . . you could do whatever you wanted, within certain limitations.  It wasn't at all like these iPhone-esque CMS things where you only get one button on your one-trick-pony app.  They are, to quote an ex's apt t-shirt, "cute but dumb".

I much prefer the idea of a static website, because there are a ton of advantages.   There's nothing to screw up, you can set things up however you want, and it's way more secure than some freaky .php-and-SQL-driven gobbledygook.   If I need to back up, or pick up and move web hosts, I can do so almost effortlessly.  And if someone needs to come in behind me for any reason, it's a ton easier on them.   The issues were basically made most plain by this fellow who passed away in 2011.

Oh, and one more thing . . . I always hated the fact that Bob Brown's long-defunct (but now not) website, though generally available in the Wayback Machine, had all sorts of special gobbledygook on it that prevented it from working properly in Wayback form.  The old Obsidian Order pages, which were true dynamic pages by design, were also completely unusable for such a purpose.

In short, then, I really would prefer to avoid having any junk running in the background serving files, because that immediately means the site is not static.

However, there are some things that CMS software allows that I also like, such as automatic generation of certain pieces like RSS or even menus in some cases, or dynamic inclusion of other bits of other pages, et cetera.   The new NoLettersHome.Info requires dynamic content as part of the design.  Indeed, that Twitter and Facebook feed you see on the main page is dynamic content, albeit not from a CMS . . . but I figure that's extraneous and not necessary for the main site anyway, so it's good.

I have looked around from time to time for the next stage of ST-v-SW.Net.  Around 2007 I fiddled around with a Xoops site, then later a Joomla version.   A few years ago I had a Drupal version up and running, but the image handling at the time was so poor that the idea of actually converting the existing 200 pages over to it was a nightmare, and it never went any further.   The new logo was kinda neat, though . . . maybe at some point I can even find it and show it to you.

Amusingly, I would keep checking out Drupal from time to time but they have this silly thing where they're always advertising the as-yet-unreleased next-integer version.  So, when at one point I was looking at Drupal 6 seriously, they were advertising 7 as the next great thing, and-oh-by-the-way-upgrading-is-hard.   Even now with 7 out they're advertising 8 as the next great thing, and oh by the way we're only making an upgrade path from 6.   What the hell?  I appreciate the active development if I'm pondering locking myself into a CMS, but c'mon . . . give a little space.   Let a version be a positive thing and not always feel like a stopgap till the next one, and that I'm settling.  Geez.

And while Drupal is the software powering a lot of major sites, the fact is that they have IT staff.   I need to be able to walk away from this for months at a time unattended and know it won't explode.

Anyway, I never considered Wordpress for this, though I've built a site in it before . . . it's perfectly usable as a CMS, but given the vitriolic hatred my site engendered I wanted to be sure I had maximum security.  Any CMS is a problem in that regard, but some more than others.

Long story short, ST-v-SW.Net has seen several new versions come and go.   Invariably I would come up against something basic I wanted to do that the software didn't support, meaning I either had to go all psycho  codemonkey on it or else give up.   This is a hobby, so giving up was usually the better option.

But this time, I'm pretty serious about finding a solution that works.

I looked around at assorted things and eventually came across the notion of "static site generators".   This sounded delightful at first, though I quickly realized that, for the most part, these are completely useless.

First, most involve writing in Markdown or some similar "lightweight" markup language.   If HTML is like doing a document in Word or Libre/OpenOffice where you can control every little thing, Markdown is like Windows Write . . . OpenOffice produces real .doc documents, the latter is only really good for .rtf "rich text" crap.

You've probably used a lightweight markup language before.  BBCode is ubiquitous on forums, and all it is is a light markup.

Now, most of my pages are written with rather ancient HTML . . . newer HTML is far more ridiculous and heavy, yes, but old-school basic HTML is not that bad as a markup language.  Just remember the "a href" and "img src" stuff and you're golden.   And while Markdown claims to use normal e-mail and text file conventions, this is not actually true.  If I *want* you to read something I might *do this*, which to *my mind* is like bold, but in Markdown it's italics.  Heaven forbid if you want to _underline_ something properly . . . that's italics, too.  And tables?   Those are usually done in HTML anyway.   What?

So basically, you're stuck learning another language into which you must type, learning Markdown's particular idiosyncracies.

Second, most static site generators are meant to run on your computer, producing files which you then upload manually.   The hell?   What year is this, 1998?   Oh, sure, folks have found workarounds such as hosting their own servers or using Dropbox or other techniques, but that's pretty silly.

After continued searching I came across . . . I don't even know what they're called.  Online static site editors?  I actually paid money to the guys at Veolay, but got completely annoyed when it didn't work at all out of the box.   Like, you do everything it says (and I'm a smart cookie) and nothing works . . . that's annoying.  And there's approximately zero support unless you call them out on their Facebook page.  The utility of Veolay would've been that I could've left the site as-is and live-edited the pages.  But, it was a heaping failure.  I half-suspected it was a scam and if I don't see the promised refund soon I may go back to that idea.

I'm not going to pursue that option further because those sorts of not-a-CMS things are just messy.  For one, you have to go in and add div tags to all your content . . . meaning your site already has to be up to recent HTML standards.   In my day, you didn't need div tags.   Another issue is that most don't allow you to make a new page, which is completely weird to me.

After that fiasco I gave up and went back to my proverbial database-abusive spouse and set up a damnably non-static Drupal version of the site, and even brought the blog over to it via the same import mechanisms I'd had to use years ago (so much for advancement).  But, I discovered it didn't come with any of the handy-dandy sub-indexes (e.g. all posts from 2007 or all posts from March 2010).   This means that it is very pretty, but a giant mess and kinda useless.

Still not satisfied, I went looking around elsewhere, with the plan to use Drupal as a fallback position.

I was still intrigued by static site generators, but the fact is it's basically the exact same workflow I used almost 15 years ago except instead of writing HTML you're writing Markdown, which seems and extraneous step.

But I kept researching and found reference to AsciiDoc.   AsciiDoc is a similar concept to Markdown but twenty times better, even if its loudest online proponent Dan Allen strikes me as a total douche in several ways.  The problem is that Markdown, though fractured by numerous different versions, is well-supported . . . AsciiDoc is not.  That is to say, there are a ton of other tools that can do Markdown . . . even Android apps . . . but there's no such thing for AsciiDoc.  (Dan needs to turn down the douche and rally the troops.)

Even AsciiDoc has its annoyances, yes.  For instance, I might "quote" something or 'paraphrase' something, but the latter will become italics.  If I want to paraphrase, I have to use a leading `backtick' way over by the 1 key.  That's a needless screw-up of normal usage.  The backtick should be the coding key.   Granted, I don't use that sort of thing terribly often, but still.

AsciiDoc's main strength is that it can support markup for internal linking, a la a table of contents.  That's awesome.

In any case, that led me to finding the Pandoc program, which is totally amazeballs.   It is software that will readily convert numerous types of input into about a zillion types of output . . . meaning if you feed it text written in something like HTML or even MediaWiki markup, you can output MediaWiki, PDF, ODT, AsciiDoc, Markdown, et cetera.   It'll even dump to BBCode for easy quoting.  Of course, it won't accept AsciiDoc input yet, but I'm hopeful that will change.

So what I really want to be able to do is to convert the site as it stands now over into a standardized lightweight markup (preferably AsciiDoc but I could be coerced elsewhere) and then use that as source code (and write new material in that source).   That would mean I could quite readily convert the entire site into PDF files if I were so inclined, or have MediaWiki markup ready to go.

Of course, I am doing the NoLettersHome project right now which is MediaWiki based, so the best idea might be to aim for all-MediaWiki and use that as my source code until AsciiDoc gets better.   One advantage to this approach is that Pandoc eats MediaWiki right now.   However, I'd have to check further to see if MediaWiki will do things like I want.  The answer, I'm afraid, is probably a no when I consider things like the Volumetrics table.   Even doing it in .ODT as the source, while not implausible, is probably not desirable.

What I realized I really wanted was:

1.  A static site

I'd lose comment capability, but since I'm not using it now anyway except on the blog . . . well, that's what Twitter and Facebook and e-mail can be for.

2.  A server-side static site generator usable on a normal webserver

That is to say, something that would allow me to modify the "source" easily but the public pages would be static.   And a generator would allow for some dynamicism . . . such as repeatable blocks and such.   And it has to be able to live on any old server . . . I don't need an S3 bucket for this sort of thing.

3.  AsciiDoc input.

From what I can tell, AsciiDoc input is sufficient markup to achieve anything one wishes to achieve insofar as typographic prettiness and readability.   It can do internal linking (such as on my assorted tables of content, or the Volumetrics page notes, et cetera).  I think it even accepts two spaces after periods . . . so there.

3A.  WYSIWYG, whether client-side or server-side

It's nice to be able to see a picture in the document and not have to imagine it.

4.  Mobile-friendly workflow

I don't want to have to sit in front of a real computer . . . or even a Mac . . . if I see a typo that needs fixing.   I should be able to fix it using an old iPaq running Windows Mobile 2003 (which is *still* more useful than an iPhone).   If that means an online editor or merely the capacity to fix the source file and then regenerate the page, I don't care so long as I can get it done.

5.  RSS

RSS is considered a dying technology, but only by people with no sex life.

Yeah, I said it.

Also desirable:

6.  Draft

I may have a long-term edit of a page to do . . . I don't necessarily want it sitting out there in the wild while I create or fix it.   Some options that allow Markdown stuff don't have draft capability so you basically have to simply try to hide the page somewhere.   That's kinda silly.

7.  Math support

I don't really want to get into LaTeX, but I do need some way to attractively present calculations.   The text-only stuff I do now is pretty ghetto-tastic.   But, I can live with it if needed.

8.  Free

I don't put a lot of money into this and I plan to keep it that way.   Hell, most of the reason I know what I know about technology and whatnot is because, being a cheapskate, I'd always keep looking for a free way to do things.

Searching further, I finally found Pico CMS, which seemed to be the closest thing I was going to find.  It didn't support AsciiDoc, but it satisfied most of the requirements.  I thought it was completely wonderful until I started trying to do this newfangled Twig theming that it requires.   Also, the developer who made it seems to hate it and doesn't act like he wants anything more to do with it.

There was a fork of it to Phile CMS, and there's also the seemingly-unnamed-as-such fork called Morfy (which is funny since the guy who made it is all persnickety about folks wanting to white-label his other CMS).   But, between the reliance on flimsy Markdown, as well as the issues of plugin incompatibility, make these iffy choices as well.   And, of course, there's the fact that Pico and its brethren aren't really server-side static site generators, but seem instead to be software that live-renders your Markdown, which isn't quite what I'm going for.

Put simply, it doesn't look like it has occurred to anyone to have a server-side static site generator, which is quite disappointing really.

So I kept looking, and allowed my search to expand to flat-file CMS software that would at least accept Markdown, and came across Monstra.   Monstra seems quite interesting, despite being made by the Morfy guy, but has like zero useful documentation and very little works out of the box other than the basic CMS itself.  It does a lot better in that regard than competitors GetSimple CMS or some others that can only create Error 500 messages, but it's still pretty annoying.  (I have come to like to think the Ukrainian who made it is pro-Putin, which would of course make it okay to dislike him.)

So really, the search goes on for now . . . but expect a change at some point soon.