head 3.1; access; symbols; locks; strict; comment @.\" @; 3.1 date 95.09.11.09.48.28; author grog; state Exp; branches; next 3.0; 3.0 date 95.06.25.14.35.08; author grog; state Exp; branches; next 2.7; 2.7 date 95.06.25.10.46.52; author grog; state Exp; branches; next 2.6; 2.6 date 95.06.09.06.17.39; author grog; state Exp; branches; next 2.5; 2.5 date 95.05.17.10.20.24; author grog; state Exp; branches; next 2.4; 2.4 date 95.02.17.09.38.02; author grog; state Exp; branches; next 2.3; 2.3 date 95.02.16.09.34.01; author grog; state Exp; branches; next 2.2; 2.2 date 95.02.04.16.49.17; author grog; state Exp; branches; next 2.1; 2.1 date 95.01.25.13.23.05; author grog; state Exp; branches; next 2.0; 2.0 date 94.12.28.13.40.41; author grog; state Exp; branches; next ; desc @@ 3.1 log @Fix typos @ text @.\" For emacs, this file is in -*- nroff-fill -*- mode .\" $Id: documentation.ms,v 3.0 1995年06月25日 14:35:08 grog Exp grog $ .\" $Log: documentation.ms,v $ .\" Revision 3.0 1995年06月25日 14:35:08 grog .\" Final draft .\" .\" Revision 2.6 1995年06月09日 06:17:39 grog .\" Remove date from page headers .\" Minor mods .\" .\" Revision 2.5 1995年05月17日 10:20:24 grog .\" Major mods after Andy's final draft review .\" .\" Revision 2.4 1995年02月17日 09:38:02 grog .\" Minor mods, remove question flags .\" .\" Revision 2.3 1995年02月16日 09:34:01 grog .\" Mods per Andy's review .\" .\" Revision 2.2 1995年02月04日 16:49:17 grog .\" Minor mods .\" .\" Revision 2.1 1995年01月25日 13:23:05 grog .\" Minor mods .\" .so global.ms .Se \*[nchdoc] "Documentation" .St "Documentation" .\" Why doesn't this work if I define it in global.ms? It seems to get reset by .\" the .Se directive .de TX T\h'-.2m'\v'.3n'E\v'-.3n'\h'-.25n'X\\1ドル .. .de TXI \" italic TeX - can't get this to work otherwise \fIT\h'-.2m'\v'.3n'E\v'-.3n'\h'-.25n'X\fR\\1ドル .. Ask any real guru a question, so the saying goes, and he will reply with a cryptic "\fIRTFM\fR".\** .XX "RTFM" .FS "Read The Manual"--the F is usually silent. .FE Cynics claim this is even the answer to the question "Where can I find the manual?" All too often, programmers consider documentation a necessary (or even unnecessary) evil, and if it gets done at all, it's usually the last thing that gets done. This is particularly evident when you look at the quality of documentation supplied with some free software packages (though many free packages, such as most of those from the Free Software Foundation, are very well documented). The quality and kind of the documentation in source packages varies wildly. In \*[chunpack], page \*[archive-doc], we looked at the documentation that \fIshould\fR be automatically supplied with the package to describe what it is and how to install it. In this chapter, we'll look at documentation that is intended for use after you have installed the package. .LP The documentation you get with a package is usually in one of the following formats: .Ls B .Li .XX "man pages" \fIman pages\fR, the traditional on-line documentation for UNIX, which are formatted with \fInroff\fR. .XX "nroff, program" .XX "program, nroff" .Li .XX "info, program" .XX "program, info" \fIinfo\fR files, used with the GNU project's \fIinfo\fR on-line documentation reader. .Li .XX "texinfo, program" .XX "program, texinfo" Unformatted \fIroff\fR, .TXI , or \fItexinfo\fR hardcopy documentation. .Li .XX ".dvi, file format" .XX "file format, .dvi" Preformatted documentation in PostScript or \fI.dvi\fR format, or occasionally in other formats such as HP LaserJet. .Le We know where we want to get to--the formatted documentation--but we don't always know where to start, so it's easier to look at documentation in reverse order: first, we'll look at the end result, then at the formatters, and finally at the input files. .Ah "Preformatted documentation" .XX "documentation, preformatted" Occasionally you get documentation that has been formatted so that you can print it on just about any printer, but this doesn't happen very much: in order to achieve this, the text must be free of any frills and formatted so that any typewriter can print it. Nearly any printer nowadays is capable of better results, so preformatted files are usually supplied in a format that can print high quality printout on a laser printer. The following three are about the only ones you will come across: .Ls B .Li .XX "PostScript, data format" .XX "data format, PostScript" \fIPostScript\fR is a specialized programming language for printers, and the printed data are in fact embedded in the program. This makes it an extremely flexible format. .Li .XX ".dvi, file format" .XX "file format, .dvi" \fI\&.dvi\fR is the format that is output by .TXI . In order to print it, you need a .TXI \& driver. .Li .XX "Hewlett-Packard LaserJet, data format" .XX "LaserJet, data format" .XX "data format, LaserJet" Unlike PostScript and \fI.dvi\fR, the \fIHewlett-Packard LaserJet\fR format is not portable: you need a LaserJet-compatible printer to print it. The LaserJet format is obsolescent: even many LaserJet printers made today also support PostScript, and there are programmatic ways to print PostScript on other laser printers, so there is little motivation for using the much more restrictive LaserJet format. .Le .Bh "PostScript" .XX "PostScript, data format" .XX "data format, PostScript" .Pn PostScript PostScript is the current format of choice. Because it is a programming language, it is much more flexible than conventional data formats. For example, it is easily scalable. You can take a file intended for a phototypesetter with a resolution of 2540 bpi and print it on a laser printer, and it will come out correctly.\** .FS You may have to wait a while before a few megabytes of font information are transferred and processed, but eventually you get your document. .FE In addition, better quality printers perform the formatting themselves, resulting in a considerable load reduction for the computer. A large number of printers and all modern phototypesetters can process PostScript directly. .LP .XX "ghostscript, program" .XX "program, ghostscript" If your printer doesn't handle PostScript, you can use programs like \fIghostscript\fR, which interpret PostScript programs and output in a multitude of other formats, including LaserJet, so even if you have a LaserJet, it can be a better idea to use PostScript format. \fIghostscript\fR is distributed by the Free Software Foundation--see \*[appsource]. \fIghostscript\fR can also display PostScript files on X displays. .LP Most PostScript files are encoded in plain ASCII without any control characters except newline (though that doesn't make them easy to read). Even when you include special characters in your text, they appear in the PostScript document as plain ASCII sequences. It's usually pretty easy to recognize PostScript, even without the \fIfile\fR program. Here's the start of a draft version of this chapter: .XX "file, program" .XX "program, file" .Ps %!PS-Adobe-3.0 %%Creator: groff version 1.09 %%CreationDate: Thu Aug 18 17:34:24 1994 %%DocumentNeededResources: font Times-Bold .Pe The data itself is embedded in parentheses between the commands. Looking at a draft of this text, we see things like .Ps (It')79.8 273.6 Q 2.613(su)-.55 G .113 (sually pretty easy to recognize a PostScript program, e)-2.613 F -.15 (ve)-.25 G 2.614(nw).15 G .114(ithout the)-2.614 F F2(\e214le)2.614 E F1 (program--here')79.8 285.6 Q 2.5(st)-.55 G(he start of a draft v)-2.5 E .Pe .Ch "Problems with PostScript" .XX "PostScript, problems" PostScript doesn't pose too many problems, but occasionally you might see one of these: .LP .XX "PostScript, problems, missing font" .IP "\fIMissing fonts\fR" 5 PostScript documents include information about the fonts they require. Many fonts are built in to printers and PostScript display software, but if the fonts are not present, the system chooses a default value which may have little in common with the font which the document requested. The default font is typically Courier, which is \s10\f(CWfixed-width\fR\s0, and the results look terrible. If this happens, you can find the list of required fonts with the following: .Ps $ \f(CBgrep '%%.* font ' mumble.ps\f(CW %%DocumentNeededResources: font Garamond-BookItalic %%+ font Times-Roman %%+ font Garamond-Light %%+ font Garamond-LightItalic %%+ font Courier %%+ font Garamond-Book %%+ font Courier-Bold %%IncludeResource: font Garamond-BookItalic %%IncludeResource: font Times-Roman %%IncludeResource: font Garamond-Light %%IncludeResource: font Garamond-LightItalic %%IncludeResource: font Courier %%IncludeResource: font Garamond-Book %%IncludeResource: font Courier-Bold (%%DocumentNeededResources: font Times-Bold)131.711 327.378 S F1 1.281 .Pe This extracts the font requests from the PostScript file: in this case, the document requires Times Roman, Courier and Garamond fonts. Just about every printer and software package supplies Times Roman and Courier, but Garamond (the font in which this book is written) is less common. In addition, most fonts are copyrighted, so you probably won't be able to find them on the net. If you have a document like this in PostScript format, your choices are: .Ls B .Li Reformat it with a different font if you have the source. .Li Get the Garamond fonts. .Li Edit the file and change the name of the font to a font with similar metrics (in other words, with similar size characters). The results won't be as good, but if the font you find is similar enough, they might be acceptable. For example, you might change the text \fIGaramond\fR to \fITimes Roman\fR. .Le .XX "PostScript, problems, wrong font type" .IP "\fIWrong font type\fR" 5 \fIMost\fR PostScript fonts are in plain ASCII. You may also come across \fIType 2 PostScript\fR and \fIdisplay PostScript\fR, both of which include binary data. Many printers can't understand the binary format, and they may react to it in an unfriendly way. For example, my National KX-P 4455 printer just hangs if I copy display PostScript to it. See the section \fIformat conversion\fR below for ways to solve this dilemma. .Bh ".dvi format" .XX ".dvi, data format" .XX "data format, .dvi" .Pn dviformat One of the goals of .TXI \& .XX "troff, program" .XX "program, troff" was to be able to create output for just about any printer. As we will see, old versions of \fItroff\fR, the main competitor, were able to produce output only for a very limited number of phototypesetters. Even if you have one of them in your office, it's unlikely that you will want to use it for printing out a draft of a 30-page paper. .LP The .TXI \& .XX "device-independent, data format" .XX "data format, device-independent" .XX "ditroff, program" .XX "program, ditroff" .XX "printer, driver" .XX "driver, printer" solution, which was later adopted by \fItroff\fR in \fIditroff\fR (device independent troff), was to output the formatted data in a \fIdevice-independent\fR format, \fI\&.dvi\fR, and leave it to another program, a so-called \fIdriver\fR, to format the files in a format appropriate to the output device. Unlike PostScript, \fI.dvi\fR contains large numbers of control characters and characters with the sign bit set, and is not even remotely legible. Most versions of \fIfile\fR know about \fI.dvi\fR format. .Bh "Format conversion" .XX "documentation, format conversion" .XX "format conversion, documentation" .Pn format-conversion Not so long ago your choice of documentation software determined your output format. For example, if you used .TXI , you would get \fI.dvi\fR output, and you would need a .TXI \& driver to print it. Nowadays, it's becoming easier to handle file formats. GNU \fItroff\fR will output in \fI.dvi\fR format if you wish, and programs are available to convert from \fI.dvi\fR to PostScript and back again. Here's a list of conversions you might like to perform--see \*[appsource] for how to get software to perform them. .Ls B .Li .XX "dvips, program" .XX "program, dvips" A number of programs convert from \fI.dvi\fR to PostScript--for example, \fIdvips\fR. .Li There's no good reason to want to convert from \fIPostScript to \fI.dvi\fR\fR, so there are no programs available. \fI.dvi\fR is not much use in itself--it needs to be tranformed to a final printer form, and if you have PostScript output, you can do that directly with \fIghostscript\fR (see below) without going via \fI.dvi\fR. .Li .XX "SeeTeX, program" .XX "program, SeeTeX" To display \fI.dvi\fR files on an X display, use \fISeeTeX\fR. .Li To convert from \fI.dvi\fR to a printer output format, use one of the \fIdvi2xxx\fR programs. .Li To convert from PostScript to a printer format, use \fIghostscript\fR. .Li .XX "ghostview, program" .XX "program, ghostview" To display PostScript on an X display, you can also use \fIghostscript\fR, but \fIghostview\fR gives you a better interface. .Li To convert PostScript with binary data into ASCII, use \fIt1ascii\fR. .Le .Ah "roff and friends" .XX "roff, program" .XX "program, roff" .XX "run-off, program" .XX "program, run-off" The original UNIX formatting program was called \fIroff\fR (for \fIrun-off)\fR. It is now completely obsolete, but it has a number of descendents: .Ls B .Li .XX "nroff, program" .XX "program, nroff" \fInroff\fR is a comparatively simple formatter designed to produce output for plain ASCII displays and printers. .Li .XX "troff, program" .XX "program, troff" \fItroff\fR is a more sophisticated formatter designed to produce output for phototypesetters. Many versions create output only for the obsolete APS-5 phototypesetter, and you need postprocessing software to convert this output to something that modern typesetters or laser printers understand. Fortunately, versions of \fItroff\fR that produce PostScript output are now available. .Li .XX "ditroff, program" .XX "program, ditroff" \fIditroff\fR (device independent troff) is a newer version of \fItroff\fR that produces output in a device-independent intermediate form that can then be converted into the final form by a conversion program. This moves the problem of correct output format from \fItroff\fR to the conversion program. Despite the terminology, this device-independent format is not the same as \fI.dvi\fR format. .Li .XX "groff, program" .XX "program, groff" \fIgroff\fR is the GNU project \fItroff\fR and \fInroff\fR replacement. In \fItroff\fR mode it can produce output in PostScript and \fI\&.dvi\fR format. .Le .XX "xman, program" .XX "program, xman" All versions of \fIroff\fR share the same source file syntax, though \fInroff\fR is more restricted in its functionality than \fItroff\fR. If you have a usable version of \fItroff\fR, you can use it to produce properly formatted hardcopy versions of the man pages, for example. This is also what \fIxman\fR (the X11 manual browser) does. .Bh "formatting with nroff or troff" .XX "formatting, with nroff" .XX "formatting, with troff" .XX "nroff, formatting with" .XX "troff, formatting with" .XX "fly" \fItroff\fR input bears a certain resemblance to the traces left behind when a fly falls into an inkwell and then walks across a desk. The first time you run \fItroff\fR against a file intended for \fItroff\fR, the results may be less than heartening. For example, consider the following passage from the documentation of the Revision Control System RCS. When correctly formatted, the output is: .LP .QS Besides the operations \fIci\fR and \fIco\fR, RCS provides the following commands: .sp 0 .\" .nr VS 12p .\".vs 12p .TS tab(%); li l. ident%extract identification markers rcs%change RCS file attributes rcsclean%remove unchanged working files (optional) rcsdiff%compare revisions rcsfreeze%record a configuration (optional) rcsmerge%merge revisions rlog%read log messages and other information in RCS files .TE A synopsis of these commands appears in the Appendix. .LP \fB2.1 Automatic Identification\fR .PP RCS can stamp source and object code with special identification strings, similar to product and serial numbers. To obtain such identification, place the marker .LP \fI$Id\&$\fR .LP into the text of a revision, for instance inside a comment. The check-out operation will replace this marker with a string of the form .LP \fI$\&Id: filename revisionnumber date time author state locker $\fR .QQE .LP To format it, you can try .Ps $ \f(CBtroff rcs.ms>rcs.ps\f(CW .Pe This assumes the use of \fIgroff\fR or another flavour of \fItroff\fR that creates PostScript output (thus the name \fIrcs.ps\fR for the output file). If you do this, you get an output that looks like: .LP .QS Besides the operations \fIci\fR and \fIco\fR, RCS provides the following commands: tab(%); li l. ident%extract identification markers rcs%change RCS file attributes rcsclean%remove unchanged working files (optional) rcsdiff%compare revisions rcsfreeze%record a configuration (optional) rcsmerge%merge revisions rlog%read log messages and other information in RCS files A synopsis of these commands appears in the Appendix. Automatic Identification RCS can stamp source and object code with special identification strings, similar to product and serial numbers. To obtain such identification, place the marker Id into the text of a revision, for instance inside a comment. The check-out operation will replace this marker with a string of the form Id: filename revisionnumber date time author state locker .QQE .LP Most of the text seems to be there, but it hasn't been formatted at all (well, it \fIhas\fR been right justified). What happened? .LP .XX "macros, troff" .XX "troff, macros" .XX "tmac, macro package" .XX "macro package, tmac" .XX "/usr/lib/tmac, directory" .XX "directory, /usr/lib/tmac" .XX "/usr/share/tmac, directory" .XX "directory, /usr/share/tmac" .XX "/usr/local/groff/tmac, directory" .XX "directory, /usr/local/groff/tmac" .XX "/usr/lib/tmac/an, directory" .XX "directory, /usr/lib/tmac/an" Almost every \fItroff\fR or \fIroff\fR input document uses some set of \fImacros\fR. You can define your own macros in the source, of course, but over time a number of standard macro packages have evolved. They are stored in a directory called \fItmac\fR. In the days of no confusion, this was \fI/usr/lib/tmac\fR, but nowadays it might equally well be \fI/usr/share/tmac\fR (for systems close to the System V.4 ABI--see \*[chconfig], page \*[file-system-structure], for more details) or \fI/usr/local/groff/tmac\fR for GNU \fIroff\fR. The name is known to \fItroff\fR either by environment variables or by instinct (the path name is compiled into the program). \fItroff\fR loads specific macros if you specify the name of the file as an argument to the \s10\f(CW-m\fR\s0 flag. For example, to specify the man page macros \fI/usr/lib/tmac/an\fR, you would supply \fItroff\fR with the parameter \s10\f(CW-man\fR\s0. \fIman\fR makes more sense than \fIan\fR, so these macros are called the \fIman\fR macros. The names of other macro packages also usually grow an \fIm\fR at the beginning. Some systems change the base name of the macros from, say, \fI/usr/lib/tmac/an\fR to \fI/usr/lib/tmac/tmac.an\fR. .LP Most versions of \fItroff\fR supply the following macro packages: .Ls B .Li .XX "tmac/an" .XX "mandoc, macro package" .XX "macro package, mandoc" .XX "tmac/andoc" The \fIman\fR (\fItmac/an\fR) and \fImandoc\fR (\fItmac/andoc\fR) packages are used to format man pages. .Li .XX "mdoc, macro package" .XX "macro package, mdoc" .XX "tmac/doc" The \fImdoc\fR (\fItmac/doc\fR) package is used to format hardcopy documents, including some man pages. .Li .XX "mm, macro package" .XX "macro package, mm" .XX "tmac/m" .XX "memorandum, macro package" .XX "macro package, memorandum" The \fImm\fR (\fItmac/m\fR) macros, the so-called \fImemorandum\fR macros, are described in the documentation as macros to "format letters, reports, memoranda, papers, manuals and books". It doesn't describe what you shouldn't use them for. .Li .XX "ms, macro package" .XX "macro package, ms" .XX "tmac/s" The \fIms\fR (\fItmac/s\fR) macros were the original macros supplied with the Seventh Edition. They are now claimed to be obsolescent, but you will see them again and again. This book was formatted with a modified version of the \fIms\fR macros. .Li .XX "me, macro package" .XX "macro package, me" .XX "tmac/e" The \fIme\fR (\fItmac/e\fR) macros are another, more recent set of macros which originated in Berkeley. .Le There is no sure-fire way to tell which macros a file needs. Here are a couple of possibilities: .Ls B .Li The file name suffix might give a hint. For example, our file is called \fIrcs.ms\fR, so there is a very good chance that it wants to be formatted with \s10\f(CW-ms\fR\s0. .Li .XX "grog, program" .XX "Lehey, Greg" .XX "program, grog" The program \fIgrog\fR, which is part of \fIgroff\fR, examines the source and guesses the kind of macro set. It is frequently wrong. .Li The only other way is trial and error. There aren't that many different macro sets, so this might be a good solution. .Le In this case, our file name suggests that it should be formatted with the \fIms\fR macros. Let's try that: .Ps $ \f(CBtroff rcs.ms>rcs.ps\f(CW .Pe Now we get: .LP .QS Besides the operations \fIci\fR and \fIco\fR, RCS provides the following commands: .sp 0 .nr VS 12p .vs 12p tab(%); li l. ident%extract identification markers rcs%change RCS file attributes rcsclean%remove unchanged working files (optional) rcsdiff%compare revisions rcsfreeze%record a configuration (optional) rcsmerge%merge revisions rlog%read log messages and other information in RCS files A synopsis of these commands appears in the Appendix. .LP \fB2.1 Automatic Identification\fR .PP RCS can stamp source and object code with special identification strings, similar to product and serial numbers. To obtain such identification, place the marker .LP \fI$Id\&$\fR .LP into the text of a revision, for instance inside a comment. The check-out operation will replace this marker with a string of the form .LP \fI$\&Id: filename revisionnumber date time author state locker $\fR .QQE .LP Well, it doesn't look quite as bad, but it's still not where we want to be. What happened to that list of program names? .LP .XX "tbl, program" .XX "program, tbl" \fItroff\fR does not do all the work by itself. The tabular layout of the program names in this example is done by the preprocessor \fItbl\fR, which handles tables. Before we let \fItroff\fR at the document, we need to pass it through \fItbl\fR, which replaces the code .Ps \&.TS tab(%); li l. ident%extract identification markers rcs%change RCS file attributes rcsclean%remove unchanged working files (optional) rcsdiff%compare revisions rcsfreeze%record a configuration (optional) rcsmerge%merge revisions rlog%read log messages and other information in RCS files \&.TE .Pe with a couple of hundred lines of complicated and illegible \fItroff\fR instructions to build the table. To get the desired results, we need to enter: .Ps $ \f(CBtbl rcs.ms | troff -ms>rcs.ps\f(CW .Pe \fInroff\fR, \fItroff\fR and \fIgroff\fR use a number of preprocessors to perform special functions. They are: .Ls B .Li .Pn soelim .XX "soelim, program" .XX "program, soelim" .XX ".so, file name suffix" .XX "file name suffix, .so" \fIsoelim\fR replaces \fI.so\fR statements (which correspond to C \fI#include\fR statements) with the contents of the file to which the line refers. The \fIroff\fR programs do this too, of course, but the other preprocessors don't, so if the contents of one of the files is of interest to another preprocessor, you need to run \fIsoelim\fR first. .Li .XX "refer, program" .XX "program, refer" \fIrefer\fR processes references. .Li .XX "pic, program" .XX "program, pic" \fIpic\fR draws simple pictures. .Li .XX "tbl, program" .XX "program, tbl" \fItbl\fR formats data in tabular form. .Li .XX "eqn, program" .XX "program, eqn" \fIeqn\fR formats equations. .Le Unless you \fIknow\fR that the document you're formatting doesn't use any of these preprocessors, or formatting takes a very long time, it's easier to use them all. There are two possible ways to do this: .Ls B .Li You can pipe from one processor to the next. This is the standard way: .Ps $ \s10\f(CWsoelim rcs.ms | refer | pic | tbl | eqn | troff -ms\fR\s0 .Pe .IP The \fIsoelim\fR preprocessor reads in the document, and replaces any \fI.so\fR commands by the contents of the file to which they refer. It then passes the output to \fIrefer\fR, which processes any textual references and passes it to \fIpic\fR, which processes any pictures it may find, and passes the result to \fItbl\fR. \fItbl\fR processes any tables and passes its result to \fIeqn\fR, which processes any equations before passing the result to \fItroff\fR. .Li Some versions of \fItroff\fR invoke the preprocessors themselves if passed appropriate flags. For example, with \fIgroff\fR: .ne 10 .Ts "Starting preprocessors from \fIgroff\fR" .TS H linesize(2), tab(#) ; lfCWp9 | lfI . \fRFlag#\fRProcessor _ .TH N -e#eqn -t#tbl -p#pic -s#soelim -R#refer .TE .Te .Le .XX "eqn, program" .XX "program, eqn" .XX "tbl, program" .XX "program, tbl" .XX "McGilton, Henry" .XX "McNabb, Mary" Starting the preprocessors from \fItroff\fR not only has the advantage of involving less typing--it also ensures that the preprocessors are started in the correct sequence. Problems can arise if you run \fIeqn\fR before \fItbl\fR, for example, when there are equations within tables. See \fITypesetting tables with tbl\fR by Henry McGilton and Mary McNabb for further details. .Bh "Other roff-related programs" .XX "troff, related programs" .XX "nroff, related programs" As you can see, the \fItroff\fR system uses a large number of programs. Once they were relatively small, and this was the UNIX way. Now they are large, but there are still a lot of them. Apart from the programs we have already seen, you could encounter the GNU variants, which can optionally be installed with a name beginning in \fIg\fR--for example, GNU \fIeqn\fR may be installed as \fIgeqn\fR if the system already has a different version of \fIeqn\fR. \fIindxbib\fR and \fIlookbib\fR (sometimes called \fIlkbib)\fR process bibliographic references, and are available in the \fIgroff\fR package if you don't have them. \fIgroff\fR also includes a number of other programs, such as \fIgrops\fR, and \fIgrotty\fR, which you don't normally need to invoke directly. .Ah "Man pages" .XX "man pages" .XX "man, program" .XX "program, man" .XX "manual, on-line" .XX "on-line manual" .Pn documentation-form .Pn man-pages Almost from the beginning, UNIX had an \fIon-line manual\fR, traditionally called \fIman pages\fR. You can peruse man pages with the \fIman\fR program, or you can print them out as hardcopy documentation. .LP Traditionally, \fIman\fR pages are cryptic and formalized: they were introduced at a time when disk storage was expensive, so they are short, and they were intended as a reference for people who already understand the product. More and more, unfortunately, they are taking on the responsibility of being the sole source of documentation. They don't perform this task very well. .Bh "man history" .XX "man, history" .XX "history, man" The UNIX \fIman\fR facility has had a long and varying history, and knowing it helps understand some of the strangenesses. The Seventh Edition of the Unix Programmer's Manual was divided into nine sections. Section 9, which contained the quick reference cards, has since atrophied. Traditionally, you refer to man pages by the name of the item to which they refer, followed by the section number in parentheses, so the man page for the C compiler would be called \fIcc(1)\fR. BSD systems have substantially retained the Seventh Edition structure, but System V has reorganized them. There are also differences of opinion about where individual man pages belong, so .Ref t \& n 1 can only be a guide: .ne 10 .Ts "UNIX manual sections" .TS H linesize(2), tab(#) ; rfCWp9 | l | rfCWp9 . \fRSeventh#Contents#\fRSystem V \fREdition##\fRSection \fRSection _ .TH N 1#Commands (programs)#1 2#System Calls (direct kernel interface)#2 3#Subroutines (library functions in user space)#3 4#Special files#7, 4 5#File Formats and Conventions#4, 5 6#Games#6 7#Macro Packages and Language Conventions#7 8#Maintenance#1m 9#Quick Reference cards .TE .Te .XX "nroff, program" .XX "program, nroff" .XX "/usr/man/man
, directory" .XX "directory, /usr/man/man
" .XX "man page, defined" .XX "definition, man page" What distinguished the UNIX manual from that of other systems was that it was designed to be kept online. Each of these sections, except for the quick reference cards, was stored in \fInroff\fR format in a directory called \fI/usr/man/man
\fR, where \fI
\fR was the section number. Each entry was (and is) called a \fIman page\fR, although nowadays some can run on for 100 pages or more. .LP The manual was stored in \fInroff\fR format in order to be independent of the display hardware, and because formatting the whole manual took such a long time. For these reasons it was chosen to format pages on an individual basis when they were accessed, which made access to the manual slower and thus less attractive to use. .LP The speed problem was solved by saving the formatted copy of the man page in a second directory hierarchy, \fI/usr/man/cat
\fR, the first time that the page was formatted. Subsequent accesses would then find the formatted page and display that more quickly. .XX "/usr/man/cat
, directory" .XX "directory, /usr/man/cat
" .XX "/usr/man/cat
, directory" .XX "directory, /usr/man/cat
" .LP This basic hierarchy has survived more or less intact to the present day. People have, of course, thought of ways to confuse it: .Ls B .Li .XX "/usr/man/cat1m, directory" .XX "directory, /usr/man/cat1m" As the manual got larger, it seemed reasonable to subdivide it further. Most users weren't interested in system administration functions, so some systems put them into a separate directory, such as \fI/usr/man/cat1m\fR, or gave them a filename suffix such as \fIm\fR, so that the manual page for \fIshutdown\fR might end up being called \fI/usr/man/cat1/shutdown.1m\fR or \fI/usr/man/man1m/shutdown.1m\fR or something similar. .Li Various commercial implementations reorganized the sequence of the sections in the printed manual, and reorganized the directories to coincide. For example, in System V the description of the file \fI/etc/group\fR is in section 4, but in the Seventh Edition and BSD it is in section 5. .Li Even without the uncertainty of which section to search for a command, it was evident that section numbers were not very informative. Some implementations, such as XENIX and some versions of System V, chose to replace the uninformative numbers with uninformative letters. For example, \fIls(1)\fR becomes \fIls(C)\fR in XENIX. .Li Some \fIman\fR programs have lost the ability to format the man pages, so you need to format them before installation. You'll find this problem on systems where \fInroff\fR is an add-on component. .Li .XX "/usr/catman/u_man, directory" .XX "directory, /usr/catman/u_man" .XX "/usr/catman/p_man, directory" .XX "directory, /usr/catman/p_man" There is no longer a single directory where you can expect to put man pages: some System V versions put formatted man pages for users in a directory \fI/usr/catman/u_man\fR, and man pages for programmers in \fI/usr/catman/p_man\fR. Since most programmers are users, and the distinction between the use of the man pages is not always as clear as you would like, this means that \fIman\fR has to search two separate directory hierarchies for the man pages. .Li .XX "/usr/share/man, directory" .XX "directory, /usr/share/man" As we saw in \*[chconfig], page \*[file-system-structure], System V.4 puts its man pages in \fI/usr/share/man\fR. Many System V.4 systems require formatted man pages, and some, such as UnixWare, don't provide a man program at all. .Li .XX "pack, program" .XX "program, pack" .XX "gzip, program" .XX "program, gzip" .XX "compress, program" .XX "program, compress" Many \fIman\fR programs accept compressed input, either formatted or non-formatted. For some reason, the \fIpack\fR program still survives here, but other versions of \fIman\fR also understand man pages compressed with \fIcompress\fR or \fIgzip\fR. We looked at all of these programs in \*[chunpack], page \*[pack]. .Li Different \fIman\fR programs place different interpretations on the suffix of the man page filename. They seldom document the meanings of the suffix. .Li .XX "mdoc, macro package" .XX "macro package, mdoc" To keep up the tradition of incompatible man pages, BSD has changed the default macro set from \fIman\fR to \fImdoc\fR. This means that older man page readers can't make any sense of unformatted BSD man pages. .Le This combination of affairs makes life difficult. For example, on my system I have a number of different man pages in different directories. The file names for the man pages for \fIprintf\fR, which is both a command and a library function, are: .Ps \fIBSD printf command, formatted\f(CW: /usr/share/man/cat1/printf.0 \fISolaris printf command, nroff\f(CW: /pub/man/solaris-2.2/man1/printf.1 \fISVR4.2 printf command, formatted, compressed\f(CW: /pub/man/svr4.2/cat1/printf.1.Z \fIBSD printf function, formatted\f(CW: /usr/share/man/cat3/printf.0 \fISolaris 2.2 printf function, nroff, standard\f(CW: /pub/man/solaris-2.2/man3/printf.3s \fISolaris 2.2 printf function, nroff, BSD version\f(CW: /pub/man/solaris-2.2/man3/printf.3b \fISunOS 4.1.3 printf function, nroff\f(CW: /pub/man/sunos-4.1.3/man3/printf.3v \fISVR3 printf function, formatted, packed\f(CW: /pub/man/catman/p_man/man3/printf.3s.z \fISVR4.2 printf function, formatted, compressed\f(CW: /pub/man/svr4.2/cat3/printf.3s.Z \fISVR4.2 printf function, formatted, compressed, BSD version\f(CW: /pub/man/svr4.2/cat3/printf.3b.Z \fIXENIX printf function, nroff, packed\f(CW: /pub/man/xenix-2.3.2/man.S/printf.S.z .Pe .XX "/usr/man, directory" .XX "directory, /usr/man" Most packages assume that unformatted man pages will be installed in \fI/usr/man\fR. They usually accept that the path may be different, and some allow you to change the subdirectory and the file name suffix, but this is as far as they normally go. .LP This lack of standardization can cause such problems that many people just give up and don't bother to install the man pages. This is a pity--instead, why not install a \fIman\fR program that isn't as fussy? A number of alternatives are available, including one for System V.4 from Walnut Creek and a number on various Linux distributions. .Ah "TeX" .XX "TeX" .XX "Knuth, Donald" .TXI is Donald Knuth's monument to the triumph of logic over convention. To quote Knuth's \fIThe .TXI book\fR, .LP .QS \fIInsiders pronounce the \(*x of .TX \& as a Greek chi, not as an 'x', so that .TX \& rhymes with the word blecchhh. It's the 'ch' sound in Scottish words like \fRloch\fI or German words like \fRach\fI; it's a Spanish 'j' and a Russian \&'kh'. When you say it correctly to your computer, the terminal may become slightly moist.\fR .QQE .LP This is one of the more informative parts of \fIThe .TXI book\fR. It is, unfortunately, not a manual but a textbook, and most of the essential parts are hidden in exercises flagged "very difficult". If you just want to figure out how to format a .TXI \& document, \fIMaking .TX \& work\fR, by Norman Walsh, is a much better option. .XX "Walsh, Norman" .LP If \fItroff\fR input looks like a fly having left an inkwell, .TXI \& .XX "spider" input resembles more the attempts of a drunken spider. Here's part of the file \fIplain.tex\fR .XX "plain.tex, file" .XX "file, plain.tex" which defines some of the things that any .TXI \& macro package should be able to do: .Ps \edef\ecases#1{\eleft\e{\e,\evcenter{\enormalbaselines\em@@th \eialign{$##\ehfil$&\equad##\ehfil\ecrcr#1\ecrcr}}\eright.} \edef\ematrix#1{\enull\e,\evcenter{\enormalbaselines\em@@th \eialign{\ehfil$##$\ehfil&&\equad\ehfil$##$\ehfil\ecrcr \emathstrut\ecrcr\enoalign{\ekern-\ebaselineskip} #1\ecrcr\emathstrut\ecrcr\enoalign{\ekern-\ebaselineskip}}}\e,} .Pe More than anywhere else in porting, it is good for your state of mind to steer clear of .TXI \& internals. The assumptions on which the syntax is based differ markedly from those of other programming languages. For example, identifiers may not contain digits, and spaces are required only when the meaning would otherwise be ambiguous (to .TXI , not to you), so the sequence \s10\f(CWfontsize300\fR\s0 is in fact the identifier \s10\f(CWfontsize\fR\s0 followed by the number \s10\f(CW300\fR\s0. On the other hand, it is almost impossible to find any good solid information in the documentation, so you could spend hours trying to solve a minor problem. I have been using .TXI \& frequently for years, and I still find it the most frustrating program I have ever seen.\** .FS When I wrote this sentence, I wondered if I wasn't overstating the case. Mike Loukides, the author of \fIProgramming with GNU Software\fR, reviewed the final draft and added a single word: \fIAmen\fR. .FE .LP Along with .TXI , there are a couple of macro packages that have become so important that they are almost text processors in their own right: .Ls B .Li .\" This is the LaTeX logo L\h'-.3m'\v'-.1m'\s9A\s0\v'.1m'\h'-.15m'T\h'-.2m'\v'.7n'E\v'-.7n'\h'-.25n'X is a macro package that is not quite as painful as plain .TXI , but also not as powerful. It is normally built as a separate program when installing .TXI , using a technique of dumping a running program to an object file that we will examine in \*[chobj], page \*[obj-dump]. .Li .\" This is the BibTeX logo B\s8IB\s0T\h'-.2m'\v'.3n'E\v'-.3n'\h'-.25n'X is an auxiliary program which, in conjuntion with L\h'-.3m'\v'-.1m'\s9A\s0\v'.1m'\h'-.15m'T\h'-.2m'\v'.7n'E\v'-.7n'\h'-.25n'X, creates bibliographic references. Read all about it in \fIMaking .TXI \& work\fR. .XX "Walsh, Norman" It usually takes three runs through the source files to create the correct auxiliary files and format the document correctly. .Li .XX "texinfo, program" .XX "program, texinfo" \fItexinfo\fR is a GNU package that supplies both online and hardcopy documentation. It uses .TXI \& to format the hardcopy documentation. We'll look at it along with GNU \fIinfo\fR in the next section. .Le .Ah "GNU Info and Texinfo" .XX "GNU texinfo" .XX "GNU info .XX "texinfo, GNU" .XX "info, GNU It's unlikely that you'll break out in storms of enthusiasm about the documentation techniques we've looked at so far. The GNU project didn't, either, when they started, though their concerns were somewhat different: .Ls B .Li Man pages are straightforward, but the \fIman\fR program is relatively primitive. In particular, \fIman\fR does not provide a way to follow up on references in the man page. .Li Man pages are intended to be stored on-line and thus tend to be cryptic. This makes them unsuited as hardcopy documentation. Making them longer and more detailed makes them less suited for online documentation. .Li There is almost no link between man pages and hardcopy documentation, unless they happen to be the same thing for a particular package. .Li Maintaining man pages \fIand\fR hardcopy documentation is double the work and opens you to the danger of omissions in one or the other document. .Le As in other areas, the GNU project started from scratch and came up with a third solution, \fIinfo\fR. This is a combined system of online and hardcopy documentation. Both forms of documentation are contained in the source file: you use \fImakeinfo\fR program to create \fIinfo\fR documents, which you read with the on-line browser \fIinfo\fR, and you use .TXI \& .XX "texinfo, program" .XX "program, texinfo" .XX "makeinfo, program" .XX "program, makeinfo" and the \fItexinfo\fR macro set are used to format the documentation for printing. .LP \fIinfo\fR is a menu-driven, tree-structured online browser. You can follow in-text references and then return to the original text. \fIinfo\fR is available both as a stand-alone program and as an \fIemacs\fR macro. .LP If you have a package that supplies documentation in \fIinfo\fR format, you should use it. Even if some GNU programs, such as \fIgcc\fR and \fIemacs\fR, have both \fIinfo\fR and man pages, the \fIinfo\fR is much more detailled. .LP Running \fItexinfo\fR is straightforward: run .TXI . The document reads in the file \fItexinfo.tex\fR, and about the only problem you are likely to encounter is if it doesn't find this file. .Ah "The World-Wide Web" The World-Wide Web (WWW) is not primarily a program documentation system, but it has a number of properties which make it suitable as a manual browser: as a result of the proliferation of the Internet, it is well known and generally available, it supplies a transparent cross-reference system, and the user interface is easier to understand. It's likely that it will gain importance in the years to come. Hopefully it will do this without causing as much confusion as its predecessors. @ 3.0 log @Final draft @ text @d2 1 a2 1 .\" $Id: documentation.ms,v 2.6 1995年06月09日 06:17:39 grog Exp grog $ d4 3 d567 1 a567 2 instructions to build the table. To get the the desired results, we need to enter: @ 2.7 log @Final draft, second cut @ text @d347 2 a348 38 documentation of the Revision Control System RCS. .\" .Xs .\" Besides the operations \efIci\efR and \efIco\efR, RCS provides the .\" following commands: .\" \&.sp 0 .\" \&.nr VS 12p .\" \&.vs 12p .\" \&.TS .\" tab(%); .\" li l. .\" ident%extract identification markers .\" rcs%change RCS file attributes .\" rcsclean%remove unchanged working files (optional) .\" rcsdiff%compare revisions .\" rcsfreeze%record a configuration (optional) .\" rcsmerge%merge revisions .\" rlog%read log messages and other information in RCS files .\" \&.TE .\" A synopsis of these commands appears in the Appendix. .\" \&.NH 2 .\" Automatic Identification .\" \&.PP .\" RCS can stamp source and object code with special .\" identification strings, .\" similar to product and serial numbers. .\" To obtain such identification, place the marker .\" \&.D( .\" \e*sId\e*s .\" \&.D) .\" into the text of a revision, for instance inside a comment. .\" The check-out operation will replace this marker with a string .\" of the form .\" \&.D( .\" \e*sId: filename revisionnumber date time author state .\" locker \e*s .\" \&.D) .\" .Xe When correctly formatted, the output is: a658 234 .\" Here's a roadmap: .\" .ne 10 .\" .Ts "troff and friends--an overview" .\" .TS H .\" linesize(2), tab(#) ; .\" lI | lw65 . .\" \fRProgram#Purpose .\" _ .\" .TH N .\" .XX "addftinfo, program" .\" .XX "program, addftinfo" .\" addftinfo#T{ .\" Read a \fItroff\fR font file and add additional font-metric information for the .\" \fIgroff\fR system. Copy the resulting augmented file to standard output. .\" T} .\" .sp .4v .\" .XX "afmtodit, program" .\" .XX "program, afmtodit" .\" afmtodit#T{ .\" Create a font file for \fIgroff\fR and \fIgrops\fR. .\" .XX "grops, program" .\" .XX "program, grops" .\" T} .\" .sp .4v .\" .XX "eqn, program" .\" .XX "program, eqn" .\" eqn#T{ .\" Compile descriptions of equations embedded within \fItroff\fR input files into .\" commands that are understood by troff. .\" T} .\" .sp .4v .\" .XX "geqn, program" .\" .XX "program, geqn" .\" geqn#T{ .\" The GNU version of \fIeqn\fR. .\" T} .\" .sp .4v .\" .XX "gindxbib, program" .\" .XX "program, gindxbib" .\" gindxbib#T{ .\" The GNU version of \fIindxbib\fR. .\" .XX "indxbib, program" .\" .XX "program, indxbib" .\" T} .\" .sp .4v .\" .XX "glookbib, program" .\" .XX "program, glookbib" .\" glookbib#T{ .\" The GNU version of \fIlkbib\fR. .\" .XX "lkbin, program" .\" .XX "program, lkbin" .\" Notice the difference in the spelling. .\" T} .\" .sp .4v .\" .XX "gnroff, program" .\" .XX "program, gnroff" .\" gnroff#T{ .\" A script that emulates the \fInroff\fR command using \fIgroff\fR. Frequently .\" installed under the name \fInroff\fR as well as \fIgnroff\fR. .\" T} .\" .sp .4v .\" .XX "gpic, program" .\" .XX "program, gpic" .\" gpic#T{ .\" The GNU version of \fIpic\fR. It can also read input and produce output for .\" .TXI . .\" T} .\" .sp .4v .\" .XX "grefer, program" .\" .XX "program, grefer" .\" grefer#T{ .\" The GNU version of \fIrefer\fR. .\" T} .\" .sp .4v .\" .XX "grodvi, program" .\" .XX "program, grodvi" .\" grodvi#T{ .\" .XX ".dvi, program" .\" .XX "program, .dvi" .\" Produce \fI.dvi\fR .\" format from the input file, which should be the output of \fIgtroff\fR. .\" Normally you will run this program implicitly by specifying the .\" \s10\f(CW-Tdvi\fR\s0 flag to \fIgroff\fR. .\" T} .\" .sp .4v .\" .XX "groff, program" .\" .XX "program, groff" .\" groff#T{ .\" The front-end to the \fIgroff\fR system. By default it runs \fIgtroff\fR and pipes .\" the output to \fIgrops\fR. .\" .XX "grops, program" .\" .XX "program, grops" .\" T} .\" .sp .4v .\" .XX "grog, program" .\" .XX "program, grog" .\" grog#T{ .\" .XX "Lehey, Greg" .\" Read files and guess which of the \fIgroff\fR flags \s10\f(CW-e\fR\s0, .\" \s10\f(CW-man\fR\s0, \s10\f(CW-me\fR\s0, \s10\f(CW-mm\fR\s0, \s10\f(CW-ms\fR\s0, .\" \s10\f(CW-p\fR\s0, \s10\f(CW-s\fR\s0, and \s10\f(CW-t\fR\s0 will correctly .\" format the file. Print the appropriate \fIgroff\fR command. .\" T} .\" .sp .4v .\" .XX "grops, program" .\" .XX "program, grops" .\" grops#T{ .\" Produce PostScript output from the input file, which should be the output of .\" \fIgtroff\fR. Normally this is run implictly by specifying the .\" \s10\f(CW-Tps\fR\s0 flag to \fIgroff\fR. .\" T} .\" .sp .4v .\" .XX "grotty, program" .\" .XX "program, grotty" .\" grotty#T{ .\" Read the input file, which should be the output of \fIgtroff\fR, and produce .\" output suitable for display on typewriter-like devices. Normally this is run .\" implicitly by specifying the \s10\f(CW-Tascii\fR\s0 or \f(CW-Tlatin\fR flag to .\" \fIgroff\fR. .\" T} .\" .sp .4v .\" .XX "gsoelim, program" .\" .XX "program, gsoelim" .\" gsoelim#T{ .\" The GNU version of \fIsoelim\fR. .\" T} .\" .sp .4v .\" .XX "gtbl, program" .\" .XX "program, gtbl" .\" gtbl#T{ .\" Compile descriptions of tables embedded within \fItroff\fR input .\" files into \fItroff\fR commands. .\" T} .\" .sp .4v .\" .XX "gtroff, program" .\" .XX "program, gtroff" .\" gtroff#T{ .\" The GNU version of \fItroff\fR. .\" T} .\" .sp .4v .\" .XX "indxbib, program" .\" .XX "program, indxbib" .\" indxbib#T{ .\" Make an inverted index for the bibliographic databases used by \fIgrefer\fR, .\" \fIglookbib\fR .\" .XX "glookbib, program" .\" .XX "program, glookbib" .\" and \fIlkbib\fR. .\" T} .\" .sp .4v .\" .XX "lookbib, program" .\" .XX "program, lookbib" .\" lookbib#T{ .\" Search bibliographic databases for references and print any references found .\" onto the standard output. Sometimes called \fIlkbib\fR. .\" T} .\" .sp .4v .\" .XX "neqn, program" .\" .XX "program, neqn" .\" neqn#T{ .\" A preprocessor for \fInroff\fR intended for use with terminals. There is .\" currently no GNU equivalent. .\" T} .\" .sp .4v .\" .XX "nroff, program" .\" .XX "program, nroff" .\" nroff#T{ .\" A version of \fItroff\fR for typewriter-like terminals. .\" T} .\" .sp .4v .\" .XX "pfbtops, program" .\" .XX "program, pfbtops" .\" pfbtops#T{ .\" Translate a PostScript font in \fI.pfb\fR .\" .XX ".pfb, program" .\" .XX "program, .pfb" .\" format to an ASCII PostScript file. .\" T} .\" .sp .4v .\" .XX "pic, program" .\" .XX "program, pic" .\" pic#T{ .\" Compile descriptions of pictures embedded within \fItroff\fR input files into .\" commands that are understood by \fItroff\fR. .\" T} .\" .sp .4v .\" .XX "psbb, program" .\" .XX "program, psbb" .\" psbb#T{ .\" Read a PostScript file and extract the information on a \fI%%BoundingBox\fR .\" .XX "%%BoundingBox" .\" line .\" in a format that can be used by \fIgrops\fR. .\" .XX "grops, program" .\" .XX "program, grops" .\" T} .\" .sp .4v .\" .XX "refer, program" .\" .XX "program, refer" .\" refer#T{ .\" Copy the contents of the specified files to the standard output, but interpret .\" lines between \s10\f(CW.[\fR\s0 and \s10\f(CW.]\fR\s0 as citations, and lines .\" between \s10\f(CW.R1\fR\s0 and \s10\f(CW.R2\fR\s0 as commands about how to .\" process citations. .\" T} .\" .sp .4v .\" .XX "soelim, program" .\" .XX "program, soelim" .\" soelim#T{ .\" Read files and replace lines of the form \s10\f(CW.so \fIfile\fR\s0 by the .\" contents of \fIfile\fR. .\" T} .\" .sp .4v .\" .XX "tbl, program" .\" .XX "program, tbl" .\" tbl#T{ .\" Format tables for \fInroff\fR or \fItroff\fR. Copy the input files to the .\" standard output, but replace lines between \s10\f(CW.TS\fR\s0 and .\" \s10\f(CW\&.TE\fR\s0 command lines with \fItroff\fR commands to display the table. .\" T} .\" .sp .4v .\" .XX "tfmtodit, program" .\" .XX "program, tfmtodit" .\" tfmtodit#T{ .\" Create a font file for use with \fIgroff -Tdvi\fR. .\" T} .\" .sp .4v .\" .XX "troff, program" .\" .XX "program, troff" .\" troff#T{ .\" The core formatter of the \fItroff\fR system. .\" T} .\" .TE .\" .Te a845 5 .\" XXX If you run into trouble with .\" man pages, try \fIsuperman\fR (see \*[appsource]). It .\" recognizes all of the above name formats. .\" Unfortunately, it's not in good shape to distribute. Leave this here, .\" maybe it'll work next time. @ 2.6 log @Remove date from page headers Minor mods @ text @d2 1 a2 1 .\" $Id: documentation.ms,v 2.5 1995年05月17日 10:20:24 grog Exp grog $ d4 4 d38 1 a38 1 Read The Manual--the F is usually silent. d693 1 a693 1 don't have them. \fIgroff\fR also includes a number of other programs, such as d1189 1 a1189 1 draft and added a single word: Amen. @ 2.5 log @Major mods after Andy's final draft review @ text @d2 1 a2 1 .\" $Id: documentation.ms,v 2.4 1995年02月17日 09:38:02 grog Exp grog $ d4 3 d21 1 a21 1 .St "Documentation ($Date: 1995年02月17日 09:38:02 $)" d31 1 a31 1 cryptic "\fIRTFM\fR"\** d65 1 a65 1 Unformatted hardcopy documentation in \fIroff\fR, d67 1 a67 1 or \fItexinfo\fR format. d107 1 a107 1 not portable: you need a LaserJet compatible printer to print it. The LaserJet d214 4 a217 4 binary data. Many printers can't understand this format, and they may react to it in an unfriendly way. For example, my National KX-P 4455 printer just hangs if I copy display PostScript to it. See the section \fIformat conversion\fR below for ways to solve this dilemma. d256 1 a256 1 driver to print it Nowadays, it's becoming easier to handle file formats. GNU d265 2 a266 2 A number of different programs convert from \fI.dvi\fR to PostScript--for example, \fIdvips\fR. d274 3 a276 3 .XX "SeeTex, program" .XX "program, SeeTex" To display \fI.dvi\fR files on an X display, use \fISeeTex\fR. d342 2 a343 2 than heartening. For example, consider the following passage from the RCS documentation. d467 1 a467 1 \*[file-system-structure] for more details) or \fI/usr/local/groff/tmac\fR for d499 2 a500 2 The \fImm\fR (\fItmac/m\fR) macros, the so-called \fImemorandum\fR macros. The documentation describes them as macros to "format letters, reports, memoranda, d611 1 a611 1 statements) with the contents of the file to which the line references. The d948 7 a954 5 the quick reference cards, has since atrophied. BSD systems have substantially retained the Seventh Edition structure, but System V has reorganized them. There are also differences of opinion about where individual man pages belong, so .Ref t \& n d991 8 a998 7 display hardware, and because formatting the whole manual took such a long time. Instead it was chosen to format pages on an individual basis when they were accessed, which made access to the manual slower and thus less attractive. .LP This problem was solved by saving the formatted copy of the man page in a second directory hierarchy, \fI/usr/man/cat
\fR, the first time that the page was formatted. Subsequent accesses would then find the formatted page and d1115 2 d1268 1 a1268 1 Running \fITexinfo\fR is straightforward: run @ 2.4 log @Minor mods, remove question flags @ text @d2 1 a2 1 .\" $Id: documentation.ms,v 2.3 1995年02月16日 09:34:01 grog Exp grog $ d4 3 d18 1 a18 1 .St "Documentation ($Date: 1995年02月16日 09:34:01 $)" d33 4 a36 4 Cynics claim this this is even the answer to the question "Where can I find the manual?". All too often, programmers consider documentation a necessary (or even unnecessary) evil, and if it gets done at all, it's usually the last thing that gets done. This is particularly evident when you look at the quality of d88 3 a90 3 \fIPostScript\fR is in fact a programming language, not a document format, but it does a good job of faking a document format: the instructions include immediate data that are, in fact, the document you want to print. d97 1 a97 1 .TX \& d103 2 a104 2 Unlike PostScript and \fI.dvi\fR, the \fIHewlett-Packard LaserJet\fR format not portable: you need a LaserJet compatible printer to print it. The LaserJet d114 5 a118 13 PostScript is rapidly becoming the format of choice: .Ls B .Li A large number of printers and all modern phototypesetters can process PostScript directly. .Li PostScript is a programming language and not a data format, so the printer can perform the real formatting. This results in a considerable load reduction for the computer. .Li Because PostScript is a programming language, it is easily scalable. You can take a file intended for a phototypesetter with a resolution of 2540 bpi and print it on a laser printer, and it will come out correctly.\** d123 4 a126 1 .Li d131 3 a133 2 of other formats. \fIghostscript\fR is distributed by the Free Software Foundation--see \*[appsource] for sources. Ghostscript can also display d135 1 a135 1 .Li d137 5 a141 6 except \s10\f(CW\en\fR\s0 (though that doesn't make them easy to read). Even when you include special characters in your text, they appear in the PostScript document as plain ASCII. .Le It's usually pretty easy to recognize a PostScript program, even without the \fIfile\fR program. Here's the start of a draft version of this chapter: d161 1 a161 1 these problems: d190 6 a195 6 This extracts the font requests from the PostScript file: the document requires Times Roman, Courier and Garamond fonts. Just about every printer and software package supplies Times Roman and Courier, but Garamond (the font in which this book is written) is less common. In addition, most fonts are copyrighted, so you probably won't be able to find them on the net. If you have a document like this in PostScript format, your choices are: d198 1 a198 1 Reformat it with a different font if possible. d212 3 a214 3 it in an unfriendly way. For example, my National KXP 4455 printer just hangs if I copy display PostScript to it. See the section \fIformat conversion\fR on page \*[format-conversion] for details of how to solve this dilemma. d220 1 a220 1 .TX \& d248 4 a251 4 Nowadays, the distinction between the file formats is becoming less and less distinct. Times were when a \fI.dvi\fR file would have been created by .TXI ,\ and that if you had a \fI.dvi\fR file you needed a d253 5 a257 7 driver to print it. Nowadays you can tell GNU \fItroff\fR to output in \fI.dvi\fR format, and you can convert from \fI.dvi\fR to PostScript and back again. Still, the writing is on the wall: PostScript is the only format with a future. .LP In the meantime, there is a plethora of conversion programs, all of which are freely available--see \*[appsource] for sources. d262 2 a263 1 A number of different programs convert from \fI.dvi\fR to PostScript. d271 4 d282 2 a283 6 To display PostScript on an X display, you \fIcan\fR also use \fIghostscript\fR, but \fIghostview\fR gives you a better interface. .Li .XX "SeeTex, program" .XX "program, SeeTex" To display \fI.dvi\fR files on an X display, use \fISeeTex\fR. d285 1 a285 2 You can convert PostScript with binary data into ASCII with the program \fIt1ascii\fR to convert it to ASCII. d304 4 a307 7 phototypesetters. .IP The usefulness of \fItroff\fR is somewhat limited by the fact that many versions create output only for the obsolete APS-5 phototypesetter. Postprocessing software is needed to convert this output to something that modern typesetters or laser printers understand. Fortunately, versions of \fItroff\fR that produce PostScript output are becoming available. d314 3 a316 1 of correct output format from \fItroff\fR to the conversion program. d321 1 a321 1 \fItroff\fR mode it produces output in PostScript and \fI\&.dvi\fR format. d325 5 a329 6 All versions of \fIroff\fR are compatible with each other to the extent that they both accept the same kind of source files, though \fInroff\fR is more restricted in its functionality than \fItroff\fR. If you have a usable version of \fItroff\fR, you can use it to produce properly formatted hardcopy versions of the man pages, for example. This is also what \fIxman\fR (the X11 manual browser) does. d338 39 a376 39 \fItroff\fR against a file \fIintended\fR for \fItroff\fR, the results may be less than heartening. For example, consider the following text from the RCS documentation: .Xs Besides the operations \efIci\efR and \efIco\efR, RCS provides the following commands: \&.sp 0 \&.nr VS 12p \&.vs 12p \&.TS tab(%); li l. ident%extract identification markers rcs%change RCS file attributes rcsclean%remove unchanged working files (optional) rcsdiff%compare revisions rcsfreeze%record a configuration (optional) rcsmerge%merge revisions rlog%read log messages and other information in RCS files \&.TE A synopsis of these commands appears in the Appendix. \&.NH 2 Automatic Identification \&.PP RCS can stamp source and object code with special identification strings, similar to product and serial numbers. To obtain such identification, place the marker \&.D( \e*sId\e*s \&.D) into the text of a revision, for instance inside a comment. The check-out operation will replace this marker with a string of the form \&.D( \e*sId: filename revisionnumber date time author state locker \e*s \&.D) .Xe d417 2 a418 3 creates PostScript output (thus the name \fIrcs.ps\fR for the output file). You can invoke \fIgroff\fR under the name \fItroff\fR. If you do this, you get an output that looks like: d459 15 a473 14 \fImacros\fR or another. You can define your own macros in the source, of course, but in the course of time a number of standard macro packages have evolved. They are stored in a directory called \fItmac\fR. In the days of no confusion, this was \fI/usr/lib/tmac\fR, but nowadays it might equally well be \fI/usr/share/tmac\fR (for systems close to the System V.4 ABI. See \*[chconfig], page \*[file-system-structure] for more details) or \fI/usr/local/groff/tmac\fR for GNU \fIroff\fR. The name is known to \fItroff\fR either by environment variables or by instinct (the path name is compiled into the program). \fItroff\fR loads specific macros if you specify the name of the file as an argument to the \s10\f(CW-m\fR\s0 flag. For example, to specify the man page macros \fI/usr/lib/tmac/an\fR, you would supply \fItroff\fR with the parameter \s10\f(CW-man\fR\s0. \fIman\fR makes more sense than \fIan\fR, so these macros are called the \fIman\fR macros. The names of other macro packages also usually grow an \fIm\fR at the beginning. d482 1 a482 1 The \fIman\fR (\fItmac/an\fR) and \fImandoc\fR (\fItmac/andoc\fR packages are d524 1 d670 5 a674 5 Starting the preprocessors from \fItroff\fR has not only the advantage that it is less typing, it also ensures that the preprocessors are started in the correct sequence: problems can arise if you run \fIeqn\fR before \fItbl\fR, for example, when there are equations within tables. See [McGilton & McNabb 90] for further details. d680 242 a921 234 there is still a large number of them. Here's a roadmap: .ne 10 .Ts "troff and friends--an overview" .TS H linesize(2), tab(#) ; lI | lw65 . \fRProgram#Purpose _ .TH N .XX "addftinfo, program" .XX "program, addftinfo" addftinfo#T{ Read a \fItroff\fR font file and add additional font-metric information for the \fIgroff\fR system. Copy the resulting augmented file to standard output. T} .sp .4v .XX "afmtodit, program" .XX "program, afmtodit" afmtodit#T{ Create a font file for \fIgroff\fR and \fIgrops\fR. .XX "grops, program" .XX "program, grops" T} .sp .4v .XX "eqn, program" .XX "program, eqn" eqn#T{ Compile descriptions of equations embedded within \fItroff\fR input files into commands that are understood by troff. T} .sp .4v .XX "geqn, program" .XX "program, geqn" geqn#T{ The GNU version of \fIeqn\fR. T} .sp .4v .XX "gindxbib, program" .XX "program, gindxbib" gindxbib#T{ The GNU version of \fIindxbib\fR. .XX "indxbib, program" .XX "program, indxbib" T} .sp .4v .XX "glookbib, program" .XX "program, glookbib" glookbib#T{ The GNU version of \fIlkbin\fR. .XX "lkbin, program" .XX "program, lkbin" Notice the difference in the spelling. T} .sp .4v .XX "gnroff, program" .XX "program, gnroff" gnroff#T{ A script that emulates the \fInroff\fR command using \fIgroff\fR. Frequently installed under the name \fInroff\fR as well as \fIgnroff\fR. T} .sp .4v .XX "gpic, program" .XX "program, gpic" gpic#T{ The GNU version of \fIpic\fR. It can also read input and produce output for .TXI . T} .sp .4v .XX "grefer, program" .XX "program, grefer" grefer#T{ The GNU version of \fIrefer\fR. T} .sp .4v .XX "grodvi, program" .XX "program, grodvi" grodvi#T{ .XX ".dvi, program" .XX "program, .dvi" Produce \fI.dvi\fR format from the input file, which should be the output of \fIgtroff\fR. Normally you will run this program implicitly by specifying the \s10\f(CW-Tdvi\fR\s0 flag to \fIgroff\fR. T} .sp .4v .XX "groff, program" .XX "program, groff" groff#T{ The front-end to the \fIgroff\fR system. By default it runs \fIgtroff\fR and pipes the output to \fIgrops\fR. .XX "grops, program" .XX "program, grops" T} .sp .4v .XX "grog, program" .XX "program, grog" grog#T{ .XX "Lehey, Greg" Read files and guess which of the \fIgroff\fR flags \s10\f(CW-e\fR\s0, \s10\f(CW-man\fR\s0, \s10\f(CW-me\fR\s0, \s10\f(CW-mm\fR\s0, \s10\f(CW-ms\fR\s0, \s10\f(CW-p\fR\s0, \s10\f(CW-s\fR\s0, and \s10\f(CW-t\fR\s0 will correctly format the file. Print the appropriate \fIgroff\fR command. T} .sp .4v .XX "grops, program" .XX "program, grops" grops#T{ Produce PostScript output from the input file, which should be the output of \fIgtroff\fR. Normally this is run implictly by specifying the \s10\f(CW-Tps\fR\s0 flag to \fIgroff\fR. T} .sp .4v .XX "grotty, program" .XX "program, grotty" grotty#T{ Read the input file, which should be the output of \fIgtroff\fR, and produce output suitable for display on typewriter-like devices. Normally this is run implicitly by specifying the \s10\f(CW-Tascii\fR\s0 or \f(CW-Tlatin\fR flag to \fIgroff\fR. T} .sp .4v .XX "gsoelim, program" .XX "program, gsoelim" gsoelim#T{ The GNU version of \fIsoelim\fR. T} .sp .4v .XX "gtbl, program" .XX "program, gtbl" gtbl#T{ Compile descriptions of tables embedded within \fItroff\fR input files into \fItroff\fR commands. T} .sp .4v .XX "gtroff, program" .XX "program, gtroff" gtroff#T{ The GNU version of \fItroff\fR. T} .sp .4v .XX "indxbib, program" .XX "program, indxbib" indxbib#T{ Make an inverted index for the bibliographic databases used by \fIgrefer\fR, \fIglookbib\fR .XX "glookbib, program" .XX "program, glookbib" and \fIlkbib\fR. T} .sp .4v .XX "lookbib, program" .XX "program, lookbib" lookbib#T{ Search bibliographic databases for references and print any references found onto the standard output. Sometimes called \fIlkbib\fR. T} .sp .4v .XX "neqn, program" .XX "program, neqn" neqn#T{ A preprocessor for \fInroff\fR intended for use with terminals. There is currently no GNU equivalent. T} .sp .4v .XX "nroff, program" .XX "program, nroff" nroff#T{ A version of \fItroff\fR for typewriter-like terminals. T} .sp .4v .XX "pfbtops, program" .XX "program, pfbtops" pfbtops#T{ Translate a PostScript font in \fI.pfb\fR .XX ".pfb, program" .XX "program, .pfb" format to an ASCII PostScript file. T} .sp .4v .XX "pic, program" .XX "program, pic" pic#T{ Compile descriptions of pictures embedded within \fItroff\fR input files into commands that are understood by \fItroff\fR. T} .sp .4v .XX "psbb, program" .XX "program, psbb" psbb#T{ Read a PostScript file and extract the information on a \fI%%BoundingBox\fR .XX "%%BoundingBox" line in a format that can be used by \fIgrops\fR. .XX "grops, program" .XX "program, grops" T} .sp .4v .XX "refer, program" .XX "program, refer" refer#T{ Copy the contents of the specified files to the standard output, but interpret lines between \s10\f(CW.[\fR\s0 and \s10\f(CW.]\fR\s0 as citations, and lines between \s10\f(CW.R1\fR\s0 and \s10\f(CW.R2\fR\s0 as commands about how to process citations. T} .sp .4v .XX "soelim, program" .XX "program, soelim" soelim#T{ Read files and replace lines of the form \s10\f(CW.so \fIfile\fR\s0 by the contents of \fIfile\fR. T} .sp .4v .XX "tbl, program" .XX "program, tbl" tbl#T{ Format tables for \fInroff\fR or \fItroff\fR. Copy the input files to the standard output, but replace lines between \s10\f(CW.TS\fR\s0 and \s10\f(CW\&.TE\fR\s0 command lines with \fItroff\fR commands to display the table. T} .sp .4v .XX "tfmtodit, program" .XX "program, tfmtodit" tfmtodit#T{ Create a font file for use with \fIgroff -Tdvi\fR. T} .sp .4v .XX "troff, program" .XX "program, troff" troff#T{ The core formatter of the \fItroff\fR system. T} .TE .Te a923 2 .Pn documentation-form \fIman\fR d926 7 a932 3 pages are the traditional UNIX documentation method. Where space permits, they can be installed on-line and perused with the \fIman\fR program. They can also be printed out as hardcopy documentation. d944 28 a971 21 Programmer's Manual was divided into nine sections: .Ls N .Li Commands (programs) .Li System Calls (direct kernel interface) .Li Subroutines (library functions in user space) .Li Special files .Li File Formats and Conventions .Li Games .Li Macro Packages and Language Conventions .Li Maintenance .Li Quick Reference cards .Le d979 2 a980 2 designed to be kept online. Each of these sections except for the quick reference cards was stored in \fInroff\fR format in a directory called d1019 3 a1021 3 such as XENIX and some implementations of System V, chose to replace the uninformative numbers with uninformative letters. For example, \fIls(1)\fR becomes \fIls(C)\fR in XENIX. d1025 1 a1025 1 where \fInroff\fR is not part of the base system. d1102 7 a1108 4 up and don't bother to install the man pages. This is a pity--there is an easier way: install a \fIman\fR program which isn't as fussy. If you run into trouble with man pages, try \fIsuperman\fR (see \*[appsource] for availability). It recognizes all of the above name formats. d1114 3 a1116 1 [Knuth 89], d1119 1 a1119 1 \fIInsiders pronounce the \(*x of d1129 9 a1137 5 This is one of the more informative parts of [Knuth 89]. It is, unfortunately, not a manual but a textbook, and most of the interesting parts are hidden in exercises flagged "very difficult". If you just want to use .TX , [Walsh 94] is a much better option. d1141 1 a1141 1 .TX \& d1148 1 a1148 1 .TX \& d1160 1 a1160 1 .TX \& d1163 1 a1163 1 digits, and spaces are only required when the meaning would otherwise be d1165 1 a1165 1 .TX , d1171 1 a1171 1 .TX \& d1173 6 a1178 1 ever seen. d1180 2 a1181 2 Apart from .TX \& d1189 1 a1189 1 .TX , d1192 1 a1192 1 .TX , d1197 2 a1198 2 B\s8IB\s0T\h'-.2m'\v'.3n'E\v'-.3n'\h'-.25n'X is an auxiliary program which, in conjuntion with d1200 3 a1202 1 creates bibliographic references. Read all about it in [Walsh 94]. d1204 2 a1205 2 An interesting point is that it usually takes three runs through the source files to create the correct auxiliary files and format the document correctly. d1211 1 a1211 1 .TX \& d1241 6 a1246 5 documentation: .Ls B .Li All documentation is contained in a single source file. .Li a1248 6 The \fImakeinfo\fR program makes \fIinfo\fR documents, which you read with the on-line browser \fIinfo\fR. .Li .TX \& .XX "texinfo, program" .XX "program, texinfo" d1251 1 a1251 1 .Li d1255 4 a1258 9 .Le If you have a package that uses \fIinfo\fR (and you are almost sure to have at least one), you should use it. In particular, programs like \fIgcc\fR and \fIemacs\fR have both \fIinfo\fR and man pages. The man page for gcc is 3500 lines long (60 hardcopy pages, or nearly 150 standard terminal screens), so you would probably like something better than \fIman\fR anyway. This is nothing by comparison to the 25000 lines in the \fIinfo\fR files: the GNU project takes documentation seriously. With documentation of this size (we're now talking about over 400 pages of documentation), you need some kind of structure. d1261 1 a1261 1 .TX . d1263 9 a1271 1 are likely to encounter is that it doesn't find this file. @ 2.3 log @Mods per Andy's review @ text @d2 1 a2 1 .\" $Id: documentation.ms,v 2.2 1995年02月04日 16:49:17 grog Exp grog $ d4 3 a12 2 .\" XXX .book_setup .\" XXX .FILE documentation.ms d15 1 a15 1 .St "Documentation ($Date: 1995年02月04日 16:49:17 $)" @ 2.2 log @Minor mods @ text @d2 1 a2 1 .\" $Id: documentation.ms,v 2.1 1995年01月25日 13:23:05 grog Exp grog $ d4 3 d14 1 a14 1 .St "Documentation ($Date: 1995年01月25日 13:23:05 $)" d1159 1 d1169 9 d1240 5 @ 2.1 log @Minor mods @ text @d2 1 a2 1 .\" $Id: documentation.ms,v 2.0 1994年12月28日 13:40:41 grog Exp grog $ d4 3 d11 1 a11 1 .St "Documentation ($Date: 1994年12月28日 13:40:41 $)" d24 1 a24 1 Read The Manual--the F is normally silent. d130 2 a131 3 Foundation and can be found on the companion CD-ROM in the directory \fItext/ghostscript-2.6.1\fR. Ghostscript can also display PostScript files on X displays. d257 1 a257 1 supplied on the companion CD-ROM: d262 1 a262 2 A number of different programs convert from \fI.dvi\fR to PostScript. You'll find them in the directory \fItext/dvips-5.49\fR. d271 1 a271 2 \fIdvi2xxx\fR programs on the CD-ROM in the directories under \fItext/dviware\fR. d273 1 a273 2 To convert from PostScript to a printer format, use \fIghostscript\fR (\fItext/ghostscript-2.6.1\fR). d278 1 a278 2 but \fIghostview\fR gives you a better interface. You'll find it in \fItext/ghostview-1.5\fR. d282 1 a282 2 To display \fI.dvi\fR files on an X display, use \fISeeTex\fR (\fItext/SeeTeX-2.18.5\fR on the CD-ROM). d285 1 a285 1 \fIt1ascii\fR (in \fItext/t1utils-1.1a\fR) to convert it to ASCII. d293 1 a293 1 It is now completely obsolete, but has a number of descendents: d1088 2 a1089 2 trouble with man pages, try the \fIman\fR program on the companion CD-ROM (\fIutil/superman-1.1\fR). It recognizes all of the above name formats. d1147 2 a1148 2 frequently for five years, and I still find it the most frustrating program I have ever seen. d1156 2 a1157 1 LATEX is a macro package that is not quite as painful as plain d1221 6 a1226 27 \fIemacs\fR have both \fIinfo\fR and man pages. To quote the man page for \fIgcc\fR: .LP .QS \fIWARNING The information in this man page is an extract from the full documentation of the GNU C compiler, and is limited to the meaning of the options. This man page is not kept up to date except when volunteers want to maintain it. If you find a discrepancy between the man page and the software, please check the Info file, which is the authoritative documentation.\fR .QQE .LP When you consider that the man page for gcc is 3500 lines long (60 hardcopy pages, or nearly 150 standard terminal screens), you would probably like something better than \fIman\fR anyway. This is nothing by comparison to the 25000 lines in the \fIinfo\fR files: the GNU project takes documentation seriously. With documentation of this size (we're now talking about over 400 pages of documentation), you need some kind of structure. .Ah "Summary" Programmers hate documentation, and it seems that the methods they have found to write documents reflect this hate. Modern UNIX systems almost invariably supply documentation in \fInroff\fR, \fItroff\fR, .TXI \& or \fItexinfo\fR format. To get hardcopy documentation, you may need to run a number of additional programs. @ 2.0 log @checked in with -k by grog at 1995年01月09日 13:22:41 @ text @d2 1 a2 1 .\" $Id: documentation.ms,v 1.25 1994年12月21日 13:46:18 grog Exp grog $ a3 30 .\" Revision 1.25 1994年12月21日 13:46:18 grog .\" Revised, mods for bignuts macros .\" .\" Revision 1.24 1994年12月17日 16:26:31 grog .\" Major revision .\" .\" Revision 1.23 1994年10月17日 17:30:06 grog .\" *** empty log message *** .\" .\" Revision 1.22 1994年09月30日 17:58:33 grog .\" Snapshot 30 September 94 .\" .\" Revision 1.21 1994年09月01日 13:30:58 grog .\" Snapshot 1 September 1994 .\" .\" Revision 1.20 1994年08月25日 17:09:00 grog .\" Change all names from .roff to .ps, set uniform version number 1.20, minor mods .\" .\" Revision 1.4 1994年08月07日 12:00:30 grog .\" Change global.defs to global.roff .\" .\" Revision 1.3 1994年06月09日 13:33:19 grog .\" Get globals right .\" .\" Revision 1.2 1994年06月09日 12:44:34 grog .\" Minor updates .\" .\" Revision 1.1 1994年05月11日 17:20:31 grog .\" Initial revision .\" d8 1 a8 1 .St "Documentation ($Date: 1994年12月21日 13:46:18 $)" d24 3 a26 3 manual?". Programmers tend to consider documentation a necessary (or even unnecessary) evil, and if it gets done at all, it's usually the last thing that gets done. This is particularly evident when you look at the quality of d32 1 a32 1 describe what it is and how to install it. In this chapter, we'll concentrate on a38 1 \fIman pages\fR, d40 2 a41 2 the traditional on-line documentation for UNIX, which are formatted with \fInroff\fR. a44 1 \fIinfo\fR d47 1 a47 1 files, used with the GNU project's \fIinfo\fR on-line documentation d61 4 a64 4 We know where we want to get to--the printed documentation--but we don't always know where to start, so it's easier to look at documentation in reverse order: first, we'll look at the end result, then at the formatters, and finally at the input files. d86 3 d95 4 a98 3 format is obsolescent: most LaserJet printers made today also support PostScript, so there is little motivation for using the original format, which is much more restrictive. d107 1 a107 1 A large number of printers and most modern phototypesetters can process d111 2 a112 3 perform the real formatting. This requires high-performance microprocessors in the printer, of course, but it results in a considerable load reduction for the computer. d131 2 a132 2 Most PostScript files are written in plain ASCII without any control characters except \s10\f(CW\en\fR\s0 (though that doesn't mean they're easy to read). Even d146 1 a146 1 The data itself is embedded in parentheses between the commands. Looking at the d160 8 a167 7 \fIMissing fonts\fR: PostScript documents include information about the fonts they require. Many fonts are built in to printers and PostScript display software, but if the fonts are not present, the system chooses a default value which may have little in common with the font which the document requested. The default font is typically Courier, which is \s10\f(CWfixed-width\fR\s0, and the results look terrible. If this happens, you can find the list of required fonts with the following: d191 12 a202 6 this in PostScript format, and you can't reformat it, you will need to get the Garamond fonts in order to be able to print it. You could edit the document (for example, you might change the text \fIGaramond\fR to \fITimes Roman\fR). This will almost certainly look better than the default Courier, and it may even be legible, but don't expect it to look good. .LP d204 7 a210 5 \fIWrong font type\fR: \fIMost\fR PostScript fonts are in plain ASCII. Some, however, are in a form called \fIdisplay PostScript\fR, which includes binary data. Most printers can't understand this format, and they may react to it in an unfriendly way. For example, my National KXP 4455 printer just hangs if I copy display PostScript to it. d235 5 a239 6 \fIdevice-independent\fR format, and leave it to another program, a so-called \fIdriver\fR, to format the files in a format appropriate to the output device. The intermediate format is called \fI.dvi\fR, which stands for device independent. Unlike PostScript, it contains large numbers of control characters and characters with the sign bit set, and is not even remotely legible. Most versions of \fIfile\fR recognize the format. d243 1 d286 3 d309 1 a309 1 The usefulness of \fItroff\fR is somewhat limited by the fact that most versions d384 1 a384 1 .RS d388 2 a389 2 .nr VS 12p .vs 12p d415 1 a415 1 .RE d426 1 a426 1 .RS d447 1 a447 1 .RE d472 7 a478 7 \fItroff\fR either by environment variables or by instinct (in other words, the path name is compiled into the program). \fItroff\fR loads specific macros if you specify the name of the file as an argument to the \s10\f(CW-m\fR\s0 flag. For example, to specify the man page macros \fI/usr/lib/tmac/an\fR, you would supply \fItroff\fR with the parameter \s10\f(CW-man\fR\s0. \fIman\fR makes more sense than \fIan\fR, so these macros are called the \fIman\fR macros. The names of other packages also usually grow an \fIm\fR at the beginning. d520 18 a537 4 There is no definite way to tell which macros a file needs, but the file name suffix might give a hint. For example, our file is called \fIrcs.ms\fR, so there is a very good chance that it wants to be formatted with \s10\f(CW-ms\fR\s0. Let's try that: d543 1 a543 1 .RS d572 1 a572 1 .RE d655 1 a655 1 center, linesize(2), tab(#) ; d689 1 a689 1 lI | lw55 . d1002 1 a1002 1 BSD and the Seventh Edition it is in section 5. d1007 2 a1008 2 uninformative numbers with uninformative abbreviations. For example, \fIls(1)\fR becomes \fIls(C)\fR in XENIX. d1011 2 a1012 1 need to format them before installation. d1026 2 a1027 2 .XX "/opt/share/man, directory" .XX "directory, /opt/share/man" d1029 1 a1029 1 man pages in \fI/opt/share/man\fR. Many System V.4 systems require formatted d1039 4 a1042 4 non-formatted. For some reason, the \fIpack\fR program (see \*[chunpack], page \*[pack] for more details) still survives here, but other versions of \fIman\fR also understand man pages compressed with \fIcompress\fR or \fIgzip\fR (see \*[chunpack], pages \*[compress] and \*[gzip] respectively). d1100 1 a1100 1 .RS d1109 1 a1109 1 .RE d1145 4 a1148 4 identifier \s10\f(CWfontsize\fR\s0 followed by the number 300. On the other hand, it is almost impossible to find any good solid information in the documentation, so you could spend hours trying to solve a minor problem. I have been using d1164 2 a1165 2 using the technique of dumping a running program to an object file that we examined in \*[chobj], page \*[obj-dump]. d1226 1 a1226 1 .RS d1235 1 a1235 1 .RE @

AltStyle によって変換されたページ (->オリジナル) /