Sync with master branch.

[ardour-manual-diverged] / README.md

diff --git a/README.md b/README.md
index 9a277eade36057275d260dd853dd82ef45c5b396..fd61c3b5ca408d6772596017e7333d010d7ed2b6 100644 (file)
--- a/README.md
+++ b/README.md
@@ -4,13 +4,13 @@
 
 This is the project that generates the static ardour manual website available at [manual.ardour.org](http://manual.ardour.org).
 
-The site is built using ruby (I use 1.9[.3]) and [Jekyll](https://github.com/mojombo/jekyll) (a ruby gem). You should be able to just install ruby and then `gem install jekyll` to get it up and running.
+The site is built using ruby (I use 1.9[.3]) and [liquid](http://liquidmarkup.org/), a ruby gem.
 
 ### Get the code
 
-    git clone <repo-url>
+    git clone <repo-url> ardour-manual
     cd ardour-manual
-    
+
 ## Structure of the content
 
 There are 2 different types of content:
@@ -30,7 +30,7 @@ The _raw_ content is in `_manual/` directory and has a naming convention as foll
        ^          ^     ^
        |          |     |
        |          |   extension is removed later
-       |          |        
+       |          |
        |     ends up as part of URL
        |
      only used for ordering
@@ -67,8 +67,8 @@ Content processing is applied to normal content if it has the correct header as
 Three types of content can have special processing done.
 
 - `.html` liquid/HTML files
-- `.md` markdown files
-- `.textile` textile files
+- `.md` markdown files (NOPE!)
+- `.textile` textile files (NOPE!)
 
 All files to be processed should also have a special header at the top too:
 
@@ -79,9 +79,9 @@ All files to be processed should also have a special header at the top too:
     ---
 
     <p>My Actual Content</p>
-    
+
 The `title` field will end up as an `h1` in the right panel. The `menu_title` is what is used in the menu tree on the left (if not preset it will default to using `title`).
-    
+
 ### `.html` files
 
 These are almost normal html, but extended with [Liquid templates](http://liquidmarkup.org/). There are a couple of special tags created for this project.
@@ -97,15 +97,46 @@ notes just in case you decide to anyway.
 
 ### Run it locally
 
-This will generate the final html and start a local webserver.
+You may want the manual available on a machine that doesn't have constant
+internet access. You will need `git`, `ruby`, and the ruby gem `liquid` installed.
+
+1. Download code and build manual
+
+  ```
+  git clone <repo-url> ardour-manual
+  cd ardour-manual
+  cp -r source _site
+  ruby ./build.rb
+  chmod -R a+rx _site
+  ```
+
+2. open `ardour-manual/_site/index.html` in your favorite web browser
+
+  If this page doesn't open and function correctly, follow these optional steps to serve up the page with nginx.
+  N.B.: Step 2 will *never* work; you *must* install nginx if you want to see it!
+
+3. Install [nginx](http://wiki.nginx.org/Install)
+4. Configure nginx server block in `/etc/nginx/sites-available/default`
+
+  ```
+  server {
+      listen 80;
+      server_name localhost;
+
+      root ...path_to_.../ardour-manual/_site;
+      index index.html;
+  }
+  ```
+
+5. Restart nginx server
+
+        service nginx restart
+
+6. The manual will now be available at http://localhost
 
-    jekyll serve
-    
-It should then be available at [localhost:4000](http://localhost:4000)
-    
 ### manual.rb plugin
 
-Much of the functionality comes from `_plugins/manual.rb` - it takes the _manual format_ (contained in `_manual/`) and mushes it around a bit into a tmp directory before letting jekyll do it's normal thing. It's all hooked into the jekyll command so no special actions are required.
+Much of the functionality comes from `_plugins/manual.rb` - it takes the _manual format_ (contained in `_manual/`) and mushes it around a bit into a tmp directory.
 
 This is to enable the directory tree to be understood, child page lists to be constructed, clean URLs, and the correct ordering of pages maintained.
 
@@ -115,8 +146,22 @@ To allow the clean URLs (no `.html` extension) _and_ to support simple hosting (
 
 E.g. `02_main/05_more/02_blah.html` after all processing is complete would end up in `_site/main/more/blah/index.html`.
 
-The page format contained in the `_manual/` directory is different to the final rendered output (see special `_manual` content above) to make it simple to create content (you don't need to think about the `index.html` files). 
+The page format contained in the `_manual/` directory is different to the final rendered output (see special `_manual` content above) to make it simple to create content (you don't need to think about the `index.html` files).
+
+### New Stuff
+
+The above will have to be revised eventually, but for now, here's what's what:
+
+1. All content lives in master-doc.txt and in include/ .
+
+2. A little C helper program needs to be built and run. To build it, do:
+
+        gcc munge.cpp -o munge -lstdc++ -g
+
+3. Run the 'doit' script:
+
+        ./doit
 
+4. Now _site/ should contain the correct built site. Have fun! ;-)
 
 
-