whimsical-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sam Ruby <ru...@apache.org>
Subject [whimsy.git] [1/1] Commit 7754fea: editorial pass
Date Wed, 06 Jan 2016 18:22:30 GMT
Commit 7754fea6bbe33557bfe26897c761c29381bc0b1f:
    editorial pass


Branch: refs/heads/master
Author: Sam Ruby <rubys@intertwingly.net>
Committer: Sam Ruby <rubys@intertwingly.net>
Pusher: rubys <rubys@apache.org>

------------------------------------------------------------
README.md                                                    | ++++++++ ------
------------------------------------------------------------
51 changes: 29 additions, 22 deletions.
------------------------------------------------------------


diff --git a/README.md b/README.md
index 947bfff..60205c9 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,8 @@ need to access various ASF SVN directories and/or LDAP.  To do development
and
 testing, you will need access to a machine on which you are willing to install
 libraries which do things like access LDAP, XML parsing, composing mail and
 the like.  While some tools may work on Microsoft Windows, many don't
-currently.  Alternatives include a Docker image or a Vagrant VM.
+currently.  Alternatives include a Docker image, a custom Vagrant VM, and
+a Kitchen/Puppet managed Vagrant VM.
 
 The primary advantage of using an image or a VM is isolation.  The primary
 disadvantage is that you will need to install your SVN credentials there and
@@ -17,22 +18,25 @@ Overview
 
 This directory has two main subdirectories...
 
-1. "asf" contains the "model", i.e., a set of classes which encapsulate access
+1. [lib/whimsy/asf](lib/whimsy/asf) contains the "model", i.e., a set of classes 
+   which encapsulate access
    to a number of data sources such as LDAP, ICLAs, auth lists, etc.  This
    code originally was developed as a part of separate tools and was later
    refactored out into a common library.  Some of the older tools don't fully
    make use of this refactoring.
 
-2. "www" contains the "view", largely a set of cgi scripts that produce HTML.
-   Generally a cgi script is self contained, including all of the CSS,
+2. [www](www) contains the "view", largely a set of CGI scripts that produce HTML.
+   Generally a CGI script is self contained, including all of the CSS,
    scripts, AJAX logic (client and server), SVG images, etc.  A single script
    may also produce a set (subtree) of web pages. 
 
-   Some of the scripts (like the roster tool) are long running servers.  The
-   board agenda tool is currently hosted on github, but this will be
-   consolidated to the consolidated svn repository once 
-   [INFRA-10399](https://issues.apache.org/jira/browse/INFRA-10399) 
-   is complete.
+   Some of the directories (like the roster tool) contain [rack](http://rack.github.io/)
+   applications.  These can be run independently, or under the Apache web server through
+   the use of [Phusion Passenger](https://www.phusionpassenger.com/). 
+   
+   The board agenda tool is currently hosted [separately](https://github.com/rubys/whimsy-agenda)

+   on github, but this will be consolidated into this repository as a part of the effort
+   to move whimsy.apache.org to a new VM.
 
 Setup
 =====
@@ -40,20 +44,23 @@ Setup
 This section is for those desiring to run a whimsy tool on their own machine.
 Skip this section if you are running a Docker container or a Vagrant VM.
 
-1. The ruby version needs be ruby 1.9.3 or higher.  Verify with 'ruby -v'.
+1. The ruby version needs be ruby 1.9.3 or higher.  Verify with `ruby -v`.
    If you use a system provided version of Ruby, you may need to prefix
-   certain commands (like gem install) with 'sudo'.  Alternatives to using
+   certain commands (like gem install) with `sudo`.  Alternatives to using
    the system provided version include using a Ruby version manager like
    rbenv or rvm.  Rbenv generally requires you to be more aware of what you
    are doing (e.g., the need for shims).  While rvm tends to be more of a set
    and forget operation, it tends to be more system intrusive (e.g. aliasing
    'cd' in bash).
- ## Links
- 1. [Understanding Shims](https://github.com/sstephenson/rbenv#understanding-shims)
- 2. [Understanding Binstubs](https://github.com/sstephenson/rbenv/wiki/Understanding-binstubs)
- 3. [Ruby Version Manager](https://rvm.io/)
 
-2. Make sure that the whimsy-asf gem installed.  If it is not, run
+    For more information:
+    
+    1. [Understanding Shims](https://github.com/sstephenson/rbenv#understanding-shims)
+    2. [Understanding Binstubs](https://github.com/sstephenson/rbenv/wiki/Understanding-binstubs)
+    3. [Ruby Version Manager](https://rvm.io/)
+    
+
+2. Make sure that the `whimsy-asf` gem installed.  If it is not, run
 
   `gem install whimsy-asf`
 
@@ -83,21 +90,21 @@ Skip this section if you are running a Docker container or a Vagrant VM.
         `ruby -r whimsy/asf -e "puts ASF::LDAP.cert"`<br/>
         `openssl s_client -connect ldap1-us-east.apache.org:636 </dev/null`
 
-      Copy from BEGIN to END inclusive into the file 
+      Copy from `BEGIN` to `END` inclusive into the file 
       `/etc/ldap/asf-ldap-client.pem`.  Point to the file in
       `/etc/ldap/ldap.conf` with a line like the following:
 
      ```   TLS_CACERT      /etc/ldap/asf-ldap-client.pem```
 
-      N.B. OpenLDAP uses /etc/openldap/ instead of /etc/ldap/ 
+      N.B. OpenLDAP uses `/etc/openldap/` instead of `/etc/ldap/` 
       Adjust the paths above as necessary
- 
-      These above updates can be done for you with the following command:
-
-        `sudo ruby -r whimsy/asf -e "ASF::LDAP.configure"`
 
       Note: the certificate is needed because the LDAP hosts use a self-signed
       certificate
+      
+   These above updates can be done for you with the following command:
+
+        sudo ruby -r whimsy/asf -e "ASF::LDAP.configure"
 
 5. Verify that the configuration is correct by running:
 

Mime
View raw message