-The Ardour Manual
-===================
+# The Ardour Manual
-This is the project that generates the static ardour manual website available at 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`. There are no other dependencies.
+This is the project that generates the static ardour manual website available at [manual.ardour.org](http://manual.ardour.org).
-To generate the site and run it up locally you can do something like:
+The site is built using ruby (I use 1.9[.3]) and [liquid](http://liquidmarkup.org/), a ruby gem.
- git clone <repo-url>
- cd ardour-manual
- ruby export.rb
- jekyll --server
-
-To upload it (assuming your ssh key has been put on the server) you run:
-
- ./upload.sh
+### Get the code
+ git clone <repo-url> ardour-manual
+ cd ardour-manual
-Strucuture of the content
-----------------------
+## Structure of the content
There are 2 different types of content:
-- special manual content
+
+- special `_manual` content
- normal content
-Special manual content
-----------------------
+### Special `_manual` content
This is content that ends up as part of the tree on the left.
-The _raw_ content is in `_manual` directory and has a naming convention as follows:
+The _raw_ content is in `_manual/` directory and has a naming convention as follows:
# content for a page at http://manual.ardour.org/<slug>/
^ ^ ^
| | |
| | extension is removed later
- | |
+ | |
| ends up as part of URL
|
only used for ordering
So, for example:
- this file appears at
- ------------ ------------
-
- 01_main.html /main/
- 01_main/01_subpage.html /main/subpage/
+| this file | appears at url |
+|--------------------------------------------------------|
+| _manual/01_main.html | /main/ |
+| _manual/01_main/01_subpage.html | /main/subpage/ |
-Normal content
-----------------------
+### Normal content
This is anything else, css files, images, fixed pages, layouts. This content lives in the `source` directory.
+If you added `source/images/horse.png` is would be available at the url `/images/horse.png` after publishing it.
-Content processing
-----------------------
+Content processing is applied to normal content if it has the correct header as described below.
+
+
+## Content processing
Three types of content can have special processing done.
-- `.html` files
-- `.md` files
-- `.textile` files
+- `.html` liquid/HTML files
+- `.md` markdown files (NOPE!)
+- `.textile` textile files (NOPE!)
-All special files should also have a special header at the top too:
+All files to be processed should also have a special header at the top too:
---
layout: default
<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.
+
+- `{% tree %}` is what shows the manual structure in the left column
+- `{% children %}` shows the immediate list of children for a page
+
+
+## More Advanced Stuff
+
+You probably don't want or need to do any of this, but here are some
+notes just in case you decide to anyway.
+
+### Run it locally
+
+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
+
+### 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.
+
+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.
+
+### Clean URLs
+
+To allow the clean URLs (no `.html` extension) _and_ to support simple hosting (no `.htaccess` or apache configuration required) each page ends up in it's own directory with an `index.html` page for the content.
+
+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).
+
+### 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! ;-)
+
-
\ No newline at end of file
projects / ardour-manual-diverged / blobdiff