Pandoc vs. Asciidoctor for print

I’m writing a small book. ~160 pages at 6″ x 9″. I want great-looking print editions so PDF output is critical.

I started writing in Markdown, using a few scripts to pre-process for each output format (EPUB ebook, screen PDF, print PDF, HTML) and invoke Pandoc. It worked well at first, but after a year of work my scripts had grown to be complex and annoying. I was running into the edge of what Pandoc is good at. I had issues with table formatting (text mixed up with cell borders), variable handling (had to do my own replacements), special characters (had to strip some of these or the PDF backend would croak), index generation and cross-references (both require confusing extensions). The Pandoc that came with my OS was outdated and I wound up needed several versions. I was starting down a path of customizing outputs with TeX directives and Lua extensions.

I looked around for better typesetting toolchains and came across the source code for the book Pro Git 2. Scott and Ben used Asciidoctor to convert Asciidoc source text to various formatted outputs. Their outputs looked great and there wasn’t much code needed to build them.

To give it a shot, I used Pandoc to convert my Markdown book source to Asciidoc then used the (tiny) Pro Git 2 build system. Asciidoctor created more and better-looking outputs for my book. I switched to Asciidoc/Asciidoctor. I no longer needed my pre-processing scripts, Asciidoctor did well at everything I mentioned above with mostly default settings. Customization was easy, even in the case where I had to add custom Ruby code. The Asciidoctor community seems healthy and strong.

Pandoc remains awesome for many reasons. I still love it for converting between common formats. I’ve be using it for a long time for Markdown and HTML and I hope that continues. Perhaps it is not the best at generating print-ready PDFs (nor ebooks), though.

Blue? Green? Signal.

I rolled my eyes far beyond acceptable limits when I first learned the meaning of the phrase green bubble shame. Still, I was curious, so I asked a handful of high school students about it. I rolled my eyes back into place (as they rolled theirs at my questions) and learned it is in fact real and common. Text message bubble color divides kids along lines of financial disparity and technological choice.

It starts when someone with an Android phone sends a direct text message or joins a chat. iPhone user messages appear to each other enclosed in beautiful blue bubbles. Android messages are othered in annoying green bubbles. It’s a subtle and meaningful cue. Green equates to hassle (group chats are impacted), bad quality (images/videos look worse), and worse security (not guaranteed to be encrypted). If the Android users are then socially excluded, we are in “green bubble shame” territory.

Don’t wait for Apple or Google to solve this problem. Encourage your kids to use Signal instead. This quick fix will reap rewards far beyond the next several phones they and their friends are able to afford.

Tips & Tricks

If you do decide to try Signal:

  • Disable Stories (these don’t add value).
  • Disable the notification sent when a contact joins Signal in Settings → Notifications (these are unnecessary).
  • Note how Signal forgets by design (because privacy and security), so look into saving messages if you want that.
  • Consider donating to the nonprofit that keeps Signal alive.

Further reading

Self-Hosting talks in Seattle at SeaGL this weekend

Folks in the Seattle area Friday and Saturday this week (or wishing to join remotely online): there are at least 3 relevant self-hosting talks at the SeaGL conference.

  1. Steadfast Self-Hosting: this is a preview of my book, with background and context. Demonstrates Ubuntu server, ZFS, docker-compose, Traefik reverse proxy.
  2. Lessons learned from growing a Home Lab: Guilherme Carvalho Trindade covers self-hosting of private chat, social media, and game servers.
  3. Simple Site Hosting with Lightweight Kubernetes: James Pannacciulli walks through MicroK8s fundamentals.

I’m a SeaGL co-founder. SeaGL is free to attend. I’m promoting my own book in my talk, and the book itself will be liberally licensed to encourage sharing and remixing. It will include code, all of which is FOSS.

FOSSY 2023

I am honored to be giving a talk at FOSSY 2023. The title is Steadfast Self-Hosting: Rapid-Rise Personal Cloud.

Event details

Description

Your data are essential to your life, your agency, and your future. Come learn how to save, serve, and safely share your data at home with a smorgasbord of FOSS. I’ll cover rapid setup and basic use of tools such as Traefik, Nextcloud, Wallabag, Jellyfin, and more. With these powerful and private services at your disposal you can collaboratively edit documents in realtime online, stream music and video, and future-proof your digital assets.

This talk pairs well with a soon-to-be released book of the same topic and title. Both the book and talk are about self-hosting FOSS, were created with FOSS, and are FOSS themselves (open source, free to copy, free to modify and redistribute).

GnuCash

TL;DR – it works well for one specific purpose, for a single user. Use it if you like to tinker and are academically interested in accounting.

Gnucash-input-date.png
Gnucash-input-date.png () by , .
Screenshot of a GnuCash Account Register

I’ve used GnuCash for many years. I started using it without a sense for how much time I’d spend in the manual and forums figuring out the UI/UX. After having done so, I’m still glad I did. I learned quite a bit about double-entry accounting. This way of accounting forces you to contend with the fact that money always comes from somewhere and always goes somewhere. GnuCash maybe does not enough to help you manage this complexity. GnuCash is complex in part because finances are complex, but that’s not a great excuse for its often confusing UI/UX.

GnuCash is strictly single-user. I think this is a good way to think about it, too. Just use it for yourself. Only subject another to it if they really are, let’s say, academically interested in accounting and expect to fiddle with their accounting software (to the point of writing custom reports in Scheme).

Good luck getting a quicken/quickbooks power user to use GnuCash. I can’t speak to proprietary accounting software since I barely used any, though. I’ve never met a pro who used it.

GnuCash is mature. There is a rich body of knowledge available and a strong community.

It is written in C/C++. If it were rewritten it would surely not be. I’m not sure how much this matters in terms of project sustainability though, it has been around since 1998 and is still in active development.

It’s fast.

There is no mobile client.

I have never lost data with GnuCash. This is an incredible confidence-builder (and a requirement) for me. Data is hard work. It appears to be very careful about never losing any with its lock file and log files and such. It is also FOSS, which is a big deal for me.

I’ve used it for business invoicing and I remember being really proud when I got it to spit out good-looking invoices that were true and reconcilable with all my carefully-entered financial data. It’s not worth the effort for simple invoices, though.

If you have the privilege of working with multiple financial institutions, you get to import transactions from multiple sources. This is painful. In the USA this is perhaps painful by design.

I used Mint for a while. All that thing did (besides trigger my privacy spidey-sense) was sort of pull down transactions automatically with a lot of hand-holding. GnuCash is even worse at pulling down transactions, though. I never got the online stuff (OFXDirectConnect/AQBanking) to work well and I recommend against trying it in the USA. Even manual QIF/OFX/CSV importing is a pain, but it is generally predictable and reliable. There’s some intelligence built in (matching, remembering previous categorizations, etc) but it is hard to figure out. The real problem there IMHO is that our banks don’t want to become commodities themselves and they have resisted interoperability. Check out FinTS (was HBCI) in Germany for a counterexample where they’re trying to make it work.

The best part about GnuCash’s UI/UX is also the most boring part (you’ll find boring is a Good Thing with finances): the transaction register. Filling in a ledger for a particular account is very nice, especially in double-line mode. Auto-complete works well. I’ve grown to love the shades of lime green like an old-school paper ledger.

So there you go. One accountant, one desktop, maybe a few reports. Consider using a spreadsheet instead.

Good luck!

The Immortal Cookbook

Check out my LibrePlanet 2023 workshop about digital recipe management titled The Immortal Cookbook!

Event details

Description

Join us in the journey: chart your course to digital recipe freedom! Celebrate your favorite home-cooked meals with all their history, comfort, and tradition. Cherish and share these meals with friends and family. Gather and curate your delicious recipes with ease. Recall your favorite dishes in an instant and keep them forever. This workshop will cover practical digital recipe storage and maintenance with free software using libre data formats. The focus will be on ease of use and collaboration. The workshop is designed to attract people capable at plaintext editing, including some coding experience.

Crossword Data Detective Unravels Massive Scandal

One fine day in 2016, Saul Pwanson invented a simple, standard, plain text crossword data storage format. One outcome of Saul’s work was the uncovering of a decades-long crossword copy-and-paste fiasco. This is the kind of story you’d expect to hear on Tim Harford’s Cautionary Tales. Excellent work, Saul!

https://inv.riverside.rocks/watch?v=9aHfK8EUIzg

https://fivethirtyeight.com/crossword

blank crossword puzzle

One action you can take to make social media more kind 🎀

Sign this petition:

https://oneclicksafer.tech

This is an important experiment for Facebook to try limiting “freedom of reach”. It’s a hard thing to regulate and our government is struggling to do so. Facebook itself did the research and came up with the solution to limit resharing, and it is a relatively easy change in their user interface.

More background:

https://www.humanetech.com/podcast/42-a-conversation-with-facebook-whistleblower-frances-haugen

Frances Haugen portrait

I hope we hear a lot more from Frances Haugen. She is an absolute champion. Here’s a quote from Ms. Haugen about the proposed change to limit resharing:

I think it’s one of those things where this is a change that Facebook could show that they were serious about decreasing extreme, polarizing, divisive content very, very easily. And they could show that they’re willing to trade off a very small amount of profits for the safety of the platform. And I think it’s a wonderful, content-neutral, language-neutral solution. It’s not about picking winners or losers. It’s not about censorship. It’s about changing the dynamics of the platform so that it’s less twitchy and reactive. And it allows us to be thoughtful. And I think we want social media that helps us connect with people we care about. We want social media we enjoy. And I think that all those things are true about this change.

If you use Facebook, will you also let me know if you noticed my post about this petition? Facebook won’t give me analytics about it.