doc: add README

2 files changed, 81 insertions, 9 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..807e55e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,81 @@
+# Easy index and Atom generator
+
+This is a simple tool to generate an Atom and an HTML index from a very simple
+scheme file.
+It doesn't control errors for the moment so be careful with what you do.
+
+## Usage
+
+`(src atom)` and `(src html)` are libraries you can use independently as in
+`tests/`, but the magic comes when you read the basic Format (see below) as a
+generic generator.
+
+The following script shows one way to do it:
+
+``` scm
+(define-module (scripts create)
+  #:use-module ((src atom) #:prefix atom:)
+  #:use-module ((src html) #:prefix html:)
+  #:use-module (src as))
+
+(define root (canonicalize-path (cadr (command-line))))
+
+(define atom-feed  (lambda () (atom:render (as 'atom root))))
+(define html-index (lambda () (html:render (as 'html root))))
+
+(atom-feed)   ;; writes your feed to current-output-port
+(html-index)  ;; writes your html to current-output-port
+```
+
+`(as 'atom root)` and `(as 'html root)` the scheme file in `root` and interpret
+it as atom and html respectively. From that, the result can be generated
+calling the `render` function of the modules as suggested in the example.
+
+There's also a `media-uploader` module that would upload all the independent
+media to the server, but it's still a WIP.
+
+## Format
+
+You have the following constructs to generate your site:
+
+- `main`: represents the core of your website and atom feed. It has these
+  fields represented as guile keyword args:
+  - `#:title`: `string`.
+  - `#:subtitle`: `string`.
+  - `#:uri`: URI of main document to insert in Atom. It's a `string`.
+  - `#:posts`: posts of your website. Used form Atom to create entries of your
+    feed. It's a `list` of `post`s.
+  - `#:updated`: date of the latest update of your site. If nothing is added
+    it's automatically filled from the posts. Only used by Atom.
+  - `#:short-description`: `string`
+  - `#:long-description`: SXML
+  - `#:author`: the author of the website and feed. Each post can have its own.
+     `person`
+  - `#:styles`: CSS to apply to your HTML. List of `media` or `string`
+    elements.
+  - `#:scripts`: JavaScript to apply to your HTML. List of `media` or `string`
+    elements.
+- `post`: represents each content units of your site. It has these fields
+  represented as guile keyword args:
+  - `#:title`: `string`.
+  - `#:id`: `string`, if ignored it's generated from the title.
+  - `#:published`: Publishing date. `date`
+  - `#:updated`: Update date. `date`
+  - `#:authors`: list of `person`
+  - `#:summary-html`: SXML
+  - `#:content-html`: SXML
+  - `#:categories`: list of `string`
+  - `#:contributors`: list of `person`
+  - `#:media`: list of `media`
+- `person`: requires a positional argument: `name`. It has some extra fields
+  represented as guile keyword args:
+  - `#:email`: `string`.
+  - `#:uri`: `string`.
+- `media`: stores information about independent files of the site. CSS, JS, and
+  multimedia files can be represented as media. It requires a positional
+  argument: `path`. It has these extra fields:
+  - `#:uri`: URI this file will have once deployed. `string`
+  - `#:type`: internally used mime-type. `string`
+- `string/ISO->date` is a helper function that creates a date from a string in
+  YYYY-MM-DD format.
+
diff --git a/scripts/create.scm b/scripts/create.scm
deleted file mode 100644
index 6f7f549..0000000
--- a/scripts/create.scm
+++ /dev/null
@@ -1,9 +0,0 @@
-(define-module (scripts create)
-  #:use-module ((src atom) #:prefix atom:)
-  #:use-module ((src html) #:prefix html:)
-  #:use-module (src as))
-
-(define root (canonicalize-path (cadr (command-line))))
-
-(define atom-feed  (atom:render (as 'atom root)))
-(define html-index (html:render (as 'html root)))