Usenet 1994 January

home *** CD-ROM | disk | FTP | other *** search

/ Usenet 1994 January / usenetsourcesnewsgroupsinfomagicjanuary1994.iso / sources / misc / volume26 / wroff / part01 / doc / wroff.tut.w < prev

Wrap

Text File | 1991-12-11 | 15.7 KB | 657 lines

.fo \f0Bill Walker/page #/October 18, 1989\fP .ce 10 \fBWroff Tutorial\fP .ce 0 .sp 3 .in +5 .de PP .sp .ti +5 .en .de OP .sp .ti -5 .en .OP \fBIntroduction:\fP .ls 2 .PP "Wroff" is a general purpose text formatter, written in the spirit of Unix's \f2trademark of AT&T\fP \f1*roff\fP family. The purpose of this document is to make the reader able to use "wroff" for preparing documents. .PP Wroff has been specifically "tuned" to the Hewlett-Packard LaserJet II printer. Most of the system defaults will provide some reasonable output no matter \fBwhat\fP input is presented. The LaserJet can do \fBboldface\fP, \fUunderlining\fU, or even a \fB\fUcombination\fU\fP of the two. Wroff supports \fIitalics\fP as well. Wroff is aware that a page has 60 lines, and that a page should be printed with a left margin of 1 inch. (These can both be changed, of course.) .PP Wroff, when processing text, will space twice after periods, question marks, exclamation marks, and colons. .PP This document was prepared using\f1 wroff\fP. .ls 1 .bp .OP \fBEmbedded Commands:\fP .PP Wroff works by reading a text file, (created by using "vi" under Unix) and rearranging the contents of the file according to instructions which you give by "embedding" certain commands in the file. .PP An example of an embedded command would be this: .cc # #nf #in +5 .ce 3 These three lines should be centered on the page. #cc . .in -5 .fi The resulting output of wroff would be: .ce 3 These three lines should be centered on the page. .PP The three lines are centered as a result of the ".ce 3" command being embedded in the text. ".ce 3" means "center the next three lines." .PP This is an example of an embedded command. There are about forty such commands, most of which are not needed for ordinary work. An average document will require only two or three of the commands. The rest are present just to do "fancy stuff". .PP An embedded command is usually the only command on a line, and it usually starts with a period ("."). For this reason, embedded commands are often called "dot commands". It is unusual to want to actually begin a line with a period, so this works OK. If you have some reason for wanting to place a period at the first of a line (we did above in the example for ".ce"), there is a way to do it. .OP \fBModes:\fP .PP We need to explain the difference in "fill mode", and "non-fill" mode. .PP In "fill mode", wroff will pack as many words as possible on a line, no matter how you typed the lines in the original file. If you are in "non-fill" mode, the lines will appear in the output just the way you typed them in. Fill mode is usually "on", but you can turn it off with the command ".nf". If you want it back on, just use ".fi". Here is an example: .cc # #nf .nf These lines will appear in non-fill mode, just the way they were typed in. This is useful for making tables and other things that need to line up in a certain way. Here is the output that results: These lines will appear in non-fill mode, just the way they were typed in. This is useful for making tables and other things that need to line up in a certain way. #fi Here is the way things would look in fill mode. Here is the raw text: #nf .fi These lines will appear in fill mode, with the margins adjusted properly. This is the usual default for text, and so you can just omit the ".fi" if you want to. Here is the way they appear after processing by wroff: #fi #cc . These lines will appear in fill mode, with the margins adjusted properly. This is the usual default for text, and so you can just omit the ".fi" if you want to. .OP \fBjustify and non-justify modes:\fP .PP Sometimes we want to place as many words on a line as possible, but we do not want the right margins to be justified. For instance, you may be writing a business letter, and a ragged right margin gives sort of a "typed-by-hand" look to a paper. Use the commands ".ju" and ".nj" to turn right margin justification on and off. .PP Here is an example. In the text file, we enter: .nf .cc # .fi .nj These lines will appear with as many words on a line as possible, but with the right margin "ragged." This makes for a more "typed-by-hand" appearance, and is useful for correspondence. Here is the output: #nj #fi These lines will appear with as many words on a line as possible, but with the right margin "ragged." This makes for a more "typed-by-hand" appearance, and is useful for correspondence. #cc . .ju .fi .OP \fBChanging the "command character":\fP .PP Several times in the above text, we had to print a period (a "dot") as the first character on a line. Since an embedded commands usually starts with a "dot", we had to be sure that the dot at the first of a line could be ignored if we wanted it to be. .PP The "dot" is called the "command character", and actually any character can be used. If we want some other character to become the command character instead, we could use the ".cc" command (for \fBc\fPhange \fBc\fPommand). Here is how it works. .cc * After this, the command character is a "#". For instance, *nf .cc # I can now type a dot at the first of a line like this: .45 caliber automatic #cc . Now the command character is changed back to a ".". *fi *cc . .PP We will see another method of accomplishing the same end later. .OP \fBIndenting:\fP .PP Most text in letters requires indented printing. The usual left-hand margin in wroff is set to 1 inch from the left printable margin on a page. However, this can be changed in three ways. .PP The left hand margin can be changed to any other value by using ".in". For instance, ".in 20" changes the left margin to 2 inches from the left printable margin. The "20" means that the margin is to be set to 20 deci-inches (tenths of an inch) from the left printable margin. Incidentally, the left printable margin, depending on your printer, may not be at the left edge of the paper. .PP You can also do it slightly differently. Using ".in +12" would change the left margin to be 1.2 inches to the right of where it was. In a like fashion, using ".in -5" would move the left margin one-half inch to the left. For example: .nf .cc # .in 10 This would be printed at 1.0 inches from the left of the paper. .in +5 This is placed at inch 1.5. .in 15 This is also placed at inch 1.5. .in -10 This would be printed at inch 0.5 (15 -10). #cc . .fi .PP A variation on setting a margin permanently is just to change the margin for \fUonly the next line\fU. Use ".ti +5" (for \fBt\fPemporary \fBi\fPndent 5 deci-inches) to indent only the next line (by 0.5 inches). This is particularly useful at the beginning of paragraphs. .PP As an example, .cc # #nf .ti +5 The paragraph printed by processing this text will have an indented first line. The remaining lines will not be indented, but will appear at the left margin. processes into: #fi #ti +5 The paragraph printed by processing this text will have an indented first line. The remaining lines will not be indented, but will appear at the left margin. #cc . .PP An interesting variation is an "outdent", or hanging leader. Here is an example: .cc # #nf .ti -5 This paragraph has an outdent, or hanging leader in its first line. This really helps when preparing a report or other written work with section headings. #fi The output will appear as: #ti -5 This paragraph has an outdent, or hanging leader in its first line. This really helps when preparing a report or other written work with section headings. #cc . .OP \fBBoldfacing\fP, centering, and \fUunderlining\fU: .PP Centering text is easy. Just use ".ce" as in the example at the first of the paper. One "trick" is to tell wroff to center a huge number of lines, and then use ".ce 0" to turn centering off like this: .nf .cc # .ce 100 These and no telling how many other lines ---- --- should be centered. .ce 0 #cc . .fi .PP This results in all of the lines between ".ce 100" and ".ce 0" being centered, with no requirement for having to count lines ahead of time. .PP The same stunt works on boldface or underlining: .cc # #nf .ul 100 .bd 100 All of the words in this block will be both boldfaced and underlined -- -- all the way down to here, whereever this is. .bd 0 .ul 0 #cc . .fi .PP Boldfacing and underlining can be accomplished in two ways. One way is to use either ".bd" or ".ul" as above. .PP A second way, which is useful when you want to just underline or boldface a couple of words is to use an "in-line font change". .PP An illustration probably is sufficient. .PP In this paragraph, we \\fBboldfaced three words\\fP, and \\fUunderlined two\\fU words, and \\fIitalicized three words\\fP, and printed a \\\\. Here is how wroff printed it. .PP In this paragraph, we \fBboldfaced three words\fP, and \fUunderlined two\fU words, and \fIitalicized three words\fP, and printed a \\. Here is how wroff printed it. .PP In-line font changes are discussed in more detail in a later section. .OP \fBUse of Macros:\fP .PP "Macros" are collections of frequently used commands that can be called by a single name. You get to invent the name. .PP In typing this document, we frequently had need to "skip 3 lines and then temporarily outdent by 5 spaces" when we came to a new section. Rather than always type .cc # #nf .sp 3 .ti -5 #fi at the start of every section, we instead defined a "macro" named ".OP" like this: #nf .de OP .sp 3 .ti -5 .en #nf At the start of every new section, we just typed: .OP The start of the section ... .PP and went on about our business. #cc . .fi .PP Macros are really powerful. A well thought out collection of macros can make writing a letter or preparing a memo a breeze. Macros can be defined and placed in a file for future use. The file can be included in any document by using the ".so" command to read the macro file before you start processing. .PP Don't overlook the power of macros. Here is a set we use a lot. They were placed in a file called "macros" by using "vi". .in +5 .OP file macros contains: .nf .cc # .de DATE .in +30 $1 $2 $3 .br .en .de TO .in 10 .sp 3 .nf .en .de TEXT .sp 3 .fi .ti +5 .en .de SIGN .sp 3 .in +30 .nf .en #cc . .in -5 .fi .OP Now when we want to write a letter, we write .nf .in +5 .cc # .DATE October 4, 1988 .TO Mr. Joe Smith SomePlace Somewhere, USA Dear Joe: .TEXT Here is the letter and so forth ... .SIGN Yours Truly, Fred #cc . .fi .in -5 We print the letter by writing "wroff macros filename". .bp .OP \fBScanning for errors:\fP .PP wroff is somewhat sensitive to errors in input. It is sometimes useful to scan a document \fIbefore\fP you print it to see if all of the wroff commands have been entered correctly. Use the command line option "-s" to scan for errors if you are concerned. .PP If you enter "wroff -s filename", then wroff will not print anything at all, either on the screen, or on the printer. If there is some kind of problem with any of the wroff commands in your paper, wroff will report that problem, and the approximate location of it, so that you can fix it before you go to the trouble and expense of printing the document. .OP \fBFonts:\fP .PP One of the biggest pleasures in using wroff is that you can combine various typefaces in a document to give a pleasing appearance. .PP There are several fonts available. Here is a current list: .nf \fT symbol font .in +5 B Times Roman 12 point boldface I Times Roman 12 point italics M mountable - default is Presentation 18 bold T Courier 12 point P return to previous font U toggle underlining 0 Times Roman 12 point Normal (default) 1 Presentation 18 point - synonymous with M 2 Helvetica Normal 6 point \fP .fi .in -5 .PP In order to make effective use of fonts, you must understand what is meant by "proportional spacing." .PP You may have noticed that in this document, not all letters in a word are the same "width". For instance, the letter "i" is much more narrow than the letter "M". These letters were printed with a proportionally spaced font. .PP Proportional spacing is pleasant to read. It gives a "typeset" quality to printed work. Most (but not all) of this document was printed using Times Roman 12 point Normal type. .PP Wroff, in the default mode, allows for proportional printing, and adjusts the spacing in lines accordingly. .PP In the table above, the only proportional fonts are the "Times Roman" fonts. The other fonts are "fixed spacing fonts", which means that each letter takes the same amount of space as any other letter. Fixed spacing fonts are especially useful for preparing portions of a document that have lines which need to "line-up" with previous lines. One such example is when preparing a table. .PP You can switch fonts, even in the middle of a line, by using an "embedded font change." To do this, use a "\\f" followed by the symbol from the table above that indicates which font you want. .PP As an example, the line: .nf .in +5 \\fBboldface this\\fP and \\fIitalicize this\\fP .in -5 .fi would print as: .nf \fBboldface this\fP and \fIitalicize this\fP .fi .OP \fBBuilding tables and using '.nf':\fP .PP The only fixed spacing fonts available above are the Courier 12 point, and the Presentation 18 point. (Point size indicates the height of letters, not their width.) .PP Incidentally, you may occasionally want to print the character "\\". If you want to enter such a character, you may enter '\\\\' in the document. This works for other characters, too. Entering '\\x' will print the character 'x'. This seems useless until you realize that it is an alternative way of protecting a line that begins with a period. .PP Here is an example table: .nf .in +5 \fT \.nf \.in +5 \\fT Name Address Joe Smith Somewhere James Jones Nowhere Sally Sue Anywhere \\.50 caliber Guns \\fP \.in -5 .in -5 \fP .PP This was printed by wroff as: .nf .in +5 \fT Name Address Joe Smith Somewhere James Jones Nowhere Sally Sue Anywhere \.50 caliber Guns \fP .fi .in -5 .PP Just switching from a proportional font to a fixed font in the same line, when in fill mode gives no problems at all. Wroff may become confused when you build tables in non-fill mode and mix several fonts together. A good word of advice, then, is to build tables in non-fill mode, using a fixed font, just as we did above. .PP If for some reason you absolutely \fIinsist\fP on using a proportional font to build a table, you can use an "anchor". The "anchor" characters cause a specific place in the text to appear in a certain column. The anchor consists of the string "\\f|". Here is an example: .nf .sp .in +5 \fT age \\f|14 date \\f|12 today \\f|2 \fP .in -5 .fi .PP This produces the following output: .sp .in +5 .nf age \f|14 date \f|12 today \f|2 .in -5 .fi .PP When processing a line in non-fill mode under a proportional font, wroff will attempt to duplicate the appearance of the original line as best it can. Wroff takes the original line and determines by counting characters just where on a page that it should begin printing a word. It assumes that each character is 0.1 inches in width. .PP Wroff then attempts to begin each word in the line at whatever place on the page is indicated by the character position of the first letter in the word. This would make for some "funny" looking lines, unless you placed the anchors in the line. .OP \fBConclusions:\fP .PP There is a lot to wroff, and a lot more to learn. Most of the commands are reasonable to use, and actually most people only need a few of the commands. Studying the User's Guide will repay a careful reader. .PP Appendix A attached to this paper is a technical description of all of wroff's commands. After you gain skill with wroff, this appendix will probably become very useful to you. .PP Appendix B is a listing of the raw unprocessed file that was used to create this tutorial. It should provide a treasure trove of examples. .PP Enjoy !