https://bz.apache.org/bugzilla/show_bug.cgi?id=58129
Bug ID: 58129
Summary: man pages are not generated correctly
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.li...@gmail.com
Version 2.4.10 listed in the mandatory bug field, but appears to apply to most
recent versions.
In migrating a server from one OS to another, I consulted the man pages to find
the relevant differences. However, the man pages are inaccurate and
misleading.
The raw man page sources start with:
.\" XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
.\" DO NOT EDIT! Generated from XML source.
.\" XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Evidently something is wrong with the generation process or the "XML source"
(or maybe XML isn't the right tool).
For example, on openSUSE Linux 13.1 with Apache 2.4.6 installed, man httpd2
says:
"-d serverroot
Set the initial value for the ServerRoot directive to serverroot.
This can be overridden by the ServerRoot directive in the configuration file.
The default is /usr/local/apache2.
-f config
Uses the directives in the file config on startup. If config does
not begin with a /, then it is taken to be a path relative to the ServerRoot.
The default is conf/httpd.conf."
But there is no "/usr/local/apache2" directory. Obviously, there cannot
therefore be a "conf/httpd.conf" relative to that nonexistent directory.
On NetBSD 6.1.5 with Apache 2.4.10 installed, man httpd says:
"-d serverroot
Set the initial value for the ServerRoot directive to
serverroot. This can be overridden by the ServerRoot directive
in the configuration file. The default is
/usr/pkg/share/httpd/htdocs.
-f config
Uses the directives in the file config on startup. If config
does not begin with a /, then it is taken to be a path relative
to the ServerRoot. The default is conf/httpd.conf."
The directory /usr/pkg/share/httpd/htdocs exists, but it isn't where the
documents are located either before or after the configuration file is read.
Moreover, there is no "conf" subdirectory under /usr/pkg/share/httpd/htdocs, so
the configuration file cannot (and is not) read from "httpd.conf" there.
On OpenIndiana oi_151a9 with Apache 2.2.26 installed, man httpd says:
"-d serverroot
Set the initial value for the ServerRoot directive to
serverroot. This can be overridden by the ServerRoot
directive in the configuration file. The default is
/usr/local/apache2.
-f config
Uses the directives in the file config on startup. If
config does not begin with a /, then it is taken to be
a path relative to the ServerRoot. The default is
conf/httpd.conf."
And again, there is no /usr/local/apache2 directory.
The only reliable way to find the (apparently hard-coded at compile-time) true
defaults appears to be:
1. locate the httpd or httpd2 executable (a little tricky on OpenIndiana (and
presumably other Solaris-like systems) because it cannot be found via $PATH)
2. run the executable with the "-V" flag
3. translate the (very different) nomenclature used in -V to the corresponding
nomenclature used in the man page and configuration file(s) (e.g. the
equivalent of "ServerRoot" (man page and configuration files) is apparently
"HTTPD_ROOT" in -V output-ese)
As the same sort of discrepancies show up across multiple OSes and
distributions, this appears to be a core Apache httpd-2 issue rather than a
case of distribution-specific packaging issues.
As an aside, it would be nice if the build process used the same nomenclature
as the documentation and configuration (i.e. "ServerRoot" instead of
"HTTPD_ROOT") to obviate the need for a translation phrasebook...
--
You are receiving this mail because:
You are the assignee for the bug.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscr...@httpd.apache.org
For additional commands, e-mail: docs-h...@httpd.apache.org
