From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp1.rz.uni-karlsruhe.de (Debian-exim@smtp1.rz.uni-karlsruhe.de [129.13.185.217]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id o6OIlxRC008472 for ; Sat, 24 Jul 2010 14:48:03 -0400 (EDT) Received: from hekate.usta.de (asta-nat.asta.uni-karlsruhe.de [172.22.63.82]) by smtp1.rz.uni-karlsruhe.de with esmtp (Exim 4.63 #1) id 1OcjlM-00021x-LY; Sat, 24 Jul 2010 20:47:58 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.71) (envelope-from ) id 1OcjlM-0007uw-JR for discuss@mdocml.bsd.lv; Sat, 24 Jul 2010 20:47:56 +0200 Received: from iris.usta.de ([172.24.96.5] helo=usta.de) by donnerwolke.usta.de with esmtp (Exim 4.69) (envelope-from ) id 1OcjlM-00024f-Id for discuss@mdocml.bsd.lv; Sat, 24 Jul 2010 20:47:56 +0200 Received: from schwarze by usta.de with local (Exim 4.71) (envelope-from ) id 1OcjlM-0004b4-Cr for discuss@mdocml.bsd.lv; Sat, 24 Jul 2010 20:47:56 +0200 Date: Sat, 24 Jul 2010 20:47:56 +0200 From: Ingo Schwarze To: discuss@mdocml.bsd.lv Subject: Re: man.7 tweaks Message-ID: <20100724184756.GA5802@iris.usta.de> References: <20100724133216.GA15380@bramka.kerhand.co.uk> <20100724135918.GC26858@iris.usta.de> <20100724145103.GA23978@bramka.kerhand.co.uk> X-Mailinglist: mdocml-discuss Reply-To: discuss@mdocml.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20100724145103.GA23978@bramka.kerhand.co.uk> User-Agent: Mutt/1.5.20 (2009-06-14) This is all ok schwarze@. Kristaps, if you like it, go ahead and commit to both repositories. Jason McIntyre wrote on Sat, Jul 24, 2010 at 03:50:39PM +0059: > Index: man.7 > =================================================================== > RCS file: /cvs/src/share/man/man7/man.7,v > retrieving revision 1.3 > diff -u -r1.3 man.7 > --- man.7 19 Jul 2010 23:06:29 -0000 1.3 > +++ man.7 24 Jul 2010 13:23:14 -0000 > @@ -111,7 +111,7 @@ > attribute is forgotten when entering or exiting a macro block. > .Ss Whitespace > Whitespace consists of the space character. > -In free-form lines, whitespace is preserved within a line; un-escaped > +In free-form lines, whitespace is preserved within a line; unescaped > trailing spaces are stripped from input (unless in a literal context). > Blank free-form lines, which may include spaces, are permitted and > rendered as an empty line. > @@ -190,23 +190,25 @@ > which, if a unit is not provided, will instead interpret the string as > literal text. > .Ss Sentence Spacing > -When composing a manual, make sure that your sentences end at the end of > +When composing a manual, make sure that sentences end at the end of > a line. > By doing so, front-ends will be able to apply the proper amount of > spacing after the end of sentence (unescaped) period, exclamation mark, > or question mark followed by zero or more non-sentence closing > -delimiters ( > -.Ns Sq \&) , > +delimiters > +.Po > +.Sq \&) , > .Sq \&] , > .Sq \&' , > -.Sq \&" ) . > +.Sq \&" > +.Pc . > .Sh MANUAL STRUCTURE > Each > .Nm > -document must contain contains at least the > +document must contain the > .Sx \&TH > macro describing the document's section and title. > -It may occur anywhere in the document, although conventionally, it > +It may occur anywhere in the document, although conventionally it > appears as the first macro. > .Pp > Beyond > @@ -291,10 +293,7 @@ > This is useful when implementing standard functions that may have side > effects or notable algorithmic implications. > .It Em RETURN VALUES > -This section is the dual of > -.Em EXIT STATUS , > -which is used for commands. > -It documents the return values of functions in sections 2, 3, and 9. > +This section documents the return values of functions in sections 2, 3, and 9. > .It Em ENVIRONMENT > Documents any usages of environment variables, e.g., > .Xr environ 7 . > @@ -303,10 +302,8 @@ > It's helpful to document both the file name and a short description of how > the file is used (created, modified, etc.). > .It Em EXIT STATUS > -Command exit status for section 1, 6, and 8 manuals. > -This section is the dual of > -.Em RETURN VALUES , > -which is used for functions. > +This section documents the command exit status for > +section 1, 6, and 8 utilities. > Historically, this information was described in > .Em DIAGNOSTICS , > a practise that is now discouraged. > @@ -314,7 +311,7 @@ > Example usages. > This often contains snippets of well-formed, > well-tested invocations. > -Make doubly sure that your examples work properly! > +Make sure that examples work properly! > .It Em DIAGNOSTICS > Documents error conditions. > This is most useful in section 4 manuals. > @@ -351,13 +348,13 @@ > Common misuses and misunderstandings should be explained > in this section. > .It Em BUGS > -Known bugs, limitations and work-arounds should be described > +Known bugs, limitations, and work-arounds should be described > in this section. > .It Em SECURITY CONSIDERATIONS > Documents any security precautions that operators should consider. > .El > .Sh MACRO SYNTAX > -Macros are one to three three characters in length and begin with a > +Macros are one to three characters in length and begin with a > control character, > .Sq \&. , > at the beginning of the line. > @@ -444,8 +441,8 @@ > .Nm > manuals. > .Ss Block Macros > -Block macros are comprised of a head and body. > -Like for in-line macros, the head is scoped to the current line and, in > +Block macros comprise a head and body. > +As with in-line macros, the head is scoped to the current line and, in > one circumstance, the next line (the next-line stipulations as in > .Sx Line Macros > apply here as well). > @@ -602,8 +599,8 @@ > and > .Sx \&r . > .Ss \&IB > -Text is rendered alternately in italics and bold face. Whitespace > -between arguments is omitted in output. > +Text is rendered alternately in italics and bold face. > +Whitespace between arguments is omitted in output. > .Pp > See > .Sx \&BI > @@ -626,7 +623,7 @@ > The > .Cm width > argument defines the width of the left margin and is defined by > -.Sx Scaling Widths , > +.Sx Scaling Widths . > It's saved for later paragraph left-margins; if unspecified, the saved or > default width is used. > .Pp > @@ -943,7 +940,7 @@ > The stand-alone implementation that is part of the > .Xr mandoc 1 > utility written by Kristaps Dzonsons appeared in > -.Ox 4.6. > +.Ox 4.6 . > .Sh AUTHORS > This > .Nm -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv