From garys@opusnet.com  Thu Aug 11 15:26:30 2005
Return-Path: <garys@opusnet.com>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 74EC716A41F
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 11 Aug 2005 15:26:30 +0000 (GMT)
	(envelope-from garys@opusnet.com)
Received: from opusnet.com (mail.opusnet.com [209.210.200.6])
	by mx1.FreeBSD.org (Postfix) with ESMTP id EE7F243D49
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 11 Aug 2005 15:26:29 +0000 (GMT)
	(envelope-from garys@opusnet.com)
Received: from localhost.localhost [70.98.246.232] by opusnet.com with ESMTP
  (SMTPD32-8.05) id AE22BEB500AC; Thu, 11 Aug 2005 08:26:26 -0700
Received: from localhost.localhost (localhost.localhost [127.0.0.1])
	by localhost.localhost (8.13.3/8.13.3) with ESMTP id j7BFSurA006992
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 11 Aug 2005 08:28:56 -0700 (PDT)
	(envelope-from garys@opusnet.com)
Received: (from jojo@localhost)
	by localhost.localhost (8.13.3/8.13.3/Submit) id j7BFSpEV006991;
	Thu, 11 Aug 2005 08:28:51 -0700 (PDT)
	(envelope-from garys@opusnet.com)
Message-Id: <es7jesijbg.jes@mail.opusnet.com>
Date: Thu, 11 Aug 2005 08:28:51 -0700
From: "Gary W. Swearingen" <garys@opusnet.com>
Reply-To: garys@opusnet.com
To: FreeBSD-gnats-submit@freebsd.org
Subject: mdoc(7) manpage has section ordering problems
X-GNATS-Notify:

>Number:         84806
>Category:       docs
>Synopsis:       mdoc(7) manpage has section ordering problems
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    trhodes
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Aug 11 15:30:19 GMT 2005
>Closed-Date:    Sat Jan 24 00:44:16 UTC 2009
>Last-Modified:  Sat Jan 24 00:44:16 UTC 2009
>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:
State-Changed-From-To: open->closed 
State-Changed-By: trhodes 
State-Changed-When: Sat Jan 24 00:43:08 UTC 2009 
State-Changed-Why:  
Closing this PR - we do not expect to ever see a patch for 
it, and if we did, we would just be sending submitter 
upstream with it anyway.  Thanks. 


Responsible-Changed-From-To: freebsd-doc->trhodes 
Responsible-Changed-By: trhodes 
Responsible-Changed-When: Sat Jan 24 00:43:08 UTC 2009 
Responsible-Changed-Why:  
Over to me. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=84806 
>Unformatted:
