.\" @(#)intro.mex 1.1 92/07/30 SMI;.PL RIGHT.H C "Introduction to Manual Pages".IX "introduction to manual pages" "" "" "" PAGE START.H 2 "Overview".IX overview.LPThis chapter explainshow to create and maintain man pages,then discusses man page style.Following chapters describe manual sectionsand the man page requirements for each section..H 2 "Terms".IX terms.BR Argument :Letters or keywords supplied to one or more optionsthat affect the behavior of the option..br.BR Option :Letters or keywords supplied to a command thataffect the behavior of the command..H 2 "Creating A New Man Page".LP.IX "creating new manual pages".IX "man pages" creatingA sample template with the information necessaryto create a new man pageis in the current release machine:.LS/usr/src/man/policy/template/template.LE.TPA copy of the template is also in Appendix A.To create a man page, copy the template to yourhome directory and fill it inwith the help of instructions and comments.The template contains information and headers that youwon't need; delete the unnecessary data and comment lines(which begin with.L \&.\e"--- )as you create the page.To get a copy of this template with the commented instructionsremoved,simply execute the script:.LStemplate \fIfilename\fP.LEIf you supply a.I filenameargument,the stripped template will be put in a file of this name.Otherwise, the stripped template will be put in.L template.stripped ..LPWhen you have finished editing the page,forward it to the man pagewriters for final approval.They will add your page to theintroductory list and makefiles.They will then mail their editsback to you before the page is checked in on therelease machine..H 2 "Updating A Man Page".IX "updating man pages".IX "man pages" updating.LPUpdating an existing man page involves checkingthe page out from.SM SCCS(on the currentrelease machine),making the necessary changes, checking it back in, and notifingthe man page writers of the update..bp.LPMan pages sources reside in.LS/usr/src/man/man\fR[\fP1-8\fR]\fP.LPFor example, the source for the.BR lpr (1)man page is in the.L /usr/src/man/man1/lpr.1 file..LEThe material stored there is in the developmental stage and reflectsthe changes made since the last release..SM SCCSallows these changes to be made in an orderly fashionby recording who made what changes and when.Once updates have been made, the page needsto be checked in, and you should send mail to notifythe man page writersof your changes:.BS GRAY.LS 2release% \f(LBcd /usr.src/man/man1\fPrelease%  \f(LBsccs edit man.7\fP1.10new delta 1.11200 linesrelease% \f(LBvi man.7\fP                 \fImake updates\fP release% \f(LBsccs delget man.7\fPcomments? \fIexplain updates\fP1.1110 inserted2 deleted198 unchanged1.11208 lines release% \f(LBmail jah@caps\fPSubject: \f(LBupdates to man.7\fP         ...\f(LB^D\fPrelease%.LE.BE.LPWhen the man page writers receive your updatedpage, they will take care of cross-referencingit to other pagesas needed..H 2 Style.LP.IX style.IX "man pages" styleKeep in mind that the man pages comprise a.I referencemanual.Each man page is intended to answer concisely thequestion ``What does it do?''Do not write tutorials (as you would for abeginner), or detailed technical analyses of the internals.  Rememberthat the manual's audience is composed ofusers and programmers who need tofind something.I "fast" ..LPThe following are some style points to remember when writing or creatingman pages..IP \*(SQ 2.PD 0.I Alwaysuse the active voice,.I neverpassive.  Something is not.I causedto happen, the program or routine.I doesit..IP \*(SQ 2Use second orthird person to describe an action;.I neverpersonify machinery..IP \*(SQ 2Avoid contractions..IP \*(SQ 2Do not use Latin..IP \*(SQ 2.PD 0The first reference to a man page must include the section number.Thereafter, the section number may be omitted,.I exceptin the.SM "SEE ALSO"section,where.I allreferences to man pages must include the section number..IP \*(SQ 2Nested paragraphs are set off with`\(bu'(bullets), never numerals:.RS\&.TP 3\&\\&(buThis is text set off with a bullet as the ``tag''in a tagged paragraph (.TP)..RE.IP \*(SQ 2Section headers (declared with the.L "\&.SH"macro) and subsection headers (declared with the.L "\&.SS"macro) are followed by a new paragraph macro(\fL\&.LP\fP,.L \&.TP ,.L \&.IP ,or.L \&.HP )..IP \*(SQ 2References to other man pages appear in Bold font, with the numbers of thesections in which they appear in Roman..PD.IP.RS.RS.B man (1).RE.RE.IP \*(SQ 2``Warnings'' and ``notes'' to the reader appear in Roman font.Both must be printed as separateparagraphs using.L .LP ,followed by the word ``Warnings'' or ``Notes,''a colon, a space, and the text of the message:.IP.RS.RSNote: the.B \-xoption is retained for compatibility with earilierreleases.It's use is not recommended..RE.REPlease use notes sparingly..IP \*(SQ 2Use Italic font for emphasis.However, Bold font is acceptable for a severe warningabout a drastic situation..IP \*(SQ 2.PD 0Do not use`\fL<\fP\|\fL>\fP'(angle brackets)around variable placeholders.Use Italics instead.Angle brackets should only appearin C language program listings..IP \*(SQ 2.PD 0When refering to the C language, `C' is inRoman font..IP \*(SQ 2Single literal characters that could be confusedwith punctuation appear within `\|'(single quotes). There are three exceptions to thisrule:.L . ' `(periods),.L \- ' `(dashes) and multi-word literal stringswith embedded spaces.They.I alwaysappear within single quotes:.PD.IP.RS.RS.RB ` textedit.IR newfile '.RE.RE.IP \*(SQ 2To use a descriptive term,place the character in quotes and followit with the description in parentheses..IP.RS.RSThe `.' (dot) command.\|.\|..RE.RE.IP \*(SQ 2.PDEmpty grouping symbols (and other similar specialcharacters) are separated by a.L \e|space.IP.RS.PD 0.TStab(@) ;cL cL .to get:@use:[\|]@\fL[\e|]\fR(\|)@\fL(\e|)\fR|\||@\fL|\e||\fR.TE.RE.IP \*(SQ 2Escape dashes with a backslashin width declarations:\(lqThe.L \e-option...\(rq.brEnter hyphens unescaped:\(lqtime-honored tradition\(rq.IP.RS.RS.PD 0.TStab(@) ;c l lw(30) .to get:@use:@description:`-'@\fL-\fP@hyphen`\-'@\fL\e-\fP@T{dash, range indicator,precedes some options, etc.T}`\(em'@\fL\e(em\fP@T{dash to show a break in sentence structure,filename argumentT}.TE.PD.RE.RE.IP \*(SQ 2Terminal modes, such as.SM CBREAK ,.SM "NOECHO" ,etc., are printed using the.L .SMmacro..RE.PD.br.\".ne 30.\".H 2 ORDERING.\".RE.\".LP.\".IX ordering.\".IX "man pages" ordering.\"Here is a list of the of section.\"headings in their proper order..\"All of the sections follow this order,.\"but where a heading is not needed,.\"it is not used..\"For example,.\"if there are no bugs to report for a command,.\"there is no need for a.\".SM BUGS.\"Section..\".RS.\".RS.\".IP.\".nf.\".SM NAME.\"\s-1CONFIGURATION\s+1 (\fISection 4 only\fP).\".SM SYNOPSIS.\".SM "SYSTEM V SYNOPSIS".\"\s-1PROTOCOL\s+1 (\fISection 3R only\fP).\".SM AVAILABILITY.\".SM DESCRIPTION.\".SM "SYSTEM V DESCRIPTION".\"\s-1IOCTLS\s+1 (\fISection 4 only\fP).\".SM OPTIONS.\".SM "SYSTEM V OPTIONS".\"\s-1RETURN VALUE\s+1 (\fISections 2 and 3 only\fP).\"\s-1ERRORS\s+1 (\fISections 2, 3, and 4 only\fP).\".SM USAGE.\".sp .5.\".RS.\".nf.\"Commands.\"Modifiers.\"Variables.\"Expressions.\"Input Grammar.\".RE.\".sp .5.\".nf.\".SM EXAMPLE(S).\".SM ENVIRONMENT.\".SM FILES.\".SM "SEE ALSO".\".SM DIAGNOSTICS.\".SM WARNINGS.\".SM NOTES.\".SM BUGS.\".fi.\".RE.\".RE.\".LP.\".I Note :.\"the.\".SM USAGE.\"heading frequently contains subsections (listed with.\".L \&.SS )..\".LP.\".IX "introduction to manual pages" "" "" "" PAGE END.\"The specifications in these headings vary slightly from section.\"to section; the differences are.\"covered in the section descriptions below.