New build system for documentation.

The new build system is documented in README.md, take a look to see the
nitty gritty. Major changes are: structure of the document is no longer
controlled by the filesystem, internal links are now 'unbreakable'.

README.md

@@ -1,10 +1,7 @@
 
 # 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 ruby (I use 1.9[.3]) and [liquid](http://liquidmarkup.org/), a ruby gem.
+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.
 
 ### Get the code
 
@@ -15,80 +12,45 @@ The site is built using ruby (I use 1.9[.3]) and [liquid](http://liquidmarkup.or
 
 There are 2 different types of content:
 
-- special `_manual` content
-- normal content
-
-### Special `_manual` content
-
-This is content that ends up as part of the tree on the left.
+- a master document which describes the overall structure of the manual
+- normal content, which is described in the master document
 
-The _raw_ content is in `_manual/` directory and has a naming convention as follows:
+### The Master Document
 
-    # content for a page at http://manual.ardour.org/<slug>/
+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.
 
-    <ordering>_<slug>.<html|md|textile>
-       ^          ^     ^
-       |          |     |
-       |          |   extension is removed later
-       |          |
-       |     ends up as part of URL
-       |
-     only used for ordering
+All headers have a similar structure, and have to have at least the following
+minimal structure:
 
+    ---
+    title: Some Wordy and Expressive Title
+    part: part
+    ---
 
-    # a folder for subcontent is like this
-
-    <ordering>_<slug>/
-
-    # more things can then go in here for http://manual.ardour.org/<slug>/<slug2>/
-
-    <ordering>_<slug>/<ordering2>_<slug2>.html
+Keywords that go into the header are of the form:
 
-So, for example:
+	keyword: value
 
+Here are the keywords you can put in, and a brief description of what they do:
 
-| this file                        | appears at url      |
-|--------------------------------------------------------|
-| _manual/01_main.html             | /main/              |
-| _manual/01_main/01_subpage.html  | /main/subpage/      |
 
+| 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
 
-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 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` liquid/HTML files
-- `.md` markdown files
-- `.textile` textile files
-
-All files to be processed should also have a special header at the top too:
-
-    ---
-    layout: default
-    title: Some Very Wordy and Expressive Title
-    menu_title: Some Title
-    ---
-
-    <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
+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.
 
+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 Advanced Stuff
 
@@ -98,21 +60,20 @@ 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.
+internet access. You will need `git`, and `python` 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
+  ./build.py
   ```
 
-2. open `ardour-manual/_site/index.html` in your favorite web browser
+2. open `ardour-manual/website/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`
@@ -122,7 +83,7 @@ internet access. You will need `git`, `ruby`, and the ruby gem `liquid` installe
       listen 80;
       server_name localhost;
 
-      root ...path_to_.../ardour-manual/_site;
+      root ...path_to_.../ardour-manual/website;
       index index.html;
   }
   ```
@@ -133,20 +94,8 @@ internet access. You will need `git`, `ruby`, and the ruby gem `liquid` installe
 
 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).
-
+### Helper scripts: `implode` and `explode`
 
+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.
 
 

STYLE_GUIDE

@@ -114,17 +114,17 @@ is renamed or moved to another sub-directory, links should be ok.
 <dfn>
 encloses a newly introduced term that is being explained. Use for the first
 occurrence of the main concept of every manual page, or the first occurrence
-of a new concept after a sub-heading if necessary. Renders in bold face.
-Keep in mind that <dfn> tags might be used to generate an index of keywords
-- don't pollute it too much.
+of a new concept after a sub-heading if necessary. Renders in bold face. Keep
+in mind that <dfn> tags might be used to generate an index of keywords--don't
+pollute it too much.
 
 <abbr>
 is used to explain an abbreviation such as <abbr title="Linux Audio
 Developers Simple Plugin API">LADSPA</abbr>. Browsers will usually pop up the
 definition when the user hovers over the word. Renders as dotted underlined
 in most browsers.
 On each page, use only for the first occurrence of every abbreviation. Avoid
-a redundant explanation in the text - the expansion can easily be extracted 
+a redundant explanation in the text--the expansion can easily be extracted 
 via CSS for printing.
 Use only in the text body, not in headings.
 
@@ -138,6 +138,7 @@ is used to strongly emphasize a word. Commonly rendered in bold.
 See above for usage.
 
 <br />
+Most of the time, these should be avoided, and used very infrequently.
 A line-break can sometimes be used to structure a paragraph, or to split a
 longish heading. Never use spurious <br/>s at the end of paragraphs or to
 control the spacing of sections. If you're unhappy with those, fix the CSS
@@ -191,6 +192,9 @@ So if you want the user to press Ctrl-N on Linux, that's actually <kbd
 class="mod1">N</kbd>. It will render as "Ctrl N" for you, and as "Cmd N" for
 your Mac-using friend. Nice, uh?
 
+N.B.: If you want to have just the name of the modifier key by itself, use
+<kbd class="mod1>&zwnj;</kbd> (zero-width non-joiner).
+
 For anything you want the user to type, use <kbd> as a block-level element.
 See above for other <kbd> classes to denote menu items, selections, mouse
 events and controller actions.
@@ -227,7 +231,8 @@ descriptive 'alt="A short textual description of the image content"'
 element.
 Images are usually placed as block-level elements, i.e. outside of a
 paragraph, unless they are no higher than one row and make sense in the text
-flow.
+flow. Aside from this exception, they should *always* be wrapped inside of a
+<p></p> block.
 
 5. Other conventions
 ====================
@@ -240,21 +245,27 @@ flow.
   kind of subtle inflection, use semantic markup instead.
 * The hyphen is used to for compound words such as this well-advised example.
 * Do not hyphenate words at line breaks.
-* For breaks in thought &mdash; such as this splendid example &mdash; use
-  the long em-dash.
-* For ranges of values, use the en-dash: Monday &ndash; Friday, 0 &ndash;
-  11.
+* For breaks in thought&mdash;such as this splendid example&mdash;use
+  the long em-dash. Note that the em-dash is snugged up against the text on both
+  sides--this is the proper way to use them.
+* For ranges of values, use the en-dash: Monday&ndash;Friday, 0&ndash;11. Note
+  again, the en-dash is snugged up to its surrounding elements.
 * Use a non-breaking space ("&nbsp;") between a number and its unit.
+* Colons (":") always snug up to their text on the left: it is an error to add
+  space between text on the left and the colon.
 
 
 5.2 Language
 ------------
 
-* The Ardour manual is written in Americal English spelling.
+* The Ardour manual is written in American English spelling.
 * Use SI units with standard abbreviations. Give imperial units only as
   additional information, if at all.
-* Do not use contractions like "you'll", always write full forms.
-* Do not over-use "You", write about the program, not the user.
+* Do not use contractions like "it'll", always write full forms.
+* Do not over-use "You", write about the program, not the user. Avoid it if at 
+  all possible, it makes for tighter and better reading text.
+* Always write out numbers less than 11. E.g., "One or two ..." instead of
+  "1 or 2 ...".
 
 
 5.3 Chapter Headline Capitalization
@@ -297,6 +308,8 @@ content per heading and you do not expect the article to grow.
 * If pages grow long, consider splitting them into sub-chapters at their
 headings.
 * Nobody needs "the next paragraph is about the following" paragraphs.
+* When creating a <p class="note">NOTE</p>, *do not* put the word NOTE into
+  the note, the styling tells the user that it is a note.
 
 5.6. Encoding
 -------------
@@ -306,3 +319,4 @@ headings.
 HTML character entities instead, for example for cursor arrows: &rarr;
 &larr; &uarr; &darr;. Diacriticals on vowels and other special letters are
 probably ok by now, so don't bother with &eacute; and friends, just type é.
+