How to create a PDF of a Unix man page

Unix man pages are written in the troff language. There are three basic Unix programs that interpret troff code – nroff, troff, and groff. nroff is used for preparing documents for display in the terminal. troff prepares documents to be printed on phototypesetters, a technology that is pretty much obsolete by now. The Unix man program is essentially just a frontend for nroff that preprocesses the code with a set of macros known as the man macros and then pipes it into less.

What we will be using is the GNU roff program, or groff. groff is a troff interpreter that converts the troff code to Postscript. In order to apply the command, you first have to locate the man page you want to convert. On my system, most of the man pages are located in /usr/share/man. Let’s say we want to convert the file nmap.1 into Postscript. We would use a command like this:


groff -man /usr/share/man/man1/nmap.1 > nmap.ps

The -man option tells groff to run the code through the man macro package, which is the macro package used for man pages, before sending its output to the Postscript file.

Now we have a Postscript file, which is fairly easy to convert to a PDF. Many document viewing programs (such as Apple Preview) will automatically convert a Postscript file to a PDF when you open it. Alternatively, if you just want a hard copy, you can skip the PDF and send the Postscript file directly to a printer using the lp command. The only requirement is that it must be a Postscript printer, which the majority of printers on the market nowadays are.

Setting up an Apache HTTP server

Through some config file hacking, I have managed to set up an Apache HTTP server on my Macbook.  I did this so that I could test the full functionality of PHP.  Since PHP is one of the top most needed skills for freelance coding jobs, I figured it would be a good idea to learn it, and of course to use any of the features of PHP beyond just the core language, you need a web server.

Starting the Apache server is pretty easy.  All you have to do is type sudo httpd at the command line (assuming Apache is installed on your system, which I think it is for most Unix-based systems). It is recommended that you use apachectl as a frontend instead of using httpd directly, but I couldn’t seem to get this to work, so to start Apache I use sudo httpd and to stop it I use sudo killall httpd.

Now configuring the server to use PHP was somewhat more difficult, though still not too much so. First of all, for a server to use PHP, the PHP DOS initialization file needs to be present as /usr/local/lib/php.ini. After some digging around, I found the PHP ini file at etc/php.ini.default, so I just copied it (changing the filename of course).

The next thing I had to do was tell Apache to load the PHP module at startup. This is done by editing the file /etc/apache2/httpd.conf and uncommenting the appropriate code line.  It must be remembered that editing this file requires root privileges.

httpd.conf-uncomment

The appropriate line is


LoadModule php5_module libexec/apache2/libphp5.so

…Shown here already uncommented.

The next thing you have to do is find out what directory Apache is using to serve files to clients. This is determined by the DocumentRoot environment variable, and controlled by a <Directory> tag.

http.conf-root

Here we see that the server’s filesystem is rooted at /Library/WebServer/Documents. Of course this is Mac-specific, and the root will be different on other systems, and we can also change it, though I felt no need to.

If you title a document “index.html”, “index.php”, etc. then this will be the file that the client goes to when the user types your domain name without appending a path at the end. Also, if you title a document, say, my-pictures.html, the file extension can be omitted in the URL.

Apology

I would like to apologize for not posting for the last month and a half.  I was in the loony bin, and then there was a major heat wave which kept me in the house and away from any wireless networks, and those and other factors have led me to stop posting for a while.  Well, I’m back, and I hope to start posting on a regular basis again.

Some hacking – Using Keka to import data from OS X to my VMs

Ever since I started using VirtualBox, I have needed a way to get data from my host operating system (Mac OS X) to the guests. This data includes drivers that I want to install in the guest, and programs and games that I want to run in the guest.

Sure there’s Guest Additions, but that has its own problems. For one thing, it only works with Mac, Windows, and Linux guests; there’s no drag-and-drop feature for things like DOS. Secondly, it requires the guest to have Internet access so you can install the guest addition drivers; if I have Internet access, then all I need to do is just email the files to myself in the host and download them in the guest. So basically, guest additions are merely a convenience that makes the already possible more practical; they do not enable you to do anything you couldn’t do before.

I realized my best bet for guests that either don’t have networking drivers installed or aren’t in the Mac/Windows/Linux category would be to find a way to turn the directories in my OS X filesystem into disk images, either floppy images or ISO files, so I could then insert them into the virtual drives of my VMs. I found a utility called Keka, which can be downloaded here. Keka is a file compression, extraction, and archiving utility for OS X. It can archive or compress files in several formats, and it can extract even more formats. Formats it creates include zip, gzip, bzip2, 7zip, tar, DMG, and ISO.

Keka

Though it is a graphical program, the interface for Keka isn’t particularly intuitive. It allows you to select a format to archive a directory to, but gives no indication of how to select a directory for archiving.  Through wild guesswork I discovered that you can do this by dragging the icon for the directory into the Keka window, after which it will automatically create an archive in the selected format.  Who knew?

The next step is of course to insert the newly created ISO into my virtual machines.  I can only do this with VMs that recognize optical disks, obviously, so MS-DOS 5.0 doesn’t work.  However, I was able to import Deluxe Paint into my FreeDOS VM.  I’m in the process of trying to import Norton Commander.

Storage

As an experiment, I tried converting some of the DOS folders to ISO files and using them to install software directly, as if they were floppies.  This didn’t work, because the installers require the disk to be mounted on drive A.  Obviously I wouldn’t be able to just change the extension, because it would still have the ISO-9660 filesystem, rather than the FAT filesystem, and it wouldn’t be recognized as a floppy.

Yeah, I kinda figured that wouldn’t work.

I’ve also tried using some software and games in VMs that I’m running on live ISOs, but there were some problems.  First, VirtualBox only allows for one optical drive.  You can work around this limitation by adding a USB drive and telling the VM to treat it as an optical drive, but when I did this, the VM tried to boot from the wrong ISO.  Maybe I should select the “Live CD/DVD” option.

Homebrew – “the missing package manager for OS X”

I made a pretty neat discovery recently. There’s this package manager for Mac OS X called Homebrew that allows you to install Unix packages from the command line, using the brew command. It’s patched together from Ruby scripts and shell scripts and uses git as a backend. You can install it on Mac OS X using the following command:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

This is much better than using apt-get in Mac OS X (now no longer an option), where it would barf because I didn’t have the XCode command line tools, but it would provide no indication of how to get said tools. That script installs the XCode tools automatically if they’re not there. It’s also better than manually compiling code from source, which can be a major pain the ass, especially when you run into dependency issues (which is more often than not the case).

Homebrew is very similar to apt-get in its command structure. For example, here is how you install a package:

brew install lynx

There are several other Homebrew commands worth remembering. For example:

brew edit lynx

This opens the source code for the installer script for the package in the default text editor.

Also:

  • remove – uninstalls a package
  • list – lists installed packages
  • search – lists currently available packages
  • update – updates a package

All of these have the same command structure: brew <command> <package>.

I’ve installed several packages so far. I will list them here:

  • Lynx – the text-mode browser
  • Snownews – an RSS feed aggregator for the CLI
  • Bitchx – a text-based IRC client
  • NASM – an x86 assembler
  • wget – allows you to download files from the command line
  • CLISP – Command Lisp compiler, interpreter, and REPL

This is an exciting discovery. Now I can use all my favorite Linux software in Mac OS X!

Retro game review: Super Stupid Space Invaders

This was a game I discovered on dosgames.com.  It’s based on the classic Space Invaders arcade game, except it’s text-based and runs on MS-DOS.  I  downloaded it and started playing it in DOSBox.  First, the stats:

Creator: PLBM Games
Year: 1997
Graphics mode: ASCII
Download link: http://www.dosgames.com/dl.php?filename=http://www.dosgames.com/files/sssi.zip

I found this game to be extremely entertaining and fun to play. It’s a fast-paced game with exciting text-mode graphics and good-old 8-bit sounds. This is a game that truly brings me back to the 90’s and my older brother’s Apple ][c.

In this game there are two players. The players take turns fighting waves of aliens. You have multiple ships in this game, so if your ship gets destroyed, the game isn’t automatically over. For a game titled “Super Stupid Space Invaders” and deemed a “not-serious” game by its creators, this game is actually fairly complex, interesting, and well-written.

Here is a screenshot of the first level. This level looks basically like your typical arcade Space Invaders, except without the shields:

204567-super-stupid-space-invaders-dos-screenshot-got-one

Here is a screenshot of the second level, or wave:

204570-super-stupid-space-invaders-dos-screenshot-i-guess-this-is

In this level, you have one space invader, and when you hit it, it splits into two more, those split into two more, and finally those each split into two more, so in the end you have sixteen invaders to contend with, and they all move very quickly – not just side-to-side but also up and down. This makes for very challenging game play.

All in all, I love this game. In fact I can’t think of anything not to love about it. It’s a fun game to play, and it brings me back to the good old days, and that’s why I love it.