From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from krisdoz.my.domain (kristaps@localhost [127.0.0.1]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id o6QA03Kx014918 for ; Mon, 26 Jul 2010 06:00:04 -0400 (EDT) Received: (from kristaps@localhost) by krisdoz.my.domain (8.14.3/8.14.3/Submit) id o6QA03gJ016033; Mon, 26 Jul 2010 06:00:03 -0400 (EDT) Date: Mon, 26 Jul 2010 06:00:03 -0400 (EDT) Message-Id: <201007261000.o6QA03gJ016033@krisdoz.my.domain> X-Mailinglist: mdocml-source Reply-To: source@mdocml.bsd.lv MIME-Version: 1.0 From: kristaps@mdocml.bsd.lv To: source@mdocml.bsd.lv Subject: mdocml: Merge Jason McIntyre's corrections to man.7. X-Mailer: activitymail 1.26, http://search.cpan.org/dist/activitymail/ Content-Type: text/plain; charset=utf-8 Log Message: ----------- Merge Jason McIntyre's corrections to man.7. "urgle": Jason McIntyre. "This is all ok" schwarze@. Modified Files: -------------- mdocml: man.7 Revision Data ------------- Index: man.7 =================================================================== RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/man.7,v retrieving revision 1.79 retrieving revision 1.80 diff -Lman.7 -Lman.7 -u -p -r1.79 -r1.80 --- man.7 +++ man.7 @@ -111,7 +111,7 @@ The 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 @@ this differs from 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 @@ Implementation-specific notes should be 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 @@ Documents files used. 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 @@ a practise that is now discouraged. 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 @@ Authors should generally be noted by bot 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. @@ -445,8 +442,8 @@ These macros should not be used for port .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). @@ -603,8 +600,8 @@ See also 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 @@ -627,7 +624,7 @@ Begin an indented paragraph with the fol 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 @@ -954,7 +951,7 @@ It was later rewritten by James Clark as 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 source+unsubscribe@mdocml.bsd.lv