=================================================================== RCS file: /cvs/mandoc/man.7,v retrieving revision 1.129 retrieving revision 1.139 diff -u -p -r1.129 -r1.139 --- mandoc/man.7 2015/01/24 01:58:33 1.129 +++ mandoc/man.7 2018/08/18 02:08:27 1.139 @@ -1,7 +1,8 @@ -.\" $Id: man.7,v 1.129 2015/01/24 01:58:33 schwarze Exp $ +.\" $Id: man.7,v 1.139 2018/08/18 02:08:27 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons -.\" Copyright (c) 2011-2015 Ingo Schwarze +.\" Copyright (c) 2011-2015, 2017, 2018 Ingo Schwarze +.\" Copyright (c) 2017 Anthony Bentley .\" Copyright (c) 2010 Joerg Sonnenberger .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -16,7 +17,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: January 24 2015 $ +.Dd $Mdocdate: August 18 2018 $ .Dt MAN 7 .Os .Sh NAME @@ -266,8 +267,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 @@ -275,7 +274,6 @@ in the alphabetical reference below. .Bl -column "PP, LP, P" description .It Sx B Ta boldface font .It Sx I Ta italic font -.It Sx R Ta roman (default) font .It Sx SB Ta small boldface font .It Sx SM Ta small roman font .It Sx BI Ta alternate between boldface and italic fonts @@ -299,9 +297,7 @@ The optional arguments specify which release it is fro Text is rendered in bold face. .Pp See also -.Sx \&I -and -.Sx \&R . +.Sx \&I . .Ss \&BI Text is rendered alternately in bold face and italic. Thus, @@ -350,8 +346,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 @@ -369,11 +369,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. @@ -391,9 +391,7 @@ and Text is rendered in italics. .Pp See also -.Sx \&B -and -.Sx \&R . +.Sx \&B . .Ss \&IB Text is rendered alternately in italics and bold face. Whitespace between arguments is omitted in output. @@ -413,11 +411,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. @@ -425,7 +423,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 @@ -464,19 +462,33 @@ See also .Sx \&PP , and .Sx \&TP . +.Ss \&ME +End a mailto block. +This is a non-standard GNU extension, included only for compatibility. +See +.Sx \&MT . +.Ss \&MT +Begin a mailto block. +This is a non-standard GNU extension, included only for compatibility. +It has the following syntax: +.Bd -literal -offset indent +.Pf \. Sx \&MT Ar address +link description to be shown +.Pf \. Sx ME +.Ed .Ss \&OP Optional command-line argument. This is a non-standard GNU extension, included only for compatibility. 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 @@ -495,11 +507,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. @@ -530,13 +542,6 @@ See also .Sx \&P , and .Sx \&TP . -.Ss \&R -Text is rendered in roman (the default font). -.Pp -See also -.Sx \&I -and -.Sx \&B . .Ss \&RB Text is rendered alternately in roman (the default font) and bold face. Whitespace between arguments is omitted in output. @@ -598,11 +603,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. @@ -626,6 +631,18 @@ Begin a sub-section. The scope of a sub-section is closed by a subsequent sub-section, section, or end of file. The paragraph left-margin width is reset to the default. +.Ss \&SY +Begin a synopsis block with the following syntax: +.Bd -unfilled -offset indent +.Pf \. Sx \&SY Ar command +.Ar arguments +.Pf \. Sx \&YS +.Ed +.Pp +This is a non-standard GNU extension +and very rarely used even in GNU manual pages. +Formatting is similar to +.Sx \&IP . .Ss \&TH Sets the title of the manual page for use in the page header and footer with the following syntax: @@ -671,11 +688,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. @@ -689,6 +706,12 @@ See also .Sx \&P , and .Sx \&PP . +.Ss \&TQ +Like +.Sx \&TP , +except that no vertical spacing is inserted before the paragraph. +This is a non-standard GNU extension and rarely used even by GNU +manual pages. .Ss \&UC Sets the volume for the footer for compatibility with man pages from .Bx @@ -708,27 +731,23 @@ 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 \&YS +End a synopsis block started by +.Pf \. Sx SY . +This is a non-standard GNU extension. .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. @@ -738,24 +757,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 @@ -779,11 +780,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 @@ -804,19 +801,15 @@ The syntax is as follows: .It Sx \&IR Ta n Ta current Ta \& .It Sx \&OP Ta 0, 1 Ta current Ta compat .It Sx \&PD Ta 1 Ta current Ta \& -.It Sx \&R Ta n Ta next-line Ta \& .It Sx \&RB Ta n Ta current Ta \& .It Sx \&RI Ta n Ta current Ta \& .It Sx \&SB Ta n Ta next-line Ta \& .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 @@ -898,53 +891,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 mentions some areas of questionable portability between -implementations of the -.Nm -language. -More incompatibilities exist. -.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 -troff suppresses a newline before -.Sq \(aq -macro output; in mandoc, it is an alias for the standard -.Sq \&. -control character. -.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 EE , -.Sx EX , -.Sx OP , -.Sx UE , -and -.Sx UR -macros are part of the GNU extended -.Nm -macro set, and may not be portable to non-GNU troff implementations. .Sh SEE ALSO .Xr man 1 , .Xr mandoc 1 ,