You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@httpd.apache.org by bu...@apache.org on 2015/07/12 17:14:04 UTC
[Bug 58129] New: man pages are not generated correctly
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
[Bug 58129] man pages are not generated correctly
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=58129
--- Comment #3 from Luca Toscano <to...@gmail.com> ---
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
--
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
[Bug 58129] man pages are not generated correctly
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=58129
André Malo <nd...@perlig.de> changed:
What |Removed |Added
----------------------------------------------------------------------------
Status|NEW |NEEDINFO
--- Comment #1 from André Malo <nd...@perlig.de> ---
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?
--
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
[Bug 58129] man pages are not generated correctly
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=58129
Bruce Lilly <br...@gmail.com> changed:
What |Removed |Added
----------------------------------------------------------------------------
Status|NEEDINFO |NEW
--- Comment #2 from Bruce Lilly <br...@gmail.com> ---
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.
--
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
[Bug 58129] man pages are not generated correctly
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=58129
--- Comment #4 from Rich Bowen <rb...@apache.org> ---
Revisiting this ancient bug, and it seems that the xml source (ie
$SVN/docs/manual/programs/httpd.xml (and, while we're at it, configure.xml and
log_server_status.xml) all have /usr/local/apache2 in there, which *should* be
the actual default value, /usr/local/apache
Am I missing something here? It seems like this just needs to be fixed there.
--
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
[Bug 58129] man pages are not generated correctly
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=58129
--- Comment #5 from Rich Bowen <rb...@apache.org> ---
I stand corrected. For some reason, I thought that the default prefix was
/usr/local/apache however it appears that it is /usr/local/apache2 everywhere,
and has been for a long time, and that it's the ServerRoot docs that are
actually wrong.
--
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