1(This file written by Nelson H. F. Beebe <beebe@math.utah.edu>.) 2 3This directory contains UNIX manual pages for TeXware and MFware. 4 5Here are some guidelines for writing UNIX manual page files, based on 6the standards used by Sun Microsystems. The manual pages in this 7directory have been revised to conform to these guidelines. 8 9*** The sections of a manual page are identified by these headings: 10 11.TH PROGRAM 1 "dd month yyyy" 12.SH NAME 13.SH SYNOPSIS 14.SH DESCRIPTION 15.SH OPTIONS 16.SH ENVIRONMENT 17.SH FILES 18.SH "SEE ALSO" 19.SH AUTHOR 20 21Additional sections may be supplied, but the above section order 22should be preserved. If you are adding a new section, try to find 23several examples in existing UNIX manual pages to justify the header 24name you choose. 25 26To improve readability of the [nt]roff man page files in this 27directory, each section header has been prefixed by a comment line of 28the form 29.\"===================================================================== 30 31 32------------------------------------------------------------------------ 33 34*** The 35 36.TH PROGRAM 1 "dd month yyyy" 37 38line should be the first [nt]roff dotted command in the .man file, 39other than comments, which begin with the 3-character sequence .\". 40 41The PROGRAM name should be spelled entirely in uppercase letters. 42 43The single character following PROGRAM is the manual page section, 44generally 1 for user commands. Any character from the set [1-8nl] is 45recognized by the UNIX man command, but the sections have specific 46meanings (1=user commands, 2=system calls, 3=library routines, 4=special 47files, 5=file formats and conventions, 6=games, 7=macro packages and 48language conventions, 8=maintenance, l=local, and n=new). 49 50Historically, man page files were stored in /usr/man/man[1-8nl], with 51local additions to /usr/man/manl. That approach offered no 52subdivision of local additions into sections, so the trend today is to 53leave the /usr/man tree in the state supplied by the vendor, and to 54maintain a separate tree, /usr/man/man[1-8nl], to hold local 55additions. Most UNIX man implementations support a MANPATH variable 56to specify a search path, such as /usr/man:/usr/local/man. 57 58If your man command doesn't support a MANPATH variable, get the 59freely-available man implementation man-1.0.tar.Z available on several 60Internet archive sites, including gatekeeper.dec.com in 61/.8/GNU/man-1.0.tar.Z. Some bugs exist in that version, and fixes were 62supplied to the program's author on 12 December 1992, so look for a new 63version, or ask Nelson Beebe <beebe@math.utah.edu> for a set of patches. 64This new man implementation has some nice features, including support 65for compressed files, and checking of formatted and raw file time stamps 66to decide whether to reformat or not. Furthermore, it can be configured 67to use either [nt]roff, or GNU groff; some UNIX vendors charge extra for 68[nt]roff, so groff may offer a cheaper man page implementation. 69 70The last argument to .TH is the date in the form 01 December 1992; the 71month is NOT abbreviated. 72 73 74------------------------------------------------------------------------ 75 76*** Following 77.SH NAME 78should be a single line with NO macros, such as 79 80bibtex \- make a bibliography for (La)TeX 81 82This line is very important, because it is used by the "man -k" and 83"apropos" commands to look up commands by keywords; every word in the 84line is a potential keyword match. 85 86 87------------------------------------------------------------------------ 88 89*** Following 90.SH SYNOPSIS 91there should be one or more lines in the form 92 93.B vftovp 94[ 95.B \-verbose 96] 97[ 98.BI \-charcode-format =format 99] 100.I vf_file_name 101.I tfm_file_name 102[ 103.I vpl_file_name 104] 105 106Program names and option switches are typeset in bold type (.B), and 107file names in italics (.I). Switch values are in italics. 108 109Give option switches in alphabetical order in the SYNOPSIS 110section, and their descriptions in the same order in the OPTIONS 111section. 112 113 114------------------------------------------------------------------------ 115 116*** Here are some general [nt]roff hints for writing the 117.SH DESCRIPTION 118section. 119 120 121*** Separate paragraphs by a .PP command, not by blank lines. 122 123 124*** When using the multi-font selectors, like .BI (bold, then italic), 125remember that fonts alternate in the following space-separated words: 126 127.BI aaa bbb ccc ddd 128 129will typeset aaa and cccc in bold, and bbb and ddd in italic, with NO 130intervening spaces, so the result here will be aaabbbcccddd. If you 131want spaces between the words, use quotation marks: 132 133.BI "aaa " "bbb " "ccc " ddd 134 135will produce aaa bbb ccc ddd. 136 137Use [nt]roff dotted font change sequences (.I, .B, .BI, .BR, ...) 138instead of the \fX...\fP alternatives. The single exception is when 139you need quotation marks in italics, such as \fIsetenv FOOBAR "foo 140bar"\fP. 141 142 143*** Represent en dashes by the current font minus (\-), and use the 144same character in front of option switches. Hyphens in words, as 145``multi-font'', are written with the ASCII minus sign. 146 147 148*** Quotation marks are [nt]roff grouping commands, analogous to curly 149braces in TeX files. They will NOT survive in the formatted output. 150If you want typeset quotation marks, use ``phrase'', just as in TeX. 151 152 153*** Ellipses (...) in [nt]roff are coded as .\|.\|., for the same 154reason that \ldots{} is used in TeX instead of .... 155 156 157*** UNIX is a trademark of AT&T Bell Laboratories and must be spelled 158in uppercase letters. 159 160 161*** Watch out for spaces. Unlike TeX, [nt]roff preserve ALL input 162spaces. This means you cannot indent [nt]roff input for readability. 163Two spaces should follow a sentence-ending period, and otherwise, only 164one space should be used. Tabs are special in [nt]roff; they are used 165to separate columns of tables, like & in TeX, and no other character 166can be used for that purpose. The man page files in this directory 167contain no tabs, and trailing blanks have been stripped from all 168files. 169 170 171*** Do not used fixed indentation dimensions for displayed material. 172Instead, use .RS and .RE to mark the indented paragraphs, with .IP to 173separate paragraphs: 174 175.RS 176Blah blah blah blah blah blah blah blah blah. 177Blah blah blah blah blah blah blah blah blah. 178.IP 179Blah blah blah blah blah blah blah blah blah. 180Blah blah blah blah blah blah blah blah blah. 181.RE 182 183 184*** Use macros for phrases that require special typesetting, such as 185the TeX logo, and provide both nroff and troff definitions: 186 187.if n .ds AB nroff-definition 188.if t .ds AB troff-definition 189 190Macro names are exactly 2 characters long, and are referenced by \*( 191prefixed to their names, e.g. \*(AB. 192 193If a macro expansion requires another macro, it must be given after 194that macro. For example, the BibTeX and LaTeX macros follow the TeX 195macro so they can use \*(TX in their definitions. 196 197Suitable macros have been provided for TeX, BibTeX, LaTeX, Metafont, 198and Web, and adjusted for troff's default Times Roman typeface to 199match their appearance with Computer Modern typefaces. 200 201 202------------------------------------------------------------------------ 203 204*** The 205.SH ENVIRONMENT 206section should list all the relevant environment variables, with a brief 207description and system defaults if appropriate. 208 209 210*** Environment variables are spelled in uppercase letters, e.g., 211TEXFONTS, and NO font size changes are made around them. When font 212sizes were changed in the past, many inconsistencies were present, so 213the practice has been abandoned. 214 215 216*** Do not use fixed dimensions for indented labelled paragraphs. 217Instead, use the width of the longest label, plus 2n, as follows: 218 219.TP \w'LONGESTLABEL'u+2n 220LABEL 221Blah blah blah blah blah blah blah blah blah. 222.TP 223LONGESTLABEL 224Blah blah blah blah blah blah blah blah blah. 225Blah blah blah blah blah blah blah blah blah. 226 227If the longest label is extremely long, pick a somewhat shorter one so 228as to avoid having very short paragraph lines. 229 230 231------------------------------------------------------------------------ 232 233*** Spell TeX control sequences in Roman letters, doubling the 234backslash, e.g. \\input, or for better visibility, use italics 235with the backslash represented as \e: 236 237.I \einput 238 239Although some [nt]roff implementations support a typewriter font which 240is conventional for TeX control sequences, historically only roman, 241bold, italic, and special fonts were available. 242 243 244*** These manual pages in the *.man form are filtered by sedscript to 245expand @XYZ@ into something else, producing corresponding *.1 files 246which are installed in the system manual page directories. This is 247used to insert local paths into the manual pages, so that for example 248@TEXINPUTS@ is replaced by the local default TEXINPUTS search path. 249Such paths are set at installation time in the top-level Makefile. 250 251 252*** You can use the UNIX checknr utility to do a rudimentary validation of 253your manual page files, e.g. 254 255 checknr -c.BI.BR.IR.IB.RB.RI tex.man 256 257The -c.BI.BR.IR.IB.RB.RI is needed because checknr doesn't know about 258the -man document style, and otherwise complains about those font 259change commands. The command "make check" will run checknr with each 260of the *.1 files. 261