No, Your Son is Probably Not Brain Damaged

But how is it that two year old boys just know that they need to run around and shriek, “OOGIE SKOOGIE KAN-NOOGIE!”

Is it nurture? It sure as hell isn’t nurture.

Is it some kind of Jungian collective unconscious… thingy?

Is it genetic? Does it provide some kind of increased chance of survival in the wild? (Because from where I’m standing, quite the opposite.)

Songs for Git Commands

git push

“Salt-N-Pepa — Push It”

Okay, this one was kind of a gimmie.

git commit

“Beyonce — Single Ladies (Put A Ring On It)”

If you wanted it, you shoulda put a hash on it!

git log

“Ren & Stimpy — Log”

It’s better than bad, it’s good.

git config

“Eminem — My Name Is”

Got other suggestions? Leave ’em in comments. (Extra points awarded for whatever mad genius comes up with something for git reflog.)

git reflog [new]

“Britney Spears — Baby One More Time”

Thank you, Allen!

git fetch [new]

“Queen — I Want It All”

Thank you, Josh Adell!

git rebase [new]

“Bad-CRC — All Your Base Are Belong To Us”

Thank you, Petey!

Tech Pubs Tuesday: Converting TWiki/Foswiki to Markdown, reStructuredText, or Some Other Sane Format

Once upon a time, there was a young technical writer who dwelled in an elegant cubicle with high, noise-baffling walls. He was handsome and clever, beloved by engineers and product managers throughout the Valley, and could write like the wind itself.

One dark winter’s evening just before close of business, an ancient crone came tottering over to his desk. In her arms she clutched a tattered collection of printouts of the DR DOS 3.31 manual. “Please, young sir,” the crone asked, “could you trouble yourself to help me edit this poor old woman’s manuscript?”

The young technical writer laughed and refused. “I am far too busy to help the likes of you,” he said, by which he meant too busy reading Reddit. “Begone!”

Once more the crone asked the young man for help with her edits, taking care to warn him that things were not always what they seemed on the surface… and once more the young man refused to help her.

BAMF! With a flash of light and an acrid whiff of toner, the crone’s disguise fell away, revealing her true form: the Goddess of Technical Writing herself.

The young man fell onto his knees, begging forgiveness and sobbing, but it was too little, too late. The Goddess faded away, but not before spitting out her most venomous curse: “May all your software manuals forever be written in TWiki!”

So if you’re an unlucky person, you might find yourself stuck with a pile of technical documentation in TWiki or some other baroque “enterprise” wiki. If so, here’s a hacky recipe for getting yourself unstuck.

  1. View a rendered wiki page and select the content div out of the HTML, saving each page as an HTML snippet. In TWiki or Foswiki, the content div typically has an ID of patternMainContents. For a small number of pages, you can use your browser’s element inspector to help you copy and paste the content. For a large number of pages, you can try automating this process with curl and some custom script that strips off everything that isn’t the content div.

  2. Run all resulting HTML snippets through /usr/bin/tidy.

  3. Download and install pandoc.

  4. Run all tidied HTML snippets through pandoc, converting them to Markdown, RST, or the output format of your choice.

There’s a good chance the conversion won’t go all the way, particularly if your documentation used any TWiki plugins that rely on JavaScript (like the “Twisty” plugin). Look for sections that didn’t convert properly and fix them up by hand.

The main takeaway is that you don’t want to mess with parsing the horrible native wiki format. Let the wiki do its thing and just get the resulting HTML — that’s something you can work with.