Date: Thu, 11 Aug 2005 08:28:51 -0700 From: "Gary W. Swearingen" <garys@opusnet.com> To: FreeBSD-gnats-submit@FreeBSD.org Subject: docs/84806: mdoc(7) manpage has section ordering problems Message-ID: <es7jesijbg.jes@mail.opusnet.com> Resent-Message-ID: <200508111530.j7BFUKr4034112@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>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:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?es7jesijbg.jes>