httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bugzi...@apache.org
Subject [Bug 58129] New: man pages are not generated correctly
Date Sun, 12 Jul 2015 15:14:04 GMT
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.lilly@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-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org


Mime
View raw message