=================================================================== RCS file: /cvs/mandoc/man.7,v retrieving revision 1.125 retrieving revision 1.135 diff -u -p -r1.125 -r1.135 --- mandoc/man.7 2014/03/17 06:57:48 1.125 +++ mandoc/man.7 2017/05/07 21:44:49 1.135 @@ -1,7 +1,7 @@ -.\" $Id: man.7,v 1.125 2014/03/17 06:57:48 schwarze Exp $ +.\" $Id: man.7,v 1.135 2017/05/07 21:44:49 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons -.\" Copyright (c) 2011, 2012, 2013 Ingo Schwarze +.\" Copyright (c) 2011-2015 Ingo Schwarze .\" Copyright (c) 2010 Joerg Sonnenberger .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -16,7 +16,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: March 17 2014 $ +.Dd $Mdocdate: May 7 2017 $ .Dt MAN 7 .Os .Sh NAME @@ -106,6 +106,8 @@ file for a utility \efBprogname\efR [\efB\e-options\efR] \efIfile ...\efR \&.SH DESCRIPTION The \efBfoo\efR utility processes files ... +\&.\e\(dq .Sh CONTEXT +\&.\e\(dq For section 9 functions only. \&.\e\(dq .SH IMPLEMENTATION NOTES \&.\e\(dq Not used in OpenBSD. \&.\e\(dq .SH RETURN VALUES @@ -171,6 +173,9 @@ This expands upon the brief, one-line description in .Em NAME . It usually contains a break-down of the options (if documenting a command). +.It Em CONTEXT +This section lists the contexts in which functions can be called in section 9. +The contexts are autoconf, process, or interrupt. .It Em IMPLEMENTATION NOTES Implementation-specific notes should be kept here. This is useful when implementing standard functions that may have side @@ -261,8 +266,6 @@ in the alphabetical reference below. .It Sx TP Ta tagged paragraph: Op Ar width .It Sx HP Ta hanged paragraph: Op Ar width .It Sx PD Ta set vertical paragraph distance: Op Ar height -.It Sx \&br Ta force output line break in text mode (no arguments) -.It Sx \&sp Ta force vertical space: Op Ar height .It Sx fi , nf Ta fill mode and no-fill mode (no arguments) .It Sx in Ta additional indent: Op Ar width .El @@ -345,8 +348,12 @@ See also and .Sx \&IR . .Ss \&DT -Has no effect. -Included for compatibility. +Restore the default tabulator positions. +They are at intervals of 0.5 inches. +This has no effect unless the tabulator positions were changed with the +.Xr roff 7 +.Ic \&ta +request. .Ss \&EE This is a non-standard GNU extension, included only for compatibility. In @@ -364,11 +371,11 @@ Begin a paragraph whose initial output line is left-ju subsequent output lines are indented, with the following syntax: .Bd -filled -offset indent .Pf \. Sx \&HP -.Op Cm width +.Op Ar width .Ed .Pp The -.Cm width +.Ar width argument is a .Xr roff 7 scaling width. @@ -408,11 +415,11 @@ and Begin an indented paragraph with the following syntax: .Bd -filled -offset indent .Pf \. Sx \&IP -.Op Cm head Op Cm width +.Op Ar head Op Ar width .Ed .Pp The -.Cm width +.Ar width argument is a .Xr roff 7 scaling width defining the left margin. @@ -420,7 +427,7 @@ It's saved for later paragraph left-margins; if unspec default width is used. .Pp The -.Cm head +.Ar head argument is used as a leading term, flushed to the left margin. This is useful for bulleted paragraphs and so on. .Pp @@ -465,13 +472,13 @@ This is a non-standard GNU extension, included only fo It has the following syntax: .Bd -filled -offset indent .Pf \. Sx \&OP -.Cm key Op Cm value +.Ar key Op Ar value .Ed .Pp The -.Cm key +.Ar key is usually a command-line flag and -.Cm value +.Ar value its argument. .Ss \&P Synonym for @@ -490,11 +497,11 @@ Specify the vertical space to be inserted before each The syntax is as follows: .Bd -filled -offset indent .Pf \. Sx \&PD -.Op Cm height +.Op Ar height .Ed .Pp The -.Cm height +.Ar height argument is a .Xr roff 7 scaling width. @@ -550,9 +557,29 @@ and .Ss \&RE Explicitly close out the scope of a prior .Sx \&RS . -The default left margin is restored to the state of the original +The default left margin is restored to the state before that .Sx \&RS invocation. +.Pp +The syntax is as follows: +.Bd -filled -offset indent +.Pf \. Sx \&RE +.Op Ar level +.Ed +.Pp +Without an argument, the most recent +.Sx \&RS +block is closed out. +If +.Ar level +is 1, all open +.Sx \&RS +blocks are closed out. +Otherwise, +.Ar level No \(mi 1 +nested +.Sx \&RS +blocks remain open. .Ss \&RI Text is rendered alternately in roman (the default font) and italics. Whitespace between arguments is omitted in output. @@ -573,11 +600,11 @@ Temporarily reset the default left margin. This has the following syntax: .Bd -filled -offset indent .Pf \. Sx \&RS -.Op Cm width +.Op Ar width .Ed .Pp The -.Cm width +.Ar width argument is a .Xr roff 7 scaling width. @@ -602,7 +629,8 @@ The scope of a sub-section is closed by a subsequent s section, or end of file. The paragraph left-margin width is reset to the default. .Ss \&TH -Sets the title of the manual page with the following syntax: +Sets the title of the manual page for use in the page header +and footer with the following syntax: .Bd -filled -offset indent .Pf \. Sx \&TH .Ar title section date @@ -624,6 +652,11 @@ is empty or not specified, the current date is used. The optional .Ar source string specifies the organisation providing the utility. +When unspecified, +.Xr mandoc 1 +uses its +.Fl Ios +argument. The .Ar volume string replaces the default rendered volume, which is dictated by the @@ -640,11 +673,11 @@ Subsequent output lines are indented. The syntax is as follows: .Bd -filled -offset indent .Pf \. Sx \&TP -.Op Cm width +.Op Ar width .Ed .Pp The -.Cm width +.Ar width argument is a .Xr roff 7 scaling width. @@ -677,27 +710,19 @@ It has the following syntax: link description to be shown .Pf \. Sx UE .Ed -.Ss \&br -Breaks the current line. -Consecutive invocations have no further effect. -.Pp -See also -.Sx \&sp . .Ss \&fi End literal mode begun by .Sx \&nf . .Ss \&in Indent relative to the current indentation: .Pp -.D1 Pf \. Sx \&in Op Cm width +.D1 Pf \. Sx \&in Op Ar width .Pp If -.Cm width +.Ar 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 Begin literal mode: all subsequent free-form lines have their end of line boundaries preserved. @@ -707,24 +732,6 @@ Literal mode is implicitly ended by .Sx \&SH or .Sx \&SS . -.Ss \&sp -Insert vertical spaces into output with the following syntax: -.Bd -filled -offset indent -.Pf \. Sx \&sp -.Op Cm height -.Ed -.Pp -The -.Cm height -argument is a scaling width as described in -.Xr roff 7 . -If 0, this is equivalent to the -.Sx \&br -macro. -Defaults to 1, if unspecified. -.Pp -See also -.Sx \&br . .Sh MACRO SYNTAX The .Nm @@ -748,11 +755,7 @@ is equivalent to .Sq \&.I foo . If next-line macros are invoked consecutively, only the last is used. If a next-line macro is followed by a non-next-line macro, an error is -raised, except for -.Sx \&br , -.Sx \&sp , -and -.Sx \&na . +raised. .Pp The syntax is as follows: .Bd -literal -offset indent @@ -780,12 +783,9 @@ The syntax is as follows: .It Sx \&SM Ta n Ta next-line Ta \& .It Sx \&TH Ta >1, <6 Ta current Ta \& .It Sx \&UC Ta <=1 Ta current Ta \& -.It Sx \&br Ta 0 Ta current Ta compat .It Sx \&fi Ta 0 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 \&sp Ta 1 Ta current Ta compat .El .Pp Macros marked as @@ -867,82 +867,6 @@ until the end of the macro scope. Note that macros like .Sx \&BR open and close a font scope for each argument. -.Sh COMPATIBILITY -This section documents areas of questionable portability between -implementations of the -.Nm -language. -.Pp -.Bl -dash -compact -.It -Do not depend on -.Sx \&SH -or -.Sx \&SS -to close out a literal context opened with -.Sx \&nf . -This behaviour may not be portable. -.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 , -.Sq \ek -.Pq horizontal position marker , -.Sq \eo -.Pq text overstrike , -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 -In page header lines, GNU troff versions up to and including 1.21 -only print -.Ar volume -names explicitly specified in the -.Sx \&TH -macro; mandoc and newer groff print the default volume name -corresponding to the -.Ar section -number when no -.Ar volume -is given, like in -.Xr mdoc 7 . -.El -.Pp -The -.Sx OP -macro is part of the extended -.Nm -macro set, and may not be portable to non-GNU troff implementations. .Sh SEE ALSO .Xr man 1 , .Xr mandoc 1 ,