Broken Apache Server documentation local links-fix?

Question

Level 1

75 points

Broken Apache Server documentation local links-fix?

I'm not a Unix geek, but wanted to learn more about the built-in Apache server so on the advice of a Help Viewer file, went to /Library/WebServer/Documents/manual/ and chose the index.html.html file, which is entitled Apache HTTP Server Version 1.3 Documentation and opened it in my browser. Well, there are a bunch of links that are broken, e.g. CGI: Dynamic Content with CGI, Configuration Files -- for example the target file in the 1st link is called cgi.html and it doesn't exist on my computer (though a search revealed that cgi.html.html does) -- (and these same links are broken in the FAQ page). I know I could search out the name of each file plus the extra .html in the name, open up the documentation and FAQ index pages in a text editor and fix the links, but instead of all that time fixing Apple's mess, I'm hoping corrected versions of the files exist somewhere.

G3 Platinum Minitower Mac OS X (10.4.6) G4 upgrade 768 megs RAM, Radeon 64 meg video

Posted on Apr 27, 2006 1:47 AM

Reply

Answer 1

Camelot

Level 9

58,527 points

Apr 27, 2006 10:10 AM in response to Joe Wheeler

Are you opening the files directly? that's the problem. Don't do that.

The default apache configuration has a map for /manual/ URLs

Just open http://localhost/manual/ and you'll get the documentation in a form where all the links work correctly.

Reply

Answer 2

Joe Wheeler Author

Level 1

75 points

Apr 30, 2006 1:27 AM in response to Camelot

Camelot,

I'm afraid I don't know what you're talking about.
The Apple help file simply says:
"To learn more, use a browser to open index.html in your Sites folder, or look in /Library/WebServer/Documents/Manual"
The first option means the index.html file the title of which is "Mac OS X Personal Web Sharing", containing near the end a link labeled "Apache Manual" which when clicked gets:
"File not found
Firefox can't find the file at /manual/."
The path in the link's source code is simply "file:///manual/"
The second option, to follow the path (I pasted it into the Go to Folder menu in the Finder and hit return), takes one to a directory called "manual" not a file, so naturally I looked for a file in the folder called "index.html" but the closest I could find was the one called "index.html.html" which is the one when opened contains some working and many broken links. I believe this option/method is the one you refer to in your authoritative reply.

If there is a third way to get the right index or site map page with links that work, and which Apple forgot to adequately disclose in their Help system documentation, I'd sure like to know about it. Please explain if you would, thanks.

Reply

Answer 3

Apr 30, 2006 2:53 AM in response to Joe Wheeler

I dont know, for what reason the path do the documentation of apache is broken in your case, but it is online availible at:
http://httpd.apache.org/docs/1.3/
It should be excactly the same the as the offline version on your harddisk.

If you want to fix your offline Documentation:
Check the following:
The Documentation is in: /Library/Documentation/Services/apache
the "/manual/" path is a symlink in the /Library/WebServer/Documents folder, which points to the actual location.
If the symlink is not there any more, recreate it by:
sudo ln -s /Library/Documentation/Services/apache /Library/WebServer/Documents/manual.
Then, turn on personal web sharing and again try to go to:
http://localhost/manual/

If that still does not work, use the online version at the apache website - it should be more recent anyway.

Reply

Answer 4

Apr 30, 2006 1:14 PM in response to Joe Wheeler

Joe--

If you clicked on Camelot's link and it didn't work, have you activated Personal Web Sharing in your System Preferences? As Camelot says, the way the files are laid out, they won't work if you just open the files directly without using a web server.

Like nobody loopback says, you can always use the docs at Apache's site. Since they're served through a web server, all the links will work properly.

The reason things are this way is that Apache distributes the documentation for multiple languages. It's relying on a feature of the Apache server called Content Negotiation. For example, if your browser showed you preferred French pages, even though you might be requesting the index.html page, Apache will give you index.html.fr. If you look at the links in the French page, you'll see that they're just generic links, so that if a French page exists it'll serve it out, but if not, it will just serve up the page in whatever default language is available. In the case of the Apache pages, it's the page with .html.html on the end. But, as you've seen, without the intervention of the web server, the browser simply doesn't know how to follow the links.

charlie

Reply

Answer 5

Joe Wheeler Author

Level 1

75 points

Apr 30, 2006 4:08 PM in response to Charles Minow

...
The reason things are this way is that Apache
distributes the documentation for multiple languages.
It's relying on a feature of the Apache server called
Content Negotiation.

Thank you Charlie, now the question is answered. I still fault the Help documentation supplied by Apple, which should add something like "Personal Web Sharing must be active to view the manual."

I'm one of those people who won't activate that opens my computer to the Internet without understanding it first. As you say, I can look at the Web served version until I feel I know enough to activate PWS.

My reason for looking into this in the 1st place is to figure out a way to preview in-progress web pages made in a web authoring program that, since Tiger, no longer works directly from the authoring progam via "View in Browser". I'm not interested in any kind of WAN sharing.

Reply

Answer 6

Apr 30, 2006 8:48 PM in response to Joe Wheeler

Joe--

I still fault the Help documentation supplied by Apple,
which should add something like "Personal Web Sharing
must be active to view the manual."

I looked at the Mac Help page and I agree, it's not very clear about that. I've sent in feedback to Apple, so maybe they'll make it a little clearer in the future.

My reason for looking into this in the 1st place is
to figure out a way to preview in-progress web pages

Yep, that's a perfect use for it, and one I use for a couple of different sites, both personal and for work.

"View in Browser". I'm not interested in any kind of
WAN sharing.

Well, if you're already behind a firewall, and it's not set up to forward port 80 to your computer, you should already be all set. Otherwise, you can use Apache itself to deny the pages to any client but your own computer if you want.

charlie

Reply