Bug 58132 - non-standard, non-traditional man page layout makes searching for relevant information tedious and inefficient
Summary: non-standard, non-traditional man page layout makes searching for relevant in...
Status: NEW
Alias: None
Product: Apache httpd-2
Classification: Unclassified
Component: Documentation (show other bugs)
Version: 2.4.10
Hardware: PC All
: P2 normal (vote)
Target Milestone: ---
Assignee: HTTP Server Documentation List
URL:
Keywords:
Depends on: 62678
Blocks:
  Show dependency tree
 
Reported: 2015-07-12 16:14 UTC by Bruce Lilly
Modified: 2018-09-05 09:39 UTC (History)
0 users



Attachments

Note You need to log in before you can comment on or make changes to this bug.
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