Bug 58132

Summary: non-standard, non-traditional man page layout makes searching for relevant information tedious and inefficient
Product: Apache httpd-2 Reporter: Bruce Lilly <bruce.lilly>
Component: DocumentationAssignee: HTTP Server Documentation List <docs>
Status: NEW ---    
Severity: normal    
Priority: P2    
Version: 2.4.10   
Target Milestone: ---   
Hardware: PC   
OS: All   
Bug Depends on: 62678    
Bug Blocks:    

Description Bruce Lilly 2015-07-12 16:14:44 UTC
Mandatory version field in bug set to 2.4.10, but this applies to all recent versions.

Traditional (e.g. UNIX v7 and later man pages, such as at https://docs.oracle.com/cd/E36784_01/html/E36871/makehtml-id-0.html#REFMAN1Mmakehtml-id-1) and standardized (e.g. The Open Group Base Specifications Issue 7, Shell & Utilities, Introduction, 1.4 Utility Description Defaults) man page layout summarizes important files used by a command or program in the "FILES" or "INPUT FILES" and/or "OUTPUT FILES" section(s).  Such layout makes it easy to find relevant information about important files (e.g. configuration files) simply by searching for "FILES".

Apache httpd-2 man pages, including especially the page for httpd itself, lack such structure, and consequently it is tedious to find the relevant information (lack of accuracy of the information, as reported in Bug 58129, is a separate issue).

The documents referenced above should make clear what is desired of well-organized man pages; specifically for FILES, quoting in part from a couple of the referenced documents:
"FILES
This section lists all file names referred to by the man page, files of interest, and files created or required by commands. Each is followed by a descriptive summary or explanation."

"INPUT FILES

The INPUT FILES section describes the files, other than the standard input, used as input by the utility. It includes files named as operands and option-arguments as well as other files that are referred to, such as start-up and initialization files, databases, and so on."
Comment 1 Bruce Lilly 2015-07-12 16:24:10 UTC
Addendum: for a vendor-specific example of useful standardized layout for Apache httpd-2, see https://docs.oracle.com/cd/E36784_01/html/E36871/apache2-1m.html#scrolltoc