Item10996: Various typoes/fixes for online docs and web pages
Current State: Closed
Released In: 1.1.4
Target Release: patch
Applies To: Engine
On the Apache Config Generator page, the reader is advised to generate the config file, then "paste the generated configuration" into their existing config file. For most Apache installs, however, it's cleaner to add a new file to the configuration subdirectory /etc/apache2/conf.d, so as to leave the original, package-installed files unmodified.
- 22 Jul 2011
(As a side note, there's no task category for documentation; the closest I could find was "Web Page" so I went with that. As long as I can add extra content to a task on an ongoing basis, I'll just append observations as I find them. Perhaps another task would be opening up a task category for documentation?
Note that any documentation outside of the "System" web can be updated by anyone registered to the Foswiki site. Please feel free to fix errors like this by editing the topic. -- GeorgeClark - 22 Jul 2011
- In the Installation Guide, Part 1, under "Apache config file", there is a reference to the web server config file "http.conf". I've seen config files apache2.conf and httpd.conf, but never just http.conf. Did you really mean httpd.conf? (And I know I've seen another reference to "http.conf" elsewhere on the web site, just don't remember where. AH, found it, it's on the Apache Config Generator web page.) (Fixed)
- In the Installation Guide "Configure the web server" section, the latter part of that section is a bit confusing. Under "Protect the configure script," there are instructions on how to run "htpasswd" to protect that script, but there is also a reference to the Apache Config Generator (described in the next section), and the way that is worded, it's unclear whether a reader would choose which approach to take, or whether he must do both (that is, run "htpasswd", followed by running the config generator.)
Unfortunately this becomes a bit of a peeling the onion exercise - at what point is everyone's eyes watering from details. The recommendation to use
htpasswd in the suggested form generates a "crypt" encrypted password which is the weakest of the methods and ignores anything beyond the first 8 characters of the password. It should probably suggest
-s to generate a SHA1 hash, or better yet use of htdigest authentication. But this needs to be balanced with the need to get the new user up and running. -- GeorgeClark - 22 Jul 2011
(Fixed) I've tried to clarify this a bit. Added an example of using a separate .htpasswd file to protect configure v.s. Foswiki. -- GeorgeClark - 01 Oct 2011
- Regarding required Perl modules, it might be worth showing readers how to simply list all their installed modules in one shot. On Linux (at least on Ubuntu), there is a "pmtools" package that provides numerous handy utilities, particularly "pmall" to list all of your installed modules. It's a judgment call as to whether this might be useful information for the reader to save them time.
On my distribution (gentoo) pmtools is the system power management tools. Not sure where to go with this one. The first run of configure will report any missing modules, and as you say, most distributions have all the dependencies already installed. We try to ship any non-perl-core dependencies in the lib/CPAN directory to avoid issues with missing modules. -- GeorgeClark - 22 Jul 2011
- I think one or more "Quick Start" sections would be useful. For instance, as you mention in the Installation Guide, if you're already running a recent distro of Linux, chances are you're almost set up. If that's the case, knowledgeable readers don't want to read the entire Install Guide, they just need the condensed recipe, which in most cases like that will be fairly short, probably less than one page.
More to come as I continue ...
- 22 Jul 2011
I've reworked some of the Installation guide to clarify the section about protecting configure. The revised document is at http://trunk.foswiki.org/System/InstallationGuidePart1
- 22 Jul 2011
Changing to Waiting for Release.
- 01 Oct 2011