whimsical-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Chris Mattmann <mattm...@apache.org>
Subject [whimsy.git] [6/6] Commit 40b4b47: Merge pull request #1 from chrismattmann/fix-markdown
Date Sun, 03 Jan 2016 17:22:02 GMT
Commit 40b4b47842943019f55e53eb80516aec95d3471b:
    Merge pull request #1 from chrismattmann/fix-markdown
    Finish cleaning up Markdown README file.


Branch: refs/heads/master
Author: Chris Mattmann <chris.mattmann@gmail.com>
Committer: Chris Mattmann <chris.mattmann@gmail.com>
Pusher: mattmann <mattmann@apache.org>

------------------------------------------------------------
README.md                                                    | ++++++ -------
------------------------------------------------------------
100 changes: 46 additions, 54 deletions.
------------------------------------------------------------


diff --git a/README.md b/README.md
index 045f438..ddbe85b 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,5 @@
-************************************************************************
-*                               Preface                                *
-************************************************************************
+Preface
+=======
 
 Whimsy is a set of independent tools and a common library which typically will
 need to access various ASF SVN directories and/or LDAP.  To do development and
@@ -13,38 +12,35 @@ 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
 arrange to either duplicate or mount your SVN directories.
 
-************************************************************************
-*                               Overview                               *
-************************************************************************
+Overview
+========
 
 This directory has two main subdirectories...
 
-1) "asf" contains the "model", i.e., a set of classes which encapsulate access
+1. "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.
+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,
    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 the following
-   request is complete:
+   consolidated to the consolidated svn repository once 
+   [INFRA-10399](https://issues.apache.org/jira/browse/INFRA-10399) 
+   is complete.
 
-     https://issues.apache.org/jira/browse/INFRA-10399
-
-************************************************************************
-*                                Setup                                 *
-************************************************************************
+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
    the system provided version include using a Ruby version manager like
@@ -52,79 +48,75 @@ Skip this section if you are running a Docker container or a Vagrant VM.
    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/)
 
-   Links:
-
-   https://github.com/sstephenson/rbenv#understanding-shims
-   https://github.com/sstephenson/rbenv/wiki/Understanding-binstubs
-
-   https://rvm.io/
-
-2) Make sure that the whimsy-asf gem installed.  If it is not, run
+2. Make sure that the whimsy-asf gem installed.  If it is not, run
 
-  gem install whimsy-asf
+  `gem install whimsy-asf`
 
-3) current SVN checkouts of various repositories are made (or linked to from)
-   /home/whimsysvn/svn:
+3. current SVN checkouts of various repositories are made (or linked to from)
+   `/home/whimsysvn/svn`
 
+```
    svn co --depth=files https://svn.apache.org/repos/private/foundation
+```
 
    You can specify an alternate location for these directories by placing
    a configuration file named `.whimsy` in your home directory.  The format
    for this file is YAML, and an example (be sure to include the dashed
    lines):
 
-     ---
+```
      :svn:
      - /home/rubys/svn/foundation
      - /home/rubys/svn/committers
+```
 
-4) Access to LDAP requires configuration, and a cert.
-
-   a) The model code determines what host and port to connect to by parsing
-      either /etc/ldap/ldap.conf or /etc/ldap/ldap.conf for a line that looks
+4. Access to LDAP requires configuration, and a cert.
+ 1. The model code determines what host and port to connect to by parsing
+      either `/etc/ldap/ldap.conf` or `/etc/ldap/ldap.conf` for a line that looks
       like the following:
-        uri     ldaps://ldap1-us-east.apache.org:636
+        `uri     ldaps://ldap1-us-east.apache.org:636`
 
-   b) A TLS_CACERT can be obtained via either of the following commands:
+ 2. A `TLS_CACERT` can be obtained via either of the following commands:
 
-        ruby -r whimsy/asf -e "puts ASF::LDAP.cert"
-        openssl s_client -connect ldap1-us-east.apache.org:636 </dev/null
+        `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 
-      /etc/ldap/asf-ldap-client.pem.  Point to the file in
-      /etc/ldap/ldap.conf with a line like the following:
+      `/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
+     ```   TLS_CACERT      /etc/ldap/asf-ldap-client.pem```
 
       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"
+        `sudo ruby -r whimsy/asf -e "ASF::LDAP.configure"`
 
       Note: the certificate is needed because the LDAP hosts use a self-signed
       certificate
 
-5) Verify that the configuration is correct by running:
+5. Verify that the configuration is correct by running:
 
-   ruby examples/board.rb
+   `ruby examples/board.rb`
 
    See comments in that file for running the script as a standalone server.
 
-************************************************************************
-*                           Further reading                            *
-************************************************************************
-
-An example of a complete tool that makes full use of the library factoring,
-has a suite of test cases, and client componentization (using ReactJS), and
-provides instructions for setting up both a Docker component and a Vagrant VM:
+Further Reading
+===============
 
-  https://github.com/rubys/whimsy-agenda#readme
+An [example](https://github.com/rubys/whimsy-agenda#readme) of a complete tool 
+that makes full use of the library factoring, has a suite of test cases, and 
+client componentization (using ReactJS), and provides instructions for setting 
+up both a Docker component and a Vagrant VM:
 
 If you would like to understand how the view code works, you can get started
-by looking at a few of the Wunderbar demos and README:
-
-  https://github.com/rubys/wunderbar/tree/master/demo
-  https://github.com/rubys/wunderbar/blob/master/README.md
+by looking at a 
+few of the [Wunderbar demos](https://github.com/rubys/wunderbar/tree/master/demo) 
+and [README](https://github.com/rubys/wunderbar/blob/master/README.md).

Mime
View raw message