Re: Conventional lists in mdoc(7) sections.

[Ingo Schwarze <schwarze@usta.de>]

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