| blob | c8f684c01e51248fdaa4ae04c6d1a2d6d5f807c5 |
1 '\" t
2 .ig
3 roff.man
5 Last update: 02 Feb 2007
7 This file is part of groff, the GNU roff type-setting system.
9 Copyright (C) 2000, 2001, 2002, 2003, 2004, 2006, 2007
10 Free Software Foundation, Inc.
11 written by Bernd Warken <bwarken@mayn.de>
12 maintained by Werner Lemberg <wl@gnu.org>
14 Permission is granted to copy, distribute and/or modify this document
15 under the terms of the GNU Free Documentation License, Version 1.1 or
16 any later version published by the Free Software Foundation; with the
17 Invariant Sections being this .ig-section and AUTHORS, with no
18 Front-Cover Texts, and with no Back-Cover Texts.
20 A copy of the Free Documentation License is included as a file called
21 FDL in the main directory of the groff source package.
22 ..
23 .
24 .
25 .\" --------------------------------------------------------------------
26 .\" Local macros
27 .
28 .de Esc
29 . ds @1 \\$1
30 . shift
31 . nop \f[B]\[rs]\\*[@1]\f[]\\$*
32 . rm @1
33 ..
34 .
35 .
36 .de QuotedChar
37 . ds @1 \\$1
38 . shift
39 . nop `\f[B]\\*[@1]\f[]'\\$*
40 . rm @1
41 ..
42 .
43 .
44 .\" --------------------------------------------------------------------
45 .\" Title
46 .\" --------------------------------------------------------------------
47 .
48 .TH ROFF @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
49 .SH NAME
50 roff \- concepts and history of roff typesetting
51 .
52 .
53 .\" --------------------------------------------------------------------
54 .SH DESCRIPTION
55 .\" --------------------------------------------------------------------
56 .
57 .I roff
58 is the general name for a set of type-setting programs, known under
59 names like
60 .BR troff ,
61 .BR nroff ,
62 .BR ditroff ,
63 .BR groff ,
64 etc.
65 .
66 A
67 .I roff
68 type-setting system consists of an extensible text formatting language
69 and a set of programs for printing and converting to other text
70 formats.
71 .
72 Traditionally, it is the main text processing system of Unix; every
73 Unix-like operating system still distributes a
74 .I roff
75 system as a core package.
76 .
77 .P
78 The most common
79 .I roff
80 system today is the free software implementation \f[CR]GNU\f[]
81 .IR roff ",
82 .BR groff (@MAN1EXT@).
83 .
84 The
85 .RI pre- groff
86 implementations are referred to as
87 .I classical
88 (dating back as long as 1973).
89 .
90 .I groff
91 implements the look-and-feel and functionality of its classical
92 ancestors, but has many extensions.
93 .
94 .P
95 In some ancient Unix systems, there was a binary called
96 .B roff
97 that implemented the even more ancient
98 .B runoff
99 of the
100 .I Multics
101 operating system, cf.\& section
102 .BR HISTORY .
103 The functionality of this program was very restricted even in
104 comparison to ancient
105 .IR troff ;
106 it is not supported any longer.
107 .
108 Consequently, in this document, the term
109 .I roff
110 always refers to the general meaning of
111 .IR "roff system" ,
112 not to the ancient
113 .B roff
114 binary.
115 .
116 .P
117 In spite of its age,
118 .I roff
119 is in wide use today, for example, the manual pages on UNIX systems
120 .RI ( man\~pages\/ ),
121 many software books, system documentation, standards, and corporate
122 documents are written in roff.
123 .
124 The
125 .I roff
126 output for text devices is still unmatched, and its graphical output
127 has the same quality as other free type-setting programs and is better
128 than some of the commercial systems.
129 .
130 .P
131 The most popular application of
132 .I roff
133 is the concept of
134 .IR "manual pages" ,
135 or shortly
136 .IR "man pages" ;
137 this is the standard documentation system on many operating systems.
138 .
139 .P
140 This document describes the historical facts around the development
141 of the
142 .IR "roff system" ;
143 some usage aspects common to all
144 .I roff
145 versions, details on the
146 .I roff
147 pipeline, which is usually hidden behind front-ends like
148 .BR groff (@MAN1EXT@);
149 a general overview of the formatting language; some tips for editing
150 .I roff
151 files; and many pointers to further readings.
152 .
153 .
154 .\" --------------------------------------------------------------------
155 .SH "HISTORY"
156 .\" --------------------------------------------------------------------
157 .
158 The
159 .I roff
160 text processing system has a very long history, dating back to the
161 1960s.
162 .
163 The
164 .I roff
165 system itself is intimately connected to the Unix operating system,
166 but its roots go back to the earlier operating systems CTSS and
167 Multics.
168 .
169 .
170 .\" --------------------------------------------------------------------
171 .SS "The Predecessor RUNOFF"
172 .\" --------------------------------------------------------------------
173 .
174 .P
175 The evolution of
176 .I roff
177 is intimately related to the history of the operating systems.
178 .
179 Its predecessor
180 .B RUNOFF
181 was written by
182 .I Jerry Saltzer
183 for the
184 .I CTSS
185 operating system
186 .RI ( "Compatible Time Sharing System" )
187 as early as 1964 \[en] note that CTSS commands were all uppercase.
188 .
189 When CTSS was further developed into the operating system
190 .UR http://\:www.multicians.org
191 Multics
192 .UE ,
193 the famous predecessor of Unix from 1963,
194 .I runoff
195 has been improved further by people from the Massachusetts Institute of
196 Technology (MIT) and the Bell Technical Laboratory (BTL), including Dennis
197 Ritchie and Joe Ossanna.
198 .
199 .BR "Multics runoff" ,
200 for example, was now able to do two-pass operations; it became the main
201 format for documentation and text processing.
202 .
203 Both operating systems could only be run on very expensive computers
204 at that time, so they were mostly used in research and for official
205 and military tasks.
206 .
207 .P
208 The possibilities of the
209 .I runoff
210 language were quite limited as compared to modern
211 .IR roff .
212 .
213 Only text output was possible in the 1960s.
214 .
215 This could be implemented by a set of requests of length\~2, many of
216 which are still identically used in
217 .IR roff .
218 .
219 The language was modelled according to the habits of typesetting in
220 the pre-computer age, where lines starting with a dot were used in
221 manuscripts to denote formatting requests to the person who would
222 perform the typesetting manually later on.
223 .
224 .P
225 The runoff program was written in the
226 .I MAD
227 language first, later on in
228 .IR BCPL ,
229 the grandmother of the
230 .IR C \~\c
231 programming language.
232 .
233 In the Multics operating system, the help system was handled by
234 runoff, similar to
235 .IR roff 's
236 task to manage the Unix manual pages.
237 .
238 On the other hand, BCPL and runoff were ported to the GCOS system
239 at Bell Labs since BTL left the development of Multics.
240 .
241 .P
242 There are still documents written in the RUNOFF language; for examples
243 see Saltzer's home page, cf.\& section
244 .BR "SEE ALSO" .
245 .
246 .
247 .\" --------------------------------------------------------------------
248 .SS "The Classical nroff/troff System"
249 .\" --------------------------------------------------------------------
250 .
251 At the Bell Labs, there was a need to
252 drive the Wang
253 .I Graphic Systems CAT
254 typesetter, a graphical output device from a PDP-11 computer running
255 Unix.
256 .
257 As runoff was too limited for this task it was further developed into
258 a more powerful text formatting system by
259 .IR "Josef F. Osanna" ,
260 who already programmed several runoff ports.
261 .
262 .P
263 The name
264 .I runoff
265 was shortened to
266 .IR roff .
267 The greatly enlarged language of Osanna's concept included already all
268 elements of a full
269 .IR "roff system" .
270 .
271 All modern
272 .I roff
273 systems try to implement compatibility to this system.
274 .
275 So Joe Osanna can be called the father of all
276 .I roff
277 systems.
278 .
279 .P
280 This first
281 .I roff system
282 had three formatter programs.
283 .
284 .TP
285 .B troff
286 .RI ( "typesetter roff\/" )
287 generated a graphical output for the
288 .I CAT
289 typesetter as its only device.
290 .
291 .TP
292 .B nroff
293 produced text output suitable for terminals and line printers.
294 .
295 .TP
296 .B roff
297 was the reimplementation of the former
298 .B runoff
299 program with its limited features; this program was abandoned in later
300 versions.
301 .
302 Today, the name
303 .I roff
304 is used to refer to a
305 .I troff/\:nroff
306 sytem as a whole.
307 .
308 .P
309 Osanna's first version was written in the PDP-11 assembly language and
310 released in 1973.
311 .
312 .I Brian Kernighan
313 joined the
314 .I roff
315 development by rewriting it in the C\~programming language.
316 .
317 The C\~version was released in 1975.
318 .
319 .P
320 The syntax of the formatting language of the
321 .BR nroff / troff
322 programs was documented in the famous
323 .IR "Troff User's Manual [CSTR\~#54]" ,
324 first published in 1976, with further revisions up to 1992 by Brian
325 Kernighan.
326 .
327 This document is the specification of the
328 .IR "classical troff" .
329 All later
330 .I roff
331 systems tried to establish compatibility with this specification.
332 .
333 .P
334 After Osanna had died in 1977 by a heart-attack at the age of about\~50,
335 Kernighan went on with developing
336 .IR troff .
337 .
338 The next milestone was to equip
339 .I troff
340 with a general interface to support more devices, the intermediate
341 output format and the postprocessor system.
342 .
343 This completed the structure of a
344 .I "roff system"
345 as it is still in use today; see section
346 .BR "USING ROFF" .
347 .
348 In 1979, these novelties were described in the paper
349 .IR "[CSTR\~#97]" .
350 This new
351 .I troff
352 version is the basis for all existing newer
353 .I troff
354 systems, including
355 .IR groff .
356 .
357 On some systems, this
358 .I device independent troff
359 got a binary of its own, called
360 .BR ditroff (@MAN7EXT@).
361 .
362 All modern
363 .B troff
364 programs already provide the full
365 .B ditroff
366 capabilities automatically.
367 .
368 .
369 .\" --------------------------------------------------------------------
370 .SS "Commercialization"
371 .\" --------------------------------------------------------------------
372 .
373 A major degradation occurred when the easily available Unix\~7
374 operating system was commercialized.
375 .
376 A whole bunch of divergent operating systems emerged, fighting each
377 other with incompatibilities in their extensions.
378 .
379 Luckily, the incompatibilities did not fight the original
380 .IR troff .
381 .
382 All of the different commercial
383 .I roff
384 systems made heavy use of Osanna/\:Kernighan's open source code and
385 documentation, but sold them as \[lq]their\[rq] system \[en] with only
386 minor additions.
387 .
388 .P
389 The source code of both the ancient Unix and classical
390 .I troff
391 weren't available for two decades.
392 .
393 Fortunately, Caldera bought SCO UNIX in 2001.
394 .
395 In the following, Caldera made the ancient source code accessible
396 on-line for non-commercial use, cf. section
397 .BR "SEE ALSO" .
398 .
399 .
400 .\" --------------------------------------------------------------------
401 .SS "Free roff"
402 .\" --------------------------------------------------------------------
403 .
404 The most important free
405 .I roff
406 project was the \f[CR]GNU\f[] implementation of
407 .IR troff ,
408 written from scratch by James Clark and put under the
409 .UR http://\:www.gnu.org/\:copyleft
410 GNU Public License
411 .UE .
412 .
413 It was called
414 .I groff
415 (\f[CR]GNU\f[]
416 .IR roff ).
417 See
418 .BR groff (@MAN1EXT@)
419 for an overview.
420 .
421 .P
422 The
423 .I groff
424 system is still actively developed.
425 .
426 It is compatible to the classical
427 .IR troff ,
428 but many extensions were added.
429 .
430 It is the first
431 .I roff
432 system that is available on almost all operating systems \[en] and it
433 is free.
434 .
435 This makes
436 .I groff
437 the de-facto
438 .I roff
439 standard today.
440 .
441 .P
442 An alternative is Gunnar Ritter's
443 .UR http://\:heirloom.sf.net
444 Heirloom Documentation Tools
445 .UE
446 project, started in 2005, which provides enhanced versions of the various
447 roff tools found in the OpenSolaris and Plan\~9 operating systems, now
448 available under free licenses.
449 .
450 .
451 .\" --------------------------------------------------------------------
452 .SH "USING ROFF"
453 .\" --------------------------------------------------------------------
454 .
455 Most people won't even notice that they are actually using
456 .IR roff .
457 .
458 When you read a system manual page (man page)
459 .I roff
460 is working in the background.
461 .
462 .I roff
463 documents can be viewed with a native viewer called
464 .BR \%xditview (1x),
465 a standard program of the X window distribution, see
466 .BR X (7x).
467 .
468 But using
469 .I roff
470 explicitly isn't difficult either.
471 .
472 .P
473 Some
474 .I roff
475 implementations provide wrapper programs that make it easy to use the
476 .I roff
477 system on the shell command line.
478 .
479 For example, the \f[CR]GNU\f[]
480 .I roff
481 implementation
482 .BR groff (@MAN1EXT@)
483 provides command line options to avoid the long command pipes of
484 classical
485 .IR troff ;
486 a program
487 .BR grog (@MAN1EXT@)
488 tries to guess from the document which arguments should be used for a
489 run of
490 .BR groff ;
491 people who do not like specifying command line options should try the
492 .BR groffer (@MAN1EXT@)
493 program for graphically displaying
494 .I groff
495 files and man pages.
496 .
497 .
498 .\" --------------------------------------------------------------------
499 .SS "The roff Pipe"
500 .\" --------------------------------------------------------------------
501 .
502 Each
503 .I roff
504 system consists of preprocessors,
505 .I roff
506 formatter programs, and a set of device postprocessors.
507 .
508 This concept makes heavy use of the
509 .I piping
510 mechanism, that is, a series of programs is called one after the other,
511 where the output of each program in the queue is taken as the input
512 for the next program.
513 .
514 .RS
515 .P
516 cat \f[I]file\f[P] \
517 | .\|.\|. \
518 | \f[I]preproc\f[P] \
519 | .\|.\|. \
520 | troff \f[I]options\f[P] \
521 | \f[I]postproc\f[P]
522 .RE
523 .
524 .P
525 The preprocessors generate
526 .I roff
527 code that is fed into a
528 .I roff
529 formatter (e.g.\&
530 .BR troff ),
531 which in turn generates
532 .I intermediate output
533 that is fed into a device postprocessor program for printing or final
534 output.
535 .
536 .P
537 All of these parts use programming languages of their own; each
538 language is totally unrelated to the other parts.
539 .
540 Moreover,
541 .I roff
542 macro packages that were tailored for special purposes can be
543 included.
544 .
545 .P
546 Most
547 .I roff
548 documents use the macros of some package, intermixed with code for one
549 or more preprocessors, spiced with some elements from the plain
550 .I roff
551 language.
552 .
553 The full power of the
554 .I roff
555 formatting language is seldom needed by users; only programmers of
556 macro packages need to know about the gory details.
557 .
558 .
559 .
560 .\" --------------------------------------------------------------------
561 .SS "Preprocessors"
562 .\" --------------------------------------------------------------------
563 .
564 A
565 .I roff
566 preprocessor is any program that generates output that syntactically
567 obeys the rules of the
568 .I roff
569 formatting language.
570 .
571 Each preprocessor defines a language of its own that is translated
572 into
573 .I roff
574 code when run through the preprocessor program.
575 .
576 Parts written in these languages may be included within a
577 .I roff
578 document; they are identified by special
579 .I roff
580 requests or macros.
581 .
582 Each document that is enhanced by preprocessor code must be run
583 through all corresponding preprocessors before it is fed into the
584 actual
585 .I roff
586 formatter program, for the formatter just ignores all alien code.
587 .
588 The preprocessor programs extract and transform only the document
589 parts that are determined for them.
590 .
591 .P
592 There are a lot of free and commercial
593 .I roff
594 preprocessors.
595 .
596 Some of them aren't available on each system, but there is a small
597 set of preprocessors that are considered as an integral part of each
598 .I roff
599 system.
600 .
601 The classical preprocessors are
602 .
603 .RS
604 .TS
605 tab (@);
606 lb l.
607 tbl@for tables.
608 eqn@for mathematical formul\[ae].
609 pic@for drawing diagrams.
610 refer@for bibliographic references.
611 soelim@for including macro files from standard locations.
612 chem@for drawing chemical formul\[ae].
613 .TE
614 .RE
615 .
616 .P
617 Other known preprocessors that are not available on all systems
618 include
619 .
620 .RS
621 .TS
622 tab (@);
623 lb l.
624 grap@for constructing graphical elements.
625 grn@for including \fBgremlin\fR(1) pictures.
626 .TE
627 .RE
628 .
629 .\" --------------------------------------------------------------------
630 .SS "Formatter Programs"
631 .\" --------------------------------------------------------------------
632 .
633 A
634 .I roff formatter
635 is a program that parses documents written in the
636 .I roff
637 formatting language or uses some of the
638 .I roff
639 macro packages.
640 .
641 It generates
642 .IR "intermediate output" ,
643 which is intended to be fed into a single device postprocessor that
644 must be specified by a command-line option to the formatter program.
645 .
646 The documents must have been run through all necessary preprocessors
647 before.
648 .
649 .P
650 The output produced by a
651 .I roff
652 formatter is represented in yet another language, the
653 .IR "intermediate output format"
654 or
655 .IR "troff output" .
656 This language was first specified in
657 .IR "[CSTR\~#97]" ;
658 its \f[CR]GNU\f[] extension is documented in
659 .BR groff_out (@MAN5EXT@).
660 .
661 The intermediate output language is a kind of assembly language
662 compared to the high-level
663 .I roff
664 language.
665 .
666 The generated intermediate output is optimized for a special device,
667 but the language is the same for every device.
668 .
669 .P
670 The
671 .I roff
672 formatter is the heart of the
673 .I roff
674 system.
675 .
676 The traditional
677 .I roff
678 had two formatters,
679 .B nroff
680 for text devices and
681 .B troff
682 for graphical devices.
683 .
684 .P
685 Often, the name
686 .I troff
687 is used as a general term to refer to both formatters.
688 .
689 .
690 .\" --------------------------------------------------------------------
691 .SS "Devices and Postprocessors"
692 .\" --------------------------------------------------------------------
693 .
694 Devices are hardware interfaces like printers, text or graphical
695 terminals, etc., or software interfaces such as a conversion into a
696 different text or graphical format.
697 .
698 .P
699 A
700 .I roff
701 postprocessor is a program that transforms
702 .I troff
703 output into a form suitable for a special device.
704 .
705 The
706 .I roff
707 postprocessors are like device drivers for the output target.
708 .
709 .P
710 For each device there is a postprocessor program that fits the device
711 optimally.
712 .
713 The postprocessor parses the generated intermediate output and
714 generates device-specific code that is sent directly to the device.
715 .
716 .P
717 The names of the devices and the postprocessor programs are not fixed
718 because they greatly depend on the software and hardware abilities of
719 the actual computer.
720 .
721 For example, the classical devices mentioned in
722 .I [CSTR\~#54]
723 have greatly changed since the classical times.
724 .
725 The old hardware doesn't exist any longer and the old graphical
726 conversions were quite imprecise when compared to their modern
727 counterparts.
728 .
729 .P
730 For example, the Postscript device
731 .I post
732 in classical
733 .I troff
734 had a resolution of 720, while
735 .IR groff 's
736 .I ps
737 device has 72000, a refinement of factor 100.
738 .
739 .P
740 Today the operating systems provide device drivers for most
741 printer-like hardware, so it isn't necessary to write a special
742 hardware postprocessor for each printer.
743 .
744 .
745 .\" --------------------------------------------------------------------
746 .SH "ROFF PROGRAMMING"
747 .\" --------------------------------------------------------------------
748 .
749 Documents using
750 .I roff
751 are normal text files decorated by
752 .I roff
753 formatting elements.
754 .
755 The
756 .I roff
757 formatting language is quite powerful; it is almost a full programming
758 language and provides elements to enlarge the language.
759 .
760 With these, it became possible to develop macro packages that are
761 tailored for special applications.
762 .
763 Such macro packages are much handier than plain
764 .IR roff .
765 .
766 So most people will choose a macro package without worrying about the
767 internals of the
768 .I roff
769 language.
770 .
771 .
772 .\" --------------------------------------------------------------------
773 .SS "Macro Packages"
774 .\" --------------------------------------------------------------------
775 .
776 Macro packages are collections of macros that are suitable to format a
777 special kind of documents in a convenient way.
778 .
779 This greatly eases the usage of
780 .IR roff .
781 .
782 The macro definitions of a package are kept in a file called
783 .IB name .tmac
784 (classically
785 .BI tmac. name\c
786 ).
787 .
788 All tmac files are stored in one or more directories at standardized
789 positions.
790 .
791 Details on the naming of macro packages and their placement is found
792 in
793 .BR groff_tmac (@MAN5EXT@).
794 .
795 .P
796 A macro package that is to be used in a document can be announced to
797 the formatter by the command line option
798 .BR \-m ,
799 see
800 .BR troff (@MAN1EXT@),
801 or it can be specified within a document using the file inclusion
802 requests of the
803 .I roff
804 language, see
805 .BR groff (@MAN7EXT@).
806 .
807 .P
808 Famous classical macro packages are
809 .I man
810 for traditional man pages,
811 .I mdoc
812 for \f[CR]BSD\f[]-style manual pages;
813 the macro sets for books, articles, and letters are
814 .I me
815 (probably from the first name of its creator
816 .I Eric
817 Allman),
818 .I ms
819 (from
820 .IR "Manuscript Macros\/" ),
821 and
822 .I mm
823 (from
824 .IR "Memorandum Macros\/" ).
825 .
826 .
827 .\" --------------------------------------------------------------------
828 .SS "The roff Formatting Language"
829 .\" --------------------------------------------------------------------
830 .
831 The classical
832 .I roff
833 formatting language is documented in the
834 .I Troff User's Manual
835 .IR "[CSTR\~#54]" .
836 .
837 The
838 .I roff
839 language is a full programming language providing requests, definition
840 of macros, escape sequences, string variables, number or size
841 registers, and flow controls.
842 .
843 .P
844 .I Requests
845 are the predefined basic formatting commands similar to the commands
846 at the shell prompt.
847 .
848 The user can define request-like elements using predefined
849 .I roff
850 elements.
851 .
852 These are then called
853 .IR macros .
854 .
855 A document writer will not note any difference in usage for requests
856 or macros; both are written on a line on their own starting with a dot.
857 .
858 .P
859 .I Escape sequences
860 are
861 .I roff
862 elements starting with a backslash
863 .QuotedChar \[rs] .
864 They can be inserted anywhere, also in the midst of text in a line.
865 .
866 They are used to implement various features, including the insertion of
867 non-\f[CR]ASCII\f[] characters with
868 .Esc ( ,
869 font changes with
870 .Esc f ,
871 in-line comments with
872 .Esc \[dq] ,
873 the escaping of special control characters like
874 .Esc \[rs] ,
875 and many other features.
876 .
877 .P
878 .I Strings
879 are variables that can store a string.
880 .
881 A string is stored by the
882 .B .ds
883 request.
884 .
885 The stored string can be retrieved later by the
886 .B \[rs]*
887 escape sequence.
888 .
889 .P
890 .I Registers
891 store numbers and sizes.
892 .
893 A register can be set with the request
894 .B .nr
895 and its value can be retrieved by the escape sequence
896 .BR "\[rs]n" .
897 .
898 .
899 .\" --------------------------------------------------------------------
900 .SH "FILE NAME EXTENSIONS"
901 .\" --------------------------------------------------------------------
902 .
903 Manual pages (man pages) take the section number as a file name
904 extension, e.g., the filename for this document is
905 .IR roff.7 ,
906 i.e., it is kept in section\~7
907 of the man pages.
908 .
909 .P
910 The classical macro packages take the package name as an extension, e.g.\&
911 .IB file. me
912 for a document using the
913 .I me
914 macro package,
915 .IB file. mm
916 for
917 .IR mm ,
918 .IB file. ms
919 for
920 .IR ms ,
921 .IB file. pic
922 for
923 .I pic
924 files,
925 etc.
926 .
927 .P
928 But there is no general naming scheme for
929 .I roff
930 documents, though
931 .IB file. tr
932 for
933 .I troff file
934 is seen now and then.
935 .
936 Maybe there should be a standardization for the filename extensions of
937 .I roff
938 files.
939 .
940 .P
941 File name extensions can be very handy in conjunction with the
942 .BR less (1)
943 pager.
944 .
945 It provides the possibility to feed all input into a command-line pipe
946 that is specified in the shell environment variable
947 .BR LESSOPEN .
948 This process is not well documented, so here an example:
949 .
950 .RS
951 .P
952 .EX
953 LESSOPEN='|lesspipe %s'
954 .EE
955 .RE
956 .
957 .P
958 where
959 .B lesspipe
960 is either a system supplied command or a shell script of your own.
961 .
962 .
963 .\" --------------------------------------------------------------------
964 .SH "EDITING ROFF"
965 .\" --------------------------------------------------------------------
966 .
967 The best program for editing a
968 .I roff
969 document is Emacs (or Xemacs), see
970 .BR emacs (1).
971 It provides an
972 .I nroff
973 mode that is suitable for all kinds of
974 .I roff
975 dialects.
976 .
977 This mode can be activated by the following methods.
978 .
979 .P
980 When editing a file within Emacs the mode can be changed by typing
981 .RI ` "M-x nroff-mode" ',
982 where
983 .B M-x
984 means to hold down the
985 .B Meta
986 key (or
987 .BR Alt )
988 and hitting the
989 .BR x\~ key
990 at the same time.
991 .
992 .P
993 But it is also possible to have the mode automatically selected when
994 the file is loaded into the editor.
995 .
996 .IP \(bu
997 The most general method is to include the following 3 comment lines at
998 the end of the file.
999 .
1000 .RS
1001 .IP
1002 .EX
1003 \&.\[rs]" Local Variables:
1004 \&.\[rs]" mode: nroff
1005 \&.\[rs]" End:
1006 .EE
1007 .RE
1008 .
1009 .IP \(bu
1010 There is a set of file name extensions, e.g.\& the man pages that
1011 trigger the automatic activation of the
1012 .I nroff
1013 mode.
1014 .
1015 .IP \(bu
1016 Theoretically, it is possible to write the sequence
1017 .
1018 .RS
1019 .IP
1020 .EX
1021 \&.\[rs]" \%-*-\ nroff\ -*-
1022 .EE
1023 .RE
1024 .
1025 .IP
1026 as the first line of a file to have it started in
1027 .I nroff
1028 mode when loaded.
1029 .
1030 Unfortunately, some applications such as the
1031 .B man
1032 program are confused by this; so this is deprecated.
1033 .
1034 .P
1035 All
1036 .I roff
1037 formatters provide automated line breaks and horizontal and vertical
1038 spacing.
1039 .
1040 In order to not disturb this, the following tips can be helpful.
1041 .
1042 .IP \(bu
1043 Never include empty or blank lines in a
1044 .I roff
1045 document.
1046 .
1047 Instead, use the empty request (a line consisting of a dot only) or a
1048 line comment
1049 .B .\e"
1050 if a structuring element is needed.
1051 .
1052 .IP \(bu
1053 Never start a line with whitespace because this can lead to
1054 unexpected behavior.
1055 .
1056 Indented paragraphs can be constructed in a controlled way by
1057 .I roff
1058 requests.
1059 .
1060 .IP \(bu
1061 Start each sentence on a line of its own, for the spacing after a dot
1062 is handled differently depending on whether it terminates an
1063 abbreviation or a sentence.
1064 .
1065 To distinguish both cases, do a line break after each sentence.
1066 .
1067 .IP \(bu
1068 To additionally use the auto-fill mode in Emacs, it is best to insert
1069 an empty
1070 .I roff
1071 request (a line consisting of a dot only) after each sentence.
1072 .
1073 .P
1074 The following example shows how optimal
1075 .I roff
1076 editing could look.
1077 .
1078 .RS
1079 .P
1080 .EX
1081 This is an example for a
1082 \&.I roff
1083 document.
1084 \&.
1085 This is the next sentence in the same paragraph.
1086 \&.
1087 This is a longer sentence stretching over several
1088 lines; abbreviations like `cf.' are easily
1089 identified because the dot is not followed by a
1090 line break.
1091 \&.
1092 In the output, this will still go to the same
1093 paragraph.
1094 .EE
1095 .RE
1096 .
1097 .P
1098 Besides Emacs, some other editors provide
1099 .I nroff
1100 style files too, e.g.\&
1101 .BR vim (1),
1102 an extension of the
1103 .BR vi (1)
1104 program.
1105 .
1106 .
1107 .\" --------------------------------------------------------------------
1108 .SH BUGS
1109 .\" --------------------------------------------------------------------
1110 .
1111 .I UNIX\[rg]
1112 is a registered trademark of the Open Group.
1113 .
1114 But things have improved considerably after Caldera had bought SCO
1115 UNIX in 2001.
1116 .
1117 .
1118 .\" --------------------------------------------------------------------
1119 .SH "SEE ALSO"
1120 .\" --------------------------------------------------------------------
1121 .
1122 There is a lot of documentation on
1123 .IR roff .
1124 .
1125 The original papers on classical
1126 .I troff
1127 are still available, and all aspects of
1128 .I groff
1129 are documented in great detail.
1130 .
1131 .
1132 .\" --------------------------------------------------------------------
1133 .SS "Internet sites"
1134 .\" --------------------------------------------------------------------
1135 .
1136 .TP
1137 troff.org
1138 .UR http://\:www.troff.org
1139 The historical troff site
1140 .UE
1141 provides an overview and pointers to all historical aspects of
1142 .IR roff .
1143 .
1144 .TP
1145 Multics
1146 .UR http://\:www.multicians.org
1147 The Multics site
1148 .UE
1149 contains a lot of information on the MIT projects, CTSS, Multics,
1150 early Unix, including
1151 .IR runoff ;
1152 especially useful are a glossary and the many links to ancient
1153 documents.
1154 .
1155 .TP
1156 Unix Archive
1157 .UR http://\:www.tuhs.org/\:Archive/
1158 The Ancient Unixes Archive
1159 .UE
1160 .
1161 provides the source code and some binaries of the ancient Unixes
1162 (including the source code of
1163 .I troff
1164 and its documentation) that were made public by Caldera since 2001,
1165 e.g.\& of the famous Unix version\~7 for PDP-11 at the
1166 .UR http://\:www.tuhs.org/\:Archive/\:PDP-11/\:Trees/\:V7
1167 Unix V7 site
1168 .UE .
1169 .
1170 .TP
1171 Developers at AT&T Bell Labs
1172 .UR http://\:www.bell-labs.com/
1173 Bell Labs Computing and Mathematical Sciences Research
1174 .UE
1175 .
1176 provides a search facility for tracking information on the early
1177 developers.
1178 .
1179 .TP
1180 Plan 9
1181 .UR http://\:plan9.bell-labs.com
1182 The Plan\~9 operating system
1183 .UE
1184 .
1185 by AT&T Bell Labs.
1186 .
1187 .TP
1188 runoff
1189 .UR http://web.mit.edu/\:Saltzer/\:www/\:publications/\:pubs.html
1190 Jerry Saltzer's home page
1191 .UE
1192 .
1193 stores some documents using the ancient RUNOFF formatting language.
1194 .
1195 .TP
1196 CSTR Papers
1197 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr.html
1198 The Bell Labs CSTR site
1199 .UE
1200 .
1201 stores the original
1202 .I troff
1203 manuals (CSTR #54, #97, #114, #116, #122) and famous historical
1204 documents on programming.
1205 .
1206 .TP
1207 \f[CR]GNU\f[] \f[I]roff\f[]
1208 .UR http://\:www.gnu.org/\:software/\:groff
1209 The groff web site
1210 .UE
1211 provides the free
1212 .I roff
1213 implementation
1214 .IR groff ,
1215 the actual standard
1216 .IR roff .
1217 .
1218 .
1219 .\" --------------------------------------------------------------------
1220 .SS "Historical roff Documentation"
1221 .\" --------------------------------------------------------------------
1222 .
1223 Many classical
1224 .B troff
1225 documents are still available on-line.
1226 .
1227 The two main manuals of the
1228 .I troff
1229 language are
1230 .
1231 .TP
1232 [CSTR\~#54]
1233 J. F. Osanna,
1234 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:54.ps.gz
1235 .I "Nroff/\:Troff User's Manual"
1236 .UE ;
1237 .
1238 Bell Labs, 1976; revised by Brian Kernighan, 1992.
1239 .
1240 .TP
1241 [CSTR\~#97]
1242 Brian Kernighan,
1243 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:97.ps.gz
1244 .I "A Typesetter-independent TROFF"
1245 .UE ,
1246 .
1247 Bell Labs, 1981, revised March 1982.
1248 .
1249 .P
1250 The \[lq]little language\[rq]
1251 .I roff
1252 papers are
1253 .
1254 .TP
1255 [CSTR\~#114]
1256 Jon L. Bentley and Brian W. Kernighan,
1257 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:114.ps.gz
1258 .I "GRAP \[en] A Language for Typesetting Graphs"
1259 .UE ;
1260 .
1261 Bell Labs, August 1984.
1262 .
1263 .TP
1264 [CSTR\~#116]
1265 Brian W. Kernighan,
1266 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:116.ps.gz
1267 .I "PIC \[en] A Graphics Language for Typesetting"
1268 .UE ;
1269 .
1270 Bell Labs, December 1984.
1271 .
1272 .TP
1273 [CSTR\~#122]
1274 J. L. Bentley, L. W. Jelinski, and B. W. Kernighan,
1275 .UR http://\:cm.bell-labs.com/\:cm/\:cs/\:cstr/\:122.ps.gz
1276 .I "CHEM \[en] A Program for Typesetting Chemical Structure Diagrams,"
1277 .I "Computers and Chemistry"
1278 .UE ;
1279 .
1280 Bell Labs, April 1986.
1281 .
1282 .
1283 .\" --------------------------------------------------------------------
1284 .SS "Manual Pages"
1285 .\" --------------------------------------------------------------------
1286 .
1287 Due to its complex structure, a full
1288 .I roff
1289 system has many man pages, each describing a single aspect of
1290 .IR roff .
1291 .
1292 Unfortunately, there is no general naming scheme for the documentation
1293 among the different
1294 .I roff
1295 implementations.
1296 .
1297 .P
1298 In
1299 .IR groff ,
1300 the man page
1301 .BR groff (@MAN1EXT@)
1302 contains a survey of all documentation available in
1303 .IR groff .
1304 .
1305 .P
1306 On other systems, you are on your own, but
1307 .BR troff (1)
1308 might be a good starting point.
1309 .
1310 .
1311 .\" --------------------------------------------------------------------
1312 .SH AUTHORS
1313 .\" --------------------------------------------------------------------
1314 .
1315 Copyright (C) 2000, 2001, 2002, 2003, 2004, 2006, 2007
1316 Free Software Foundation, Inc.
1317 .
1318 .P
1319 This document is distributed under the terms of the \f[CR]FDL\f[]
1320 (\f[CR]GNU Free Documentation License\f[]) version 1.1 or later.
1321 .
1322 You should have received a copy of the \f[CR]FDL\f[] on your system,
1323 it is also available on-line at the
1324 .UR http://\:www.gnu.org/\:copyleft/\:fdl.html
1325 GNU copyleft site
1326 .UE .
1327 .
1328 .P
1329 This document is part of
1330 .IR groff ,
1331 the \f[CR]GNU\f[]
1332 .I roff
1333 distribution.
1334 .
1335 It was written by
1336 .MT bwarken@mayn.de
1337 Bernd Warken
1338 .ME ;
1339 it is maintained by
1340 .MT wl@gnu.org
1341 Werner Lemberg
1342 .ME .
1343 .
1344 .\" --------------------------------------------------------------------
1345 .\" Emacs setup
1346 .\" --------------------------------------------------------------------
1347 .
1348 .\" Local Variables:
1349 .\" mode: nroff
1350 .\" End: