From db57b10a9a725bbca115bc9c2c65cb4f9cb34c86 Mon Sep 17 00:00:00 2001 From: Alex Karle Date: Thu, 19 May 2022 00:18:52 -0400 Subject: [PATCH] blog: Add post about mandoc resume Also link it to the homepage! --- www/blog/index.txt | 1 + www/blog/mandoc-resume.txt | 117 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ www/index.txt | 2 ++ 3 files changed, 120 insertions(+) create mode 100644 www/blog/mandoc-resume.txt diff --git a/www/blog/index.txt b/www/blog/index.txt index 2d2fe98..d41d968 100644 --- a/www/blog/index.txt +++ b/www/blog/index.txt @@ -12,6 +12,7 @@ For an up to date list of software/hardware I use, see ## 2022 +- 05/22 [Typesetting a Resume with `mandoc(1)`](/blog/mandoc-resume.html) - 04/22 [Exploring Acme, Plan 9, and `NO_COLOR`](/blog/exploring-plan9.html) ## 2021 diff --git a/www/blog/mandoc-resume.txt b/www/blog/mandoc-resume.txt new file mode 100644 index 0000000..9967301 --- /dev/null +++ b/www/blog/mandoc-resume.txt @@ -0,0 +1,117 @@ +# Typesetting a Resume with `mandoc(1)` + +_Published: May 18, 2022_ + +## History + +My first real resume was written freshman year of college in a haste +because a friend told me his dad's software company was looking to +hire interns. It was a scraped together Word doc that had typos in +the headers because ALLCAPSWORDS were considered acronyms and are +not subject to the red squiggly spell check. I didn't notice until +someone pointed it out to me after sending it out. I didn't get the +job. + +Updating a resume was always way low on my todo list--the kind of +thing that didn't happen until it was needed. So this first resume +lived on for years in a similar format. Needless to say, I was never +really proud of how my resume looked. + +Towards the end of college, I got really into version controlling +my written assignments. `git` for code wasn't enough--I wanted to +know, without another proofread, that I hadn't fat fingered a typo +into my essay since the last time I proofread it. So I started +writing my non-technical essays in `LaTeX`, which fit well into my +`git` workflow. + +I decided somewhere around then that I would one day rewrite my +resume in `LaTeX`; however, there was no need at the time, since I +had already accepted a return offer to MathWorks. So I put it on +hold. + +As I moved to Linux and OpenBSD on personal computers, the desire +to leave `docx` behind became even greater; but again, updating a +resume just wasn't fun. I had better things to do, like write +[Gopher clients](https://sr.ht/~akarle/gc/) using `nc(1)` and +`awk(1)` or [install Plan 9](/blog/exploring-plan9.html). + +At this point, it's been years since I've touched `LaTeX`. I don't +have a compiler installed, nor do I remember the Vim setup I had +going that made for a reasonably fast preview cycle. Could I find +it in my [dotfile history](https://sr.ht/~akarle/dotfiles/)? Of +course (`git` for everything!). But the effort to port it kept +looking less appealing until a few months ago when it occurred to +me: _what if I could write a reasonable looking resume in `mdoc(7)`_? +I [had the experience](/blog/my-old-man.html), and UNIX has a long +history of typesetting. It felt like the perfect blend of: + +- Easily versionable +- Plaintext / archivable +- Exportable to PDF +- (IMHO) The right amount of nerdy + +So I set out to do it. + +## The Results + +See for yourself: + + $ curl -sS https://alexkarle.com/resume.7 | mandoc -l + +There's of course a [PDF version](https://alexkarle.com/akarle.pdf) +too. + +Overall, I'm really happy with how it turned out! + +## Lessons Learned + +Originally I thought I'd try to replicate a more traditional resume. +Or at least hide the fact that it's typeset using a man-page tool. + +I discovered pretty quickly though that `mandoc(1)` is focused on +`man` pages and less suited for general typesetting. Reading the +[`roff(7)` man page](https://man.openbsd.org/roff.7#COMPATIBILITY), +things like setting font, margins, etc are pretty limited (which +makes total sense if targeting a terminal more than a printer). + +I realized my options were to switch to `groff(1)`, which looks to +be a more fully featured typesetting tool, or double down on the +man-page appearance. + +For now, I've chosen the latter, mostly because I think it's a cute +hat tip to one of my favorite tools--`man(1)`. + +In lieu of margin/spacing/font adjustments I was able to keep a +relatively compact feeling by: + +- Using `.br` (line breaks) instead of `.Pp` (new paragraphs) +- Using `.Sy` (bold font) instead of `.Ss` (subsections) in WORK EXPERIENCE +- Creating a two column work experience layout using a `-tag` list + (importantly, the list items themselves can be lists for job description!) + + .Bl -tag -width "YYYY-MM - YYYY-MM" -compact + .It 2021-10 - Present + .Em Senior Software Engineer + .Bl -dash -compact + .It + Wrote custom CLI tooling for bug triage and local development + ... + .El + .El + +## Conclusion + +For the first time maybe ever, I'm happy with how my resume looks. +I had a blast learning some fine-grained `roff(7)` commands that +don't show up in regular man-pages even though I removed them in +favor of the classic `NAME`, `SYNOPSIS`, ... `SEE ALSO` layout. + +I am not a lawyer, so I don't know for sure if traditional software +licenses apply to `mdoc(7)` resumes, but the MIT license does mention +"associated documentation" so I put one in the comments of the +source. + +If you like how it looks, feel free to remix it and make it your +own! If you do, I'd appreciate if you keep the link to this post +and license in the header, but more importantly, I'd love to see +it! My email is in the source :) diff --git a/www/index.txt b/www/index.txt index 0ae42e4..cc6fcfd 100644 --- a/www/index.txt +++ b/www/index.txt @@ -47,3 +47,5 @@ lightweight markup parser, [`nihdoc`](https://git.sr.ht/~akarle/nihdoc). - Email: _contact AT this-domain_ - IRC: `akarle` on [libera.chat](https://libera.chat) - sourcehut: [`~akarle`](https://sr.ht/~akarle) +- Resume: `$ curl -sS https://alexkarle.com/resume.7 | mandoc -l` + # [PDF](https://alexkarle.com/akarle.pdf) -- libgit2 1.8.1