Cleanups to mdoc.7 section documentation.

Cleanups to mdoc.7 section documentation.

[Kristaps Dzonsons]

[-- Attachment #1: Type: text/plain, Size: 178 bytes --]

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

[-- Attachment #2: patch.txt --]
[-- Type: text/plain, Size: 4401 bytes --]

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.

Re: Cleanups to mdoc.7 section documentation.

[Jason McIntyre]

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

Re: Cleanups to mdoc.7 section documentation.

[Kristaps Dzonsons]

Jason McIntyre wrote:
> 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.

Ok, these make sense.  The thrust is just the examples giving the 
"conventional" section form (e.g., for errno): I'm unconcerned about 
whether the manual-section info is duplicated.

There are brief examples for both the SYNOPSIS and DESCRIPTION section. 
  Should these be off-loaded, say, to mdoc.template or something?

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

Re: Cleanups to mdoc.7 section documentation.

[Jason McIntyre]

On Sun, Sep 05, 2010 at 09:51:51AM +0200, Kristaps Dzonsons wrote:
> 
> There are brief examples for both the SYNOPSIS and DESCRIPTION section. 
>  Should these be off-loaded, say, to mdoc.template or something?
> 

i'd say that the examples given in NAME, LIBRARY, SYNOPSIS, and
DESCRIPTION are unneccessary and should just be removed.

the only bit i would leave is the details within SYNOPSIS about macros
getting their own line and so on.

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