From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp-2.sys.kth.se (smtp-2.sys.kth.se [130.237.32.160]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id p36BEjF1024454 for ; Wed, 6 Apr 2011 07:14:45 -0400 (EDT) Received: from mailscan-1.sys.kth.se (mailscan-1.sys.kth.se [130.237.32.91]) by smtp-2.sys.kth.se (Postfix) with ESMTP id 9A36E14D7D5; Wed, 6 Apr 2011 13:14:39 +0200 (CEST) X-Virus-Scanned: by amavisd-new at kth.se Received: from smtp-2.sys.kth.se ([130.237.32.160]) by mailscan-1.sys.kth.se (mailscan-1.sys.kth.se [130.237.32.91]) (amavisd-new, port 10024) with LMTP id mwVlSPO0T7iJ; Wed, 6 Apr 2011 13:14:37 +0200 (CEST) X-KTH-Auth: kristaps [193.10.49.5] X-KTH-mail-from: kristaps@bsd.lv Received: from [172.16.18.84] (unknown [193.10.49.5]) by smtp-2.sys.kth.se (Postfix) with ESMTP id 888CE14D7CB; Wed, 6 Apr 2011 13:14:36 +0200 (CEST) Message-ID: <4D9C4B1C.9060206@bsd.lv> Date: Wed, 06 Apr 2011 13:14:36 +0200 From: Kristaps Dzonsons User-Agent: Mozilla/5.0 (X11; U; Linux x86_64; en-US; rv:1.9.1.16) Gecko/20110303 Icedove/3.0.11 X-Mailinglist: mdocml-tech Reply-To: tech@mdocml.bsd.lv MIME-Version: 1.0 To: Jason McIntyre CC: tech@mdocml.bsd.lv Subject: Re: [PATCH] mdoc.7 tweaks. References: <4D9C3699.7080802@bsd.lv> <20110406104809.GD7870@harkle.bramka> In-Reply-To: <20110406104809.GD7870@harkle.bramka> Content-Type: multipart/mixed; boundary="------------000702080107090502020607" This is a multi-part message in MIME format. --------------000702080107090502020607 Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Jason, thanks for your feedback. Enclosed is a corrected patch with the exception of the following: >> -This expands upon the brief, one line description in >> -.Em NAME . >> -It usually contains a breakdown of the options (if documenting a >> +This begins with an expansion of the brief, one line description in >> +.Em NAME : > > you should use Sx to refer to other section names. We don't have section documentation `Ss'd, so I can't refer back to them as such. The reason being that we stipulate (in both `Ss' and `Sh' documentation) that names should be unique, so I can't `Ss NAME'. On the other hand, I agree that `Em' is not a good choice. Do you have another suggestion? (Note that using `It Em NAME' to document and refer to per-section documentation has long since irritated me.) Thanks, Kristaps --------------000702080107090502020607 Content-Type: text/plain; name="patch.mdoc.txt" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="patch.mdoc.txt" Index: mdoc.7 =================================================================== RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mdoc.7,v retrieving revision 1.184 diff -u -r1.184 mdoc.7 --- mdoc.7 1 Apr 2011 19:50:49 -0000 1.184 +++ mdoc.7 6 Apr 2011 11:08:35 -0000 @@ -40,25 +40,25 @@ .Nm document follows simple rules: lines beginning with the control character -.Sq \. +.Sq \&. are parsed for macros. -Other lines are interpreted within the scope of -prior macros: +Text lines, those not beginning with the control character, are +interpreted within the scope of prior macros: .Bd -literal -offset indent \&.Sh Macro lines change control state. -Other lines are interpreted within the current state. +Text lines are interpreted within the current state. .Ed .Sh LANGUAGE SYNTAX .Nm documents may contain only graphable 7-bit ASCII characters, the space character, and, in certain circumstances, the tab character. .Pp -If the first character of a line is a space, that line is printed +If the first character of a text line is a space, that line is printed with a leading newline. .Ss Comments Text following a .Sq \e\*q , -whether in a macro or free-form text line, is ignored to the end of +whether in a macro or text line, is ignored to the end of line. A macro line with only a control character and comment escape, .Sq \&.\e\*q , @@ -102,8 +102,9 @@ For general use in macro lines, these can be escaped with a non-breaking space .Pq Sq \e& . +In text lines, these may be used as normal punctuation. .Ss Special Characters -Special characters may occur in both macro and free-form lines. +Special characters may occur in both macro and text lines. Sequences begin with the escape character .Sq \e followed by either an open-parenthesis @@ -132,18 +133,15 @@ .Pp A numerical representation 3, 2, or 1 (bold, italic, and Roman, respectively) may be used instead. -A text decoration is valid within -the current font scope only: if a macro opens a font scope alongside -its own scope, such as -.Sx \&Bf -.Cm \&Sy , -in-scope invocations of -.Sq \ef -are only valid within the font scope of the macro. -If +If a macro opens a font scope after calling +.Sq \ef , +such as with +.Sx \&Bf , +the .Sq \ef -is specified outside of any font scope, such as in unenclosed, free-form -text, it will affect the remainder of the document. +mode will be restored upon exiting the +.Sx \&Bf +scope. .Pp Note this form is .Em not @@ -177,9 +175,9 @@ .Pq vertical bar . .Ss Whitespace Whitespace consists of the space character. -In free-form lines, whitespace is preserved within a line; unescaped +In text lines, whitespace is preserved within a line; unescaped trailing spaces are stripped from input (unless in a literal context). -Blank free-form lines, which may include whitespace, are only permitted +Blank text lines, which may include whitespace, are only permitted within literal contexts. .Pp In macro lines, whitespace delimits arguments and is discarded. @@ -199,7 +197,7 @@ \&.Op "Fl a" .Ed .Pp -In free-form mode, quotes are regarded as opaque text. +In text lines, quotes are regarded as opaque text. .Ss Scaling Widths Many macros support scaled widths for their arguments, such as stipulating a two-inch list indentation with the following: @@ -270,8 +268,8 @@ the boundary of a macro line. For example: .Pp -.Dl \&Xr mandoc 1 \. -.Dl \&Fl T \&Ns \&Cm ascii \. +.Dl \&.Xr mandoc 1 \&. +.Dl \&.Fl T \&Ns \&Cm ascii \&. .Sh MANUAL STRUCTURE A well-formed .Nm @@ -359,6 +357,10 @@ \&.Nd a one line description .Ed .Pp +Multiple +.Sq \&Nm +names should be separated by commas. +.Pp The .Sx \&Nm macro(s) must precede the @@ -386,16 +388,18 @@ For the first, utilities (sections 1, 6, and 8), this is generally structured as follows: .Bd -literal -offset indent -\&.Nm foo +\&.Nm bar \&.Op Fl v \&.Op Fl o Ar file \&.Op Ar -\&.Nm bar +\&.Nm foo \&.Op Fl v \&.Op Fl o Ar file \&.Op Ar .Ed .Pp +Commands should be ordered alphabetically. +.Pp For the second, function calls (sections 2, 3, 9): .Bd -literal -offset indent \&.In header.h @@ -406,6 +410,14 @@ \&.Fn bar "const char *src" .Ed .Pp +Ordering of +.Sx \&In , +.Sx \&Vt , +.Sx \&Fn , +and +.Sx \&Fo +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 @@ -454,9 +466,15 @@ .Sx \&Ss macro or the end of an enclosing block, whichever comes first. .It Em DESCRIPTION -This expands upon the brief, one line description in -.Em NAME . -It usually contains a breakdown of the options (if documenting a +This begins with an expansion of the brief, one line description in +.Em NAME : +.Bd -literal -offset indent +The +\&.Nm +utility does this, that, and the other. +.Ed +.Pp +It usually follows with a breakdown of the options (if documenting a command), such as: .Bd -literal -offset indent The arguments are as follows: @@ -604,7 +622,10 @@ Multi-line scope closed by an explicit closing macro. All macros contains bodies; only .Sx \&Bf -contains a head. +and +.Pq optionally +.Sx \&Bl +contain a head. .Bd -literal -offset indent \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \(lBbody...\(rB @@ -1040,7 +1061,7 @@ .Pp Display blocks are used to select a different indentation and justification than the one used by the surrounding text. -They may contain both macro lines and free-form text lines. +They may contain both macro lines and text lines. By default, a display block is preceded by a vertical space. .Pp The @@ -1157,7 +1178,7 @@ .Ss \&Bk Keep the output generated from each macro input line together on one single output line. -Line breaks in free-form text lines are unaffected. +Line breaks in text lines are unaffected. The syntax is as follows: .Pp .D1 Pf \. Sx \&Bk Fl words @@ -1851,9 +1872,9 @@ Its syntax is as follows: .Bd -ragged -offset indent .Pf \. Ns Sx \&Fn -.Op Cm functype -.Cm funcname -.Op Oo Cm argtype Oc Cm argname +.Op Ar functype +.Ar funcname +.Op Oo Ar argtype Oc Ar argname .Ed .Pp Function arguments are surrounded in parenthesis and @@ -1882,15 +1903,15 @@ .Sx \&Fn . Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Fo Cm funcname +.D1 Pf \. Sx \&Fo Ar funcname .Pp Invocations usually occur in the following context: .Bd -ragged -offset indent -.Pf \. Sx \&Ft Cm functype +.Pf \. Sx \&Ft Ar functype .br -.Pf \. Sx \&Fo Cm funcname +.Pf \. Sx \&Fo Ar funcname .br -.Pf \. Sx \&Fa Oo Cm argtype Oc Cm argname +.Pf \. Sx \&Fa Oo Ar argtype Oc Ar argname .br \&.\.\. .br @@ -1911,7 +1932,7 @@ A function type. Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Ft Cm functype +.D1 Pf \. Sx \&Ft Ar functype .Pp Examples: .Dl \&.Ft int @@ -1992,7 +2013,7 @@ .Fl diag have the following syntax: .Pp -.D1 Pf \. Sx \&It Cm args +.D1 Pf \. Sx \&It Ar args .Pp Lists of type .Fl bullet , @@ -2065,14 +2086,14 @@ Specify a library. The syntax is as follows: .Pp -.D1 Pf \. Sx \&Lb Cm library +.D1 Pf \. Sx \&Lb Ar library .Pp The -.Cm library +.Ar library parameter may be a system library, such as -.Cm libz +.Ar libz or -.Cm libpam , +.Ar libpam , in which case a small library description is printed next to the linker invocation; or a custom library, in which case the library name is printed in quotes. @@ -2098,7 +2119,7 @@ Format a hyperlink. Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Lk Cm uri Op Cm name +.D1 Pf \. Sx \&Lk Ar uri Op Ar name .Pp Examples: .Dl \&.Lk http://bsd.lv \*qThe BSD.lv Project\*q @@ -2113,7 +2134,7 @@ Display a mathematical symbol. Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Ms Cm symbol +.D1 Pf \. Sx \&Ms Ar symbol .Pp Examples: .Dl \&.Ms sigma @@ -2124,7 +2145,7 @@ hyperlink. Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Mt Cm address +.D1 Pf \. Sx \&Mt Ar address .Pp Examples: .Dl \&.Mt discuss@manpages.bsd.lv @@ -2262,10 +2283,10 @@ file. Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Os Op Cm system Op Cm version +.D1 Pf \. Sx \&Os Op Ar system Op Ar version .Pp The optional -.Cm system +.Ar system parameter specifies the relevant operating system or environment. Left unspecified, it defaults to the local operating system version. This is the suggested form. @@ -2324,14 +2345,14 @@ between its arguments. Its syntax is as follows: .Pp -.D1 Pf \. \&Pf Cm prefix suffix +.D1 Pf \. \&Pf Ar prefix suffix .Pp The -.Cm suffix +.Ar suffix argument may be a macro. .Pp Examples: -.Dl \&.Pf \e. \&Sx \&Pf \&Cm prefix suffix +.Dl \&.Pf \e. \&Sx \&Pf \&Ar prefix suffix .Ss \&Po Multi-line version of .Sx \&Pq . @@ -2452,11 +2473,11 @@ .D1 Pf \. Sx \&Sm Cm on | off .Pp By default, spacing is -.Cm on . +.Ar on . When switched -.Cm off , +.Ar off , no white space is inserted between macro arguments and between the -output generated from adjacent macros, but free-form text lines +output generated from adjacent macros, but text lines still get normal spacing between words and sentences. .Ss \&So Multi-line version of @@ -2679,15 +2700,15 @@ .Pq Qq cross-reference . Its syntax is as follows: .Pp -.D1 Pf \. Sx \&Xr Cm name section +.D1 Pf \. Sx \&Xr Ar name section .Pp The -.Cm name +.Ar name and -.Cm section +.Ar section are the name and section of the linked manual. If -.Cm section +.Ar section is followed by non-punctuation, an .Sx \&Ns is inserted into the token stream. @@ -2712,10 +2733,10 @@ historical manuals. Its syntax is as follows: .Pp -.D1 Pf \. Sx \&sp Op Cm height +.D1 Pf \. Sx \&sp Op Ar height .Pp The -.Cm height +.Ar height argument must be formatted as described in .Sx Scaling Widths . If unspecified, --------------000702080107090502020607-- -- To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv