IInneesssseennttiiaall ''rrooffff _J_o_h_n _H_a_w_k_i_n_s_o_n Student Information Processing Board Massachusetts Institute of Technology 84 Massachusetts Avenue Cambridge, Massachusetts 02139 _A_B_S_T_R_A_C_T This document provides a guide to using ttrrooffff, nnrrooffff, ggrrooffff, and similar variants on Athena. At MIT other document preparation systems have traditionally been used (TeX, Scribe, LaTeX, RUNOFF, ASCII text, FrameMaker). Despite general ignorance on the part of the community, it remains the dominant language for writing UNIX(R) documen- tation (man pages). The majority of documents in the Internet Engineering Task Force (IETF)'s Request For Com- ments (RFC) and Internet-Drafts serieses are authored in 'roff (although templates for LaTeX and Scribe are widely available). _R_e_v_i_s_i_o_n_s_: _u_s_e _\_f_B _i_n_s_t_e_a_d _o_f _._B _f_o_r _p_u_n_c_t_u_a_- _t_i_o_n_. 1 December 1996 IInneesssseennttiiaall ''rrooffff _J_o_h_n _H_a_w_k_i_n_s_o_n Student Information Processing Board Massachusetts Institute of Technology 84 Massachusetts Avenue Cambridge, Massachusetts 02139 11.. IInnttrroodduuccttiioonn [[mmaayybbee ppuutt iinn TTOOCC?? --eelllliioott]] 'roff is the classic UNIX typesetting system. A version comes with almost all UNIX variants, and they are generally compatible. For those systems without it, GNU ggrrooffff is available, written in C++. As typesetting systems go, 'roff is fairly lightweight and executes quickly. Many UNIX systems invoke it in real time to provide formatted documentation (man pages). Other typesetting packages (such as TeX and its derivatives) tend to be much slower and consume more resources. 'roff output conforms to well-defined standards, and can be used to produce output destined for high-quality typesetting devices, desktop PostScript printers, as well as CRT devices (such as the xterm program). Other applications prove the dominance of 'roff by including conversion pro- grams, such as Frame Technology's ttrrooffff22mmiiff program (dis- tributed with FrameMaker), or the mmss22hhttmmll program. 'roff can be used for more than just typesetting. Larry Wall, UNIX guru and author of ppaattcchh and ppeerrll has been known to post to Usenet nnrrooffff scripts to accomplish various tasks too difficult to perform in Perl. Try doing _t_h_a_t in LaTeX. 22.. SSccrriippttiinngg Umm, go look at the perl scripts that double as nroff? 33.. TThhee --mmaann MMaaccrrooss 44.. UUssiinngg EEMMAACCSS Emacs has a nnrrooffff--mmooddee to make editing 'roff files eas- ier. If you use the default Emacs setup on Athena, it will automatically invoked when you read in a file that ends with .mm, .me, .ms, .man, or .1 through .8 (for man pages). This mode provides features such as filling and indenting para- graphs properly, counting the actual number of lines in the document (with editing commands excluded), centering a line, -2- and hiliting. 55.. HHiissttoorriiccaall _A _T_R_O_F_F _T_u_t_o_r_i_a_l by Brian W. Kernighan states "ttrrooffff resembles an assembly language -- a remarkably powerful and flexible one." 66.. TToo--ddoo We need sections on -me, -ms, -mandoc, -man, scripting, using nroff for fillout forms, using RFC1543 RFC macros, and maybe something else (ideas?). Folks should volunteer. [perhaps also pic, tbl, eqn, and nroff emacs-mode -elliot] elliot has agreed to do the form-filling-out section, and -man/man pages, and emacs mode. Given that EZ depends heavily on nroff as its primary back end, a section on EZ interactions would be helpful. Since sometimes you get a document and it's not clear whether it's written for the -me or -ms macro sets, a triv- ial set of instructions on how to identify those would be nice. Using nroff as your default shell on athena might be interesting. Probably we'll need to create an nroff locker so that folks can have a path that's consistent on all plat- forms... How to do change bars in 'roff would be useful, since so very few people know how to do them properly in their document preparation system of choice. 77.. AAcckknnoowwlleeddggeemmeennttss We stole the text from lots of places. We cheated and used a PostScript figure. We used -ms macros.