I’m very excited (and proud) to announce that on March 3rd, 2016 I reached a long-term goal I set for myself 3½ years ago, by self-publishing my first book, The Linux Sysadmin’s Guide to Virtual Disks. The book is published under my new brand, Scribe’s Guides.
The first edition of The Virtual Disk Guide has been a long time coming. Nearly 7 years of on-and-off writing have gone into it. I’m relieved to have made it this far.
I view the book as the definitive reference guide for virtual disk related activities — clear, concise, accurate, and approachable to readers of all skill levels— but that’s just my opinion. You can decide that for yourself.
The book is quite thoroughly cited and annotated with nearly 100 individual footnotes and references to additional learning resources. The book weighs in at around 80 pages, 7 chapters, and two technical appendices. Here’s the byline from the scribesguides.com website:
The Linux Sysadmin’s Guide to Virtual Disks demonstrates the core concepts of virtual disk management. Real-world problems are covered in the book’s “Cookbook” section. Other topics include: helper utilities, disk formats, troubleshooting tips, performance considerations, and comprehensive appendices.
Or do both! Say “thanks!” by purchasing a copy, and then enjoy the latest builds online forever, for free!
[1] – The original first edition text is also available for free in PDF and HTML formats and is identical to the print copy
The official publishing of The Virtual Disk Guide does not change anything about it’s openness or your freedom to remix it however you wish. The book is still freely licensed under the Creative Commons Attribution-ShareAlike 4.0 International License (CC BY-SA 4.0).
All of the source material used to build the book’s body material and cover images are still free and open source, covered under the same license. All digital media displayed in the book, such as figures and the cover art, was created using free/open source software. Each media item was created and saved in digital formats unencumbered by patents.
As ever, if you identify errors in the book or have thought of a way to improve it, please open a ticket on the GitHub issue tracker. If you’ve read a copy of the book already and would like to contribute a review or statement, feel free to reach out to me. Find my email in a github commit, or look at my other contact methods under the author highlight panel on scribesguides.com.
The experience of writing and publishing this book has taught me much, and it’s time to spread that information. Check back soon for a follow-up post I’m writing which covers more of the technical side of self-publishing. Specifically, self-publishing a DocBook 5 document at the on-demand printing website lulu.com.
Let me be explicitly clear, this is not a promotion for lulu.com.
Rather, the post will review some of the technical challenges I encountered (old examples: #1, #2, #3) during the publishing process, including challenges specific to Lulu. Such as, how I customized the PDF output from dblatex to look more personal and less generically academic, why I had to order three proof copies of the book before the cover matter printed in decent quality, and how to adjust your inner and outer page margins so there’s a reasonable amount of whitespace between the spine/binding and the body text.
I have a feeling that by the time I’m done with the blog posts I’m going to have written another book of documentation about how I wrote a book of documentation
Updating to the 0.3.4 version of dblatex has fixed many of the issues detailed in The Aftermath (end of this blog post). See the blog post for more information.
You’re writing a book in DocBook XML, publishing it with dblatex, and you dislike (or want to customize) the fonts it uses in the rendered PDF.
You hunt around the internet and find a nice family of fonts you want to use in your final product. Best of all, they’re free and released under the Open Font License!(Thanks, Adobe!)
The dblatex documentation shows you how to set your fonts, but you can’t seem to get it to work.
Caveat: I can verify that this solution works for TTF type fonts, I can not comment on how well it works for other font types.
First, you will need to identify the actual family name of the fonts you want to use. If your font is not installed on your system there is a command called otfinfo that can tell you the family of the font file (despite sounding specific to OTF fonts, this works on TTFs as well). The otfinfo command is provided by the lcdf-typetools package:
If your desired font is already installed on your system you can use the fc-list command instead to find the same information (fc-list is provided by the fontconfig package):
If this is a new font on your system then you’ll need to install it. There are (at least) two locations that work:
$HOME/.fonts
/usr/share/fonts/truetype/
The Font Manager application (package: font-manager) also provides a graphical way to install font collections.
Rebuild your font caches with the fc-cache -f -v
command. If I recall correctly, you need to have super user permissions to run this. I may be wrong though.
The necessary changes to consume your custom fonts isn’t difficult. Assume that up until now you’ve been rendering your PDFs from XML source like this:
dblatex -o output/Virtual-Disk-Operations.pdf Virtual-Disk-Operations.xml
We need to use XSLT stylesheets to define what our chosen font families are going to be. In this example I’m using Source Sans Pro for the body font and Source Code Pro for monospaced sequences.
First, make a directory called xsl and put a file like this in it:
Next, slightly modify the command you run to build your PDFs (new parts are in bold text):
dblatex -p xsl/dblatex-pdf.xsl -b xetex -o output/Virtual-Disk-Operations.pdf Virtual-Disk-Operations.xml
-p xsl/dblatex-pdf.xsl: This tells dblatex that we’re providing a “user stylesheet” to use when transforming the XML. This stylesheet only has our font customizations in it, but you can put much more in them than just that.
-b xetex: This tells dblatex that instead of rendering our PDF with pdftex we want to use a different backend driver (or “TeX engine”). Specifically we want to use the xetex driver. We choose the xetex driver because of it’s superior font handling abilities via the fontspec LaTeX package. When we use the xetex engine dblatex will insert some special macros into the intermediate LaTeX document it generates, this process is transparent to the end user:
After this, dblatex runs any custom post-compilation scripts, and then hands the intermediate file off to xetex where it is finally transformed into PDF format.
In my case there were some unexpected side-effects from switching backends. Here’s what I’ve noticed so far:
The only thing that really bothers me is the broken word-wrapping character. I can deal with the others breaking. I had intended to remove them from the final product anyway.
I do a lot of DocBook XML editing, either at my job or at home. Because of that I’ve built up a pretty customized .emacs file. Every so often I meet another person whose also found themselves having to edit a bunch of XML. The most fantastic thing about nXML mode I think is the automatic slash completion feature. It works like this: If I have an open element, say I’ve started an <xref>, you can configure nXML mode such that upon typing the closing </ characters it will complete that sequence for you. I can just never remember how to set that option in emacs. So today I’m taking the time to finally document that procedure.
For even more fun, use the C-c C-f macro which will auto complete your current block, regardless of your position inside of it. For additional references, I invite you to check out the docs NM Tech has posted on nXML-Mode.