Return to u3 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / share / doc / usd / 01.begin

Annotation of 43BSDReno/share/doc/usd/01.begin/u3, revision 1.1

1.1     ! root        1: .\"    @(#)u3  6.1 (Berkeley) 5/22/86
        !             2: .\"
        !             3: .sp
        !             4: .SH
        !             5: III. DOCUMENT PREPARATION
        !             6: .PP
        !             7: .UC UNIX
        !             8: systems are used extensively for document preparation.
        !             9: There are two major 
        !            10: formatting
        !            11: programs,
        !            12: that is,
        !            13: programs that produce a text with
        !            14: justified right margins, automatic page numbering and titling,
        !            15: automatic hyphenation,
        !            16: and the like.
        !            17: .UL nroff
        !            18: is designed to produce output on terminals and
        !            19: line-printers.
        !            20: .UL troff
        !            21: (pronounced ``tee-roff'')
        !            22: instead drives a phototypesetter,
        !            23: which produces very high quality output
        !            24: on photographic paper.
        !            25: This paper was formatted with
        !            26: .UL troff .
        !            27: .SH
        !            28: Formatting Packages
        !            29: .PP
        !            30: The basic idea of
        !            31: .UL nroff 
        !            32: and 
        !            33: .UL troff
        !            34: is that the text to be formatted contains within it
        !            35: ``formatting commands'' that indicate in detail
        !            36: how the formatted text is to look.
        !            37: For example, there might be commands that specify how long
        !            38: lines are, whether to use single or double spacing,
        !            39: and what running titles to use on each page.
        !            40: .PP
        !            41: Because
        !            42: .UL nroff
        !            43: and
        !            44: .UL troff
        !            45: are relatively hard to learn to use effectively,
        !            46: several
        !            47: ``packages'' of canned formatting requests are available
        !            48: to let you specify
        !            49: paragraphs, running titles, footnotes, multi-column output,
        !            50: and so on, with little effort
        !            51: and without having to learn
        !            52: .UL nroff
        !            53: and
        !            54: .UL troff .
        !            55: These packages take a modest effort to learn,
        !            56: but the rewards for using them are so great
        !            57: that it is time well spent.
        !            58: .PP
        !            59: In this section,
        !            60: we will provide a hasty look at the ``manuscript'' 
        !            61: package known as
        !            62: .UL \-ms .
        !            63: Formatting requests typically consist of a period and two upper-case letters,
        !            64: such as
        !            65: .UL .TL ,
        !            66: which is used to introduce a title,
        !            67: or
        !            68: .UL .PP
        !            69: to begin a new paragraph.
        !            70: .PP
        !            71: A document is typed so it looks something like this:
        !            72: .P1
        !            73: \&.TL
        !            74: title of document
        !            75: \&.AU
        !            76: author name
        !            77: \&.SH
        !            78: section heading
        !            79: \&.PP
        !            80: paragraph ...
        !            81: \&.PP
        !            82: another paragraph ...
        !            83: \&.SH
        !            84: another section heading
        !            85: \&.PP
        !            86: etc.
        !            87: .P2
        !            88: The lines that begin with a period are the formatting requests.
        !            89: For example,
        !            90: .UL .PP
        !            91: calls for starting a new paragraph.
        !            92: The precise meaning of
        !            93: .UL .PP
        !            94: depends on what output device is being used
        !            95: (typesetter or terminal, for instance),
        !            96: and on what publication the document will appear in.
        !            97: For example,
        !            98: .UL \-ms
        !            99: normally assumes that a paragraph is preceded by a space
        !           100: (one line in
        !           101: .UL nroff ,
        !           102: \(12 line in
        !           103: .UL troff ),
        !           104: and the first word is indented.
        !           105: These rules can be changed if you like,
        !           106: but they are changed by changing the interpretation
        !           107: of
        !           108: .UL .PP ,
        !           109: not by re-typing the document.
        !           110: .PP
        !           111: To actually produce a document in standard format
        !           112: using
        !           113: .UL \-ms ,
        !           114: use the command
        !           115: .P1
        !           116: troff -ms files ...
        !           117: .P2
        !           118: for the typesetter, and
        !           119: .P1
        !           120: nroff -ms files ...
        !           121: .P2
        !           122: for a terminal.
        !           123: The
        !           124: .UL \-ms
        !           125: argument tells
        !           126: .UL troff
        !           127: and
        !           128: .UL nroff
        !           129: to use the manuscript package of formatting requests.
        !           130: .PP
        !           131: There are several similar packages;
        !           132: check with a local expert to determine which ones
        !           133: are in common use on your machine.
        !           134: .SH
        !           135: Supporting Tools
        !           136: .PP
        !           137: In addition to the basic formatters,
        !           138: there is
        !           139: a host of supporting programs
        !           140: that help with document preparation.
        !           141: The list in the next few paragraphs
        !           142: is far from complete,
        !           143: so browse through the manual
        !           144: and check with people around you for other possibilities.
        !           145: .PP
        !           146: .UL eqn
        !           147: and
        !           148: .UL neqn
        !           149: let you integrate mathematics
        !           150: into the text of a document,
        !           151: in an easy-to-learn language that closely resembles the way
        !           152: you would speak it aloud.
        !           153: For example, the
        !           154: .UL eqn
        !           155: input
        !           156: .P1
        !           157: sum from i=0 to n x sub i ~=~ pi over 2
        !           158: .P2
        !           159: produces the output
        !           160: .EQ
        !           161: sum from i=0 to n x sub i ~=~ pi over 2
        !           162: .EN
        !           163: .PP
        !           164: The program
        !           165: .UL tbl
        !           166: provides an analogous service for preparing tabular material;
        !           167: it does all the computations necessary to align complicated columns
        !           168: with elements of varying widths.
        !           169: .PP
        !           170: .UL refer
        !           171: prepares bibliographic citations from a data base,
        !           172: in whatever style is defined by the formatting package.
        !           173: It looks after all the details of numbering references in sequence,
        !           174: filling in page and volume numbers,
        !           175: getting the author's initials and the journal name right,
        !           176: and so on.
        !           177: .PP
        !           178: .UL spell
        !           179: and
        !           180: .UL typo
        !           181: detect possible spelling mistakes in a document.\(dg
        !           182: .FS
        !           183: \(dg "typo" is not provided with Berkeley Unix.
        !           184: .FE
        !           185: .UL spell
        !           186: works by comparing the words in your document
        !           187: to a dictionary,
        !           188: printing those that are not in the dictionary.
        !           189: It knows enough about English spelling to detect plurals and the like,
        !           190: so it does a very good job.
        !           191: .UL typo
        !           192: looks for words which are ``unusual'',
        !           193: and prints those.
        !           194: Spelling mistakes tend to be more unusual,
        !           195: and thus show up early when the most unusual words
        !           196: are printed first.
        !           197: .PP
        !           198: .UL grep
        !           199: looks through a set of files for lines
        !           200: that contain a particular text pattern 
        !           201: (rather like the editor's context search does,
        !           202: but on a bunch of files).
        !           203: For example,
        !           204: .P1
        !           205: grep \(fming$\(fm chap*
        !           206: .P2
        !           207: will find all lines that end with
        !           208: the letters
        !           209: .UL ing
        !           210: in the files
        !           211: .UL chap* .
        !           212: (It is almost always a good practice to put single quotes around
        !           213: the pattern you're searching for,
        !           214: in case it contains characters like
        !           215: .UL *
        !           216: or
        !           217: .UL $
        !           218: that have a special meaning to the shell.)
        !           219: .UL grep
        !           220: is often useful for finding out in which of a set of files
        !           221: the misspelled words detected by
        !           222: .UL spell
        !           223: are actually located.
        !           224: .PP
        !           225: .UL diff
        !           226: prints a list of the differences between
        !           227: two files,
        !           228: so you can compare
        !           229: two versions of something automatically
        !           230: (which certainly beats proofreading by hand).
        !           231: .PP
        !           232: .UL wc
        !           233: counts the words, lines and characters in a set of files.
        !           234: .UL tr
        !           235: translates characters into other characters;
        !           236: for example it will convert upper to lower case and vice versa.
        !           237: This translates upper into lower:
        !           238: .P1
        !           239: tr A-Z a-z <input >output
        !           240: .P2
        !           241: .PP
        !           242: .UL sort
        !           243: sorts files in a variety of ways;
        !           244: .UL cref
        !           245: makes cross-references;
        !           246: .UL ptx
        !           247: makes a permuted index
        !           248: (keyword-in-context listing).
        !           249: .UL sed
        !           250: provides many of the editing facilities
        !           251: of
        !           252: .UL ed ,
        !           253: but can apply them to arbitrarily long inputs.
        !           254: .UL awk
        !           255: provides the ability to do both pattern matching and numeric computations,
        !           256: and to conveniently process fields within lines.
        !           257: These programs are for more advanced users,
        !           258: and they are not limited to document preparation.
        !           259: Put them on your list of things to learn about.
        !           260: .PP
        !           261: Most of these programs are either independently documented
        !           262: (like
        !           263: .UL eqn
        !           264: and
        !           265: .UL tbl ),
        !           266: or are sufficiently simple that the description in
        !           267: the
        !           268: .ul 2
        !           269: .UC UNIX
        !           270: Programmer's Manual
        !           271: is adequate explanation.
        !           272: .SH
        !           273: Hints for Preparing Documents
        !           274: .PP
        !           275: Most documents go through several versions (always more than you expected) before they
        !           276: are finally finished.
        !           277: Accordingly, you should do whatever possible to make
        !           278: the job of changing them easy.
        !           279: .PP
        !           280: First, when you do the purely mechanical operations of typing,
        !           281: type so that subsequent editing will be easy.
        !           282: Start each sentence on a new line.
        !           283: Make lines short,
        !           284: and break lines at natural places,
        !           285: such as after commas and semicolons,
        !           286: rather than randomly.
        !           287: Since most people change documents by rewriting phrases
        !           288: and adding, deleting and rearranging sentences,
        !           289: these precautions simplify any editing
        !           290: you have to do later.
        !           291: .PP
        !           292: Keep the individual files of a document down
        !           293: to modest size,
        !           294: perhaps ten to fifteen thousand characters.
        !           295: Larger files edit more slowly,
        !           296: and of course if you make a dumb mistake
        !           297: it's better to have clobbered a small file than a big one.
        !           298: Split into files at natural boundaries in the document,
        !           299: for the same reasons that you start each sentence
        !           300: on a new line.
        !           301: .PP
        !           302: The second aspect of making change easy
        !           303: is to not commit yourself to formatting details too early.
        !           304: One of the advantages of formatting packages like
        !           305: .UL \-ms
        !           306: is that they permit you to delay decisions
        !           307: to the last possible moment.
        !           308: Indeed,
        !           309: until a document is printed,
        !           310: it is not even decided whether it will be typeset
        !           311: or put on a line printer.
        !           312: .PP
        !           313: As a rule of thumb, for all but the most trivial jobs,
        !           314: you should type a document in terms of a set of requests
        !           315: like
        !           316: .UL .PP ,
        !           317: and then define them appropriately,
        !           318: either by using one of the canned packages
        !           319: (the better way)
        !           320: or by defining your own
        !           321: .UL nroff
        !           322: and
        !           323: .UL troff
        !           324: commands.
        !           325: As long as you have entered the text in some systematic way,
        !           326: it can always be cleaned up and re-formatted
        !           327: by a judicious combination of
        !           328: editing commands and request definitions.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.