+# The Ardour Manual
-The Ardour Manual
-===================
+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 python 3.
-This is the project that generates the static ardour manual website available at http://manual.ardour.org.
+### Get the code
-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.
+ git clone <repo-url> ardour-manual
+ cd ardour-manual
-To generate the site and run it up locally you can do something like:
+## Structure of the content
- git clone <repo-url>
- cd ardour-manual
- ruby export.rb
- jekyll --server
+There are 2 different types of content:
-To upload it (assuming your ssh key has been put on the server) you run:
+- a master document which describes the overall structure of the manual
+- normal content, which is described in the master document
- ./upload.sh
+### The Master Document
+This is a text file (master-doc.txt) which describes the structure of the manual. It does this
+through headers which tell the build script where the content lives, what its
+relationship to the overall structure is, as well as a few other things.
-Strucuture of the content
-----------------------
+All headers have a similar structure, and have to have at least the following
+minimal structure:
-There are 2 different types of content:
-- special manual content
-- normal content
+ ---
+ title: Some Wordy and Expressive Title
+ part: part
+ ---
-Special manual content
-----------------------
+Keywords that go into the header are of the form:
-This is content that ends up as part of the tree on the left.
+ keyword: value
-The _raw_ content is in `_manual` directory and has a naming convention as follows:
+Here are the keywords you can put in, and a brief description of what they do:
- # content for a page at http://manual.ardour.org/<slug>/
- <ordering>_<slug>.<html|md|textile>
- ^ ^ ^
- | | |
- | | extension is removed later
- | |
- | ends up as part of URL
- |
- only used for ordering
+| Keyword | Meaning |
+| ------- | -------- |
+| title | Sets the title for the content that follows |
+| menu_title | Sets the title for the content that follows which will appear in the menu link sidebar. If this is not specified, it defaults to the value of the `title` keyword |
+| part | Sets the hierarchy for the content that follows. It must be one of the following (listed in order of lowering hierarchy): part, chapter, subchapter, section, subsection. |
+| link | Sets the unbreakable link to the content that follows. Links in the *content* should be prefixed with a double at-sign (@@) to tell the build system that the link is an internal one |
+| include | Tells the build system that the content lives in an external file; these normally live in the `include/` directory. Note that the filename should **not** be prefixed with `include/` |
+| exclude | Tells the `implode` and `explode` scripts that file referred to by the `include` keyword should be ignored. Note that the value of this keyword is ignored |
+| style | Sets an alternate CSS stylesheet; the name should match the one referred to (sans the `.css` suffix) in the `source/css` directory |
+### Normal content
- # a folder for subcontent is like this
+Manual content goes into the `include/` directory (or in the Master Document itself); and consists of normal HTML, sans the usual headers that is normally seen in regular HTML web pages. Any other content, such as css files, images, files and fixed pages goes into the `source/` directory.
- <ordering>_<slug>/
+Adding `source/images/horse.png` makes it available at the url `/images/horse.png` after publishing it; things work similarly for `source/files/` and `source/css/`.
- # more things can then go in here for http://manual.ardour.org/<slug>/<slug2>/
+## More Advanced Stuff
- <ordering>_<slug>/<ordering2>_<slug2>.html
+You probably don't want or need to do any of this, but here are some
+notes just in case you decide to anyway.
-So, for example:
+### Run it locally
- this file appears at
- ------------ ------------
+You may want the manual available on a machine that doesn't have constant
+internet access. You will need `git`, and `python` installed.
- 01_main.html /main/
+1. Download code and build manual
- 01_main/01_subpage.html /main/subpage/
+ ```
+ git clone <repo-url> ardour-manual
+ cd ardour-manual
+ ./build.py
+ ```
+2. open `ardour-manual/website/index.html` in your favorite web browser
-Normal content
-----------------------
+ 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!
-This is anything else, css files, images, fixed pages, layouts. This content lives in the `source` directory.
+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;
-Content processing
-----------------------
+ root ...path_to_.../ardour-manual/website;
+ index index.html;
+ }
+ ```
-Three types of content can have special processing done.
+5. Restart nginx server
-- `.html` files
-- `.md` files
-- `.textile` files
+ service nginx restart
-All special files should also have a special header at the top too:
+6. The manual will now be available at http://localhost
- ---
- layout: default
- title: Some Very Wordy and Expressive Title
- menu_title: Some Title
- ---
+### Helper scripts: `implode` and `explode`
- <p>My Actual Content</p>
+The `implode` and `explode` scripts exist in order to accomodate different working styles. `implode` takes all the files referenced by the `include` keywords in the headers in the Master Document and automagically puts them into the Master Document in their proper places. Note that any header that has an `exclude` keyword will remain in the `include/` directory. `explode` does the inverse of `implode`; it takes all the content in the Master Document and blows it into individual files in the `include/` directory. Filenames are automagically derived from the value of the `title` keyword.
-
\ No newline at end of file
projects / ardour-manual / blobdiff