diff options
| -rw-r--r-- | mdoc.7 | 137 |
1 files changed, 65 insertions, 72 deletions
@@ -63,11 +63,11 @@ and .Sx Special Characters . .Ss Comments Text following an escaped double-quote -.Sq \e\*q , +.Sq \e\(dq , whether in a macro or text line, is ignored to the end of line. A macro line beginning with a control character and comment escape -.Sq \&.\e\*q +.Sq \&.\e\(dq is also ignored. Furthermore, macro lines with only a control character and optional trailing @@ -76,10 +76,10 @@ stripped from input. .Pp Examples: .Bd -literal -offset indent -compact -\&.\e\*q This is a comment line. -\&.\e\*q The next line is ignored: +\&.\e\(dq This is a comment line. +\&.\e\(dq The next line is ignored: \&. -\&.Em Emphasis \e\*q This is also a comment. +\&.Em Emphasis \e\(dq This is also a comment. .Ed .Ss Special Characters Special characters are used to encode special glyphs and are rendered @@ -97,9 +97,9 @@ or a single one character sequence. .Pp Examples: .Bl -tag -width Ds -offset indent -compact -.It \e(em +.It Li \e(em em dash -.It \ee +.It Li \ee backslash .El .Pp @@ -125,9 +125,9 @@ scope. .Pp Examples: .Bl -tag -width Ds -offset indent -compact -.It \efBbold\efR +.It Li \efBbold\efR write in bold, then switch to regular -.It \efIitalic\efP +.It Li \efIitalic\efP write in italic, then return to previous .El .Pp @@ -151,9 +151,9 @@ and N-character .Pp Examples: .Bl -tag -width Ds -offset indent -compact -.It \e*(Am +.It Li \e*(Am ampersand -.It \e*(Ba +.It Li \e*(Ba vertical bar .El .Pp @@ -176,44 +176,37 @@ In the rare case that a blank character is needed at the end of an input line, it may be forced by .Sq \e\ \e& . .Pp +In general, space characters can be considered as non-whitespace +characters by using non-breaking space escapes or +.Sx Quotation . +.Pp Blank text lines, which may include whitespace, are only permitted within literal contexts. If the first character of a text line is a space, that line is printed with a leading newline. .Ss Quotation -Macro arguments may be quoted with double-quotes; in this case, -whitespace within the quotes is retained as part of the argument. -For example, -.Pp -.D1 Pf \. \&Fn strlen "\(dqconst char *s\(dq" -.Pp -renders as -.Sq Fn strlen "const char *s" , -while -.Pp -.D1 Pf \. \&Fn strlen "const char *s" -.Pp -would produce -.Sq Fn strlen const char *s . +Macro arguments may be quoted with double-quotes to so that the +enclosed text is one literal term. +Quoted text, even if whitespace or if it would cause a macro invocation +when unquoted, is considered literal text. .Pp A quoted argument begins with a double-quote preceded by whitespace. The next double-quote not pairwise adjacent to another double-quote terminates the literal, regardless of surrounding whitespace. .Pp -In unquoted arguments, space characters can alternatively be included -by preceding them with a backslash -.Pq Sq \e\~ , -but quoting is usually better for clarity. -.Pp -Note that any quoted text, even if it would cause a macro invocation -when unquoted, is considered literal text. -Thus, the following produces -.Sq Op "Fl a" : -.Bd -literal -offset indent -\&.Op "Fl a" -.Ed -.Pp -In text lines, quotes are regarded as opaque text. +Examples: +.Bl -tag -width Ds -offset indent -compact +.It Li .Fn strlen \(dqconst char *s\(dq +groups +.Qq const char *s +into one term +.Pq see Sx \&Fn +.It Li .Op \(dqFl a\(dq +considers +.Qq \&Fl a +as literal text +.Pq see Sx \&Op , \&Fl +.El .Ss Scaling Widths Many macros support scaled widths for their arguments. The syntax for a scaled width is @@ -265,10 +258,10 @@ See .Pp Examples: .Bl -tag -width Ds -offset indent -compact -.It \&.Bl -tag -width 2i +.It Li \&.Bl -tag -width 2i two-inch tagged list indentation .Pq see Sx \&Bl -.It \&.sp 2v +.It Li \&.sp 2v two vertical spaces .Pq see Sx \&sp .El @@ -332,9 +325,9 @@ file for a utility \&.Sh NAME \&.Nm progname \&.Nd one line about what it does -\&.\e\*q .Sh LIBRARY -\&.\e\*q For sections 2, 3, & 9 only. -\&.\e\*q Not used in OpenBSD. +\&.\e\(dq .Sh LIBRARY +\&.\e\(dq For sections 2, 3, & 9 only. +\&.\e\(dq Not used in OpenBSD. \&.Sh SYNOPSIS \&.Nm progname \&.Op Fl options @@ -343,29 +336,29 @@ file for a utility The \&.Nm utility processes files ... -\&.\e\*q .Sh IMPLEMENTATION NOTES -\&.\e\*q Not used in OpenBSD. -\&.\e\*q .Sh RETURN VALUES -\&.\e\*q For sections 2, 3, & 9 only. -\&.\e\*q .Sh ENVIRONMENT -\&.\e\*q For sections 1, 6, 7, & 8 only. -\&.\e\*q .Sh FILES -\&.\e\*q .Sh EXIT STATUS -\&.\e\*q For sections 1, 6, & 8 only. -\&.\e\*q .Sh EXAMPLES -\&.\e\*q .Sh DIAGNOSTICS -\&.\e\*q For sections 1, 4, 6, 7, & 8 only. -\&.\e\*q .Sh ERRORS -\&.\e\*q For sections 2, 3, & 9 only. -\&.\e\*q .Sh SEE ALSO -\&.\e\*q .Xr foobar 1 -\&.\e\*q .Sh STANDARDS -\&.\e\*q .Sh HISTORY -\&.\e\*q .Sh AUTHORS -\&.\e\*q .Sh CAVEATS -\&.\e\*q .Sh BUGS -\&.\e\*q .Sh SECURITY CONSIDERATIONS -\&.\e\*q Not used in OpenBSD. +\&.\e\(dq .Sh IMPLEMENTATION NOTES +\&.\e\(dq Not used in OpenBSD. +\&.\e\(dq .Sh RETURN VALUES +\&.\e\(dq For sections 2, 3, & 9 only. +\&.\e\(dq .Sh ENVIRONMENT +\&.\e\(dq For sections 1, 6, 7, & 8 only. +\&.\e\(dq .Sh FILES +\&.\e\(dq .Sh EXIT STATUS +\&.\e\(dq For sections 1, 6, & 8 only. +\&.\e\(dq .Sh EXAMPLES +\&.\e\(dq .Sh DIAGNOSTICS +\&.\e\(dq For sections 1, 4, 6, 7, & 8 only. +\&.\e\(dq .Sh ERRORS +\&.\e\(dq For sections 2, 3, & 9 only. +\&.\e\(dq .Sh SEE ALSO +\&.\e\(dq .Xr foobar 1 +\&.\e\(dq .Sh STANDARDS +\&.\e\(dq .Sh HISTORY +\&.\e\(dq .Sh AUTHORS +\&.\e\(dq .Sh CAVEATS +\&.\e\(dq .Sh BUGS +\&.\e\(dq .Sh SECURITY CONSIDERATIONS +\&.\e\(dq Not used in OpenBSD. .Ed .Pp The sections in an @@ -446,8 +439,8 @@ macros should follow C header-file conventions. .Pp And for the third, configurations (section 4): .Bd -literal -offset indent -\&.Cd \*qit* at isa? port 0x2e\*q -\&.Cd \*qit* at isa? port 0x4e\*q +\&.Cd \(dqit* at isa? port 0x2e\(dq +\&.Cd \(dqit* at isa? port 0x4e\(dq .Ed .Pp Manuals not in these sections generally don't need a @@ -2103,8 +2096,8 @@ section, this macro starts a new output line, and a blank line is automatically inserted between function definitions. .Pp Examples: -.Dl \&.Fn \*qint funcname\*q \*qint arg0\*q \*qint arg1\*q -.Dl \&.Fn funcname \*qint arg0\*q +.Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq +.Dl \&.Fn funcname \(dqint arg0\(dq .Dl \&.Fn funcname arg0 .Pp .Bd -literal -offset indent -compact @@ -2369,7 +2362,7 @@ Its syntax is as follows: .D1 Pf \. Sx \&Lk Ar uri Op Ar name .Pp Examples: -.Dl \&.Lk http://bsd.lv \*qThe BSD.lv Project\*q +.Dl \&.Lk http://bsd.lv \(dqThe BSD.lv Project\(dq .Dl \&.Lk http://bsd.lv .Pp See also |