Bug 58129 - man pages are not generated correctly
Summary: man pages are not generated correctly
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:
Blocks:
 
Reported: 2015-07-12 15:14 UTC by Bruce Lilly
Modified: 2016-01-16 23:38 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 15:14:04 UTC
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...
Comment 1 André Malo 2015-07-13 07:53:09 UTC
Hi,

I think you should file this bug to the distributions. The httpd project neither does create distributor packages nor can it support them. The paths given here are for the httpds own installation process.

I'm not exactly sure, what the httpd bug here should be. Could you elaborate?
Comment 2 Bruce Lilly 2015-07-14 00:51:39 UTC
To be quite clear:
The default file and directory locations are established during configure prior to building from sources (e.g. via --prefix=).  These are then hard-coded into the httpd executable.
The default prefix, not the configured default location, is what is written in docs/man/httpd.8 as distributed in the source tarball.

One of the problems is that httpd.8 is *NOT* updated to reflect the configured default locations.
A related problem is that 'make install' as directed in http://httpd.apache.org/docs/2.4/install.html installs -- without notice or warning -- the *unmodified* httpd.8 (as part of the generated Makefile install-man target).
There is certainly nothing in the generated Makefile nor in the "Compiling and Installing" instructions that would result in httpd.8 being "Generated from XML source" to reflect the actual configured and compiled-in locations.
http://httpd.apache.org/docs/2.4/install.html does not even mention the documentation, the generation of which is apparently only described in a separate, well-hidden area not likely to be seen by anybody following the "Compiling and Installing" instructions.

To make matters worse, the gobbledygook hidden away regarding building the documentation doesn't even mention the man pages -- at all.  I refer specifically to http://mirror.symnds.com/software/Apache//httpd/docs/README.html and http://httpd.apache.org/docs-project/docsformat.html ("Module Format and Transformation").
It is unclear (to me) whether or not going following what's hidden there would result in pages being updated to reflect as-configured builds.

It is unreasonable to pin the blame for this on every single distribution, since the Apache-distributed tarballs, the "Compiling and Installing" procedure, and the (frankly) poorly documented procedure for building the documentation directly result in this problem.
Comment 3 Luca Toscano 2016-01-16 23:38:52 UTC
Hi Bruce,

I completely understand your points and indeed is not intuitive to figure out how to build the man pages. Under $YOUR_SVN_REPO_DIR/httpd-trunk/docs/manual/build there is a file called build.sh that offers various targets as stated in https://httpd.apache.org/docs-project/docsformat.html:

./build.sh -projecthelp

..
..
 man-da          - builds the Dansk nroff files
 man-en          - builds the English nroff files
 man-tr          - builds the Turkish nroff files
..
..

It is not that clear though and we need to add a reference to it in the files that you mentioned. I am a bit new to the documentation project but I'll try to figure out how to improve the issue with the use of --prefix=

I'll post in here my progress, hopefully we'll have something better soon :)

Luca