Bug 84806

Summary: mdoc(7) manpage has section ordering problems
Product: Documentation Reporter: Gary W. Swearingen <garys>
Component: Books & ArticlesAssignee: Tom Rhodes <trhodes>
Status: Closed FIXED    
Severity: Affects Only Me    
Priority: Normal    
Version: Latest   
Hardware: Any   
OS: Any   

Description Gary W. Swearingen 2005-08-11 16:30:19 UTC
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.

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.
How-To-Repeat: n/a
Comment 1 Tom Rhodes freebsd_committer freebsd_triage 2009-01-24 00:43:08 UTC
State Changed
From-To: open->closed

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. 


Comment 2 Tom Rhodes freebsd_committer freebsd_triage 2009-01-24 00:43:08 UTC
Responsible Changed
From-To: freebsd-doc->trhodes

Over to me.