Update README.md
This commit is contained in:
parent
b8f143e350
commit
6e9c7edd1d
183
README.md
183
README.md
|
|
@ -5,23 +5,26 @@ deployment
|
||||||
|
|
||||||
### Install the dependencies
|
### Install the dependencies
|
||||||
|
|
||||||
1. flex (for hmmlib)
|
1. curl
|
||||||
2. curl (for cinera)
|
|
||||||
|
|
||||||
### Download, and prepare the parser
|
### Download, and copy the parser into place
|
||||||
|
|
||||||
1. `git clone git@gitssh.handmade.network:Annotation-Pushers/Annotation-System.git`
|
1. `git clone git@gitssh.handmade.network:Annotation-Pushers/Annotation-System.git`
|
||||||
2. `cd Annotation-System/hmmlib`
|
2. `cd Annotation-System/cinera`
|
||||||
3. `make`
|
3. `cp ../hmmlib2/hmmlib.h .`
|
||||||
4. `cp hmml.a hmmlib.h ../cinera/`
|
|
||||||
5. `cd ../cinera/`
|
|
||||||
|
|
||||||
Note: For each parser update, remember to make and copy it into place.
|
Note: For each parser update, remember to copy it into place.
|
||||||
|
|
||||||
### Build
|
### Build
|
||||||
|
|
||||||
1. `$SHELL cinera.c`
|
1. `$SHELL cinera.c`
|
||||||
|
|
||||||
|
### Configure
|
||||||
|
|
||||||
|
cinera -h
|
||||||
|
|
||||||
|
This documents the configuration file format and default settings.
|
||||||
|
|
||||||
### Configure the server
|
### Configure the server
|
||||||
|
|
||||||
If you enforce a strict Content Security Policy and X-Frame-Options in your
|
If you enforce a strict Content Security Policy and X-Frame-Options in your
|
||||||
|
|
@ -38,56 +41,24 @@ and [Hardening your HTTP response headers](https://scotthelme.co.uk/hardening-yo
|
||||||
|
|
||||||
### Run
|
### Run
|
||||||
|
|
||||||
#### Single Edition operation
|
cinera -c /path/to/config.conf
|
||||||
|
|
||||||
cinera test.hmml
|
|
||||||
|
|
||||||
This simply generates an HTML file (and updates `cinera_topics.css` if needed)
|
|
||||||
from `test.hmml` and outputs to `out.html` (configurable with -o).
|
|
||||||
|
|
||||||
#### Project Edition operation
|
|
||||||
|
|
||||||
cinera -p ProjectID
|
|
||||||
|
|
||||||
Setting the ProjectID with the `-p` flag triggers Project Edition. In this
|
|
||||||
edition _Cinera_ monitors the Project Input Directory for new, edited and
|
|
||||||
deleted .hmml files, and generates one table of contents / search page and a
|
|
||||||
player page each for valid sets of annotations (or removes them, if needed).
|
|
||||||
|
|
||||||
By default all directories - input and output - are set to the current working
|
|
||||||
directory. Typical operation will involve setting these flags:
|
|
||||||
|
|
||||||
-d Project Input Directory, the directory where the .hmml files reside
|
|
||||||
-r Asset Root Directory, path shallower than or equal to the CSS, Images and
|
|
||||||
JS directories
|
|
||||||
-R Asset Root URL, corresponding to the Root Directory
|
|
||||||
-c CSS Directory, relative to Root
|
|
||||||
-i Images Directory, relative to Root
|
|
||||||
-j JS Directory, relative to Root
|
|
||||||
-b Output Base Directory, location of the table of contents / search page
|
|
||||||
-B Output Base URL, corresponding to the Output Base Directory
|
|
||||||
-t Template Directory
|
|
||||||
-x Search Template Location, relative to Template Directory
|
|
||||||
-y Player Template Location, relative to Template Directory
|
|
||||||
|
|
||||||
#### Templates
|
#### Templates
|
||||||
|
|
||||||
*Search Template*
|
*(Global) Search Template*
|
||||||
- `<!-- __CINERA_INCLUDES__ -->` _to put inside your own `<head></head>`_
|
- `<!-- __CINERA_INCLUDES__ -->` _to put inside your own `<head></head>`_
|
||||||
- `<!-- __CINERA_SEARCH__ -->` _the table of contents and search functionality_
|
- `<!-- __CINERA_SEARCH__ -->` _the table of contents and search functionality_
|
||||||
|
|
||||||
*Player Template*
|
*Player Template*
|
||||||
- `<!-- __CINERA_INCLUDES__ -->` _to put inside your own `<head></head>`_
|
- `<!-- __CINERA_INCLUDES__ -->` _to put inside your own `<head></head>`_
|
||||||
- `<!-- __CINERA_MENUS__ -->`
|
|
||||||
- `<!-- __CINERA_PLAYER__ -->`
|
- `<!-- __CINERA_PLAYER__ -->`
|
||||||
- `<!-- __CINERA_SCRIPT__ -->` _must come after `<!-- __CINERA_MENUS__ -->` and `<!-- __CINERA_PLAYER__ -->`_
|
|
||||||
|
|
||||||
*Optional tags available for use in your Player Template*
|
*Optional tags available for use in your Player Template*
|
||||||
- `<!-- __CINERA_TITLE__ -->`
|
- `<!-- __CINERA_TITLE__ -->`
|
||||||
- `<!-- __CINERA_VIDEO_ID__ -->`
|
- `<!-- __CINERA_VIDEO_ID__ -->`
|
||||||
- `<!-- __CINERA_VOD_PLATFORM__ -->`
|
- `<!-- __CINERA_VOD_PLATFORM__ -->`
|
||||||
|
|
||||||
*Other tags available for use in either template*
|
*Other tags available for use in any template*
|
||||||
- Asset tags:
|
- Asset tags:
|
||||||
- `<!-- __CINERA_ASSET__ path.ext -->`
|
- `<!-- __CINERA_ASSET__ path.ext -->`
|
||||||
General purpose tag that outputs the URL of the specified asset
|
General purpose tag that outputs the URL of the specified asset
|
||||||
|
|
@ -113,8 +84,29 @@ All these asset tags additionally perform revving, appending a query
|
||||||
string (-Q) and the file's checksum to the URL. Changes to a file
|
string (-Q) and the file's checksum to the URL. Changes to a file
|
||||||
trigger a rehash and edit of all HTML pages citing this asset.
|
trigger a rehash and edit of all HTML pages citing this asset.
|
||||||
|
|
||||||
|
- Navigation / Menu tags:
|
||||||
|
- `<!-- __CINERA_NAV__ -->`
|
||||||
|
This menu will contain only the current project, its siblings and
|
||||||
|
subprojects of both the aforementioned
|
||||||
|
- `<!-- __CINERA_GLOBAL_NAV__ -->`
|
||||||
|
This menu will contain every project in the configuration
|
||||||
|
These navigation tags additionally take one parameter, e.g.
|
||||||
|
`<!-- __CINERA_NAV__ horizontal -->`:
|
||||||
|
- `dropdown`
|
||||||
|
A dropdown menu, that opens on hover
|
||||||
|
- `horizontal`
|
||||||
|
More-or-less the same as `dropdown`, but always open
|
||||||
|
- `plain`
|
||||||
|
A straightforward `<ul>` for you to style how you like
|
||||||
|
|
||||||
- `<!-- __CINERA_PROJECT__ -->`
|
- `<!-- __CINERA_PROJECT__ -->`
|
||||||
|
The project's `html_title` if configured, otherwise its `title`
|
||||||
|
- `<!-- __CINERA_PROJECT_PLAIN__ -->`
|
||||||
|
The project's `title`
|
||||||
- `<!-- __CINERA_PROJECT_ID__ -->`
|
- `<!-- __CINERA_PROJECT_ID__ -->`
|
||||||
|
- `<!-- __CINERA_PROJECT_LINEAGE__ -->`
|
||||||
|
The IDs of all projects from the root to the current project, separated
|
||||||
|
by a spaced-slash
|
||||||
- `<!-- __CINERA_SEARCH_URL__ -->`
|
- `<!-- __CINERA_SEARCH_URL__ -->`
|
||||||
- `<!-- __CINERA_THEME__ -->`
|
- `<!-- __CINERA_THEME__ -->`
|
||||||
- `<!-- __CINERA_URL__ -->` _Only really usable if BaseURL is set (-B)_
|
- `<!-- __CINERA_URL__ -->` _Only really usable if BaseURL is set (-B)_
|
||||||
|
|
@ -135,106 +127,15 @@ invalid, _Cinera_ will tell you what's wrong.
|
||||||
|
|
||||||
#### Arguments
|
#### Arguments
|
||||||
|
|
||||||
Usage: ./cinera [option(s)] filename(s)
|
Usage: ./cinera [option(s)]
|
||||||
|
|
||||||
Options:
|
Options:
|
||||||
Paths: (advisedly universal, but may be set per-(sub)project as required)
|
-c <config file path>
|
||||||
-r <assets root directory>
|
Set the main config file path
|
||||||
Override default assets root directory (".")
|
Defaults to: $XDG_CONFIG_HOME/cinera/cinera.conf
|
||||||
-R <assets root URL>
|
-0
|
||||||
Override default assets root URL ("")
|
Dry-run mode. Parse and print the config, but do not modify the
|
||||||
IMPORTANT: -r and -R must correspond to the same location
|
filesystem
|
||||||
UNSUPPORTED: If you move files from RootDir, the RootURL should
|
|
||||||
correspond to the resulting location
|
|
||||||
|
|
||||||
-c <CSS directory path>
|
|
||||||
Override default CSS directory (""), relative to root
|
|
||||||
-i <images directory path>
|
|
||||||
Override default images directory (""), relative to root
|
|
||||||
-j <JS directory path>
|
|
||||||
Override default JS directory (""), relative to root
|
|
||||||
-Q <revved resources query string>
|
|
||||||
Override default query string ("r")
|
|
||||||
To disable revved resources, set an empty string with -Q ""
|
|
||||||
|
|
||||||
Project Settings:
|
|
||||||
-p <project ID>
|
|
||||||
Set the project ID, triggering PROJECT EDITION
|
|
||||||
-m <default medium>
|
|
||||||
Override default default medium ("programming")
|
|
||||||
Known project defaults:
|
|
||||||
bitwise: programming
|
|
||||||
book: research
|
|
||||||
coad: research
|
|
||||||
reader: research
|
|
||||||
riscy: programming
|
|
||||||
risc: speech
|
|
||||||
chat: speech
|
|
||||||
code: programming
|
|
||||||
intro-to-c: programming
|
|
||||||
misc: admin
|
|
||||||
ray: programming
|
|
||||||
hmdshow: speech
|
|
||||||
lecture: speech
|
|
||||||
stream: programming
|
|
||||||
special: programming
|
|
||||||
obbg: programming
|
|
||||||
sysadmin: admin
|
|
||||||
-s <style>
|
|
||||||
Set the style / theme, corresponding to a cinera__*.css file
|
|
||||||
This is equal to the "project" field in the HMML files by default
|
|
||||||
|
|
||||||
Project Input Paths
|
|
||||||
-d <annotations directory>
|
|
||||||
Override default annotations directory (".")
|
|
||||||
-t <templates directory>
|
|
||||||
Override default templates directory (".")
|
|
||||||
|
|
||||||
-x <search template location>
|
|
||||||
Set search template file path, either absolute or relative to
|
|
||||||
template directory, and enable integration
|
|
||||||
-y <player template location>
|
|
||||||
Set player template file path, either absolute or relative
|
|
||||||
to template directory, and enable integration
|
|
||||||
|
|
||||||
Project Output Paths
|
|
||||||
-b <base output directory>
|
|
||||||
Override project's default base output directory (".")
|
|
||||||
-B <base URL>
|
|
||||||
Override default base URL ("")
|
|
||||||
NOTE: This must be set, if -n or -a are to be used
|
|
||||||
|
|
||||||
-n <search location>
|
|
||||||
Override default search location (""), relative to base
|
|
||||||
-a <player location>
|
|
||||||
Override default player location (""), relative to base
|
|
||||||
NOTE: The PlayerURLPrefix is currently hardcoded in cinera.c but
|
|
||||||
will be configurable in the full configuration system
|
|
||||||
|
|
||||||
Single Edition Output Path
|
|
||||||
-o <output location>
|
|
||||||
Override default output player location ("out.html")
|
|
||||||
|
|
||||||
-1
|
|
||||||
Open search result links in the same browser tab
|
|
||||||
NOTE: Ideal for a guide embedded in an iframe
|
|
||||||
-f
|
|
||||||
Force integration with an incomplete template
|
|
||||||
-g
|
|
||||||
Ignore video privacy status
|
|
||||||
NOTE: For use with projects whose videos are known to all be public,
|
|
||||||
to save us having to check their privacy status
|
|
||||||
-q
|
|
||||||
Quit after syncing with annotation files in project input directory
|
|
||||||
UNSUPPORTED: This is likely to be removed in the future
|
|
||||||
-w
|
|
||||||
Force quote cache rebuild (memory aid: "wget")
|
|
||||||
|
|
||||||
-l <n>
|
|
||||||
Override default log level (0), where n is from 0 (terse) to 7 (verbose)
|
|
||||||
-u <seconds>
|
|
||||||
Override default update interval (4)
|
|
||||||
|
|
||||||
-e
|
-e
|
||||||
Display (examine) database and exit
|
Display (examine) database and exit
|
||||||
-v
|
-v
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue