cool Be a power user at the command line

Technical writers who know their way around the command line will find themselves to be very valuable.

Technical writers don’t need to know the command line to get the job done. Most tools are aimed at desktop users, including word processors or web content management systems. But technical writers who know their way around the command line will find themselves to be very valuable. For example, many processing systems including pandoc and DITA-OT are command-line tools. If you can manipulate the command line with confidence, you’ll set yourself apart from your colleagues.

Let’s explore the basics about the Linux command line.

Accessing the command line

To get access to the command line, you have a few options:

If you are running Mac, then there’s a Terminal app that you can run. That gives you a command line that will be very similar to the Linux command line. That’s because Mac is built around an operating system called “Unix” – and Linux is a Unix-like operating system. So almost all of the things you can do on the Mac command line (the Terminal) will be the same as the things you can do on the Linux command line, and vice versa. (The difference is because Linux usually comes with a bunch of other tools that Mac doesn’t usually provide by default.)

If you are running Windows, there’s a command line environment you can access using a program called Powershell (or Cmd on older Windows systems). However, the command line on Windows is quite different from the command line on Linux. A few things are the same, but most of it is different because the Windows command line was actually built up from a similar-but-different operating system called DOS (from the 1980s and 1990s).

If you have access to a remote Linux system (like a web server) you can use a program called a Secure Shell (probably called WinSSH or Putty on Windows, or called something else on Mac) to access a Linux server. Doing that will automatically give you a command line by default.

Getting around

Once you’re at the command line, you need to know about the “prompt.” That’s just some text that tells you “the system is waiting for you to type something.” On Linux, the default prompt is $, usually with some stuff before it.

You need to know that directory is what you’d call a “folder” on Mac or Windows. It’s the same thing (just an older term). With that knowledge, you just need to know a few commands to get around: cd and ls.

ls will list the contents of a directory. If you type ls and hit Return (or Enter, depending on your keyboard) then you’ll see a list of what’s in the directory that you are in. That’s probably your “home” directory. I run a Linux system as my desktop computer at home, and my “home” directory is /home/jhall.

[jhall@linux] ~$ ls
bin      Documents  lib       Public  virtualmachines
Desktop  Downloads  Pictures  src

My prompt is [jhall@linux] ~$ and that tells you several things at once:

  • My username is jhall
  • The system that I’m connected to is called linux (my Linux desktop computer)
  • The ~ means that I am in my home directory, which is /home/jhall (the “tilde” is an old Unix shorthand)
  • The $ means that Linux is waiting for me to type something

Linux uses the / character to separate directories. So /home/jhall says it’s in the jhall directory, which is inside the home directory, which is inside the / directory (/ is also called the “root” directory, because there’s nothing before it.)

You can set up the prompt however you like, and many Linux users customize their prompt. So you might see something slightly different. When you read an article about the Linux command line, the prompt is usually just shown as $.

My home directory has a lot of stuff in it. It happens that all of those are directories (“folders”) that contain other things. If I wanted to see what I had in my Downloads directory, I could use cd to “change directory” into that location:

[jhall@linux] ~$ cd Downloads
[jhall@linux] ~/Downloads$ ls
backup  Markdown_1.0.1.zip  out

You might notice that my prompt has changed to [jhall@linux] ~/Downloads$ which tells me I’m in the Downloads folder in my home (~) directory. In other words, I’m in the /home/jhall/Downloads directory.

But I don’t have to use cd to see what’s inside a directory. I can also tell ls to look there. So if I wanted to see what was inside the out directory, I could type this:

[jhall@linux] ~/Downloads$ ls out
pdf

Now I know there’s a pdf directory in there. And I can see inside that with this ls command:

[jhall@linux] ~/Downloads$ ls out/pdf
techdocbook_fixed.pdf

If you type the cd command just by itself (with nothing after it) you should go back to your home directory:

[jhall@linux] ~/Downloads$ cd
[jhall@linux] ~$ 

Converting with pandoc

With that basic knowledge about how to get around, you can run other commands. There are a lot of powerful Linux commands, including the pandoc document transformer.

pandoc isn’t installed on every Linux system, but if you have it on your Linux system, it’s very powerful. You can use pandoc to convert from (and to) all kinds of files. Let’s say you have a Markdown file that you want to convert into a LibreOffice file. I have a bunch of Markdown files in my ~/Documents/markdown directory, so let’s start there:

[jhall@linux] ~/Downloads$ cd
[jhall@linux] ~$ cd Documents/markdown
[jhall@linux] ~/Documents/markdown$ 

If I do the ls command here, it will include all kinds of things, including temporary files and files that I’ve converted from Markdown to something else. So I’ll just show the files that end with .md by typing *.md as the “file” I want to see. The * means “anything,” so *.md means “anything that has .md at the end.” Because I name all my Markdown files with .md at the end (called a “file name extension”) that will show me just my Markdown files:

[jhall@linux] ~/Documents/markdown$ ls *.md
basic.md  transition-techwriting.md  wiki.md
baud.md   tww.md                     wordle.md
top5.md   typo.md                    wordoutline.md

Let’s convert that wordle.md file. This is the original draft of an article I wrote about solving Wordle using Linux command line tools. You tell the pandoc command what to do by typing extra stuff on the command line. (The technical term is options or arguments, but the terminology isn’t important.) I can tell pandoc that I want to convert from a Markdown file to a LibreOffice file, and save the output to another file, by typing this:

[jhall@linux] ~/Documents/markdown$ pandoc --from markdown --to odt wordle.md -o wordle.odt

The --from markdown option says to convert the file from Markdown format, and the --to odt option says to convert the file to LibreOffice Writer format (LibreOffice Writer uses .odt as its file extension). The file I want to convert is wordle.md. The -o wordle.odt option says to save the output to a file called wordle.odt.

But pandoc can convert to all kinds of other formats. Let’s try Word format, which uses .docx as the file extension:

[jhall@linux] ~/Documents/markdown$ pandoc --from markdown --to docx wordle.md -o wordle.docx

Or we can can convert to HTML format, like this:

[jhall@linux] ~/Documents/markdown$ pandoc --from markdown --to html wordle.md -o wordle.html

That creates an incomplete HTML file. It doesn’t start with <!DOCTYPE html> and doesn’t have the <html>..</html> block or <head>..</head> block or <body>..</body> block. It just creates the text that you would need to copy/paste into the “body” section. To make a complete standalone HTML file, we need to give an extra option to pandoc, like this:

[jhall@linux] ~/Documents/markdown$ pandoc --from markdown --to html --standalone wordle.md -o wordle.html
[WARNING] This document format requires a nonempty <title> element.
  Defaulting to 'wordle' as the title.
  To specify a title, use 'title' in metadata or --metadata title="...".

It complains because pandoc can’t figure out what to use for the <title> tag. There’s a way to do that by creating metadata inside the Markdown file, or we could have provided the title as metadata on the command line like this:

[jhall@linux] ~/Documents/markdown$ pandoc --from markdown --to html --standalone --metadata title="How to solve Wordle with the Linux command line" wordle.md -o wordle.html

That is a really long command line, but you should type it all on one line.

And with that, we have a LibreOffice “ODT” file, Word “DOCX” file, and HTML file that contain the same text from the original wordle.md Markdown file.

Converting with LibreOffice

To convert to PDF using pandoc requires some extra tools, because it wants to use an “intermediate” markup system called LaTeX. But if you have LibreOffice installed, it turns out you can use LibreOffice from the command line. The important thing is to use the --headless option with LibreOffice, so it doesn’t try to run the graphical program. “Headless” means “without a head,” so it runs LibreOffice without showing anything. We’ll also need to give the --convert-to option to specify the output file format:

[jhall@linux] ~/Documents/markdown$ libreoffice --headless --convert-to pdf wordle.docx
convert /home/jhall/Documents/markdown/wordle.docx as a Writer document -> /home/jhall/Documents/markdown/wordle.pdf using filter : writer_pdf_Export

LibreOffice prints out a line that basically tells you it’s using the “LibreOffice Writer PDF Export” feature to make a PDF for you.

And now we have a PDF file, too! We can see that by using ls to look for wordle.* (because * means “anything,” so that means “anything that starts with wordle plus a dot).

[jhall@linux] ~/Documents/markdown$ ls wordle.*
wordle.docx  wordle.html  wordle.md  wordle.odt  wordle.pdf