# 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 [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.
+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
- git clone <repo-url>
+ git clone <repo-url> ardour-manual
cd ardour-manual
-
+
## Structure of the content
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.
-
-The _raw_ content is in `_manual/` directory and has a naming convention as follows:
+- a master document which describes the overall structure of the manual
+- normal content, which is described in the master document
- # content for a page at http://manual.ardour.org/<slug>/
+### The Master Document
- <ordering>_<slug>.<html|md|textile>
- ^ ^ ^
- | | |
- | | extension is removed later
- | |
- | ends up as part of URL
- |
- only used for ordering
+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.
+All headers have a similar structure, and have to have at least the following
+minimal structure:
- # a folder for subcontent is like this
-
- <ordering>_<slug>/
-
- # more things can then go in here for http://manual.ardour.org/<slug>/<slug2>/
+ ---
+ title: Some Wordy and Expressive Title
+ part: part
+ ---
- <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 |
+| pdf-exclude | Does not include the content in the generated PDF, but links to its online contents. The value is also 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
-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.
+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.
-Content processing is applied to normal content if it has the correct header as described below.
+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/`.
+### CSS
-## 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
+The manual uses [Bootstrap](http://getbootstrap.com/) for its global layout, and
+a few custom CSS files 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:
+- `source/css/common.css` contains shared classes between all media and is included everywhere
+- `source/css/screen.css` adds classes used for screen display (html)
+- `source/css/pdf.css` adds classes used for print (pdf)
+- `source/css/luadocs.css` adds classes used in the Lua script documentation
## More Advanced Stuff
### Run it locally
-This will generate the final html and start a local webserver.
-
- jekyll serve
-
-It should then be available at [localhost:4000](http://localhost:4000)
-
-### manual.rb plugin
+You may want the manual available on a machine that doesn't have constant
+internet access. You will need `git`, `python3` and `cherrypy` python module installed.
-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.
+1. Download code and build manual
-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.
+ ```
+ git clone <repo-url> ardour-manual
+ cd ardour-manual
+ ./build.py
+ ```
-### Clean URLs
+2. Run the following:
+ ```
+ ./servit.py
+ ```
-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.
+3. The manual will now be available at http://127.0.0.1:8080
-E.g. `02_main/05_more/02_blah.html` after all processing is complete would end up in `_site/main/more/blah/index.html`.
+ (Ctrl-c to quit the server).
-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.
+### Build options
-
+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)
+- '-n', or '--nopdf', to prevent the build script from generate a PDF from the content
projects / ardour-manual / blobdiff