From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout.scc.kit.edu (scc-mailout.scc.kit.edu [129.13.185.202]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id p730xpY0016854 for ; Tue, 2 Aug 2011 20:59:54 -0400 (EDT) Received: from hekate.usta.de (asta-nat.asta.uni-karlsruhe.de [172.22.63.82]) by scc-mailout-02.scc.kit.edu with esmtp (Exim 4.72 #1) id 1QoPoM-0008HB-2T; Wed, 03 Aug 2011 02:59:50 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.72) (envelope-from ) id 1QoPoM-0007CC-66; Wed, 03 Aug 2011 02:59:50 +0200 Received: from iris.usta.de ([172.24.96.5] helo=usta.de) by donnerwolke.usta.de with esmtp (Exim 4.69) (envelope-from ) id 1QoPoM-0003Bw-3h; Wed, 03 Aug 2011 02:59:50 +0200 Received: from schwarze by usta.de with local (Exim 4.72) (envelope-from ) id 1QoPoL-00079X-P3; Wed, 03 Aug 2011 02:59:49 +0200 Date: Wed, 3 Aug 2011 02:59:49 +0200 From: Ingo Schwarze To: tech@mdocml.bsd.lv Cc: jmc@openbsd.org Subject: Re: checking mdoc.samples(7) Message-ID: <20110803005949.GA28176@iris.usta.de> References: <20110801072600.GA30355@iris.usta.de> X-Mailinglist: mdocml-tech Reply-To: tech@mdocml.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20110801072600.GA30355@iris.usta.de> User-Agent: Mutt/1.5.21 (2010-09-15) Hi, Ingo Schwarze wrote on Mon, Aug 01, 2011 at 09:26:00AM +0200: > since a long time, i have been planning to check whether any content > from mdoc.samples(7) is missing from mdoc(7). Now i have done > another step forward, checking all chapters except those covering > individual macros (MANUAL DOMAIN, GENERAL TEXT DOMAIN, and > PAGE STRUCTURE DOMAIN). These three remain to be checked. Another step: I have ploughed through MANUAL DOMAIN. Here is the result: * More text for An Ar Cm Fn Ft In Pa Vt. * Avoid Ns between Fl and Ar in examples where it is not needed. * Fix broken spacing in the last Ar example. * In general, just use quoted strings for new and updated examples, making the source much easier on the eye. * Mention the usual sections for Cd Er Ex In Op. * More realistical examples for Cm Fl. * Mention the term "options" for Fl, it's used in lots of manuals. * Put a blank line before the multi-line Fn example. * Add an Sx from Fn to Fo. * Typo fix: Say that Fo is closed by Fc. * A nice interactive example of Ic taken from mdoc.samples(7). * Examples of In look nicer with .h. * Avoid the confusing term "command-line option" for Op, because that sounds all too much like Fl. * Typo fix: -xpg4.3 got lost. OK? Ingo Index: mdoc.7 =================================================================== RCS file: /cvs/src/share/man/man7/mdoc.7,v retrieving revision 1.77 diff -u -r1.77 mdoc.7 --- mdoc.7 2 Aug 2011 00:52:34 -0000 1.77 +++ mdoc.7 3 Aug 2011 00:35:39 -0000 @@ -1037,6 +1037,8 @@ .Dl \&.Ad 0x00000000 .Ss \&An Author name. +Can be used both for the authors of the program, function, or driver +documented in the manual, or for the authors of the manual itself. Requires either the name of an author or one of the following arguments: .Pp .Bl -tag -width "-nosplitX" -offset indent -compact @@ -1107,9 +1109,17 @@ is used as a default. .Pp Examples: -.Dl \&.Fl o \&Ns \&Ar file1 -.Dl \&.Ar -.Dl \&.Ar arg1 , arg2 . +.Dl ".Fl o Ar file" +.Dl ".Ar" +.Dl ".Ar arg1 , arg2 ." +.Pp +The arguments to the +.Sx \&Ar +macro are names and placeholders for command arguments; +for fixed strings to be passed verbatim as arguments, rather use +.Sx \&Fl +or +.Sx \&Cm . .Ss \&At Formats an AT&T version. Accepts one optional argument: @@ -1512,6 +1522,7 @@ Kernel configuration declaration. This denotes strings accepted by .Xr config 8 . +It is most often used in section 4 manual pages. .Pp Examples: .Dl \&.Cd device le0 at scode? @@ -1524,14 +1535,17 @@ This practise is discouraged. .Ss \&Cm Command modifiers. -Useful when specifying configuration options or keys. +Typically used for fixed strings passed as arguments, unless +.Sx \&Fl +is more appropriate. +Also useful when specifying configuration options or keys. .Pp Examples: -.Dl \&.Cm ControlPath -.Dl \&.Cm ControlMaster -.Pp -See also -.Sx \&Fl . +.Dl ".Nm mt Fl f Ar device Cm rewind" +.Dl ".Nm ps Fl o Cm pid , Ns Cm command" +.Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2" +.Dl ".Cm IdentityFile Pa ~/.ssh/id_rsa" +.Dl ".Cm LogLevel Dv DEBUG" .Ss \&D1 One-line indented display. This is formatted by the default rules and is useful for simple indented @@ -1881,6 +1895,7 @@ Error constants for definitions of the .Va errno libc global variable. +This is most often used in section 2 and 3 manual pages. .Pp Examples: .Dl \&.Er EPERM @@ -1905,6 +1920,7 @@ .Ss \&Ex Insert a standard sentence regarding command exit values of 0 on success and >0 on failure. +This is used most often in section 1, 6, and 8 manual pages. Its syntax is as follows: .Pp .D1 Pf \. Sx \&Ex Fl std Op Ar utility ... @@ -1965,7 +1981,7 @@ and .Sx \&In . .Ss \&Fl -Command-line flag. +Command-line flag or option. Used when listing arguments to command-line utilities. Prints a fixed-width hyphen .Sq \- @@ -1975,10 +1991,11 @@ output. .Pp Examples: -.Dl \&.Fl a b c -.Dl \&.Fl \&Pf a b -.Dl \&.Fl -.Dl \&.Op \&Fl o \&Ns \&Ar file +.Dl ".Nm cat Fl v No considered harmful" +.Dl ".Nm cp Fl pR Ar source ... directory" +.Dl ".Nm find Ar dir Fl type Cm d Fl name Pa CVS +.Dl ".Nm kill Fl Ar signal_number pid" +.Dl ".Nm su Fl" .Pp See also .Sx \&Cm . @@ -1995,11 +2012,16 @@ Function arguments are surrounded in parenthesis and are delimited by commas. If no arguments are specified, blank parenthesis are output. +In the +.Em SYNOPSIS +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 funcname arg0 +.Pp .Bd -literal -offset indent -compact \&.Ft functype \&.Fn funcname @@ -2009,7 +2031,8 @@ .Sx \&Xr instead. See also -.Sx MANUAL STRUCTURE +.Sx MANUAL STRUCTURE , +.Sx \&Fo , and .Sx \&Ft . .Ss \&Fo @@ -2036,6 +2059,7 @@ A .Sx \&Fo scope is closed by +.Sx \&Fc . .Pp See also .Sx MANUAL STRUCTURE , @@ -2051,6 +2075,10 @@ .Pp .D1 Pf \. Sx \&Ft Ar functype .Pp +In the +.Em SYNOPSIS +section, a new output line is started after this macro. +.Pp Examples: .Dl \&.Ft int .Bd -literal -offset indent -compact @@ -2091,6 +2119,7 @@ but used for instructions rather than values. .Pp Examples: +.Dl \&.Ic :wq .Dl \&.Ic hash .Dl \&.Ic alias .Pp @@ -2105,15 +2134,17 @@ An .Dq include file. -In the +When invoked as the first macro on an input line in the .Em SYNOPSIS -section (only if invoked as the line macro), the first argument is -preceded by +section, the argument is displayed in angle brackets +and preceded by .Dq #include , -the arguments is enclosed in angle brackets. +and a blank line is inserted in front if there is a preceding +function declaration. +This is most often used in section 2, 3, and 9 manual pages. .Pp Examples: -.Dl \&.In sys/types +.Dl \&.In sys/types.h .Pp See also .Sx MANUAL STRUCTURE . @@ -2378,9 +2409,11 @@ \&.Oc .Ed .Ss \&Op -Command-line option. -Used when listing options to command-line utilities. +Optional part of a command line. Prints the argument(s) in brackets. +This is most often used in the +.Em SYNOPSIS +section of section 1 and 8 manual pages. .Pp Examples: .Dl \&.Op \&Fl a \&Ar b @@ -2438,9 +2471,9 @@ and .Sx \&Ux . .Ss \&Pa -A file-system path. -If an argument is not provided, the string -.Dq \(ti +An absolute or relative file system path, or a file or directory name. +If an argument is not provided, the character +.Sq \(ti is used as a default. .Pp Examples: @@ -2703,6 +2736,7 @@ .St -xpg4 .It \-xpg4.2 .St -xpg4.2 +.It \-xpg4.3 .St -xpg4.3 .It \-xbd5 .St -xbd5 @@ -2790,11 +2824,14 @@ section, in which case a variable name is also specified. Note that it accepts .Sx Block partial-implicit -syntax when invoked as the first macro in the +syntax when invoked as the first macro on an input line in the .Em SYNOPSIS section, else it accepts ordinary .Sx In-line syntax. +In the former case, this macro starts a new output line, +and a blank line is inserted in front if there is a preceding +function definition or include directive. .Pp Note that this should not be confused with .Sx \&Ft , -- To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv