docs/84806: mdoc(7) manpage has section ordering problems

[Gary W. Swearingen]

>Number:         84806
>Category:       docs
>Synopsis:       mdoc(7) manpage has section ordering problems
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Aug 11 15:30:19 GMT 2005
>Closed-Date:
>Last-Modified:
>Originator:     Gary W. Swearingen
>Release:        FreeBSD 5.4-RELEASE i386
>Organization:
none
>Environment:
n/a
>Description:

The mdoc(7) manpage puts information about whether a major section is
required in both the "Page Structure Domain" section and the "a Manual
Page Template" section, but not fully or consistently in each.  And
the former requires a order for some of the sections, while the later
says nothing about order except by ordering them in the example, from
which some will make an inference about the order of all sections.

Also, the manpage violates its own requirements for where to place its
"Diagnostics" section.

>How-To-Repeat:
n/a

>Fix:

(I'll write a patch if Ruslan will say what change will be acceptable.)

First decide whether the existence and order requirements each should
be in the "a Manual Page Template" section or the "Page Structure
Domain" section.

If the latter, then decide whether the existence and/or order
requirements should be given in multiple sub-section intros that cover
several ".Sh"es each or should be given with each ".Sh" description.

I prefer the later, and so I would put all these polices in the
"Section Headers" subsection of the "Page Structure Domain" section,
with _all_ the ".Sh" entries in their required order (with that
explained in the intro paragraph). Each entry would include its own
existence policy, often in a short phrase or stock sentence.  The only
comment in the template would be a general reference to the existence
and order requirements in the "Section Headers" subsection.
>Release-Note:
>Audit-Trail:
>Unformatted: