Programming in Plato’s Cave 183 LS(1) Unix Programmer's Manual LS(1) NAME ls - list contents of directory SYNOPSIS ls [ -acdfgilqrstu1ACLFR ] name ... DESCRIPTION For each directory argument, ls lists the contents of the directory for each file argument, ls repeats its name and any other information requested. By default, the output is sorted alphabetically. When no argument is given, the current directory is listed. When several arguments are given, the arguments are first sorted appropriately, but file arguments are processed before directories and their contents. There are a large number of options: [...] BUGS Newline and tab are considered printing characters in file names. The output device is assumed to be 80 columns wide. The option setting based on whether the output is a teletype is undesirable as “ls -s” is much different than “ls -s | lpr”. On the other hand, not doing this setting would make old shell scripts which used ls almost certain losers. A game that you can play while reading man pages is to look at the BUGS section and try to imagine how each bug could have come about. Take this example from the shell’s man page:

184 Programming SH(1) Unix Programmer's Manual SH(1) NAME sh, for, case, if, while, :, ., break, continue, cd, eval, exec, exit, export, login, read, readonly, set, shift, times, trap, umask, wait - command language SYNOPSIS sh [ -ceiknrstuvx ] [ arg ] ... DESCRIPTION Sh is a command programming language that executes commands read from a terminal or a file. See invocation for the meaning of arguments to the shell. [...] BUGS If is used to provide standard input to an asynchronous process invoked by &, the shell gets mixed up about naming the input document. A garbage file /tmp/sh* is created, and the shell complains about not being able to find the file by another name. We spent several minutes trying to understand this BUGS section, but we couldn’t even figure out what the hell they were talking about. One Unix expert we showed this to remarked, “As I stared at it and scratched my head, it occurred to me that in the time it must have taken to track down the bug and write the BUGS entry, the programmer could have fixed the damn bug.” Unfortunately, fixing a bug isn’t enough because they keep coming back every time there is a new release of the OS. Way back in the early 1980s, before each of the bugs in Unix had such a large cult following, a programmer at BBN actually fixed the bug in Berkeley’s make that requires starting rule lines with tab characters instead of any whitespace. It wasn’t a hard fix—just a few lines of code. Like any group of responsible citizens, the hackers at BBN sent the patch back to Berkeley so the fix could be incorporated into the master Unix sources. A year later, Berkeley released a new version of Unix with the make bug still there. The BBN hackers fixed the bug a second time, and once again sent the patch back to Berkeley.