X-Git-Url: http://shamusworld.gotdns.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=README.md;h=00fdfa3549f09b3560c30ff79787242b5bdb0c2e;hb=f3b368152615f68cecd97ba461a495d84c691b3e;hp=013724e38bdc31b1110088b20349cf53c15e8142;hpb=ae6efdc4a0dd1825a30a1b95b70d6a5f799713a9;p=ardour-manual diff --git a/README.md b/README.md index 013724e..00fdfa3 100644 --- a/README.md +++ b/README.md @@ -1,91 +1,128 @@ -The Ardour Manual -=================== +# The Ardour Manual -This is the project that generates the static ardour manual website available at http://manual.ardour.org. +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. -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. +### Get the code -To generate the site and run it up locally you can do something like: - - git clone + git clone ardour-manual cd ardour-manual - ruby export.rb - jekyll --server -To upload it (assuming your ssh key has been put on the server) you run: +## Structure of the content - ./upload.sh +There are 2 different types of content: +- a master document which describes the overall structure of the manual +- normal content, which is described in the master document -Strucuture of the content ----------------------- +### The Master Document -There are 2 different types of content: -- special manual content -- normal content +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. -Special manual content ----------------------- +All headers have a similar structure, and have to have at least the following +minimal structure: -This is content that ends up as part of the tree on the left. + --- + title: Some Wordy and Expressive Title + part: part + --- -The _raw_ content is in `_manual` directory and has a naming convention as follows: +Keywords that go into the header are of the form: - # content for a page at http://manual.ardour.org// + keyword: value - _. - ^ ^ ^ - | | | - | | extension is removed later - | | - | ends up as part of URL - | - only used for ordering +Here are the keywords you can put in, and a brief description of what they do: - # a folder for subcontent is like this +| 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 | +| uri | Sets an absolute URI where this page will go in the hierachy of the created website. It does *not* change the document structure | - _/ +### Normal content - # more things can then go in here for http://manual.ardour.org/// +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. - _/_.html +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/`. -So, for example: +### CSS - this file appears at - ------------ ------------ +The manual uses [Bootstrap](http://getbootstrap.com/) for its global layout, and +a custom CSS (`source/css/app.css`) that contains classes used for keys, menus, +tables, etc... so it is recommanded to have a look at it first, or at least see +how other pages are made to keep the manual consistent in its appearance. - 01_main.html /main/ +## More Advanced Stuff - 01_main/01_subpage.html /main/subpage/ +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 -Normal content ----------------------- +You may want the manual available on a machine that doesn't have constant +internet access. You will need `git`, and `python3` installed. -This is anything else, css files, images, fixed pages, layouts. This content lives in the `source` directory. +1. Download code and build manual + ``` + git clone ardour-manual + cd ardour-manual + ./build.py + ``` -Content processing ----------------------- +2. Install and configure a web server on your machine. Any web server should +work, Apache, nginx, etc... The following steps are for nginx, using another +server means following the same procedure for the server you decide to use. -Three types of content can have special processing done. +3. Install [nginx](http://wiki.nginx.org/Install) -- `.html` files -- `.md` files -- `.textile` files +4. Configure nginx server block in `/etc/nginx/sites-available/default` -All special files should also have a special header at the top too: + ``` + server { + listen 80; + server_name localhost; - --- - layout: default - title: Some Very Wordy and Expressive Title - menu_title: Some Title - --- + root ...path_to_.../ardour-manual/website; + index index.html; + } + ``` + +5. Restart nginx server + + service nginx restart + +6. The manual will now be available at http://localhost + +### Helper scripts: `implode` and `explode` -

My Actual Content

+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. +### Build options - \ No newline at end of file +The `build.py` script that builds the manual accepts the following options: +- '-v', or '--verbose', to display the high-level structure of the manual +- '-q', or '--quiet', to suppress all output (overrides -v) +- '-d', or '--devmode', to add content to pages to help developers debug them +(link, file name, URL)