=================================================================== RCS file: /cvs/mandoc/man.7,v retrieving revision 1.78 retrieving revision 1.84 diff -u -p -r1.78 -r1.84 --- mandoc/man.7 2010/07/19 23:21:39 1.78 +++ mandoc/man.7 2010/08/24 13:07:01 1.84 @@ -1,4 +1,4 @@ -.\" $Id: man.7,v 1.78 2010/07/19 23:21:39 schwarze Exp $ +.\" $Id: man.7,v 1.84 2010/08/24 13:07:01 kristaps Exp $ .\" .\" Copyright (c) 2009, 2010 Kristaps Dzonsons .\" @@ -14,7 +14,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: July 19 2010 $ +.Dd $Mdocdate: August 24 2010 $ .Dt MAN 7 .Os .Sh NAME @@ -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 kept here. 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. @@ -341,23 +338,21 @@ If not adhering to any standards, the .Em HISTORY section should be used. .It Em HISTORY -The history of any manual without a -.Em STANDARDS -section should be described in this section. +A brief history of the subject, including where support first appeared. .It Em AUTHORS -Credits to authors, if applicable, should appear in this section. +Credits to the person or persons who wrote the code and/or documentation. Authors should generally be noted by both name and email address. .It Em CAVEATS 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. @@ -427,6 +422,7 @@ The syntax is as follows: .It Sx \&br Ta 0 Ta current Ta compat .It Sx \&fi Ta 0 Ta current Ta compat .It Sx \&i Ta n Ta current Ta compat +.It Sx \&in Ta 1 Ta current Ta compat .It Sx \&na Ta 0 Ta current Ta compat .It Sx \&nf Ta 0 Ta current Ta compat .It Sx \&r Ta 0 Ta current Ta compat @@ -444,8 +440,8 @@ These macros should not be used for portable .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 +598,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 @@ -626,7 +622,7 @@ Begin an indented paragraph with the following syntax: 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 @@ -853,6 +849,16 @@ See also .Sx \&b , and .Sx \&r . +.Ss \&in +Indent relative to the current indentation: +.Pp +.D1 Pf \. Sx \&in Op Cm width +.Pp +If +.Cm width +is signed, the new offset is relative. +Otherwise, it is absolute. +This value is reset upon the next paragraph, section, or sub-section. .Ss \&na Don't align to the right margin. .Ss \&nf @@ -911,24 +917,42 @@ language. .Pp .Bl -dash -compact .It -The \es (font size), \em (font colour), and \eM (font filling colour) -font decoration escapes are all discarded in mandoc. -.It In quoted literals, GNU troff allowed pair-wise double-quotes to produce a standalone double-quote in formatted output. It is not known whether this behaviour is exhibited by other formatters. .It +troff suppresses a newline before +.Sq \(aq +macro output; in mandoc, it is an alias for the standard +.Sq \&. +control character. +.It The +.Sq \eh +.Pq horizontal position , +.Sq \ev +.Pq vertical position , +.Sq \em +.Pq text colour , +.Sq \eM +.Pq text filling colour , +.Sq \ez +.Pq zero-length character , +.Sq \ew +.Pq string length , +and +.Sq \es +.Pq text size +escape sequences are all discarded in mandoc. +.It +The +.Sq \ef +scaling unit is accepted by mandoc, but rendered as the default unit. +.It +The .Sx \&sp macro does not accept negative values in mandoc. In GNU troff, this would result in strange behaviour. -.It -The -.Sq \(aq -macro control character, in GNU troff (and prior troffs) suppresses a -newline before macro output; in mandoc, it is an alias for the standard -.Sq \&. -control character. .El .Sh SEE ALSO .Xr mandoc 1 , @@ -943,7 +967,7 @@ It was later rewritten by James Clark as a macro packa 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