Re: Cleanups to mdoc.7 section documentation.

[Jason McIntyre <jmc@kerhand.co.uk>]

On Sat, Sep 04, 2010 at 07:54:59PM +0200, Kristaps Dzonsons wrote:
> Hi,
> 
> I noticed that the section documentation entries redundantly noted
> relevant sections.  Removing these led to some clarification, examples,
> and so on.
> 
> Yeas, nays?
> 
> Kristaps

hmm. i'm not sure this is better. for one, it's handy not to have to
back/forward scroll to see which sections headers pertain to which
manual sections, and for another i think the place where you document
the macros is the best place for examples, not in the bit where you've
added. your diff just adds more text to the file and, if anything, we
desperately need to cut down on verbiage in this file.

and note, for example, that the section on Ev already contains an
exmaple; do we really need another?

so i'd nay say.

jmc

> Index: mdoc.7
> ===================================================================
> RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mdoc.7,v
> retrieving revision 1.158
> diff -u -r1.158 mdoc.7
> --- mdoc.7	4 Sep 2010 17:22:41 -0000	1.158
> +++ mdoc.7	4 Sep 2010 17:51:58 -0000
> @@ -386,20 +386,18 @@
>  macro(s) must precede the
>  .Sx \&Nd
>  macro.
> -.Pp
> -See
> +See also
>  .Sx \&Nm
>  and
>  .Sx \&Nd .
>  .It Em LIBRARY
> -The name of the library containing the documented material, which is
> -assumed to be a function in a section 2, 3, or 9 manual.
> +The name of the library containing the documented material.
>  The syntax for this is as follows:
>  .Bd -literal -offset indent
>  \&.Lb libarm
>  .Ed
>  .Pp
> -See
> +See also
>  .Sx \&Lb .
>  .It Em SYNOPSIS
>  Documents the utility invocation syntax, function call syntax, or device
> @@ -494,34 +492,39 @@
>  This is useful when implementing standard functions that may have side
>  effects or notable algorithmic implications.
>  .It Em RETURN VALUES
> -This section documents the
> -return values of functions in sections 2, 3, and 9.
> -.Pp
> -See
> +This section documents function return values.
> +See also
>  .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.
> +and explains the syntax and semantics of their values, such as
> +.Bd -literal -offset indent
> +\&.Bl \-tag \-width Ds
> +\&.It Ev DISPLAY
> +The location of the X11 server.
> +\&.El
> +.Ed
>  .Pp
> -See
> +See also
>  .Sx \&Ev .
>  .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.).
> +the file is used (created, modified, etc.), such as
> +.Bd -literal -offset indent
> +\&.Bl \-tag \-width Ds
> +\&.It Pa ~/.profile
> +User's login profile.
> +\&.El
> +.Ed
>  .Pp
> -See
> +See also
>  .Sx \&Pa .
>  .It Em EXIT STATUS
> -This section documents the
> -command exit status for section 1, 6, and 8 utilities.
> +This section documents a utility's exit status.
>  Historically, this information was described in
>  .Em DIAGNOSTICS ,
>  a practise that is now discouraged.
> -.Pp
>  See
>  .Sx \&Ex .
>  .It Em EXAMPLES
> @@ -529,45 +532,82 @@
>  This often contains snippets of well-formed, well-tested invocations.
>  Make sure that examples work properly!
>  .It Em DIAGNOSTICS
> -Documents error conditions.
> -This is most useful in section 4 manuals.
> +Documents error conditions, such as
> +.Bd -literal -offset indent
> +\&.Bl -diag
> +\&.It "fxp%d: couldn't map memory"
> +A fatal initialization error has occurred.
> +\&.El
> +.Ed
> +.Pp
>  Historically, this section was used in place of
> -.Em EXIT STATUS
> -for manuals in sections 1, 6, and 8; however, this practise is
> +.Em EXIT STATUS ;
> +however, this practise is now
>  discouraged.
> -.Pp
> -See
> -.Sx \&Bl
> -.Fl diag .
>  .It Em ERRORS
> -Documents error handling in sections 2, 3, and 9.
> +Documents possible
> +.Va errno
> +values in functions, such as
> +.Bd -literal -offset indent
> +\&.Bl -tag -width Ds
> +\&.It Bq Er ERANGE
> +The given string was out of range.
> +\&.El
> +.Ed
>  .Pp
> -See
> +See also
>  .Sx \&Er .
>  .It Em SEE ALSO
>  References other manuals with related topics.
>  This section should exist for most manuals.
>  Cross-references should conventionally be ordered first by section, then
> -alphabetically.
> +alphabetically, such as
> +.Bd -literal -offset indent
> +\&.Xr atof 3 ,
> +\&.Xr atoi 3 ,
> +\&.Xr atol 3 ,
> +\&.Xr atoll 3 ,
> +\&.Xr sscanf 3 ,
> +\&.Xr strtod 3 ,
> +\&.Xr strtol 3 ,
> +\&.Xr strtoul 3
> +.Ed
>  .Pp
> -See
> +See also
>  .Sx \&Xr .
>  .It Em STANDARDS
>  References any standards implemented or used.
>  If not adhering to any standards, the
>  .Em HISTORY
>  section should be used instead.
> -.Pp
> -See
> -.Sx \&St .
> +See also
> +.Sx \&St
> +and
> +.Sx \&Rs .
>  .It Em HISTORY
>  A brief history of the subject, including where support first appeared.
>  .It Em AUTHORS
>  Credits to the person or persons who wrote the code and/or documentation.
> -Authors should generally be noted by both name and email address.
> +Authors should generally be noted by both name and email address, such
> +as
> +.Bd -literal -offset indent
> +The
> +\&.Nm
> +reference was written by
> +\&.An Joe Random Aq joe@foo.lv .
> +.Ed
>  .Pp
> -See
> -.Sx \&An .
> +See also
> +.Sx \&An
> +and
> +.Sx \&Aq .
> +Note that
> +.Sx \&An
> +and
> +.Sx \&Aq
> +are used instead of
> +.Sx \&Mt
> +for historical reasons.
>  .It Em CAVEATS
>  Common misuses and misunderstandings should be explained
>  in this section.

--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv