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 pAT0L3Bv009920
	for <tech@mdocml.bsd.lv>; Mon, 28 Nov 2011 19:21:03 -0500 (EST)
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 1RVBRW-0002CC-Hn; Tue, 29 Nov 2011 01:21:02 +0100
Received: from donnerwolke.usta.de ([172.24.96.3])
	by hekate.usta.de with esmtp (Exim 4.72)
	(envelope-from <schwarze@usta.de>)
	id 1RVBRW-0002Xi-Ks
	for tech@mdocml.bsd.lv; Tue, 29 Nov 2011 01:21:02 +0100
Received: from iris.usta.de ([172.24.96.5] helo=usta.de)
	by donnerwolke.usta.de with esmtp (Exim 4.72)
	(envelope-from <schwarze@usta.de>)
	id 1RVBRW-0001Ge-Jo
	for tech@mdocml.bsd.lv; Tue, 29 Nov 2011 01:21:02 +0100
Received: from schwarze by usta.de with local (Exim 4.72)
	(envelope-from <schwarze@usta.de>)
	id 1RVBRW-0002en-Ii
	for tech@mdocml.bsd.lv; Tue, 29 Nov 2011 01:21:02 +0100
Date: Tue, 29 Nov 2011 01:21:02 +0100
From: Ingo Schwarze <schwarze@usta.de>
To: tech@mdocml.bsd.lv
Subject: Re: Conventional lists in mdoc(7) sections.
Message-ID: <20111129002102.GB7216@iris.usta.de>
References: <4ED3F1C3.3070509@bsd.lv>
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: <4ED3F1C3.3070509@bsd.lv>
User-Agent: Mutt/1.5.21 (2010-09-15)

Hi Kristaps,

Kristaps Dzonsons wrote on Mon, Nov 28, 2011 at 09:40:35PM +0100:

> Enclosed is a patch mentioned some time ago that adds some examples
> to mdoc(7) regarding the structure of sections.  It basically adds
> an quick example for DIAGNOSTICS, ERRORS, ENVIRONMENT, FILES, and
> EXAMPLES.

I like the patch, but you should also try to learns Jason's
opinion.  A few comments are inline.

Yours,
  Ingo


> Index: mdoc.7
> ===================================================================
> RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mdoc.7,v
> retrieving revision 1.213
> diff -u -r1.213 mdoc.7
> --- mdoc.7	1 Nov 2011 14:59:27 -0000	1.213
> +++ mdoc.7	28 Nov 2011 20:39:29 -0000
> @@ -194,11 +194,9 @@
>  assumed to be a function in a section 2, 3, or 9 manual.
>  The syntax for this is as follows:
>  .Bd -literal -offset indent
> +\&.Sh LIBRARY
>  \&.Lb libarm
>  .Ed
> -.Pp
> -See
> -.Sx \&Lb .

I agree with removing the Sx here.
The trailing "See Nm and Nd" is even more redundant in the preceding
paragraph, both macros are Sx'ed right above.

>  .It Em SYNOPSIS
>  Documents the utility invocation syntax, function call syntax, or device
>  configuration.
> @@ -325,38 +323,65 @@
>  .It Em RETURN VALUES
>  This section documents the
>  return values of functions in sections 2, 3, and 9.
> -.Pp
>  See
>  .Sx \&Rv .
>  .It Em ENVIRONMENT
>  Lists the environment variables used by the utility,
>  and explains the syntax and semantics of their values.
> -The
> -.Xr environ 7
> -manual provides examples of typical content and formatting.
> -.Pp
> -See
> -.Sx \&Ev .
> +Fxample:

  For example:

> +.Bd -literal -offset indent
> +\&.Sh ENVIRONMENT
> +\&.Bl -tag -width Ds
> +\&.It Ev MANPATH
> +Colon-separated paths overriding the default list of 
> +paths searched for manual databases.
> +\&.El
> +.Ed
>  .It Em FILES
>  Documents files used.
>  It's helpful to document both the file name and a short description of how
>  the file is used (created, modified, etc.).
> -.Pp
> -See
> -.Sx \&Pa .
> +Fxample:

Again:

  For example:
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv