Tag: markdown

textbook-evaluation-toolkit

March 26, 2019

This isn’t strictly Linux-related, but it is related to openness. I spent the past year as part of a team training students to evaluate textbooks. The goal of the project was to get student voices in the mix for Open Education Resources.

The toolkit we used for this project is ready and we put it up on GitHub, with the hope that others will use our work. I’m posting this here 1) out of pride and 2) to reach open-minded educators.

textbook-evaluation-toolkit | GitHub

The Linux Setup – Joseph Reagle, Academic

April 19, 2016

Joseph is a great example of why Linux is so important. He obviously knows how he wants his computer to work and Linux lets him craft an environment that works in exactly that way. I tend to focus on academics, because I work in academia, but I think anyone who spends a lot of time in front of a computer, as academics do, has a personal relationship with their machine. Linux lets us personalize our work spaces. And personalized work spaces make for happy (and productive) users.

You can find more of The Linux Setup here.

You can follow Linux Rig on Google+ here and follow me on Twitter here.

  1. Who are you, and what do you do?

    I’m Joseph Reagle, an Assistant Professor of Communication Studies at Northeastern University. My latest book, Reading the Comments: Likers, Haters, and Manipulators at the Bottom of the Web, was published in April 2015 by The MIT Press. I also published Good Faith Collaboration: The Culture of Wikipedia in 2010. I’m currently working on life hacking and geek feminism topics.

  2. Why do you use Linux?

    I first encountered Linux around 1993, at about the same time I created my first Web page. I was a computer science student, and I remember downloading it on to about 40 3.5″ floppy disks and taking it home where my brother and I installed it on our PC. It was great to have multiple terminals available on your own PC: I could have a news reader (trn), email client (pine), editor (Emacs), and a compiler running concurrently. Back then, it was quite a challenge to get X working, I still have nightmares about editing modeline files, but it was a delight to finally see those xeyes!

    Since then, GNU/Linux has been the most hospitable environment for doing the things the way I’m used to.

  3. What distribution do you run on your main desktop/laptop?

    My choice was influenced by my colleagues at the W3C. Initially, I used a really nice Windows workstation Philip DesAutels wrangled for me—and I remember being scolded by Richard Stallman! A few years later, Daniel Veillard mounted a campaign in favor of Red Hat. When he left to go work there, I followed the lead of the systems guys (like Eric Prud’hommeaux and Hugo Haas) towards Debian. At some point, I noticed that whenever I went to the Web with a question, I ended up in the Ubuntu forums. The distribution was relatively current, easy to use, and the community was great. I’m now running Kubuntu 14.04 LTS.

  4. What desktop environment do you use and why do you use it?

    I’ve been using KDE since some version of 1.0 . I used to experiment with other environments but I no longer like to tinker. I just want it to work the way I expect.

    One of my great frustrations is my dependence on speech recognition. There was a brief time, around 1999, when IBM’s ViaVoice was available on Linux. But since then, I’ve been dependent on running some version of Dragon in a virtualized Windows environment. Speech recognition is now getting to be pretty good on Macs (via Dragon and natively), so I’m considering that as an option. I had high hopes for the KDE Simon project but it’s no longer active.

  5. What one piece of Linux software do you depend upon? Why is it so
    important?

    Package management (apt-get) is the thing that really sets GNU/Linux distributions apart from anything else.

    Otherwise, I love Zim wiki. It is cross platform (it works well on Windows and is a bit creaky on OS X), but it first emerged in the Linux sphere. I also rely upon the Freemind mindmapper. I write everything in markdown, and use pandoc to produce syllabi, lectures, papers, and books.

  6. What kind of hardware do you run this setup on?

    Nothing too special. A Dell Vostro 270s at home and a System76 Wild Dog Performance at work.

  7. Will you share a screenshot of your desktop?

    Better yet, here’s a screencast of some tools I use for research and writing.

Interview conducted November 19, 2015

The Linux Setup is a feature where I interview people about their Linux setups. The concept is borrowed, if not outright stolen, from this site. If you’d like to participate, drop me a line.

You can follow Linux Rig on Google+ here, follow me on Twitter here, and subscribe to the feed here.

Writing, Not Formatting, with Asciidoc

September 22, 2015

So I’m writing a book about Linux.

You’ll hear a lot more about this over the next few months, but one of the most interesting things I’ve discovered is Asciidoc, which is a fantastically thorough markup language for writing books. It’s like Markdown with even more options, like sidebars, notes, and tables. Asciidoc lets you just type, with very simple syntax controlling the formatting.

When I first started writing the book, I was using Word style sheets with LibreOffice. Manning, my publisher, offered .odt versions for OpenOffice, but I had trouble getting the styles to work. Ironically, I wound up using the Word .docx template, which worked best with LibreOffice. But the big problem was images—they just wouldn’t embed correctly. I was spending a decent chunk of time formatting when I needed to be writing.

Comments were also tough to parse. Jim Whitehurst actually got LibreOffice patched to better handle them while he was writing his book.

After a couple of chapters of fighting through the template, my editor suggested we switch to Asciidoc and my life instantly became easier.

With LibreOffice, I had to insert an image, number it, caption it, style it, and then hope that everything held together, while with Asciidoc, I just write something like this:

.Mint's Software Manager has a similar look to the Ubuntu Software Center.
image::../images/08_11.png[]

and Asciidoc handles everything else for me, even numbering the images in the captions.

This is what the above code renders as:

Asciidoc transformed into a PDF
Asciidoc transformed into a PDF

A sidebar or note is as simple as something like this:

Asciidoc syntax for a note
Asciidoc syntax for a note

which turns it into this:

Asciidoc syntax for a note rendered into a PDF
Asciidoc syntax for a note rendered into a PDF

Asciidoc has formatting for heads and subheads and even automatically generates a table of contents based on them:

Asciidoc generates a table of contents automatically
Asciidoc generates a table of contents automatically

You can write Asciidoc in anything since it’s just text, but I like to preview the code to make sure everything looks OK. There’s a gedit plugin but it seemed to require some work to get going and I was under the gun with deadlines, so I decided to use Atom, the GitHub-created text/code editor. It had a plugin that rendered Asciidoc. I wrote a few chapters with it, but the preview was sometimes peculiar. Notes and sidebars would expand into the whole document. Also, I couldn’t directly open Asciidoc formatted documents with it. Instead, I had to open Atom and then open a document via the Atom open menu.

Atom was fine, but annoying enough that I decided to try Brackets, the Adobe open-source code/text editor. It renders Asciidoc much better and while opening Asciidoc files still isn’t seamless, it’s better than Atom. I wish it had a running spellcheck instead of the ability to run a spellcheck when you’re done, but it previews what I need to see and gives me a running word count, so I’m pretty happy.

The Brackets text editor
The Brackets text editor

Asciidoc rendered by Brackets
Asciidoc rendered by Brackets

Brackets and Atom render in HTML but the a2x command (it’s part of the Asciidoc package) makes it very easy to convert the .adoc file to a PDF (although there’s some weird bug that causes the transformation to fail when image files have a period in the name). The output looks like a professionally formatted book chapter.

Asciidoc has been a life-saver for me. I’m lucky to be working with a publisher that uses it. I think it has applications for anyone who needs nice-looking PDFs or someone self-publishing. I also think it has tremendous implications for open education resources in that it allows someone to write a textbook without necessarily having to format it. You’d have a PDF ready very easily but you could still make the underlying Asciidoc available to people who wanted to modify the original work.

Markup languages like Asciidoc are fantastic for people like me who don’t want to deal with formatting. It’s saved me hours on the book (once we moved to Asciidoc, we were also able to use a private git repository to submit drafts back and forth; Asciidoc also has the ability to comment-out text which lets us share comments in the text) and allows me to focus on writing and not on styles and formatting. I’m not sure if Asciidoc has wide appeal for everyone, but if there’s a chance you can use it to move your work forward, I encourage you to spend some time with it.