From owner-freebsd-doc@FreeBSD.ORG Thu Aug 11 15:30:21 2005 Return-Path: X-Original-To: freebsd-doc@hub.freebsd.org Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 80A6816A41F for ; Thu, 11 Aug 2005 15:30:21 +0000 (GMT) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [216.136.204.21]) by mx1.FreeBSD.org (Postfix) with ESMTP id 4A11F43D46 for ; Thu, 11 Aug 2005 15:30:20 +0000 (GMT) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) by freefall.freebsd.org (8.13.3/8.13.3) with ESMTP id j7BFUKJU034113 for ; Thu, 11 Aug 2005 15:30:20 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.13.3/8.13.1/Submit) id j7BFUKr4034112; Thu, 11 Aug 2005 15:30:20 GMT (envelope-from gnats) Resent-Date: Thu, 11 Aug 2005 15:30:20 GMT Resent-Message-Id: <200508111530.j7BFUKr4034112@freefall.freebsd.org> Resent-From: FreeBSD-gnats-submit@FreeBSD.org (GNATS Filer) Resent-To: freebsd-doc@FreeBSD.org Resent-Reply-To: FreeBSD-gnats-submit@FreeBSD.org, 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 ; 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 ; 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 ; 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: Date: Thu, 11 Aug 2005 08:28:51 -0700 From: "Gary W. Swearingen" To: FreeBSD-gnats-submit@FreeBSD.org Cc: Subject: docs/84806: mdoc(7) manpage has section ordering problems X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: garys@opusnet.com List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 11 Aug 2005 15:30:21 -0000 >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: