httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bugzi...@apache.org
Subject [Bug 58132] New: non-standard, non-traditional man page layout makes searching for relevant information tedious and inefficient
Date Sun, 12 Jul 2015 16:14:44 GMT
https://bz.apache.org/bugzilla/show_bug.cgi?id=58132

            Bug ID: 58132
           Summary: non-standard, non-traditional man page layout makes
                    searching for relevant information tedious and
                    inefficient
           Product: Apache httpd-2
           Version: 2.4.10
          Hardware: PC
                OS: All
            Status: NEW
          Severity: normal
          Priority: P2
         Component: Documentation
          Assignee: docs@httpd.apache.org
          Reporter: bruce.lilly@gmail.com

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."

-- 
You are receiving this mail because:
You are the assignee for the bug.

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org


Mime
View raw message