* mdocml: Add some new text written from scratch after checking whether
@ 2011-08-01 7:45 schwarze
0 siblings, 0 replies; only message in thread
From: schwarze @ 2011-08-01 7:45 UTC (permalink / raw)
To: source
Log Message:
-----------
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@
Modified Files:
--------------
mdocml:
mdoc.7
Revision Data
-------------
Index: mdoc.7
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mdoc.7,v
retrieving revision 1.193
retrieving revision 1.194
diff -Lmdoc.7 -Lmdoc.7 -u -p -r1.193 -r1.194
--- mdoc.7
+++ mdoc.7
@@ -178,15 +178,38 @@ trailing spaces are stripped from input
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,
--
To unsubscribe send an email to source+unsubscribe@mdocml.bsd.lv
^ permalink raw reply [flat|nested] only message in thread
only message in thread, other threads:[~2011-08-01 7:45 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2011-08-01 7:45 mdocml: Add some new text written from scratch after checking whether schwarze
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).