From 141ca86e5d57bc8071aa3f01aa4fa512c2653713 Mon Sep 17 00:00:00 2001 From: Ingo Schwarze Date: Mon, 1 Aug 2011 07:45:11 +0000 Subject: Add some new text written from scratch after checking whether anything explained in mdoc.samples(7) is missing from mdoc(7): * Discourage trailing whitespace. * Move all information about quoted arguments to the relevant subsection, shortening it a bit, and adding an example. * Mention that blanks can be quoted with a backslash. * A better .Nd line in the template (verbatim from mdoc.samples(7)). * Explain how to escape callable macro names, and provide examples. ok jmc@ --- mdoc.7 | 46 ++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 40 insertions(+), 6 deletions(-) (limited to 'mdoc.7') diff --git a/mdoc.7 b/mdoc.7 index 50b19c90..425f0133 100644 --- a/mdoc.7 +++ b/mdoc.7 @@ -1,4 +1,4 @@ -.\" $Id: mdoc.7,v 1.193 2011/07/31 17:42:50 schwarze Exp $ +.\" $Id: mdoc.7,v 1.194 2011/08/01 07:45:11 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons .\" Copyright (c) 2010 Ingo Schwarze @@ -15,7 +15,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 31 2011 $ +.Dd $Mdocdate: August 1 2011 $ .Dt MDOC 7 .Os .Sh NAME @@ -178,15 +178,38 @@ trailing spaces are stripped from input (unless in a literal context). Blank text lines, which may include whitespace, are only permitted within literal contexts. .Pp +In general, trailing whitespace on input lines is discouraged +for reasons of clarity and portability. +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 macro lines, whitespace delimits arguments and is discarded. -If arguments are quoted, whitespace within the quotes is retained. .Ss Quotation -Macro arguments may be quoted with double-quotes to group -space-delimited terms or to retain blocks of whitespace. +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 . +.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 @@ -304,7 +327,7 @@ file for a utility \&.Os \&.Sh NAME \&.Nm progname -\&.Nd a description goes here +\&.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. @@ -600,6 +623,17 @@ The .Em Callable column indicates that the macro may also be called by passing its name as an argument to another macro. +For example, +.Sq \&.Op \&Fl O \&Ar file +produces +.Sq Op Fl O Ar file . +To prevent a macro call and render the macro name literally, +escape it by prepending a non-breaking space, +.Sq \e& . +For example, +.Sq \&Op \e&Fl O +produces +.Sq Op \&Fl O . If a macro is not callable but its name appears as an argument to another macro, it is interpreted as opaque text. For example, -- cgit v1.2.3-56-ge451